Skip to content

feat: suggest dataservice description#924

Open
bolinocroustibat wants to merge 11 commits intomainfrom
feat/suggest-dataservice-description
Open

feat: suggest dataservice description#924
bolinocroustibat wants to merge 11 commits intomainfrom
feat/suggest-dataservice-description

Conversation

@bolinocroustibat
Copy link
Copy Markdown
Contributor

@bolinocroustibat bolinocroustibat commented Feb 5, 2026

Add AI-powered description suggestion for dataservices (external APIs) via the Albert API.

When editing a dataservice, a "Suggérer une description" button generates a French description. The button is enabled only when:

  • title is filled
  • at least one of these is filled: technical documentation URL or machine documentation URL (OpenAPI/Swagger)

Changes:

  • DescribeDataservice.vue: suggestion button with loading/disabled states and tooltip; enabled when title + at least one doc URL are present
  • generate-dataservice-description.post.ts (new): Nitro endpoint that fetches documentation from the given URLs, inlines it into the prompt, and calls Albert API. Requires title and at least one of technicalDocumentationUrl or machineDocumentationUrl
  • fetch-documentation.ts (new): utility to fetch doc content from URLs (HTML stripped, JSON/YAML as-is; 15s timeout, 120k char cap)

EDIT (2026-02-17):

  • generate-dataservice-description.post.ts uses shared callAlbertAPI (albert-helpers), same pattern as other Albert endpoints.
  • Doc content is now fetched from the URLs and inlined into the prompt (new fetch-documentation.ts: HTML stripped, JSON/YAML as-is, 15s timeout, 120k char cap). Previously only the URLs were sent.
  • Fixed 422 "description too short" being rethrown as 500.
  • Removed redundant validateAlbertConfig from helper and all Albert endpoints.

@bolinocroustibat bolinocroustibat self-assigned this Feb 5, 2026
@bolinocroustibat bolinocroustibat marked this pull request as draft February 5, 2026 16:30
@bolinocroustibat bolinocroustibat force-pushed the feat/suggest-dataservice-description branch 2 times, most recently from 550dbdb to df4c507 Compare February 16, 2026 16:48
@bolinocroustibat bolinocroustibat marked this pull request as ready for review February 16, 2026 16:49
Comment thread server/routes/nuxt-api/albert/generate-dataservice-description.post.ts Outdated
Comment thread components/Dataservices/DescribeDataservice.vue Outdated
+ `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` : '')
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Design: The openweight-small model can't browse these URLs — it only sees the URL strings. The prompt asks to "mention key endpoints, data types, and use cases" but the model has no access to the actual documentation content. This will likely produce hallucinated descriptions about specific endpoints.

Possible alternatives:

  • Fetch the documentation content server-side and include it in the prompt
  • Use createAgentCompletion if the Albert agent API supports web browsing
  • Adjust the prompt to only describe what can be reasonably inferred from a title + URL patterns

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Damned I was tricked by the hallucinations of the models who made me think it was indeed browsing the URLs! Good call.

I would go for option 1, trying to fetch and format the data from those URLs, with some guardrails regarding the maximum size of the prompt and what those models should/could have as a long prompt. I'll suggest a commit soon.

Comment thread components/MarkdownEditor/InternalEditor.vue Outdated
Comment thread server/routes/nuxt-api/albert/generate-dataservice-description.post.ts Outdated
Comment thread server/routes/nuxt-api/albert/generate-dataservice-description.post.ts Outdated
@bolinocroustibat bolinocroustibat force-pushed the feat/suggest-dataservice-description branch from 7c4bf25 to 3c20ce2 Compare February 17, 2026 12:51
@bolinocroustibat bolinocroustibat moved this from 🛠 Doing to 👀 Review in 🚀 Produit data.gouv.fr Feb 17, 2026
@bolinocroustibat bolinocroustibat force-pushed the feat/suggest-dataservice-description branch 3 times, most recently from 494af3c to ba1f4fa Compare February 17, 2026 19:53
Comment thread server/routes/nuxt-api/albert/utils/fetch-documentation.ts Outdated
Comment thread server/routes/nuxt-api/albert/utils/fetch-documentation.ts
Comment thread server/routes/nuxt-api/albert/utils/fetch-documentation.ts Outdated
Comment thread components/Dataservices/DescribeDataservice.vue
@bolinocroustibat bolinocroustibat force-pushed the feat/suggest-dataservice-description branch from ba1f4fa to d99abad Compare February 23, 2026 14:17
bolinocroustibat and others added 7 commits April 14, 2026 22:18
Remove explicit ref import as it's auto-imported by Nuxt

Co-authored-by: Cursor <cursoragent@cursor.com>
- 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>
…ateDescriptionFeedbackUrl

Co-authored-by: Cursor <cursoragent@cursor.com>
@bolinocroustibat bolinocroustibat force-pushed the feat/suggest-dataservice-description branch from d99abad to 86cfec4 Compare April 14, 2026 20:19
@bolinocroustibat bolinocroustibat force-pushed the feat/suggest-dataservice-description branch from 98d8896 to f02323a Compare April 14, 2026 20:55
@bolinocroustibat bolinocroustibat force-pushed the feat/suggest-dataservice-description branch from f02323a to 4ca3fb9 Compare April 14, 2026 20:57
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

Status: 👀 Review

Development

Successfully merging this pull request may close these issues.

2 participants