[MathiasVDA]

Requested by Mathias · project thread

What

A new AI view in the side panel. You open it with the AI button in the editor toolbar or with Ask AI… in Ctrl+K. It has four features:

1. Ask in natural language → SPARQL, with follow-up questions in the same conversation.
2. Fix query for syntax errors and endpoint errors. When a query runs but returns nothing, the button becomes Why no results?. The results error view also gets Fix with AI and Copy for AI buttons.
3. Explain query in plain language.
4. Explain results, which sends at most 50 rows (configurable).

Each query in an answer has four buttons: Use in editor (Ctrl+Z undoes it), Insert, New tab and Copy. Nothing runs automatically.

Where the LLM runs

• OpenAI-compatible API only. That covers OpenAI, Azure, Mistral, OpenRouter, Groq, Ollama and LM Studio.
• Bring your own key: the user enters the base URL, key and model in Settings → AI. Test connection lists the available models.
• Proxy: the embedding page sets ai.proxy (url, label, model, headers, withCredentials, privacyUrl). The developer guide includes a minimal Express proxy.
• No service: every action becomes Copy for AI. It copies a ready-made prompt, and the panel shows the copied text.
• ai: { enabled: false } removes all of it. allowOwnKey: false allows the proxy only.

Privacy

• Nothing is sent until the user clicks.
• Before the first request to a host, a notice lists exactly what will be sent and where, and what is never sent. The user can choose "Don't ask again" per host.
• Every answer has a What was sent section with the exact request, plus the service, model and token count.
• The API key is stored under its own localStorage key (<persistenceId>_ai). It is not part of the persisted config, so export and share links never contain it. A test checks this.
• Endpoint credentials are never put in a prompt.
• Answers are rendered as Markdown by building DOM nodes, never as HTML.

Endpoint context and check queries

• Ask and Fix send the endpoint's most used classes and properties with their counts, up to 150 of each, taken from endpointDescribe.getAutocompleteTerms() (the same source as autocomplete). They also send the prefixes in use.
• The model can call a run_sparql tool for up to 5 check queries per question. Only SELECT and ASK are allowed, the LIMIT is forced to 20 or less, and the query runs through tab.runBackgroundQuery with the tab's auth.
• Each check query and its result is shown in the answer. Users can switch check queries off.
• If a service rejects tools, the request is retried without them.

Architecture

• New packages/yasgui/src/ai/ folder:
  • AiAssistant: tasks, consent and the tool loop
  • AiPanel: the side panel view
  • AiSettingsForm
  • openaiClient
  • prompts
  • schemaContext
  • checkQuery
  • markdown
  • aiSettings
• yasr host API:
  • hostApi.assistant
  • yasr.askAssistant({ title, prompt, context }), so plugins (chart, explain…) can add their own "Explain this" action without handling keys
  • an assistant config hook that the error view uses
• yasqe: yasqe.syntaxError stores the first syntax error.
• SidePanel.addView(..., { before }) keeps the view order Queries / Endpoint / AI.
• The settings modal tabs now switch by data-tab instead of by index.

Docs and tests

• User guide: new "AI Assistant" section plus updates to Side Panel, Settings, Error Plugin and Troubleshooting.
• Developer guide: "AI Assistant Configuration", the proxy contract and example, the privacy notes, yasgui.aiAssistant, and the plugin host API.
• Changeset added.
• 20 new unit tests and 5 new browser tests, which use a mocked OpenAI service and endpoint. The full suite passes locally (1733 unit, 68 browser).
• Not tested against a real OpenAI/Mistral/Ollama service from the cloud environment.

Screenshots are in the project files (ai-support/screenshots/).

---

Generated by Claude Code