From e8e386aa027072de829f9496f684868c018056fb Mon Sep 17 00:00:00 2001
From: Adrien Carpentier <me@adriencarpentier.com>
Date: Thu, 5 Feb 2026 16:26:14 +0100
Subject: [PATCH 01/11] feat: suggest dataservice description

---
 .../Dataservices/DescribeDataservice.vue      | 114 +++++++++++++++++-
 components/MarkdownEditor/InternalEditor.vue  |   1 +
 .../generate-dataservice-description.post.ts  | 107 ++++++++++++++++
 3 files changed, 218 insertions(+), 4 deletions(-)
 create mode 100644 server/routes/nuxt-api/albert/generate-dataservice-description.post.ts

diff --git a/components/Dataservices/DescribeDataservice.vue b/components/Dataservices/DescribeDataservice.vue
index 03b402aad..af33d6218 100644
--- a/components/Dataservices/DescribeDataservice.vue
+++ b/components/Dataservices/DescribeDataservice.vue
@@ -251,6 +251,7 @@
             :accordion="addDescriptionAccordionId"
           >
             <InputGroup
+              :key="descriptionEditorRefreshKey"
               v-model="form.description"
               class="mb-3"
               :label="$t('Description')"
@@ -268,6 +269,49 @@
             >
               {{ getFirstWarning("description") }}
             </SimpleBanner>
+            <div class="flex items-center gap-4 mt-2 mb-3">
+              <Tooltip v-if="!canGenerateDescription">
+                <BrandedButton
+                  type="button"
+                  color="primary"
+                  :disabled="true"
+                >
+                  <div class="flex items-center space-x-2">
+                    <RiSparklingLine
+                      class="size-4"
+                      aria-hidden="true"
+                    />
+                    <span>{{ $t('Suggérer une description') }}</span>
+                  </div>
+                </BrandedButton>
+                <template #tooltip>
+                  {{ $t('Remplissez le nom de l\'API et au moins l\'un des liens (documentation technique ou documentation machine) pour utiliser cette fonctionnalité.') }}
+                </template>
+              </Tooltip>
+              <BrandedButton
+                v-else
+                type="button"
+                color="primary"
+                :icon="RiSparklingLine"
+                :loading="isGeneratingDescription"
+                @click="handleAutoCompleteDescription"
+              >
+                <template v-if="isGeneratingDescription">
+                  {{ $t('Suggestion en cours...') }}
+                </template>
+                <template v-else>
+                  {{ $t('Suggérer une description') }}
+                </template>
+              </BrandedButton>
+              <CdataLink
+                v-if="config.public.generateDescriptionFeedbackUrl"
+                :to="config.public.generateDescriptionFeedbackUrl"
+                target="_blank"
+                class="text-sm text-gray-medium"
+              >
+                {{ $t('Comment avez-vous trouvé cette suggestion ?') }}
+              </CdataLink>
+            </div>
           </LinkedToAccordion>
           <LinkedToAccordion
             class="fr-fieldset__element"
@@ -550,14 +594,16 @@
 </template>
 
 <script setup lang="ts">
-import { BrandedButton, SimpleBanner, TranslationT } from '@datagouv/components-next'
-import { RiAddLine } from '@remixicon/vue'
-import ModalClient from '../Modal/Modal.client.vue'
+import { BrandedButton, SimpleBanner, toast, Tooltip, TranslationT } from '@datagouv/components-next'
+import { RiAddLine, RiSparklingLine } from '@remixicon/vue'
+import { computed, nextTick } from 'vue'
 import Accordion from '~/components/Accordion/Accordion.global.vue'
 import AccordionGroup from '~/components/Accordion/AccordionGroup.global.vue'
-import ToggleSwitch from '~/components/Form/ToggleSwitch.vue'
+import CdataLink from '~/components/CdataLink.vue'
 import ContactPointSelect from '~/components/ContactPointSelect.vue'
 import ProducerSelect from '~/components/ProducerSelect.vue'
