sqlrite 0.1.21__tar.gz → 0.1.23__tar.gz

{sqlrite-0.1.21 → sqlrite-0.1.23}/Cargo.lock

@@ -3804,7 +3804,7 @@ dependencies = [
 
 [[package]]
 name = "sqlrite-ask"
-version = "0.1.21"
+version = "0.1.23"
 dependencies = [
  "serde",
  "serde_json",
@@ -3815,7 +3815,7 @@ dependencies = [
 
 [[package]]
 name = "sqlrite-desktop"
-version = "0.1.21"
+version = "0.1.23"
 dependencies = [
  "serde",
  "serde_json",
@@ -3827,7 +3827,7 @@ dependencies = [
 
 [[package]]
 name = "sqlrite-engine"
-version = "0.1.21"
+version = "0.1.23"
 dependencies = [
  "clap",
  "env_logger",
@@ -3844,15 +3844,17 @@ dependencies = [
 
 [[package]]
 name = "sqlrite-ffi"
-version = "0.1.21"
+version = "0.1.23"
 dependencies = [
  "cbindgen",
+ "serde",
+ "serde_json",
  "sqlrite-engine",
 ]
 
 [[package]]
 name = "sqlrite-nodejs"
-version = "0.1.21"
+version = "0.1.23"
 dependencies = [
  "napi",
  "napi-build",
@@ -3862,7 +3864,7 @@ dependencies = [
 
 [[package]]
 name = "sqlrite-python"
-version = "0.1.21"
+version = "0.1.23"
 dependencies = [
  "pyo3",
  "sqlrite-engine",

{sqlrite-0.1.21 → sqlrite-0.1.23}/Cargo.toml

@@ -27,7 +27,7 @@ resolver = "3"
 # `package =` key so the import name stays `sqlrite` internally:
 #     sqlrite = { package = "sqlrite-engine", path = "…" }
 name = "sqlrite-engine"
-version = "0.1.21"
+version = "0.1.23"
 authors = ["Joao Henrique Machado Silva <joaoh82@gmail.com>"]
 edition = "2024"
 rust-version = "1.85"

{sqlrite-0.1.21 → sqlrite-0.1.23}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sqlrite
-Version: 0.1.21
+Version: 0.1.23
 Classifier: Development Status :: 3 - Alpha
 Classifier: Intended Audience :: Developers
 Classifier: License :: OSI Approved :: MIT License

{sqlrite-0.1.21 → sqlrite-0.1.23}/desktop/package.json

@@ -1,7 +1,7 @@
 {
   "name": "sqlrite-desktop-frontend",
   "private": true,
-  "version": "0.1.21",
+  "version": "0.1.23",
   "type": "module",
   "scripts": {
     "dev": "vite",

{sqlrite-0.1.21 → sqlrite-0.1.23}/docs/phase-7-plan.md

@@ -253,8 +253,8 @@ let rows = conn.execute(&resp.sql)?;
 - **✅ 7g.2 — REPL `.ask` + structural refactor.** New `MetaCommand::Ask(String)` variant + `handle_ask` that calls `sqlrite::ask::ask_with_database`, prints the generated SQL + rationale, prompts `Run? [Y/n] ` via rustyline (Ctrl-C / EOF map to skip — paranoid default for LLM-generated SQL), and pipes through `process_command` if confirmed. The thin REPL part itself is ~120 LOC. **Required a bigger structural fix that 7g.1 didn't anticipate:** wiring the binary to call into `sqlrite-ask` created a cargo cycle (`sqlrite-engine[bin] → sqlrite-ask → sqlrite-engine[lib]`) that even `optional = true` doesn't break — cargo's static cycle detection includes all potential edges. Resolution: flipped the dep direction. `sqlrite-ask` is now pure (no engine dep, canonical API takes a `&str` schema dump + `&str` question). Schema introspection + the `Connection`/`Database` integration (`ConnectionAskExt`, `ask`, `ask_with_database`, `ask_with_provider`, `ask_with_database_and_provider`) moved into `sqlrite-engine` itself under a new `ask` feature (default-on for the CLI binary, off for `--no-default-features` / WASM). Public API for end users is unchanged in spirit: `use sqlrite::{Connection, ConnectionAskExt}` instead of `use sqlrite_ask::ConnectionAskExt`. Net effect — `sqlrite-ask` shrunk + got easier to test in isolation; the engine carries the integration weight, scoped behind a feature flag so SDK / WASM / Tauri builds opt in. 30+ tests pass on both sides (sqlrite-ask: 20 unit + 4 integration; engine ask module: 6 schema + 3 .ask parser).
 - **✅ 7g.3 — Desktop UI "Ask…" button.** New "Ask…" button in the editor toolbar plus a slide-in composer panel above the editor surface (question textarea + "Generate SQL" button + explanation slot). Submitting calls a new `ask_sql` Tauri command that reads `AskConfig::from_env()` server-side, locks the engine's `Database`, calls `sqlrite::ask::ask_with_database` (so the schema dump + LLM HTTP call stay in the Rust backend — the API key never crosses into the webview). Generated SQL drops into the editor textarea for the user to review + Run themselves; the rationale shows in the panel; an empty SQL response (model declined) surfaces the model's explanation in the same slot. Cmd/Ctrl+Enter in the question textarea submits; Esc closes. ~110 LOC of Svelte + ~30 LOC of Rust + ~85 LOC of CSS. As a side benefit, ergonomic re-exports added on `sqlrite::ask::*` (`AskConfig`, `AskResponse`, `AskError`, `Provider`, etc.) so library callers don't have to add `sqlrite-ask` as a direct dep alongside the engine.
 - **✅ 7g.4 — Python SDK `conn.ask` / `ask_run` / `AskConfig`.** PyO3 wrappers over `sqlrite::ask::*`. New `Connection.ask(question, config=None)` returns an `AskResponse` (`.sql` / `.explanation` / `.usage` with cache-hit fields). `Connection.ask_run(question, config=None)` generates SQL then immediately executes via cursor — convenience for one-shot scripts/notebooks. `Connection.set_ask_config(cfg)` stashes a per-connection config. `AskConfig(api_key=..., model=..., max_tokens=..., cache_ttl=..., base_url=...)` constructor + `AskConfig.from_env()` static method. Three precedence layers: per-call > per-connection > env > defaults. `AskConfig.__repr__` and `AskResponse.__repr__` deliberately omit the API key — printing config in logs won't leak it. Empty SQL response (model declined) on `ask_run()` raises `SQLRiteError` with the model's explanation rather than executing the empty string. ~370 LOC of Rust binding + 415 LOC of pytest tests across 20 cases (config construction, env-var parsing, error paths, full happy-path through a localhost HTTP mock built on Python's stdlib `http.server`). README rewritten — three precedence layers explained, defaults enumerated, errors documented.
-- **7g.5 — Node.js SDK (~80 LOC).** Same shape via napi-rs. `db.ask(question)` / `db.askRun(question)`.
-- **7g.6 — Go SDK (~80 LOC).** cgo wrapper. `sqlrite.Ask(db, question)` returns `(AskResponse, error)`.
+- **✅ 7g.5 — Node.js SDK `db.ask` / `askRun` / `AskConfig`.** napi-rs wrappers over `sqlrite::ask::*`. `db.ask(question, config?)` returns `AskResponse { sql, explanation, usage }`. `db.askRun(question, config?)` generates SQL then immediately executes — returns rows directly (`Array<Object>`); throws on empty-SQL response (model declined) with the model's explanation, rather than executing the empty string. `db.setAskConfig(config)` stashes per-connection config (pass `null` to clear). `new AskConfig({apiKey, model, maxTokens, cacheTtl, baseUrl})` constructor + `AskConfig.fromEnv()` static. Three precedence layers: per-call > per-connection > env > defaults — same shape as the Python SDK, with idiomatic JS option-object instead of kwargs (camelCase: `maxTokens`/`cacheTtl`/`baseUrl`). `AskConfig.toString()` deliberately omits the API key value (shows `<set>` or `null`). Auto-generated TypeScript types in `index.d.ts` — `AskConfigOptions`, `AskResponse`, `AskUsage` interfaces. ~370 LOC of Rust binding + 380 LOC of node:test cases (30 total — 19 new for ask plus the original 11). Mock HTTP server runs in a `worker_thread` so napi-rs's blocking sync POST on the main thread doesn't deadlock the response — same insight as Python's GIL deadlock, different mitigation. README rewritten — three-layer precedence, defaults table, error behavior, what AskResponse carries, the no-key-in-toString guarantee, full TypeScript shapes.
+- **✅ 7g.6 — Go SDK `sqlrite.Ask` / `AskRun` / `AskConfig`.** cgo wrapper. New FFI function `sqlrite_ask(conn, question, config_json, *out)` accepts the AskConfig as a JSON string (smaller, more extensible C ABI than 6+ separate parameters) and returns `{sql, explanation, usage}` as JSON. Go side: `Ask(db *sql.DB, question, *AskConfig) (*AskResponse, error)` plus `AskContext(ctx, ...)` for context-aware connection-pool acquisition, `AskRun(db, question, *AskConfig) (*sql.Rows, error)` (and `AskRunContext`) that generates and executes in one call. `AskConfigFromEnv()` reads `SQLRITE_LLM_*`. `AskConfig.String()` deliberately omits the API key value (shows `<set>` or `<unset>`). Plumbs through `db.Conn(ctx).Raw()` to reach the underlying `*conn`'s opaque `*C.SqlriteConnection` handle. ~310 LOC of Go + ~200 LOC of Rust FFI extension + 380 LOC of Go tests (11 cases — config defaults / from-env / overrides / invalid-max-tokens, error paths for nil-db / missing-key / closed-db, full happy-path through `httptest.Server`, AskRun execution, empty-SQL declined-model, 4xx error surfacing). `httptest.Server` runs on a Go runtime goroutine, so unlike the Python (GIL) and Node (event-loop) SDKs there's no deadlock concern with synchronous cgo calls — Go test setup is the cleanest of the three. README rewritten — three-layer precedence, context-aware variants documented, errors enumerated, AskResponse type signatures shown.
 - **7g.7 — WASM SDK (~150 LOC, see Q9).** Either skipped, or implemented with a JS-side fetch hook (the WASM binary calls back into JS to make the HTTP request, since `reqwest`'s wasm32 story is messy and CORS/keys are a separate problem).
 - **7g.8 — MCP server `ask` tool (~50 LOC).** Wires the existing tool framework from 7h to a single new tool that calls into `sqlrite-ask`.
 

{sqlrite-0.1.21 → sqlrite-0.1.23}/docs/roadmap.md

@@ -476,7 +476,7 @@ Approved sub-phases (Q1–Q10 resolved):
 - **✅ 7d — HNSW ANN index** — three PRs: 7d.1 (algorithm w/ recall@10 ≥ 0.95), 7d.2 (SQL integration + query optimizer), 7d.3 (persistence + DELETE/UPDATE rebuild). `CREATE INDEX … USING hnsw (col)`; fixed defaults `M=16, ef_construction=200, ef_search=50` (Q2). New `KIND_HNSW` cell tag.
 - **✅ 7e — JSON column type + path queries** — `JSON` data type stored as canonical text (validated via `serde_json::from_str` at INSERT/UPDATE time; SQLite-JSON1-style — Q3 scope correction since bincode was removed in Phase 3c). Functions: `json_extract` / `json_type` / `json_array_length` / `json_object_keys`. Path subset supports `$`, `.key`, `[N]`, chained. `json_object_keys` returns a JSON-array text rather than a table-valued result (no set-returning functions in the executor yet).
 - **7f — ~~Full-text search with BM25~~** — **deferred to Phase 8** (Q1).
-- **7g — `ask()` API across the product surface** — natural-language → SQL via Anthropic API (Q4), Anthropic-first then OpenAI + Ollama follow-ups. Foundational **✅ 7g.1** introduces a new `sqlrite-ask` crate (Q10 — separate crate, not a feature flag) — `ask_with_schema()` over `&str` inputs (Phase 7g.2 made it pure — see retrospective below), sync `ureq` POST to `/v1/messages`, schema-aware prompt with prompt-caching on the schema dump (Sonnet 4.6 default; configurable). **✅ 7g.2** wires the REPL's `.ask` meta-command (`MetaCommand::Ask(String)` + confirm-and-run UX) and adds the `sqlrite::ask` module on the engine side (gated under a new `ask` feature) carrying `ConnectionAskExt` + the schema introspection helper. **✅ 7g.3** adds the desktop "Ask…" composer (slide-in panel above the editor; Tauri command runs the LLM call in the Rust backend so the API key stays out of the webview). **✅ 7g.4** ships the Python SDK surface — `conn.ask(question, config=None)` returns an `AskResponse(.sql, .explanation, .usage)`; `conn.ask_run()` adds the one-shot generate-and-execute convenience; `AskConfig` carries the three-layer precedence (per-call > per-connection > env > defaults). Per-product adapters in 7g.5-7g.8 cover Node.js, Go, WASM (JS-callback shape per Q9), and the MCP `ask` tool — and fold in the SDK README catch-up for VECTOR / JSON / HNSW capabilities along the way.
+- **7g — `ask()` API across the product surface** — natural-language → SQL via Anthropic API (Q4), Anthropic-first then OpenAI + Ollama follow-ups. Foundational **✅ 7g.1** introduces a new `sqlrite-ask` crate (Q10 — separate crate, not a feature flag) — `ask_with_schema()` over `&str` inputs (Phase 7g.2 made it pure — see retrospective below), sync `ureq` POST to `/v1/messages`, schema-aware prompt with prompt-caching on the schema dump (Sonnet 4.6 default; configurable). **✅ 7g.2** wires the REPL's `.ask` meta-command (`MetaCommand::Ask(String)` + confirm-and-run UX) and adds the `sqlrite::ask` module on the engine side (gated under a new `ask` feature) carrying `ConnectionAskExt` + the schema introspection helper. **✅ 7g.3** adds the desktop "Ask…" composer (slide-in panel above the editor; Tauri command runs the LLM call in the Rust backend so the API key stays out of the webview). **✅ 7g.4** ships the Python SDK surface — `conn.ask(question, config=None)` returns an `AskResponse(.sql, .explanation, .usage)`; `conn.ask_run()` adds the one-shot generate-and-execute convenience; `AskConfig` carries the three-layer precedence (per-call > per-connection > env > defaults). **✅ 7g.5** ships the Node.js SDK surface — `db.ask(question, config?)`, `db.askRun(question, config?)`, `db.setAskConfig(cfg)`, `new AskConfig({apiKey, model, maxTokens, cacheTtl, baseUrl})` + `AskConfig.fromEnv()`. Same three-layer precedence; idiomatic JS camelCase option-object. **✅ 7g.6** ships the Go SDK surface via cgo — `sqlrite.Ask(db, q, *AskConfig)` / `AskRun(...)` plus `AskContext`/`AskRunContext` for context-aware variants. The FFI grew one new C function (`sqlrite_ask`) that takes the config as a JSON string and returns the response as JSON — smaller, more extensible ABI than plumbing 6+ struct fields across cgo. Per-product adapters in 7g.7-7g.8 cover WASM (JS-callback shape per Q9) and the MCP `ask` tool — and fold in the SDK README catch-up for VECTOR / JSON / HNSW capabilities along the way.
 - **7h — MCP server adapter** — new `sqlrite-mcp` binary, hand-rolled JSON-RPC + tool framework (Q5).
 
 Total scope budget: ~3-4 kLOC of new Rust across the wave. Each sub-phase ships as its own PR + release wave through the Phase 6 pipeline. The Phase 7 wave will likely close out **v0.2.0** (first minor bump after the 0.1.x Phase 6 cycle). Two new product lines added to lockstep versioning: `sqlrite-ask` and `sqlrite-mcp`.

{sqlrite-0.1.21 → sqlrite-0.1.23}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "maturin"
 
 [project]
 name = "sqlrite"
-version = "0.1.21"
+version = "0.1.23"
 description = "Python bindings for SQLRite — a small, embeddable SQLite clone written in Rust."
 authors = [{ name = "Joao Henrique Machado Silva", email = "joaoh82@gmail.com" }]
 license = { text = "MIT" }

{sqlrite-0.1.21 → sqlrite-0.1.23}/sdk/go/README.md

@@ -123,23 +123,90 @@ fmt.Println(name) // alice
 
 > `json_object_keys` returns a JSON-array text rather than a table-valued result (set-returning functions aren't supported yet).
 
-### Natural-language → SQL (Phase 7g — *coming soon*)
+### Natural-language → SQL (Phase 7g.6)
 
-The Phase 7g.2-7g.8 wave adds `sqlrite.Ask(db, ...)` / `sqlrite.AskRun(db, ...)` that wrap the new [`sqlrite-ask`](https://crates.io/crates/sqlrite-ask) Rust crate through cgo. Today it's available only from Rust; the Go wrapper lands in 7g.6 and will look like:
+`sqlrite.Ask(db, question, *AskConfig)` generates SQL via the configured LLM provider (Anthropic by default). `sqlrite.AskRun(db, question, *AskConfig)` is the convenience that calls `Ask` then immediately executes — returns `*sql.Rows` ready for iteration.
 
 ```go
-// 7g.6 preview — not yet released
-import "github.com/joaoh82/rust_sqlite/sdk/go"
+import (
+    "database/sql"
+    sqlrite "github.com/joaoh82/rust_sqlite/sdk/go"
+)
 
-cfg := sqlrite.AskConfigFromEnv()                // SQLRITE_LLM_API_KEY etc.
-resp, err := sqlrite.Ask(db, "How many users are over 30?", cfg)
-fmt.Println(resp.SQL)         // "SELECT COUNT(*) FROM users WHERE age > 30"
-fmt.Println(resp.Explanation) // "Counts users over the age threshold."
+db, _ := sql.Open("sqlrite", "foo.sqlrite")
+db.Exec(`CREATE TABLE users (id INTEGER PRIMARY KEY, name TEXT, age INTEGER)`)
+db.Exec(`INSERT INTO users (name, age) VALUES ('alice', 30)`)
+
+// Path 1: nil cfg → reads SQLRITE_LLM_API_KEY etc. from env.
+resp, err := sqlrite.Ask(db, "How many users are over 30?", nil)
+fmt.Println(resp.SQL)          // "SELECT COUNT(*) FROM users WHERE age > 30"
+fmt.Println(resp.Explanation)  // "Counts users older than thirty."
+
+// Path 2: explicit per-call config.
+cfg := &sqlrite.AskConfig{
+    APIKey:    "sk-ant-...",
+    Model:     "claude-haiku-4-5",
+    MaxTokens: 512,
+    CacheTTL:  "1h",          // "5m" (default) | "1h" | "off"
+}
+resp, _ := sqlrite.Ask(db, "list users over 30", cfg)
+
+// Caller decides whether to run the SQL — Ask does NOT auto-execute.
+rows, _ := db.Query(resp.SQL)
+defer rows.Close()
 
-// Convenience:
-rows, _ := sqlrite.AskRun(db, "How many users are over 30?", cfg)
+// Or one-shot:
+rows, _ := sqlrite.AskRun(db, "list users", nil)
 ```
 
+#### Configuration
+
+Three precedence layers — explicit-wins:
+
+1. **Per-call config**: `sqlrite.Ask(db, "...", &sqlrite.AskConfig{APIKey: "..."})`
+2. **Environment vars**: `SQLRITE_LLM_PROVIDER` / `_API_KEY` / `_MODEL` / `_MAX_TOKENS` / `_CACHE_TTL` — picked up automatically when cfg is nil
+3. **Built-in defaults**: `anthropic` / `claude-sonnet-4-6` / `1024` / `5m`
+
+The config flows across cgo as a JSON string (`"api_key"`, `"model"`, etc. — snake_case, matching the FFI ABI). Adding fields later is non-breaking; older bindings ignore unknown JSON keys.
+
+#### Context-aware variants
+
+```go
+// Pass a context for connection-pool acquisition. The HTTP call to
+// the LLM is currently uncancellable (the FFI doesn't expose a
+// cancel hook yet); the ctx flows to db.Conn(ctx) and to the
+// db.QueryContext call inside AskRunContext.
+resp, err := sqlrite.AskContext(ctx, db, "list users", cfg)
+rows, err := sqlrite.AskRunContext(ctx, db, "list users", cfg)
+```
+
+#### Defaults
+
+`Provider="anthropic"`, `Model="claude-sonnet-4-6"`, `MaxTokens=1024`, `CacheTTL="5m"`. The schema dump goes inside an Anthropic prompt-cache breakpoint — repeat asks against the same DB hit the cache (verify via `resp.Usage.CacheReadInputTokens`).
+
+#### Errors
+
+Missing API key → `error` with message `"sqlrite: ask: missing API key (set SQLRITE_LLM_API_KEY ...)"`. API errors (4xx/5xx) include the status code + Anthropic's structured error type+message. `AskRun()` on an empty SQL response (model declined) returns an error rather than executing the empty string.
+
+#### What `AskResponse` carries
+
+```go
+type AskResponse struct {
+    SQL         string
+    Explanation string
+    Usage       AskUsage
+}
+
+type AskUsage struct {
+    InputTokens              uint64
+    OutputTokens             uint64
+    CacheCreationInputTokens uint64
+    CacheReadInputTokens     uint64
+}
+```
+
+`AskConfig.String()` deliberately omits the API key value — `fmt.Println(cfg)` shows `apiKey=<set>` or `apiKey=<unset>` without leaking the secret. There's no separate `cfg.HasAPIKey()` method because Go's zero-value semantics make `cfg.APIKey != ""` the idiomatic check.
+
 ## API surface
 
 | Symbol                                  | Purpose                                        |

sqlrite-0.1.23/sdk/go/ask.go

@@ -0,0 +1,293 @@
+// Phase 7g.6 — natural-language → SQL surface for the Go SDK.
+//
+// Wraps the C FFI `sqlrite_ask` function with idiomatic Go types:
+//
+//	import (
+//	    "database/sql"
+//	    sqlrite "github.com/joaoh82/rust_sqlite/sdk/go"
+//	)
+//
+//	db, _ := sql.Open("sqlrite", "foo.sqlrite")
+//	resp, err := sqlrite.Ask(db, "How many users are over 30?", nil)
+//	fmt.Println(resp.SQL)         // "SELECT COUNT(*) FROM users WHERE age > 30"
+//	fmt.Println(resp.Explanation) // one-sentence rationale
+//
+// Three precedence layers for the API key (matching the Python and
+// Node SDKs):
+//
+//  1. Per-call AskConfig (highest — pass via the `cfg` arg)
+//  2. AskConfigFromEnv() (zero-config fallback)
+//  3. Built-in defaults (anthropic / claude-sonnet-4-6 / 1024 / 5m)
+//
+// The cgo bridge passes the config to C as a JSON string and receives
+// the response as a JSON string, parsed on the Go side. That keeps
+// the C ABI tiny (one function) and lets us add fields later without
+// breaking the bindings.
+
+package sqlrite
+
+/*
+#include <stdlib.h>
+#include "sqlrite.h"
+*/
+import "C"
+
+import (
+	"context"
+	"database/sql"
+	"database/sql/driver"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"os"
+	"strconv"
+	"strings"
+	"unsafe"
+)
+
+// ---------------------------------------------------------------------------
+// AskConfig
+
+// AskConfig configures one or more `Ask` / `AskRun` calls. All fields
+// are optional; missing fields fall back to env vars and then to
+// built-in defaults.
+//
+// Field tags map to the JSON keys the C FFI expects, so encoding the
+// struct with `encoding/json` and handing it across the cgo boundary
+// is a one-liner.
+type AskConfig struct {
+	Provider  string `json:"provider,omitempty"`
+	APIKey    string `json:"api_key,omitempty"`
+	Model     string `json:"model,omitempty"`
+	MaxTokens uint32 `json:"max_tokens,omitempty"`
+	// CacheTTL accepts "5m" (default), "1h", or "off". Aliases like
+	// "5min" / "1hr" / "none" / "disabled" are also recognized — the
+	// C side does the canonicalization.
+	CacheTTL string `json:"cache_ttl,omitempty"`
+	// BaseURL overrides the API endpoint. Production callers leave
+	// empty; tests point this at a localhost mock.
+	BaseURL string `json:"base_url,omitempty"`
+}
+
+// AskConfigFromEnv reads SQLRITE_LLM_* env vars and builds an
+// AskConfig. Mirrors the Rust `AskConfig::from_env()` shape so the
+// Go side has the same zero-config experience as every other SDK.
+//
+// Recognized vars:
+//   - SQLRITE_LLM_PROVIDER   (default: anthropic)
+//   - SQLRITE_LLM_API_KEY
+//   - SQLRITE_LLM_MODEL      (default: claude-sonnet-4-6)
+//   - SQLRITE_LLM_MAX_TOKENS (default: 1024)
+//   - SQLRITE_LLM_CACHE_TTL  (default: 5m)
+//
+// A missing API key is NOT an error here — the call to Ask() raises
+// the friendlier "missing API key" message later.
+//
+// (Note: the C side ALSO reads env vars during ask(), so passing a
+// zero-value `&AskConfig{}` to Ask() works too. AskConfigFromEnv is
+// useful when callers want to inspect / log / mutate the resolved
+// config before sending it.)
+func AskConfigFromEnv() (*AskConfig, error) {
+	cfg := &AskConfig{
+		Provider: envOrDefault("SQLRITE_LLM_PROVIDER", "anthropic"),
+		APIKey:   os.Getenv("SQLRITE_LLM_API_KEY"),
+		Model:    envOrDefault("SQLRITE_LLM_MODEL", "claude-sonnet-4-6"),
+		CacheTTL: envOrDefault("SQLRITE_LLM_CACHE_TTL", "5m"),
+	}
+	if v := os.Getenv("SQLRITE_LLM_MAX_TOKENS"); v != "" {
+		n, err := strconv.ParseUint(v, 10, 32)
+		if err != nil {
+			return nil, fmt.Errorf("sqlrite: SQLRITE_LLM_MAX_TOKENS not a u32: %s", v)
+		}
+		cfg.MaxTokens = uint32(n)
+	} else {
+		cfg.MaxTokens = 1024
+	}
+	return cfg, nil
+}
+
+// String returns a human-readable representation that **deliberately
+// omits the API key value**. Lets callers `fmt.Println(cfg)` in
+// debug output without leaking the secret. Shows `apiKey=<set>` or
+// `apiKey=<unset>` so callers can tell whether a key is configured.
+func (c *AskConfig) String() string {
+	keyStatus := "<unset>"
+	if c.APIKey != "" {
+		keyStatus = "<set>"
+	}
+	return fmt.Sprintf(
+		"AskConfig(provider=%q, model=%q, maxTokens=%d, cacheTtl=%q, apiKey=%s)",
+		c.Provider, c.Model, c.MaxTokens, c.CacheTTL, keyStatus,
+	)
+}
+
+func envOrDefault(key, dflt string) string {
+	if v := os.Getenv(key); v != "" {
+		return v
+	}
+	return dflt
+}
+
+// ---------------------------------------------------------------------------
+// AskResponse
+
+// AskResponse is what `Ask` returns. Carries the generated SQL, the
+// model's one-sentence rationale, and token usage.
+//
+// **The API key is not in here** — by design.
+type AskResponse struct {
+	SQL         string   `json:"sql"`
+	Explanation string   `json:"explanation"`
+	Usage       AskUsage `json:"usage"`
+}
+
+// AskUsage is the token-usage breakdown from an `Ask` call. Inspect
+// `CacheReadInputTokens` to verify prompt-caching is actually
+// working — if it stays zero across repeated calls with the same
+// schema, something in the prefix is invalidating the cache.
+type AskUsage struct {
+	InputTokens              uint64 `json:"input_tokens"`
+	OutputTokens             uint64 `json:"output_tokens"`
+	CacheCreationInputTokens uint64 `json:"cache_creation_input_tokens"`
+	CacheReadInputTokens     uint64 `json:"cache_read_input_tokens"`
+}
+
+// ---------------------------------------------------------------------------
+// Public API: Ask + AskContext + AskRun + AskRunContext
+
+// Ask generates SQL from a natural-language question via the
+// configured LLM provider. Returns an `AskResponse` with the
+// generated SQL, rationale, and token usage. Does **not** execute
+// the SQL — call `db.Query(resp.SQL)` (or use `AskRun` for one-shot).
+//
+// `cfg` may be nil to use env vars + defaults. Pass an explicit
+// `*AskConfig` to override per-call.
+//
+// Equivalent to `AskContext(context.Background(), db, question, cfg)`.
+func Ask(db *sql.DB, question string, cfg *AskConfig) (*AskResponse, error) {
+	return AskContext(context.Background(), db, question, cfg)
+}
+
+// AskContext is the context-aware form of `Ask`. The context is used
+// for `db.Conn(ctx)` (acquiring a connection from the pool); the
+// LLM HTTP call inside the C library is currently uncancellable —
+// it'll run to completion / error regardless of the context. A
+// future SDK rev can plumb cancellation through `sqlrite_ask` once
+// the FFI grows a cancel hook.
+func AskContext(ctx context.Context, db *sql.DB, question string, cfg *AskConfig) (*AskResponse, error) {
+	if db == nil {
+		return nil, errors.New("sqlrite: Ask: db is nil")
+	}
+	dbConn, err := db.Conn(ctx)
+	if err != nil {
+		return nil, fmt.Errorf("sqlrite: Ask: %w", err)
+	}
+	defer dbConn.Close()
+
+	var resp *AskResponse
+	err = dbConn.Raw(func(driverConn any) error {
+		c, ok := driverConn.(*conn)
+		if !ok {
+			return fmt.Errorf("sqlrite: Ask: driver connection is %T, not *sqlrite.conn — Ask requires a sqlrite-backed *sql.DB", driverConn)
+		}
+		r, err := c.ask(question, cfg)
+		if err != nil {
+			return err
+		}
+		resp = r
+		return nil
+	})
+	return resp, err
+}
+
+// AskRun generates SQL **and executes it as a query**. Returns
+// `*sql.Rows` ready for iteration (matching `db.Query`).
+//
+// `cfg` may be nil to use env vars + defaults.
+//
+// **Returns an error on empty SQL response** (model declined to
+// generate SQL for this schema) rather than executing the empty
+// string — the model's explanation is in the error message.
+//
+// Convenience for one-shot scripts. For interactive use, prefer
+// `Ask` + manual review (the model can be wrong; auto-execute hides
+// that).
+//
+// Equivalent to `AskRunContext(context.Background(), db, question, cfg)`.
+func AskRun(db *sql.DB, question string, cfg *AskConfig) (*sql.Rows, error) {
+	return AskRunContext(context.Background(), db, question, cfg)
+}
+
+// AskRunContext is the context-aware form of `AskRun`. The context
+// flows through to both the `Ask` call and the subsequent `Query`.
+func AskRunContext(ctx context.Context, db *sql.DB, question string, cfg *AskConfig) (*sql.Rows, error) {
+	resp, err := AskContext(ctx, db, question, cfg)
+	if err != nil {
+		return nil, err
+	}
+	trimmed := strings.TrimSpace(resp.SQL)
+	if trimmed == "" {
+		expl := resp.Explanation
+		if expl == "" {
+			expl = "(no explanation)"
+		}
+		return nil, fmt.Errorf("sqlrite: AskRun: model declined to generate SQL: %s", expl)
+	}
+	return db.QueryContext(ctx, trimmed)
+}
+
+// ---------------------------------------------------------------------------
+// Internal: ask on the conn
+
+// ask runs the C FFI `sqlrite_ask` call. Holds the conn mutex for
+// the duration of the call (which includes the synchronous HTTP
+// round-trip to the LLM, ~hundreds of ms typical, capped at ~90s by
+// ureq). Other goroutines using the same connection wait — same
+// lock discipline as `exec` / `query`.
+func (c *conn) ask(question string, cfg *AskConfig) (*AskResponse, error) {
+	c.mu.Lock()
+	defer c.mu.Unlock()
+	if c.closed {
+		return nil, driver.ErrBadConn
+	}
+
+	// Marshal the config (or empty string if cfg is nil).
+	var configJSON string
+	if cfg != nil {
+		raw, err := json.Marshal(cfg)
+		if err != nil {
+			return nil, fmt.Errorf("sqlrite: ask: marshal config: %w", err)
+		}
+		configJSON = string(raw)
+	}
+
+	cQuestion := cString(question)
+	defer freeCString(cQuestion)
+	var cConfig *C.char
+	if configJSON != "" {
+		cConfig = cString(configJSON)
+		defer freeCString(cConfig)
+	}
+
+	var out *C.char
+	status := Status(C.sqlrite_ask(c.handle, cQuestion, cConfig, &out))
+	if err := wrapErr(status, "ask"); err != nil {
+		return nil, err
+	}
+	if out == nil {
+		return nil, errors.New("sqlrite: ask: FFI returned status=ok but null response")
+	}
+	defer C.sqlrite_free_string(out)
+
+	jsonStr := C.GoString(out)
+	var resp AskResponse
+	if err := json.Unmarshal([]byte(jsonStr), &resp); err != nil {
+		return nil, fmt.Errorf("sqlrite: ask: parse response JSON: %w (raw=%q)", err, jsonStr)
+	}
+	return &resp, nil
+}
+
+// ---------------------------------------------------------------------------
+// Compile-time check that `unsafe` is imported (cgo emits unused-import
+// warnings otherwise).
+var _ = unsafe.Sizeof(C.int(0))