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

---
 .../Dataservices/DescribeDataservice.vue      | 117 +++++++++++++++++-
 components/MarkdownEditor/InternalEditor.vue  |   1 +
 .../generate-dataservice-description.post.ts  | 107 ++++++++++++++++
 3 files changed, 220 insertions(+), 5 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 5229f489a..b52e615e2 100644
--- a/components/Dataservices/DescribeDataservice.vue
+++ b/components/Dataservices/DescribeDataservice.vue
@@ -253,6 +253,7 @@
             :accordion="addDescriptionAccordionId"
           >
             <InputGroup
+              :key="descriptionEditorRefreshKey"
               v-model="form.description"
               class="mb-3"
               :label="$t('Description')"
@@ -270,6 +271,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"
@@ -506,15 +550,16 @@
 </template>
 
 <script setup lang="ts">
-import { BrandedButton, SimpleBanner, TranslationT, type Owned } from '@datagouv/components-next'
-import { RiAddLine } from '@remixicon/vue'
-import { computed } from 'vue'
-import ModalClient from '../Modal/Modal.client.vue'
+import { BrandedButton, SimpleBanner, toast, Tooltip, TranslationT, type Owned } 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<{
@@ -553,6 +598,18 @@ const ownedOptions = computed<Array<Owned>>(() => {
 
 const machineDocumentationUrlWarningMessage = t(`Il est fortement recommandé d'ajouter une documentation OpenAPI ou Swagger à votre API.`)
 const openConfirmModal = ref(false)
+const descriptionEditorRefreshKey = ref(0)
+
+// Track description generation state
+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: [],
@@ -582,6 +639,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 c38c42d6941ef99467bd51e51036f32857016371 Mon Sep 17 00:00:00 2001
From: Adrien Carpentier <me@adriencarpentier.com>
Date: Mon, 16 Feb 2026 17:57:45 +0100
Subject: [PATCH 2/7] 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 b52e615e2..65daee92c 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 85e6926e55cba24e2df3715e00c76a74122a08de Mon Sep 17 00:00:00 2001
From: Adrien Carpentier <me@adriencarpentier.com>
Date: Tue, 17 Feb 2026 15:04:50 +0100
Subject: [PATCH 3/7] 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 921fce6dd61f807d5c95c9dd1ca3d9c98486a95c Mon Sep 17 00:00:00 2001
From: Adrien Carpentier <me@adriencarpentier.com>
Date: Tue, 17 Feb 2026 15:50:42 +0100
Subject: [PATCH 4/7] 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 7046b35e3da377173af7792341d88a246cbafd27 Mon Sep 17 00:00:00 2001
From: Adrien Carpentier <me@adriencarpentier.com>
Date: Tue, 17 Feb 2026 15:57:38 +0100
Subject: [PATCH 5/7] 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 b1e881837..63a7d518b 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 eda88a9c4..4658323ef 100644
--- a/nuxt.config.ts
+++ b/nuxt.config.ts
@@ -125,7 +125,7 @@ export default defineNuxtConfig({
       datasetRestrictedGuideUrl: 'https://guides.data.gouv.fr/guides-open-data/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 458dd9c064885355b8aa58b5a92c1270866ccfda Mon Sep 17 00:00:00 2001
From: Adrien Carpentier <me@adriencarpentier.com>
Date: Tue, 17 Feb 2026 20:36:17 +0100
Subject: [PATCH 6/7] 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 d99abad84d29611abdd62db7dbbc8fc63c6e591f Mon Sep 17 00:00:00 2001
From: Adrien Carpentier <me@adriencarpentier.com>
Date: Tue, 17 Feb 2026 20:52:11 +0100
Subject: [PATCH 7/7] 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) {