+import ToggleSwitch from '~/components/Form/ToggleSwitch.vue'
+import ModalClient from '../Modal/Modal.client.vue'
 import type { DataserviceForm } from '~/types/types'
 
 const props = defineProps<{
@@ -592,6 +638,16 @@ const contactPointAccordionId = useId()
 const machineDocumentationUrlWarningMessage = t(`Il est fortement recommandé d'ajouter une documentation OpenAPI ou Swagger à votre API.`)
 const openConfirmModal = ref(false)
 const showRateLimitingUrl = ref(false)
+const descriptionEditorRefreshKey = ref(0)
+const isGeneratingDescription = ref(false)
+
+const hasTechnicalDocumentationUrl = computed(() => form.value.technical_documentation_url && form.value.technical_documentation_url.trim().length > 0)
+const hasMachineDocumentationUrl = computed(() => form.value.machine_documentation_url && form.value.machine_documentation_url.trim().length > 0)
+const hasTitle = computed(() => form.value.title && form.value.title.trim().length > 0)
+
+const canGenerateDescription = computed(() => {
+  return hasTitle.value && (hasTechnicalDocumentationUrl.value || hasMachineDocumentationUrl.value)
+})
 
 const { form, touch, getFirstError, getFirstWarning, validate } = useForm(dataserviceForm, {
   featured: [],
@@ -623,6 +679,56 @@ const accordionState = (key: keyof typeof form.value) => {
   return 'default'
 }
 
+async function handleAutoCompleteDescription() {
+  const title = form.value.title?.trim()
+  const technicalUrl = form.value.technical_documentation_url?.trim()
+  const machineUrl = form.value.machine_documentation_url?.trim()
+
+  if (!title || (!technicalUrl && !machineUrl)) {
+    return
+  }
+
+  try {
+    isGeneratingDescription.value = true
+
+    const requestBody: {
+      title: string
+      technicalDocumentationUrl?: string
+      machineDocumentationUrl?: string
+    } = {
+      title,
+      ...(technicalUrl && { technicalDocumentationUrl: technicalUrl }),
+      ...(machineUrl && { machineDocumentationUrl: machineUrl }),
+    }
+
+    // We call our server-side API route instead of Albert API directly to avoid CORS issues.
+    // The Albert API doesn't allow direct requests from browser-side JavaScript.
+    // Our server acts as a proxy, keeping the API key secure on the server side.
+    const response = await $fetch<{ description?: string }>('/nuxt-api/albert/generate-dataservice-description', {
+      method: 'POST',
+      body: requestBody,
+    })
+
+    if (response.description) {
+      form.value.description = response.description
+      descriptionEditorRefreshKey.value += 1
+      await nextTick()
+    }
+  }
+  catch (error) {
+    console.error('[Albert API] Failed to generate description:', error)
+    const message = error && typeof error === 'object' && 'data' in error && error.data && typeof error.data === 'object' && 'statusMessage' in error.data
+      ? String((error.data as { statusMessage: string }).statusMessage)
+      : error instanceof Error
+        ? error.message
+        : t('Impossible de générer une description. Vérifiez que les liens de documentation sont valides et accessibles.')
+    toast.error(message)
+  }
+  finally {
+    isGeneratingDescription.value = false
+  }
+}
+
 async function submit() {
   if (await validate()) {
     if (dataserviceForm.value.machine_documentation_url || openConfirmModal.value) {
diff --git a/components/MarkdownEditor/InternalEditor.vue b/components/MarkdownEditor/InternalEditor.vue
index 8904288da..d0b51d024 100644
--- a/components/MarkdownEditor/InternalEditor.vue
+++ b/components/MarkdownEditor/InternalEditor.vue
@@ -140,6 +140,7 @@ import { RiArrowGoBackLine, RiArrowGoForwardLine, RiBold, RiCodeSSlashLine, RiDo
 import { Milkdown, useEditor } from '@milkdown/vue'
 import { usePluginViewFactory, useWidgetViewFactory } from '@prosemirror-adapter/vue'
 import { useDebounceFn } from '@vueuse/core'
+import { ref } from 'vue'
 import { clipboard } from '@milkdown/kit/plugin/clipboard'
 import type { ImageModalForm } from '~/components/MarkdownEditor/ImageModal/ImageModalButton.vue'
 import ImageModalButton from '~/components/MarkdownEditor/ImageModal/ImageModalButton.vue'
diff --git a/server/routes/nuxt-api/albert/generate-dataservice-description.post.ts b/server/routes/nuxt-api/albert/generate-dataservice-description.post.ts
new file mode 100644
index 000000000..cf0e11d6f
--- /dev/null
+++ b/server/routes/nuxt-api/albert/generate-dataservice-description.post.ts
@@ -0,0 +1,107 @@
+import { createChatCompletion, useAlbertConfig, type ChatResponse } from '~/server/utils/albert-api-client'
+
+export default defineEventHandler(async (event) => {
+  const body = await readBody(event)
+  const { title, technicalDocumentationUrl, machineDocumentationUrl } = body
+
+  if (!title?.trim()) {
+    console.error('[Albert API] Missing required field: title')
+    throw createError({
+      statusCode: 400,
+      statusMessage: 'Title is required',
+    })
+  }
+
+  const hasTechnical = !!technicalDocumentationUrl?.trim()
+  const hasMachine = !!machineDocumentationUrl?.trim()
+  if (!hasTechnical && !hasMachine) {
+    console.error('[Albert API] At least one of technicalDocumentationUrl or machineDocumentationUrl is required')
+    throw createError({
+      statusCode: 400,
+      statusMessage: 'Either technical documentation URL or machine documentation URL is required',
+    })
+  }
+
+  const runtimeConfig = useRuntimeConfig()
+
+  if (!runtimeConfig.albertApiKey) {
+    console.error('[Albert API] API key not configured')
+    throw createError({
+      statusCode: 400,
+      statusMessage: 'Albert API is not configured',
+    })
+  }
+
+  try {
+    const albertConfig = useAlbertConfig()
+
+    const messages = [
+      {
+        role: 'system',
+        content: `You are an assistant integrated into data.gouv.fr, the French open data platform.\n`
+          + `Your purpose is to help API producers write clear, comprehensive, and factual descriptions of APIs.\n`
+          + `\n`
+          + `Guidelines:\n`
+          + `- Always respond in French.\n`
+          + `- Your tone is factual, neutral, and accessible to non-experts.\n`
+          + `- Use plain language and clear sentences, avoiding unnecessary technical jargon.\n`
+          + `- Do not make assumptions or add information that is not present in the input.\n`
+          + `- Focus on what the API does, what data it provides, and how it can be used.\n`
+          + `- Always start with a capital letter and end with a period.\n`
+          + `- The goal is to produce informative descriptions that help users understand the API's purpose and capabilities.\n`
+          + `- IMPORTANT: Return ONLY the description text, without quotes or additional punctuation.`,
+      },
+      {
+        role: 'user',
+        content: `You are asked to generate a description for an API on data.gouv.fr.\n`
+          + `\n`
+          + `Goal:\n`
+          + `→ Write a comprehensive and accessible description of the API.\n`
+          + `→ Focus on what the API does, what data it provides, and its main capabilities.\n`
+          + `→ Mention key endpoints, data types, and use cases if available.\n`
+          + `→ Explain the API's purpose and how it can be used.\n`
+          + `\n`
+          + `Here is the API information:\n`
+          + `Title: ${title.trim()}\n`
+          + (hasTechnical ? `Technical documentation URL: ${technicalDocumentationUrl.trim()}\n` : '')
+          + (hasMachine ? `Machine documentation URL (OpenAPI/Swagger): ${machineDocumentationUrl.trim()}\n` : '')
+          + `\n`
+          + `Output:\n`
+          + `→ A comprehensive description in French (no markdown, no introduction, no labels, no emojis).\n`
+          + `→ The description should be detailed enough to help users understand the API's purpose and capabilities.`,
+      },
+    ]
+
+    // Models available for text generation:
+    // - openweight-small (replaces albert-small)
+    // - openweight-medium (replaces albert-large)
+    // - openweight-large
+    const response = await createChatCompletion(messages, 'openweight-small', albertConfig) as ChatResponse
+    const generatedDescription = (response.choices?.[0]?.message?.content || '').trim()
+
+    const MIN_DESCRIPTION_LENGTH = 50
+    if (generatedDescription.length < MIN_DESCRIPTION_LENGTH) {
+      console.error('[Albert API] Generated description too short or empty - documentation may be unreachable or insufficient')
+      throw createError({
+        statusCode: 422,
+        statusMessage: 'Could not generate a sufficient description from the provided documentation. Please check that the URLs are valid, reachable, and point to API documentation.',
+      })
+    }
+
+    return { description: generatedDescription }
+  }
+  catch (error) {
+    console.error('[Albert API] Error calling Albert API:', error)
+    if (error && typeof error === 'object') {
+      console.error('[Albert API] Error details:', {
+        message: (error as Error).message,
+        stack: (error as Error).stack,
+        ...error,
+      })
+    }
+    throw createError({
+      statusCode: 500,
+      statusMessage: (error as Error).message || 'Failed to call Albert API',
+    })
+  }
+})

From f4c512edfb6a0bde88d893aced018d94920bccc6 Mon Sep 17 00:00:00 2001
From: Adrien Carpentier <me@adriencarpentier.com>
Date: Mon, 16 Feb 2026 17:57:45 +0100
Subject: [PATCH 02/11] docs: add help text

---
 components/Dataservices/DescribeDataservice.vue | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/components/Dataservices/DescribeDataservice.vue b/components/Dataservices/DescribeDataservice.vue
index af33d6218..04cb00434 100644
--- a/components/Dataservices/DescribeDataservice.vue
+++ b/components/Dataservices/DescribeDataservice.vue
@@ -40,6 +40,12 @@
           <p class="fr-m-0">
             {{ t("Rédigez une description claire et précise de l'API. Les usagers ont besoin de comprendre l'objectif de l'API, les données délivrées, le périmètre couvert (la donnée est-elle exhaustive, y-a t'il des manques ?), la fréquence d'actualisation de la donnée, ainsi que les paramètres avec lesquels ils peuvent effectuer un appel.") }}
           </p>
+          <p class="fr-mt-3v font-bold">
+            {{ $t("Suggestions automatiques") }}
+          </p>
+          <p class="fr-m-0">
+            {{ $t(`Une première version peut être générée automatiquement si vous avez rempli le nom de l'API et au moins un lien fonctionnel vers la documentation (technique ou machine), puis adaptée selon vos besoins.`) }}
+          </p>
         </Accordion>
         <Accordion
           :id="addBaseUrlAccordionId"

From 5ec0ff79db2e5a6f79333871f36d8e2472232ea0 Mon Sep 17 00:00:00 2001
From: Adrien Carpentier <me@adriencarpentier.com>
Date: Tue, 17 Feb 2026 15:04:50 +0100
Subject: [PATCH 03/11] refactor(markdown-editor): remove unnecessary ref
 import

Remove explicit ref import as it's auto-imported by Nuxt

Co-authored-by: Cursor <cursoragent@cursor.com>
---
 components/MarkdownEditor/InternalEditor.vue | 1 -
 1 file changed, 1 deletion(-)

diff --git a/components/MarkdownEditor/InternalEditor.vue b/components/MarkdownEditor/InternalEditor.vue
index d0b51d024..8904288da 100644
--- a/components/MarkdownEditor/InternalEditor.vue
+++ b/components/MarkdownEditor/InternalEditor.vue
@@ -140,7 +140,6 @@ import { RiArrowGoBackLine, RiArrowGoForwardLine, RiBold, RiCodeSSlashLine, RiDo
 import { Milkdown, useEditor } from '@milkdown/vue'
 import { usePluginViewFactory, useWidgetViewFactory } from '@prosemirror-adapter/vue'
 import { useDebounceFn } from '@vueuse/core'
-import { ref } from 'vue'
 import { clipboard } from '@milkdown/kit/plugin/clipboard'
 import type { ImageModalForm } from '~/components/MarkdownEditor/ImageModal/ImageModalButton.vue'
 import ImageModalButton from '~/components/MarkdownEditor/ImageModal/ImageModalButton.vue'

From 4066749518e7647eb4b1ba14f67a226a784ec8d5 Mon Sep 17 00:00:00 2001
From: Adrien Carpentier <me@adriencarpentier.com>
Date: Tue, 17 Feb 2026 15:50:42 +0100
Subject: [PATCH 04/11] refactor(albert): use shared helpers and remove
 duplicate config check

- Use callAlbertAPI from albert-helpers in generate-dataservice-description
  (align with other Albert endpoints)
- Fix 422 for 'description too short' so it is returned to client instead of 500
- Remove validateAlbertConfig; useAlbertConfig() already throws when API key
  is missing
- Drop redundant error logging in dataservice-description handler

Co-authored-by: Cursor <cursoragent@cursor.com>
---
 .../generate-dataservice-description.post.ts  | 124 +++++++-----------
 ...generate-dataset-short-description.post.ts |   4 +-
 .../albert/generate-dataset-tags.post.ts      |   4 +-
 .../albert/generate-reuse-tags.post.ts        |   4 +-
 .../nuxt-api/albert/utils/albert-helpers.ts   |  14 --
 5 files changed, 47 insertions(+), 103 deletions(-)

diff --git a/server/routes/nuxt-api/albert/generate-dataservice-description.post.ts b/server/routes/nuxt-api/albert/generate-dataservice-description.post.ts
index cf0e11d6f..6f39dce2d 100644
--- a/server/routes/nuxt-api/albert/generate-dataservice-description.post.ts
+++ b/server/routes/nuxt-api/albert/generate-dataservice-description.post.ts
@@ -1,11 +1,10 @@
-import { createChatCompletion, useAlbertConfig, type ChatResponse } from '~/server/utils/albert-api-client'
+import { callAlbertAPI } from './utils/albert-helpers'
 
 export default defineEventHandler(async (event) => {
   const body = await readBody(event)
   const { title, technicalDocumentationUrl, machineDocumentationUrl } = body
 
   if (!title?.trim()) {
-    console.error('[Albert API] Missing required field: title')
     throw createError({
       statusCode: 400,
       statusMessage: 'Title is required',
@@ -15,93 +14,58 @@ export default defineEventHandler(async (event) => {
   const hasTechnical = !!technicalDocumentationUrl?.trim()
   const hasMachine = !!machineDocumentationUrl?.trim()
   if (!hasTechnical && !hasMachine) {
-    console.error('[Albert API] At least one of technicalDocumentationUrl or machineDocumentationUrl is required')
     throw createError({
       statusCode: 400,
       statusMessage: 'Either technical documentation URL or machine documentation URL is required',
     })
   }
 
-  const runtimeConfig = useRuntimeConfig()
+  const messages = [
+    {
+      role: 'system',
+      content: `You are an assistant integrated into data.gouv.fr, the French open data platform.\n`
+        + `Your purpose is to help API producers write clear, comprehensive, and factual descriptions of APIs.\n`
+        + `\n`
+        + `Guidelines:\n`
+        + `- Always respond in French.\n`
+        + `- Your tone is factual, neutral, and accessible to non-experts.\n`
+        + `- Use plain language and clear sentences, avoiding unnecessary technical jargon.\n`
+        + `- Do not make assumptions or add information that is not present in the input.\n`
+        + `- Focus on what the API does, what data it provides, and how it can be used.\n`
+        + `- Always start with a capital letter and end with a period.\n`
+        + `- The goal is to produce informative descriptions that help users understand the API's purpose and capabilities.\n`
+        + `- IMPORTANT: Return ONLY the description text, without quotes or additional punctuation.`,
+    },
+    {
+      role: 'user',
+      content: `You are asked to generate a description for an API on data.gouv.fr.\n`
+        + `\n`
+        + `Goal:\n`
+        + `→ Write a comprehensive and accessible description of the API.\n`
+        + `→ Focus on what the API does, what data it provides, and its main capabilities.\n`
+        + `→ Mention key endpoints, data types, and use cases if available.\n`
+        + `→ Explain the API's purpose and how it can be used.\n`
+        + `\n`
+        + `Here is the API information:\n`
+        + `Title: ${title.trim()}\n`
+        + (hasTechnical ? `Technical documentation URL: ${technicalDocumentationUrl.trim()}\n` : '')
+        + (hasMachine ? `Machine documentation URL (OpenAPI/Swagger): ${machineDocumentationUrl.trim()}\n` : '')
+        + `\n`
+        + `Output:\n`
+        + `→ A comprehensive description in French (no markdown, no introduction, no labels, no emojis).\n`
+        + `→ The description should be detailed enough to help users understand the API's purpose and capabilities.`,
+    },
+  ]
 
-  if (!runtimeConfig.albertApiKey) {
-    console.error('[Albert API] API key not configured')
-    throw createError({
-      statusCode: 400,
-      statusMessage: 'Albert API is not configured',
-    })
-  }
-
-  try {
-    const albertConfig = useAlbertConfig()
+  const generatedDescription = (await callAlbertAPI(messages, 'openweight-small')).trim()
 
-    const messages = [
-      {
-        role: 'system',
-        content: `You are an assistant integrated into data.gouv.fr, the French open data platform.\n`
-          + `Your purpose is to help API producers write clear, comprehensive, and factual descriptions of APIs.\n`
-          + `\n`
-          + `Guidelines:\n`
-          + `- Always respond in French.\n`
-          + `- Your tone is factual, neutral, and accessible to non-experts.\n`
-          + `- Use plain language and clear sentences, avoiding unnecessary technical jargon.\n`
-          + `- Do not make assumptions or add information that is not present in the input.\n`
-          + `- Focus on what the API does, what data it provides, and how it can be used.\n`
-          + `- Always start with a capital letter and end with a period.\n`
-          + `- The goal is to produce informative descriptions that help users understand the API's purpose and capabilities.\n`
-          + `- IMPORTANT: Return ONLY the description text, without quotes or additional punctuation.`,
-      },
-      {
-        role: 'user',
-        content: `You are asked to generate a description for an API on data.gouv.fr.\n`
-          + `\n`
-          + `Goal:\n`
-          + `→ Write a comprehensive and accessible description of the API.\n`
-          + `→ Focus on what the API does, what data it provides, and its main capabilities.\n`
-          + `→ Mention key endpoints, data types, and use cases if available.\n`
-          + `→ Explain the API's purpose and how it can be used.\n`
-          + `\n`
-          + `Here is the API information:\n`
-          + `Title: ${title.trim()}\n`
-          + (hasTechnical ? `Technical documentation URL: ${technicalDocumentationUrl.trim()}\n` : '')
-          + (hasMachine ? `Machine documentation URL (OpenAPI/Swagger): ${machineDocumentationUrl.trim()}\n` : '')
-          + `\n`
-          + `Output:\n`
-          + `→ A comprehensive description in French (no markdown, no introduction, no labels, no emojis).\n`
-          + `→ The description should be detailed enough to help users understand the API's purpose and capabilities.`,
-      },
-    ]
-
-    // Models available for text generation:
-    // - openweight-small (replaces albert-small)
-    // - openweight-medium (replaces albert-large)
-    // - openweight-large
-    const response = await createChatCompletion(messages, 'openweight-small', albertConfig) as ChatResponse
-    const generatedDescription = (response.choices?.[0]?.message?.content || '').trim()
-
-    const MIN_DESCRIPTION_LENGTH = 50
-    if (generatedDescription.length < MIN_DESCRIPTION_LENGTH) {
-      console.error('[Albert API] Generated description too short or empty - documentation may be unreachable or insufficient')
-      throw createError({
-        statusCode: 422,
-        statusMessage: 'Could not generate a sufficient description from the provided documentation. Please check that the URLs are valid, reachable, and point to API documentation.',
-      })
-    }
-
-    return { description: generatedDescription }
-  }
-  catch (error) {
-    console.error('[Albert API] Error calling Albert API:', error)
-    if (error && typeof error === 'object') {
-      console.error('[Albert API] Error details:', {
-        message: (error as Error).message,
-        stack: (error as Error).stack,
-        ...error,
-      })
-    }
+  const MIN_DESCRIPTION_LENGTH = 50
+  if (generatedDescription.length < MIN_DESCRIPTION_LENGTH) {
     throw createError({
-      statusCode: 500,
-      statusMessage: (error as Error).message || 'Failed to call Albert API',
+      statusCode: 422,
+      statusMessage: 'Could not generate a sufficient description from the provided documentation. Please check that the URLs are valid, reachable, and point to API documentation.',
     })
   }
+
+  return { description: generatedDescription }
 })
diff --git a/server/routes/nuxt-api/albert/generate-dataset-short-description.post.ts b/server/routes/nuxt-api/albert/generate-dataset-short-description.post.ts
index 1f0dcb74b..fe51e43e6 100644
--- a/server/routes/nuxt-api/albert/generate-dataset-short-description.post.ts
+++ b/server/routes/nuxt-api/albert/generate-dataset-short-description.post.ts
@@ -1,5 +1,5 @@
 import { DESCRIPTION_SHORT_MAX_LENGTH } from '~/datagouv-components/src/functions/description'
-import { validateAlbertConfig, callAlbertAPI } from './utils/albert-helpers'
+import { callAlbertAPI } from './utils/albert-helpers'
 
 export default defineEventHandler(async (event) => {
   const body = await readBody(event)
@@ -12,8 +12,6 @@ export default defineEventHandler(async (event) => {
     })
   }
 
-  validateAlbertConfig()
-
   const messages = [
     {
       role: 'system',
diff --git a/server/routes/nuxt-api/albert/generate-dataset-tags.post.ts b/server/routes/nuxt-api/albert/generate-dataset-tags.post.ts
index 00600cf26..26c497538 100644
--- a/server/routes/nuxt-api/albert/generate-dataset-tags.post.ts
+++ b/server/routes/nuxt-api/albert/generate-dataset-tags.post.ts
@@ -1,4 +1,4 @@
-import { validateAlbertConfig, callAlbertAPI, parseTags } from './utils/albert-helpers'
+import { callAlbertAPI, parseTags } from './utils/albert-helpers'
 
 export default defineEventHandler(async (event) => {
   const body = await readBody(event)
@@ -11,8 +11,6 @@ export default defineEventHandler(async (event) => {
     })
   }
 
-  validateAlbertConfig()
-
   const messages = [
     {
       role: 'system',
diff --git a/server/routes/nuxt-api/albert/generate-reuse-tags.post.ts b/server/routes/nuxt-api/albert/generate-reuse-tags.post.ts
index 87240995f..ac07bb759 100644
--- a/server/routes/nuxt-api/albert/generate-reuse-tags.post.ts
+++ b/server/routes/nuxt-api/albert/generate-reuse-tags.post.ts
@@ -1,4 +1,4 @@
-import { validateAlbertConfig, callAlbertAPI, parseTags } from './utils/albert-helpers'
+import { callAlbertAPI, parseTags } from './utils/albert-helpers'
 
 export default defineEventHandler(async (event) => {
   const body = await readBody(event)
@@ -11,8 +11,6 @@ export default defineEventHandler(async (event) => {
     })
   }
 
-  validateAlbertConfig()
-
   const messages = [
     {
       role: 'system',
diff --git a/server/routes/nuxt-api/albert/utils/albert-helpers.ts b/server/routes/nuxt-api/albert/utils/albert-helpers.ts
index c7a312553..c6d85a57b 100644
--- a/server/routes/nuxt-api/albert/utils/albert-helpers.ts
+++ b/server/routes/nuxt-api/albert/utils/albert-helpers.ts
@@ -1,19 +1,5 @@
 import { type ChatResponse, createChatCompletion, useAlbertConfig } from '~/server/utils/albert-api-client'
 
-/**
- * Validates that Albert API is properly configured
- * @throws {Error} If Albert API key is not configured
- */
-export function validateAlbertConfig() {
-  const runtimeConfig = useRuntimeConfig()
-  if (!runtimeConfig.albertApiKey) {
-    throw createError({
-      statusCode: 400,
-      statusMessage: 'Albert API is not configured',
-    })
-  }
-}
-
 /**
  * Calls Albert API with the given messages and model
  * @param messages - Array of chat messages (system and user prompts)

From 93c5c1952572433cea6b1da958f9064a8e26860d Mon Sep 17 00:00:00 2001
From: Adrien Carpentier <me@adriencarpentier.com>
Date: Tue, 17 Feb 2026 15:57:38 +0100
Subject: [PATCH 05/11] refactor(config): rename
 generateShortDescriptionFeedbackUrl to generateDescriptionFeedbackUrl

Co-authored-by: Cursor <cursoragent@cursor.com>
---
 components/Datasets/DescribeDataset.vue | 4 ++--
 nuxt.config.ts                          | 2 +-
 2 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/components/Datasets/DescribeDataset.vue b/components/Datasets/DescribeDataset.vue
index b4391b3ce..646daf41f 100644
--- a/components/Datasets/DescribeDataset.vue
+++ b/components/Datasets/DescribeDataset.vue
@@ -352,8 +352,8 @@
                 </template>
               </BrandedButton>
               <CdataLink
-                v-if="config.public.generateShortDescriptionFeedbackUrl"
-                :to="config.public.generateShortDescriptionFeedbackUrl"
+                v-if="config.public.generateDescriptionFeedbackUrl"
+                :to="config.public.generateDescriptionFeedbackUrl"
                 target="_blank"
                 class="text-sm text-gray-medium"
               >
diff --git a/nuxt.config.ts b/nuxt.config.ts
index f0cd84372..131b44f8b 100644
--- a/nuxt.config.ts
+++ b/nuxt.config.ts
@@ -128,7 +128,7 @@ export default defineNuxtConfig({
       datasetRestrictedGuideUrl: 'https://guides.data.gouv.fr/guides/guide-juridique/producteurs-de-donnees/quelles-sont-les-obligations',
       dataSearchFeedbackFormUrl: 'https://tally.so/r/mDKv1N',
       forumUrl: 'https://forum.data.gouv.fr/',
-      generateShortDescriptionFeedbackUrl: 'https://tally.so/r/wbbRxo',
+      generateDescriptionFeedbackUrl: 'https://tally.so/r/wbbRxo',
       generateTagsFeedbackUrl: 'https://tally.so/r/w80JNP',
       publishingDatasetFeedbackUrl: 'https://tally.so/r/nGo0yO',
       publishingDataserviceFeedbackUrl: 'https://tally.so/r/w2J7lL',

From 92d279c81a82c4a0b43ac34f43238d84726ca817 Mon Sep 17 00:00:00 2001
From: Adrien Carpentier <me@adriencarpentier.com>
Date: Tue, 17 Feb 2026 20:36:17 +0100
Subject: [PATCH 06/11] feat: fetch documentation URLs to build prompt to
 suggest description

---
 .../generate-dataservice-description.post.ts  | 146 +++++++++++++-----
 .../albert/utils/fetch-documentation.ts       |  66 ++++++++
 2 files changed, 172 insertions(+), 40 deletions(-)
 create mode 100644 server/routes/nuxt-api/albert/utils/fetch-documentation.ts

diff --git a/server/routes/nuxt-api/albert/generate-dataservice-description.post.ts b/server/routes/nuxt-api/albert/generate-dataservice-description.post.ts
index 6f39dce2d..39fcd7f62 100644
--- a/server/routes/nuxt-api/albert/generate-dataservice-description.post.ts
+++ b/server/routes/nuxt-api/albert/generate-dataservice-description.post.ts
@@ -1,4 +1,16 @@
+import { DESCRIPTION_MIN_LENGTH } from '~/datagouv-components/src/functions/description'
 import { callAlbertAPI } from './utils/albert-helpers'
+import { fetchDocumentationContent } from './utils/fetch-documentation'
+
+/**
+ * Maximum total prompt length in characters (not tokens).
+ * Covers the full payload sent to the model: system message + user message, where the user
+ * message includes the prompt template and the formatted documentation content (technical
+ * and/or machine) fetched from the URLs. openweight-small/medium: 128k tokens,
+ * openweight-large: 256k tokens; 120k chars ≈ 30k tokens leaves ample headroom. Large API
+ * specs may still hit this limit and trigger a "documentation too long" error.
+ */
+const MAXIMUM_PROMPT_LENGTH = 120_000
 
 export default defineEventHandler(async (event) => {
   const body = await readBody(event)
@@ -11,59 +23,113 @@ export default defineEventHandler(async (event) => {
     })
   }
 
-  const hasTechnical = !!technicalDocumentationUrl?.trim()
-  const hasMachine = !!machineDocumentationUrl?.trim()
-  if (!hasTechnical && !hasMachine) {
+  const technicalUrl = technicalDocumentationUrl?.trim() || ''
+  const machineUrl = machineDocumentationUrl?.trim() || ''
+  if (!technicalUrl && !machineUrl) {
     throw createError({
       statusCode: 400,
       statusMessage: 'Either technical documentation URL or machine documentation URL is required',
     })
   }
 
+  const systemContent = `You are an assistant integrated into data.gouv.fr, the French open data platform.
+Your purpose is to help API producers write clear, comprehensive, and factual descriptions of APIs.
+
+Guidelines:
+- Always respond in French.
+- Your tone is factual, neutral, and accessible to non-experts.
+- Use plain language and clear sentences, avoiding unnecessary technical jargon.
+- Do not make assumptions or add information that is not present in the input.
+- Focus on what the API does, what data it provides, and how it can be used.
+- Always start with a capital letter and end with a period.
+- The goal is to produce informative descriptions that help users understand the API's purpose and capabilities.
+- IMPORTANT: Return ONLY the description text, without quotes or additional punctuation.`
+
+  let technicalContent = ''
+  let machineContent = ''
+
+  const fetchPromises: Promise<void>[] = []
+  if (technicalUrl) {
+    fetchPromises.push(
+      fetchDocumentationContent(technicalUrl)
+        .then((content) => { technicalContent = content })
+        .catch((err) => {
+          throw createError({
+            statusCode: 422,
+            statusMessage: err instanceof Error ? err.message : 'Failed to load technical documentation URL.',
+          })
+        }),
+    )
+  }
+  if (machineUrl) {
+    fetchPromises.push(
+      fetchDocumentationContent(machineUrl)
+        .then((content) => { machineContent = content })
+        .catch((err) => {
+          throw createError({
+            statusCode: 422,
+            statusMessage: err instanceof Error ? err.message : 'Failed to load machine documentation URL.',
+          })
+        }),
+    )
+  }
+
+  await Promise.all(fetchPromises)
+
+  if (!technicalContent && !machineContent) {
+    throw createError({
+      statusCode: 422,
+      statusMessage: 'The documentation URLs returned no usable content. Please check that the links point to readable API documentation (e.g. OpenAPI/Swagger or a technical doc page).',
+    })
+  }
+
+  const documentationParts: string[] = []
+  if (technicalContent) {
+    documentationParts.push(`Technical documentation content:\n\n${technicalContent}`)
+  }
+  if (machineContent) {
+    documentationParts.push(`Machine documentation content (OpenAPI/Swagger):\n\n${machineContent}`)
+  }
+
+  const userContent = `You are asked to generate a description for an API on data.gouv.fr.
+
+Goal:
+→ Write a comprehensive and accessible description of the API.
+→ Focus on what the API does, what data it provides, and its main capabilities.
+→ Mention key endpoints, data types, and use cases if available.
+→ Explain the API's purpose and how it can be used.
+
+Here is the API information:
+
+Title: ${title.trim()}
+
+${documentationParts.join('\n\n---\n\n')}
+
+Output:
+→ A comprehensive description in French (no markdown, no introduction, no labels, no emojis).
+→ The description should be detailed enough to help users understand the API's purpose and capabilities.
+→ Minimum length: at least ${DESCRIPTION_MIN_LENGTH} characters.`
+
+  const totalLength = systemContent.length + userContent.length
+  if (totalLength > MAXIMUM_PROMPT_LENGTH) {
+    throw createError({
+      statusCode: 422,
+      statusMessage: `The documentation is too long to process (${totalLength} characters, maximum ${MAXIMUM_PROMPT_LENGTH}). Please use shorter documentation or provide a single, smaller documentation URL.`,
+    })
+  }
+
   const messages = [
-    {
-      role: 'system',
-      content: `You are an assistant integrated into data.gouv.fr, the French open data platform.\n`
-        + `Your purpose is to help API producers write clear, comprehensive, and factual descriptions of APIs.\n`
-        + `\n`
-        + `Guidelines:\n`
-        + `- Always respond in French.\n`
-        + `- Your tone is factual, neutral, and accessible to non-experts.\n`
-        + `- Use plain language and clear sentences, avoiding unnecessary technical jargon.\n`
-        + `- Do not make assumptions or add information that is not present in the input.\n`
-        + `- Focus on what the API does, what data it provides, and how it can be used.\n`
-        + `- Always start with a capital letter and end with a period.\n`
-        + `- The goal is to produce informative descriptions that help users understand the API's purpose and capabilities.\n`
-        + `- IMPORTANT: Return ONLY the description text, without quotes or additional punctuation.`,
-    },
-    {
-      role: 'user',
-      content: `You are asked to generate a description for an API on data.gouv.fr.\n`
-        + `\n`
-        + `Goal:\n`
-        + `→ Write a comprehensive and accessible description of the API.\n`
-        + `→ Focus on what the API does, what data it provides, and its main capabilities.\n`
-        + `→ Mention key endpoints, data types, and use cases if available.\n`
-        + `→ Explain the API's purpose and how it can be used.\n`
-        + `\n`
-        + `Here is the API information:\n`
-        + `Title: ${title.trim()}\n`
-        + (hasTechnical ? `Technical documentation URL: ${technicalDocumentationUrl.trim()}\n` : '')
-        + (hasMachine ? `Machine documentation URL (OpenAPI/Swagger): ${machineDocumentationUrl.trim()}\n` : '')
-        + `\n`
-        + `Output:\n`
-        + `→ A comprehensive description in French (no markdown, no introduction, no labels, no emojis).\n`
-        + `→ The description should be detailed enough to help users understand the API's purpose and capabilities.`,
-    },
+    { role: 'system', content: systemContent },
+    { role: 'user', content: userContent },
   ]
 
+  // openweight-small: 128k tokens; openweight-medium: 128k tokens; openweight-large: 256k tokens
   const generatedDescription = (await callAlbertAPI(messages, 'openweight-small')).trim()
 
-  const MIN_DESCRIPTION_LENGTH = 50
-  if (generatedDescription.length < MIN_DESCRIPTION_LENGTH) {
+  if (generatedDescription.length < DESCRIPTION_MIN_LENGTH) {
     throw createError({
       statusCode: 422,
-      statusMessage: 'Could not generate a sufficient description from the provided documentation. Please check that the URLs are valid, reachable, and point to API documentation.',
+      statusMessage: 'The model could not generate a sufficient description. Please try again or provide more detailed documentation.',
     })
   }
 
diff --git a/server/routes/nuxt-api/albert/utils/fetch-documentation.ts b/server/routes/nuxt-api/albert/utils/fetch-documentation.ts
new file mode 100644
index 000000000..057dd3332
--- /dev/null
+++ b/server/routes/nuxt-api/albert/utils/fetch-documentation.ts
@@ -0,0 +1,66 @@
+/**
+ * Fetches documentation content from a URL for use in Albert prompts.
+ * Handles HTML (strips tags), trims and normalizes whitespace.
+ */
+
+const FETCH_TIMEOUT_MS = 15_000
+
+/**
+ * Fetches raw content from a URL as text.
+ * @throws Error if request fails, times out, or returns non-2xx
+ */
+export async function fetchDocumentationContent(url: string): Promise<string> {
+  const controller = new AbortController()
+  const timeoutId = setTimeout(() => controller.abort(), FETCH_TIMEOUT_MS)
+
+  try {
+    const response = await $fetch<string>(url, {
+      responseType: 'text',
+      signal: controller.signal,
+      headers: {
+        'Accept': 'text/html, application/json, application/x-yaml, text/yaml, text/plain, */*',
+        'User-Agent': 'data.gouv.fr-dataservice-description-generator/1.0',
+      },
+      ignoreResponseError: false,
+    })
+    clearTimeout(timeoutId)
+    const raw = typeof response === 'string' ? response : String(response)
+    return formatDocumentationContent(raw, url)
+  }
+  catch (error) {
+    clearTimeout(timeoutId)
+    if (error instanceof Error) {
+      if (error.name === 'AbortError') {
+        throw new Error(`Documentation URL could not be loaded within ${FETCH_TIMEOUT_MS / 1000} seconds: ${url}`)
+      }
+      throw new Error(`Failed to load documentation from URL: ${error.message}`)
+    }
+    throw new Error('Failed to load documentation from URL.')
+  }
+}
+
+/**
+ * Trims and formats content: strips HTML tags if present, normalizes whitespace.
+ */
+function formatDocumentationContent(raw: string, _url: string): string {
+  let text = raw.trim()
+  if (!text) {
+    return ''
+  }
+  // If content looks like HTML, strip tags and collapse whitespace
+  if (/<html[\s>]|<body[\s>]|<!DOCTYPE/i.test(text)) {
+    text = text
+      .replace(/<script\b[^>]*>[\s\S]*?<\/script>/gi, '')
+      .replace(/<style\b[^>]*>[\s\S]*?<\/style>/gi, '')
+      .replace(/<[^>]+>/g, ' ')
+      .replace(/\s+/g, ' ')
+      .trim()
+  }
+  else {
+    // Normalize excessive newlines for JSON/YAML/text
+    text = text.replace(/\r\n/g, '\n').replace(/\r/g, '\n')
+    const lines = text.split('\n').map(line => line.trimEnd())
+    text = lines.join('\n').trim()
+  }
+  return text
+}

From 86cfec40bb89aa073291da31e5f6867c6491a01e Mon Sep 17 00:00:00 2001
From: Adrien Carpentier <me@adriencarpentier.com>
Date: Tue, 17 Feb 2026 20:52:11 +0100
Subject: [PATCH 07/11] docs: add comments

---
 .../nuxt-api/albert/generate-dataservice-description.post.ts | 5 ++++-
 1 file changed, 4 insertions(+), 1 deletion(-)

diff --git a/server/routes/nuxt-api/albert/generate-dataservice-description.post.ts b/server/routes/nuxt-api/albert/generate-dataservice-description.post.ts
index 39fcd7f62..15f14446b 100644
--- a/server/routes/nuxt-api/albert/generate-dataservice-description.post.ts
+++ b/server/routes/nuxt-api/albert/generate-dataservice-description.post.ts
@@ -123,7 +123,10 @@ Output:
     { role: 'user', content: userContent },
   ]
 
-  // openweight-small: 128k tokens; openweight-medium: 128k tokens; openweight-large: 256k tokens
+  // Models available for text generation:
+  // - openweight-small (replaces albert-small): 128k tokens
+  // - openweight-medium (replaces albert-large): 128k tokens
+  // - openweight-large: 256k tokens
   const generatedDescription = (await callAlbertAPI(messages, 'openweight-small')).trim()
 
   if (generatedDescription.length < DESCRIPTION_MIN_LENGTH) {

From 512e430f367e3ec45643f32dd59bf702f3f484cc Mon Sep 17 00:00:00 2001
From: Adrien Carpentier <me@adriencarpentier.com>
Date: Tue, 14 Apr 2026 22:22:05 +0200
Subject: [PATCH 08/11] feat: infer content type from the URL extension when
 fetching dataservice documentation

---
 .../albert/utils/fetch-documentation.ts       | 26 ++++++++++++++++---
 1 file changed, 23 insertions(+), 3 deletions(-)

diff --git a/server/routes/nuxt-api/albert/utils/fetch-documentation.ts b/server/routes/nuxt-api/albert/utils/fetch-documentation.ts
index 057dd3332..760477965 100644
--- a/server/routes/nuxt-api/albert/utils/fetch-documentation.ts
+++ b/server/routes/nuxt-api/albert/utils/fetch-documentation.ts
@@ -39,16 +39,36 @@ export async function fetchDocumentationContent(url: string): Promise<string> {
   }
 }
 
+function pathnameExtensionFromUrl(urlString: string): string {
+  try {
+    const { pathname } = new URL(urlString)
+    const lastSegment = pathname.split('/').pop() ?? ''
+    const dot = lastSegment.lastIndexOf('.')
+    if (dot <= 0 || dot === lastSegment.length - 1) {
+      return ''
+    }
+    return lastSegment.slice(dot + 1).toLowerCase()
+  }
+  catch {
+    return ''
+  }
+}
+
 /**
  * Trims and formats content: strips HTML tags if present, normalizes whitespace.
+ * Uses the URL path extension as a hint when the body lacks typical HTML markers.
  */
-function formatDocumentationContent(raw: string, _url: string): string {
+function formatDocumentationContent(raw: string, url: string): string {
   let text = raw.trim()
   if (!text) {
     return ''
   }
-  // If content looks like HTML, strip tags and collapse whitespace
-  if (/<html[\s>]|<body[\s>]|<!DOCTYPE/i.test(text)) {
+  const ext = pathnameExtensionFromUrl(url)
+  const treatAsHtml
+    = ext === 'html'
+      || ext === 'htm'
+      || /<html[\s>]|<body[\s>]|<!DOCTYPE/i.test(text)
+  if (treatAsHtml) {
     text = text
       .replace(/<script\b[^>]*>[\s\S]*?<\/script>/gi, '')
       .replace(/<style\b[^>]*>[\s\S]*?<\/style>/gi, '')

From de43c0770aeb9137ea6116589538cd8473cebdac Mon Sep 17 00:00:00 2001
From: Adrien Carpentier <me@adriencarpentier.com>
Date: Tue, 14 Apr 2026 22:31:52 +0200
Subject: [PATCH 09/11] feat(dataservice): show description feedback link after
 AI suggestion

Made-with: Cursor
---
 components/Dataservices/DescribeDataservice.vue | 6 +++++-
 1 file changed, 5 insertions(+), 1 deletion(-)

diff --git a/components/Dataservices/DescribeDataservice.vue b/components/Dataservices/DescribeDataservice.vue
index 04cb00434..b2854dc39 100644
--- a/components/Dataservices/DescribeDataservice.vue
+++ b/components/Dataservices/DescribeDataservice.vue
@@ -310,7 +310,7 @@
                 </template>
               </BrandedButton>
               <CdataLink
-                v-if="config.public.generateDescriptionFeedbackUrl"
+                v-if="config.public.generateDescriptionFeedbackUrl && hasReceivedAiDescriptionSuggestion"
                 :to="config.public.generateDescriptionFeedbackUrl"
                 target="_blank"
                 class="text-sm text-gray-medium"
@@ -646,6 +646,7 @@ const openConfirmModal = ref(false)
 const showRateLimitingUrl = ref(false)
 const descriptionEditorRefreshKey = ref(0)
 const isGeneratingDescription = ref(false)
+const hasReceivedAiDescriptionSuggestion = ref(false)
 
 const hasTechnicalDocumentationUrl = computed(() => form.value.technical_documentation_url && form.value.technical_documentation_url.trim().length > 0)
 const hasMachineDocumentationUrl = computed(() => form.value.machine_documentation_url && form.value.machine_documentation_url.trim().length > 0)
@@ -717,6 +718,9 @@ async function handleAutoCompleteDescription() {
 
     if (response.description) {
       form.value.description = response.description
+      if (form.value.description.trim().length > 0) {
+        hasReceivedAiDescriptionSuggestion.value = true
+      }
       descriptionEditorRefreshKey.value += 1
       await nextTick()
     }

From 9dd21ca9d27a692687fb5b2154e549c720bdf07d Mon Sep 17 00:00:00 2001
From: Adrien Carpentier <me@adriencarpentier.com>
Date: Tue, 14 Apr 2026 22:38:01 +0200
Subject: [PATCH 10/11] fix(albert): decode HTML entities in fetched
 documentation

Made-with: Cursor
---
 .../albert/utils/fetch-documentation.ts       | 187 +++++++++++++++++-
 1 file changed, 185 insertions(+), 2 deletions(-)

diff --git a/server/routes/nuxt-api/albert/utils/fetch-documentation.ts b/server/routes/nuxt-api/albert/utils/fetch-documentation.ts
index 760477965..3da7fe76a 100644
--- a/server/routes/nuxt-api/albert/utils/fetch-documentation.ts
+++ b/server/routes/nuxt-api/albert/utils/fetch-documentation.ts
@@ -1,10 +1,190 @@
 /**
  * Fetches documentation content from a URL for use in Albert prompts.
- * Handles HTML (strips tags), trims and normalizes whitespace.
+ * Handles HTML (strips tags, decodes character references), trims and normalizes whitespace.
  */
 
 const FETCH_TIMEOUT_MS = 15_000
 
+/**
+ * Common HTML named character references (ASCII names only; accents use exact case).
+ * Numeric &#…; / &#x…; are handled separately for full Unicode coverage.
+ */
+const NAMED_HTML_ENTITIES: Record<string, string> = {
+  amp: '&',
+  lt: '<',
+  gt: '>',
+  quot: '"',
+  apos: '\'',
+  nbsp: '\u00A0',
+  iexcl: '\u00A1',
+  cent: '\u00A2',
+  pound: '\u00A3',
+  curren: '\u00A4',
+  yen: '\u00A5',
+  brvbar: '\u00A6',
+  sect: '\u00A7',
+  uml: '\u00A8',
+  copy: '\u00A9',
+  ordf: '\u00AA',
+  laquo: '\u00AB',
+  not: '\u00AC',
+  shy: '\u00AD',
+  reg: '\u00AE',
+  macr: '\u00AF',
+  deg: '\u00B0',
+  plusmn: '\u00B1',
+  sup2: '\u00B2',
+  sup3: '\u00B3',
+  acute: '\u00B4',
+  micro: '\u00B5',
+  para: '\u00B6',
+  middot: '\u00B7',
+  cedil: '\u00B8',
+  sup1: '\u00B9',
+  ordm: '\u00BA',
+  raquo: '\u00BB',
+  frac14: '\u00BC',
+  frac12: '\u00BD',
+  frac34: '\u00BE',
+  iquest: '\u00BF',
+  Agrave: '\u00C0',
+  Aacute: '\u00C1',
+  Acirc: '\u00C2',
+  Atilde: '\u00C3',
+  Auml: '\u00C4',
+  Aring: '\u00C5',
+  AElig: '\u00C6',
+  Ccedil: '\u00C7',
+  Egrave: '\u00C8',
+  Eacute: '\u00C9',
+  Ecirc: '\u00CA',
+  Euml: '\u00CB',
+  Igrave: '\u00CC',
+  Iacute: '\u00CD',
+  Icirc: '\u00CE',
+  Iuml: '\u00CF',
+  ETH: '\u00D0',
+  Ntilde: '\u00D1',
+  Ograve: '\u00D2',
+  Oacute: '\u00D3',
+  Ocirc: '\u00D4',
+  Otilde: '\u00D5',
+  Ouml: '\u00D6',
+  times: '\u00D7',
+  Oslash: '\u00D8',
+  Ugrave: '\u00D9',
+  Uacute: '\u00DA',
+  Ucirc: '\u00DB',
+  Uuml: '\u00DC',
+  Yacute: '\u00DD',
+  THORN: '\u00DE',
+  szlig: '\u00DF',
+  agrave: '\u00E0',
+  aacute: '\u00E1',
+  acirc: '\u00E2',
+  atilde: '\u00E3',
+  auml: '\u00E4',
+  aring: '\u00E5',
+  aelig: '\u00E6',
+  ccedil: '\u00E7',
+  egrave: '\u00E8',
+  eacute: '\u00E9',
+  ecirc: '\u00EA',
+  euml: '\u00EB',
+  igrave: '\u00EC',
+  iacute: '\u00ED',
+  icirc: '\u00EE',
+  iuml: '\u00EF',
+  eth: '\u00F0',
+  ntilde: '\u00F1',
+  ograve: '\u00F2',
+  oacute: '\u00F3',
+  ocirc: '\u00F4',
+  otilde: '\u00F5',
+  ouml: '\u00F6',
+  divide: '\u00F7',
+  oslash: '\u00F8',
+  ugrave: '\u00F9',
+  uacute: '\u00FA',
+  ucirc: '\u00FB',
+  uuml: '\u00FC',
+  yacute: '\u00FD',
+  thorn: '\u00FE',
+  yuml: '\u00FF',
+  OElig: '\u0152',
+  oelig: '\u0153',
+  Scaron: '\u0160',
+  scaron: '\u0161',
+  Yuml: '\u0178',
+  circ: '\u02C6',
+  tilde: '\u02DC',
+  ensp: '\u2002',
+  emsp: '\u2003',
+  thinsp: '\u2009',
+  zwnj: '\u200C',
+  zwj: '\u200D',
+  lrm: '\u200E',
+  rlm: '\u200F',
+  ndash: '\u2013',
+  mdash: '\u2014',
+  lsquo: '\u2018',
+  rsquo: '\u2019',
+  sbquo: '\u201A',
+  ldquo: '\u201C',
+  rdquo: '\u201D',
+  bdquo: '\u201E',
+  dagger: '\u2020',
+  Dagger: '\u2021',
+  permil: '\u2030',
+  lsaquo: '\u2039',
+  rsaquo: '\u203A',
+  euro: '\u20AC',
+  trade: '\u2122',
+  hellip: '\u2026',
+  bull: '\u2022',
+}
+
+function decodeHtmlEntitiesOnce(text: string): string {
+  return text.replace(
+    /&(#(?:x[0-9a-f]{1,6}|\d{1,7})|[a-zA-Z][a-zA-Z0-9]*);/gi,
+    (full, inner: string) => {
+      if (inner.startsWith('#')) {
+        const body = inner.slice(1)
+        const isHex = body.toLowerCase().startsWith('x')
+        const numStr = isHex ? body.slice(1) : body
+        const radix = isHex ? 16 : 10
+        const cp = Number.parseInt(numStr, radix)
+        if (!Number.isFinite(cp) || cp < 0 || cp > 0x10_FFFF) {
+          return full
+        }
+        try {
+          return String.fromCodePoint(cp)
+        }
+        catch {
+          return full
+        }
+      }
+      const decoded = NAMED_HTML_ENTITIES[inner]
+      return decoded ?? full
+    },
+  )
+}
+
+/**
+ * Decodes HTML character references (named + numeric), repeatedly for chains like &amp;amp;.
+ */
+function decodeHtmlEntities(text: string): string {
+  let decoded = text
+  for (let i = 0; i < 32; i++) {
+    const next = decodeHtmlEntitiesOnce(decoded)
+    if (next === decoded) {
+      break
+    }
+    decoded = next
+  }
+  return decoded
+}
+
 /**
  * Fetches raw content from a URL as text.
  * @throws Error if request fails, times out, or returns non-2xx
@@ -55,7 +235,7 @@ function pathnameExtensionFromUrl(urlString: string): string {
 }
 
 /**
- * Trims and formats content: strips HTML tags if present, normalizes whitespace.
+ * Trims and formats content: strips HTML tags if present, decodes entities, normalizes whitespace.
  * Uses the URL path extension as a hint when the body lacks typical HTML markers.
  */
 function formatDocumentationContent(raw: string, url: string): string {
@@ -75,6 +255,9 @@ function formatDocumentationContent(raw: string, url: string): string {
       .replace(/<[^>]+>/g, ' ')
       .replace(/\s+/g, ' ')
       .trim()
+    text = decodeHtmlEntities(text)
+      .replace(/\s+/g, ' ')
+      .trim()
   }
   else {
     // Normalize excessive newlines for JSON/YAML/text

From 4ca3fb9a4dca1610d095e9d20661f686dc31e93f Mon Sep 17 00:00:00 2001
From: Adrien Carpentier <me@adriencarpentier.com>
Date: Tue, 14 Apr 2026 22:57:01 +0200
Subject: [PATCH 11/11] fix(albert): secure documentation URL fetch (SSRF, size
 cap, redirects)

Made-with: Cursor
---
 .../albert/utils/fetch-documentation.ts       | 157 +++++++++++++--
 server/utils/assert-public-fetch-host.ts      | 187 ++++++++++++++++++
 2 files changed, 332 insertions(+), 12 deletions(-)
 create mode 100644 server/utils/assert-public-fetch-host.ts

diff --git a/server/routes/nuxt-api/albert/utils/fetch-documentation.ts b/server/routes/nuxt-api/albert/utils/fetch-documentation.ts
index 3da7fe76a..bcd734e02 100644
--- a/server/routes/nuxt-api/albert/utils/fetch-documentation.ts
+++ b/server/routes/nuxt-api/albert/utils/fetch-documentation.ts
@@ -3,8 +3,25 @@
  * Handles HTML (strips tags, decodes character references), trims and normalizes whitespace.
  */
 
+import { assertPublicFetchHost } from '~/server/utils/assert-public-fetch-host'
+
 const FETCH_TIMEOUT_MS = 15_000
 
+/**
+ * Maximum bytes read per documentation URL (streaming cap + Content-Length check).
+ * Should stay aligned with the prompt budget in `generate-dataservice-description.post.ts`.
+ */
+export const MAX_DOCUMENTATION_DOWNLOAD_BYTES = 120_000 + 16_384
+
+const MAX_REDIRECTS = 5
+
+const DISALLOWED_URL_MESSAGE = 'Documentation URL is not allowed. Use a public http(s) URL.'
+
+const FETCH_HEADERS = {
+  'Accept': 'text/html, application/json, application/x-yaml, text/yaml, text/plain, */*',
+  'User-Agent': 'cdata',
+} as const
+
 /**
  * Common HTML named character references (ASCII names only; accents use exact case).
  * Numeric &#…; / &#x…; are handled separately for full Unicode coverage.
@@ -144,6 +161,123 @@ const NAMED_HTML_ENTITIES: Record<string, string> = {
   bull: '\u2022',
 }
 
+async function assertSafeDocumentationUrl(urlString: string): Promise<URL> {
+  let parsed: URL
+  try {
+    parsed = new URL(urlString)
+  }
+  catch {
+    throw new Error(DISALLOWED_URL_MESSAGE)
+  }
+  const proto = parsed.protocol.toLowerCase()
+  if (proto !== 'http:' && proto !== 'https:') {
+    throw new Error(DISALLOWED_URL_MESSAGE)
+  }
+  await assertPublicFetchHost(parsed.hostname, DISALLOWED_URL_MESSAGE)
+  return parsed
+}
+
+function parseContentLength(headers: Headers): number | null {
+  const raw = headers.get('content-length')
+  if (raw == null || raw === '') {
+    return null
+  }
+  const n = Number.parseInt(raw, 10)
+  if (!Number.isFinite(n) || n < 0) {
+    return null
+  }
+  return n
+}
+
+async function readBodyWithByteCap(response: Response, maxBytes: number): Promise<string> {
+  const reader = response.body?.getReader()
+  if (!reader) {
+    return ''
+  }
+  const decoder = new TextDecoder('utf-8')
+  let total = 0
+  const chunks: Uint8Array[] = []
+  try {
+    while (true) {
+      const { done, value } = await reader.read()
+      if (done) {
+        break
+      }
+      if (!value?.byteLength) {
+        continue
+      }
+      const nextTotal = total + value.byteLength
+      if (nextTotal > maxBytes) {
+        await reader.cancel().catch(() => {})
+        throw new Error(`Documentation response exceeds maximum size (${maxBytes} bytes).`)
+      }
+      total = nextTotal
+      chunks.push(value)
+    }
+  }
+  catch (err) {
+    await reader.cancel().catch(() => {})
+    throw err
+  }
+  return decoder.decode(Buffer.concat(chunks.map(c => Buffer.from(c))))
+}
+
+async function fetchDocumentationResponse(
+  initialUrl: string,
+  signal: AbortSignal,
+): Promise<{ text: string, finalUrl: string }> {
+  let currentHref = (await assertSafeDocumentationUrl(initialUrl)).href
+  let redirects = 0
+
+  while (true) {
+    const response = await fetch(currentHref, {
+      method: 'GET',
+      redirect: 'manual',
+      signal,
+      headers: FETCH_HEADERS,
+    })
+
+    if (response.status >= 300 && response.status < 400) {
+      if (redirects >= MAX_REDIRECTS) {
+        response.body?.cancel().catch(() => {})
+        throw new Error('Too many redirects when loading documentation URL.')
+      }
+      const location = response.headers.get('location')
+      if (!location) {
+        response.body?.cancel().catch(() => {})
+        throw new Error('Failed to load documentation from URL.')
+      }
+      redirects++
+      let nextUrl: URL
+      try {
+        nextUrl = new URL(location, currentHref)
+      }
+      catch {
+        response.body?.cancel().catch(() => {})
+        throw new Error('Failed to load documentation from URL.')
+      }
+      await assertSafeDocumentationUrl(nextUrl.href)
+      currentHref = nextUrl.href
+      response.body?.cancel().catch(() => {})
+      continue
+    }
+
+    if (!response.ok) {
+      response.body?.cancel().catch(() => {})
+      throw new Error(`Failed to load documentation from URL: HTTP ${response.status}`)
+    }
+
+    const declared = parseContentLength(response.headers)
+    if (declared != null && declared > MAX_DOCUMENTATION_DOWNLOAD_BYTES) {
+      response.body?.cancel().catch(() => {})
+      throw new Error(`Documentation response exceeds maximum size (${MAX_DOCUMENTATION_DOWNLOAD_BYTES} bytes).`)
+    }
+
+    const text = await readBodyWithByteCap(response, MAX_DOCUMENTATION_DOWNLOAD_BYTES)
+    return { text, finalUrl: currentHref }
+  }
+}
+
 function decodeHtmlEntitiesOnce(text: string): string {
   return text.replace(
     /&(#(?:x[0-9a-f]{1,6}|\d{1,7})|[a-zA-Z][a-zA-Z0-9]*);/gi,
@@ -194,24 +328,23 @@ export async function fetchDocumentationContent(url: string): Promise<string> {
   const timeoutId = setTimeout(() => controller.abort(), FETCH_TIMEOUT_MS)
 
   try {
-    const response = await $fetch<string>(url, {
-      responseType: 'text',
-      signal: controller.signal,
-      headers: {
-        'Accept': 'text/html, application/json, application/x-yaml, text/yaml, text/plain, */*',
-        'User-Agent': 'data.gouv.fr-dataservice-description-generator/1.0',
-      },
-      ignoreResponseError: false,
-    })
+    const { text, finalUrl } = await fetchDocumentationResponse(url, controller.signal)
     clearTimeout(timeoutId)
-    const raw = typeof response === 'string' ? response : String(response)
-    return formatDocumentationContent(raw, url)
+    const raw = typeof text === 'string' ? text : String(text)
+    return formatDocumentationContent(raw, finalUrl)
   }
   catch (error) {
     clearTimeout(timeoutId)
     if (error instanceof Error) {
       if (error.name === 'AbortError') {
-        throw new Error(`Documentation URL could not be loaded within ${FETCH_TIMEOUT_MS / 1000} seconds: ${url}`)
+        throw new Error(`Documentation URL could not be loaded within ${FETCH_TIMEOUT_MS / 1000} seconds.`)
+      }
+      if (
+        error.message === DISALLOWED_URL_MESSAGE
+        || error.message.includes('maximum size')
+        || error.message.includes('Too many redirects')
+      ) {
+        throw error
       }
       throw new Error(`Failed to load documentation from URL: ${error.message}`)
     }
diff --git a/server/utils/assert-public-fetch-host.ts b/server/utils/assert-public-fetch-host.ts
new file mode 100644
index 000000000..4e87737d8
--- /dev/null
+++ b/server/utils/assert-public-fetch-host.ts
@@ -0,0 +1,187 @@
+/**
+ * Ensures a hostname is safe for server-initiated HTTP(S) fetches (SSRF mitigation).
+ * Blocks literal private/reserved IPs and hostnames whose DNS answers include any such address.
+ */
+
+import type { LookupAddress } from 'node:dns'
+import { lookup } from 'node:dns/promises'
+import net from 'node:net'
+
+function isForbiddenIPv4(ip: string): boolean {
+  const parts = ip.split('.').map(p => Number(p))
+  // Reject malformed strings (SSRF tricks, octal confusion, etc.): require four decimal octets 0–255.
+  if (parts.length !== 4 || parts.some(n => !Number.isInteger(n) || n < 0 || n > 255)) {
+    return true
+  }
+  const [a, b] = parts
+
+  // 127.0.0.0/8 — loopback (localhost, internal services bound to loopback only).
+  if (a === 127) {
+    return true
+  }
+  // 10.0.0.0/8 — RFC 1918 private class A.
+  if (a === 10) {
+    return true
+  }
+  // 172.16.0.0/12 — RFC 1918 private (172.16.x.x through 172.31.x.x).
+  if (a === 172 && b >= 16 && b <= 31) {
+    return true
+  }
+  // 192.168.0.0/16 — RFC 1918 private class C space.
+  if (a === 192 && b === 168) {
+    return true
+  }
+  // 169.254.0.0/16 — link-local (includes cloud instance metadata endpoints such as 169.254.169.254).
+  if (a === 169 && b === 254) {
+    return true
+  }
+  // 0.0.0.0/8 — "this network", non-routable / ambiguous on many stacks.
+  if (a === 0) {
+    return true
+  }
+  // 224.0.0.0/4 — multicast; 240.0.0.0/4 — reserved / future use. Not suitable targets for outbound fetches.
+  if (a >= 224) {
+    return true
+  }
+  return false
+}
+
+/** RFC 4291 IPv4-mapped IPv6: ::ffff: followed by 32 bits (dotted quad or two hextets). */
+const IPV4_MAPPED_COMPRESSED = '::ffff:'
+/** Same mapping in fully expanded form (no :: compression before ffff). */
+const IPV4_MAPPED_EXPANDED = '0:0:0:0:0:ffff:'
+
+const DOTTED_IPV4 = /^\d{1,3}(?:\.\d{1,3}){3}$/
+const TWO_HEXTETS = /^([0-9a-f]{1,4}):([0-9a-f]{1,4})$/i
+
+function tailAfterIpv4MappedPrefix(normalizedIpv6: string): string | null {
+  if (normalizedIpv6.startsWith(IPV4_MAPPED_COMPRESSED)) {
+    return normalizedIpv6.slice(IPV4_MAPPED_COMPRESSED.length)
+  }
+  if (normalizedIpv6.startsWith(IPV4_MAPPED_EXPANDED)) {
+    return normalizedIpv6.slice(IPV4_MAPPED_EXPANDED.length)
+  }
+  return null
+}
+
+/** Last 32 bits of an IPv4-mapped address given as two 16-bit words (e.g. c0a8 and 0001 → 192.168.0.1). */
+function dottedIpv4FromMappedWords(highU16: number, lowU16: number): string | null {
+  const o1 = (highU16 >> 8) & 0xff
+  const o2 = highU16 & 0xff
+  const o3 = (lowU16 >> 8) & 0xff
+  const o4 = lowU16 & 0xff
+  const dotted = `${o1}.${o2}.${o3}.${o4}`
+  return net.isIP(dotted) === 4 ? dotted : null
+}
+
+/**
+ * If `ipv6` is an IPv4-mapped address in a strict canonical form, returns the embedded IPv4 string.
+ * Only `::ffff:…` and `0:0:0:0:0:ffff:…` prefixes are accepted so unrelated `ffff` labels are ignored.
+ */
+function ipv4MappedEmbedded(ipv6: string): string | null {
+  const norm = ipv6.toLowerCase()
+  const payload = tailAfterIpv4MappedPrefix(norm)
+  if (!payload) {
+    return null
+  }
+  if (DOTTED_IPV4.test(payload)) {
+    return payload
+  }
+  const parts = TWO_HEXTETS.exec(payload)
+  if (!parts) {
+    return null
+  }
+  const high = Number.parseInt(parts[1], 16)
+  const low = Number.parseInt(parts[2], 16)
+  if (!Number.isFinite(high) || !Number.isFinite(low)) {
+    return null
+  }
+  return dottedIpv4FromMappedWords(high, low)
+}
+
+function ipv6FirstHextet(ipv6: string): number {
+  const s = ipv6.toLowerCase()
+  const doubleIdx = s.indexOf('::')
+  if (doubleIdx === -1) {
+    const seg = s.split(':')[0] || '0'
+    return Number.parseInt(seg, 16) || 0
+  }
+  if (doubleIdx === 0) {
+    return 0
+  }
+  const left = s.slice(0, doubleIdx)
+  const first = left.split(':').filter(Boolean)[0] ?? '0'
+  return Number.parseInt(first, 16) || 0
+}
+
+function isForbiddenIPv6(ip: string): boolean {
+  if (net.isIP(ip) !== 6) {
+    return true
+  }
+  const norm = ip.toLowerCase()
+  if (norm === '::1' || norm === '0:0:0:0:0:0:0:1') {
+    return true
+  }
+  const mapped = ipv4MappedEmbedded(norm)
+  if (mapped) {
+    return isForbiddenIPv4(mapped)
+  }
+  const first = ipv6FirstHextet(norm)
+  if (first >= 0xfe80 && first <= 0xfebf) {
+    return true
+  }
+  if (first >= 0xfc00 && first <= 0xfdff) {
+    return true
+  }
+  return false
+}
+
+function isForbiddenHostAddress(address: string, family: number): boolean {
+  if (family === 4) {
+    return isForbiddenIPv4(address)
+  }
+  if (family === 6) {
+    return isForbiddenIPv6(address)
+  }
+  return true
+}
+
+/**
+ * @param hostname - `URL.hostname` (already punycode for IDN)
+ * @param rejectedErrorMessage - thrown when the host must not be fetched
+ */
+export async function assertPublicFetchHost(hostname: string, rejectedErrorMessage: string): Promise<void> {
+  if (!hostname) {
+    throw new Error(rejectedErrorMessage)
+  }
+
+  const literalKind = net.isIP(hostname)
+  if (literalKind === 4) {
+    if (isForbiddenIPv4(hostname)) {
+      throw new Error(rejectedErrorMessage)
+    }
+    return
+  }
+  if (literalKind === 6) {
+    if (isForbiddenIPv6(hostname)) {
+      throw new Error(rejectedErrorMessage)
+    }
+    return
+  }
+
+  let records: LookupAddress[]
+  try {
+    records = await lookup(hostname, { all: true, verbatim: true })
+  }
+  catch {
+    throw new Error(rejectedErrorMessage)
+  }
+  if (!records.length) {
+    throw new Error(rejectedErrorMessage)
+  }
+  for (const r of records) {
+    if (isForbiddenHostAddress(r.address, r.family)) {
+      throw new Error(rejectedErrorMessage)
+    }
+  }
+}