fn_registry/dev/issues/0080-tables-llm-api.md

id, title, status, priority, created, related_components

id	title	status	priority	created	related_components
0080	tables playground — LLM API "Ask AI" (fase 11)	pending	medium	2026-05-12	cpp/apps/primitives_gallery/playground/tables

Contexto

Fase 11 del roadmap del tables playground. El user escribe en lenguaje natural una pregunta sobre los datos ("show me top 10 langs by total size"). El LLM recibe el TQL actual + schema + pregunta, devuelve nuevo TQL. App aplica via tql::apply y renderiza.

Cambios

1. UI

• Boton "Ask AI" en toolbar (al lado de "+ Viz").
• Modal con:
  • InputText multiline para la pregunta.
  • Boton "Send" + spinner durante la llamada.
  • Diff side-by-side: TQL actual vs TQL propuesto (texto con highlight).
  • Botones "Apply" / "Reject" / "Edit before apply".

2. Backend LLM

• Provider: Anthropic Claude (API key desde pass anthropic/api-key).
• Endpoint: https://api.anthropic.com/v1/messages.
• Model: claude-sonnet-4-6 por defecto. Configurable via env FN_LLM_MODEL.
• Cliente HTTP: cURL via popen (sin deps nuevas) o libcurl si ya esta linkada.
• Prompt template incluye:
  • Esquema TQL (de docs/TQL.md).
  • Cols disponibles del stage 0 (name, type) + cols joinables.
  • Funciones Lua disponibles (de lua_engine).
  • TQL actual.
  • Pregunta del user.
• Response: extraer lua block del markdown, strip prose.

3. Validacion + safety

• Antes de aplicar: tql::apply con dry-run (parsea sin mutar State). Si fail, mostrar error + boton "Ask AI again with this error".
• Lua sandbox ya cubre side effects en formulas — el TQL en si es declarativo, no ejecuta nada peligroso.

4. Streaming

• Stream tokens via SSE (stream=true en Anthropic API).
• Mostrar texto en vivo en el modal.
• Cuando termina, parsear lua block final.

5. Persistencia conversation

• UiState guarda lista de turns (pregunta + TQL propuesto + resultado apply).
• "Ask AI" siguiente turn incluye history previa.
• Boton "Reset chat" limpia.
• NO persistido en TQL (es UI state).

6. Coste / rate limit

• Mostrar tokens estimados antes de enviar (rough char count / 4).
• Cap input a 8000 tokens.
• Error handling: 429 / 5xx -> mensaje + reintentar.

Tests

• Mockear HTTP response con cURL stub.
• Test: prompt build incluye schema + TQL + pregunta en formato esperado.
• Test: response parse extrae lua block correctamente.
• Test: tql::apply sobre output del LLM funciona end-to-end con dataset sintetico.

No-objetivos

• Generacion de visualizaciones nuevas via LLM (la viz la elige TQL display, suficiente).
• Acciones del LLM mas alla de modificar TQL (sin acceso a I/O del sistema).
• Multi-provider (OpenAI / local) — fase futura. Hardcode Anthropic primero.