Skip to content

AI providers

Jump to bottom
Sanni heruwala edited this page Jun 13, 2026 · 2 revisions

AI providers

RedNotebook AI is pluggable across five providers. Every AI surface in the app (Generate SQL, Summarize result, Optimize, Ask AI, Knowledge chat, Knowledge Studio, Chart auto-suggest, Generate infographic) runs through the configured provider — no mock fallback that silently hides a misconfigured key.

Provider Setup Notes
Mock (default) nothing Offline + deterministic. Great for CI and demos with no API key.
OpenAI AI_PROVIDER=openai, OPENAI_API_KEY=sk-… SDK bundled.
Anthropic AI_PROVIDER=anthropic, ANTHROPIC_API_KEY=sk-ant-… SDK bundled.
Ollama (local) AI_PROVIDER=ollama, OLLAMA_BASE_URL=http://localhost:11434 Fully local. Pair with llama3, qwen2, etc.

The earlier cursor provider was removed in v0.7.20 — Cursor doesn't publish a public chat-completions API, so the provider couldn't do real work. Use OpenAI / Anthropic / Ollama instead.

Configure either via .env (above) or via the admin UI: Settings → Admin → AI with a built-in Test connection button.

Privacy defaults

Out of the box:

  • Sample rows are not sent to AI unless AI_ALLOW_SAMPLE_ROWS=true.
  • PII columns are masked when sample rows are shared.
  • Secrets are stripped from SQL before any provider call.
  • Connection credentials are never forwarded to AI.
  • The AI context mode is set to schema_and_stats by default — schema
    • aggregated stats, no rows.

See docs/ai.md for the full privacy model + per-provider details.

What each AI surface does

  • Generate SQL — Ask AI cell. Turns plain English into a SQL query, schema-grounded with [n]-style table ranking.
  • Optimize SQL — Replaces the cell's SQL with a rewritten faster version (predicate pushdown, column pruning, EXISTS over IN, …).
  • Summarize result — In-cell button after a run. Returns a deep numeric briefing — headline, numbers worth knowing, key findings, distribution shape, anomalies, suggested next questions. All citations come from the actual result, no hallucinated values.
  • Knowledge chat — Multi-turn Q&A over the notebook's knowledge sources. Emits [n] citation chips that scroll to the cited source.
  • Knowledge Studio — One-click generation of Overview / FAQ / Study guide / Suggested follow-up questions across the whole notebook's source set.
  • Chart auto-suggest — Recommends the best chart type for a result.
  • Generate infographic — Renders the result as a designed SVG + HTML infographic ready for PDF / PNG export.

Switching providers without restarting

Save a new key in the admin AI page → the active provider switches immediately. The page surfaces both the configured provider and the active one, so silent fallbacks to mock are visible.

A common gotcha: a provider falls back to mock only when the configured one fails to initialize (missing SDK, bad key). The admin AI page has a Test connection button that probes the configured provider with a trivial prompt — surfacing the exact provider / model / error.

Clone this wiki locally