Phase 7g.6: Go SDK sqlrite.Ask() / AskRun() / AskConfig

[joaoh82]

Summary

cgo wrapper for natural-language → SQL via the engine's sqlrite::ask module. Same three-layer config precedence as Python (7g.4) and Node (7g.5), idiomatic Go shape: free functions on *sql.DB plus context-aware variants.

import (
    "database/sql"
    sqlrite "github.com/joaoh82/rust_sqlite/sdk/go"
)

db, _ := sql.Open("sqlrite", "foo.sqlrite")

// 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", cfg)

// Convenience: generate + execute
rows, _ := sqlrite.AskRun(db, "list users", nil)
defer rows.Close()

What's new

Surface	Description
AskConfig struct	Provider / APIKey / Model / MaxTokens / CacheTTL / BaseURL. JSON tags match the FFI's snake_case ABI.
AskConfigFromEnv()	Reads SQLRITE_LLM_*. Errors on invalid MAX_TOKENS.
(*AskConfig).String()	Debug repr that omits the API key value (shows <set> or <unset>).
Ask(db, q, *AskConfig)	Generates SQL. Does NOT execute. Returns *AskResponse.
AskContext(ctx, db, q, *AskConfig)	Context-aware variant — ctx flows to db.Conn(ctx).
AskRun(db, q, *AskConfig)	Generates + executes; returns *sql.Rows. Errors on empty SQL response (model declined) with the model's explanation.
AskRunContext(ctx, db, q, *AskConfig)	Context-aware variant — ctx flows through both Ask and Query.
AskResponse { SQL, Explanation, Usage }	What Ask returns.
AskUsage { InputTokens, OutputTokens, CacheCreationInputTokens, CacheReadInputTokens }	Token usage breakdown. Inspect CacheReadInputTokens to verify caching is working.

C ABI: one new FFI function

sqlrite_ask(conn, question, config_json, *out) accepts the AskConfig as a JSON string rather than 6+ separate FFI parameters. Smaller surface, more extensible (adding fields later doesn't break the C ABI for existing bindings).

The response is also JSON: {"sql":..., "explanation":..., "usage":{...}}. Caller frees with sqlrite_free_string.

build_ask_config(json) on the Rust side starts from AskConfig::from_env() and applies overrides — so a Go caller passing {"model": "claude-haiku-4-5"} still picks up SQLRITE_LLM_API_KEY from the environment without having to re-read it Go-side.

Plumbing through database/sql

The existing pattern is sql.Open("sqlrite", path) → *sql.DB. The underlying *conn (which holds the opaque *C.SqlriteConnection) is reachable via db.Conn(ctx).Raw(...). That's how Ask gets at the FFI handle — abstracted in ask.go's internal helper. Callers just see the natural Go API.

Tests — 11/11 new pass

• AskConfig + AskConfigFromEnv (4): defaults, env overrides, invalid MAX_TOKENS, String() doesn't leak the API key.
• Error paths (3): nil db, missing API key, closed db.
• Happy path (3): Ask round-trip (SQL + explanation + usage + request body shape + auth headers verified), AskRun executes the generated SQL and returns rows, AskRun on empty SQL response surfaces the model's explanation.
• API error surfacing (1): 400 with structured Anthropic error → Go error carrying status + inner type+message.

httptest.Server runs on a Go runtime goroutine, so unlike Python (GIL) and Node (event-loop), there's no deadlock concern with synchronous cgo calls. Cleanest test setup of the three SDKs.

Plus all 9 pre-existing Go SDK tests still pass.

Test plan

• cargo fmt --all -- --check — clean
• cargo build -p sqlrite-ffi --release — clean (regenerates sqlrite.h with new function)
• cargo test --workspace --exclude sqlrite-desktop --exclude sqlrite-python --exclude sqlrite-nodejs — 301/301 pass (engine + sqlrite-ask unchanged; FFI extended)
• cd sdk/go && go vet ./... — clean
• cd sdk/go && go test — 11 new + 9 existing pass
• CI: rust matrix, python-sdk, nodejs-sdk, go-sdk (linux/macos), wasm-build, desktop-build all green
• Manual smoke: export SQLRITE_LLM_API_KEY=... → cd sdk/go && go run -tags ./... against a small test program

Docs

• sdk/go/README.md — "coming soon" preview replaced with full reference.
• docs/phase-7-plan.md — 7g.6 marked ✅ with the JSON-config-over-cgo design note.
• docs/roadmap.md — 7g bullet updated.

Next up after merge

1. Merge → dispatch release-pr.yml at v0.1.23 → sdk/go/v0.1.23 tag goes live; go get github.com/joaoh82/rust_sqlite/sdk/go@v0.1.23 carries the new Ask/AskRun surface.
2. 7g.7 — WASM SDK with JS-callback shape per Q9 (browser does prompt construction in-page; HTTP call goes through a JS function the caller supplies, so the API key stays in their backend). The doc requirement from Q9: a complete worked example in sdk/wasm/README.md showing browser → backend proxy → LLM provider → response back to WASM.
3. 7g.8 — MCP ask tool (after 7h lays the MCP server framework).

🤖 Generated with Claude Code