sqlrite 0.1.19__tar.gz → 0.1.21__tar.gz

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

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

{sqlrite-0.1.19 → sqlrite-0.1.21}/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.19"
+version = "0.1.21"
 authors = ["Joao Henrique Machado Silva <joaoh82@gmail.com>"]
 edition = "2024"
 rust-version = "1.85"

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sqlrite
-Version: 0.1.19
+Version: 0.1.21
 Classifier: Development Status :: 3 - Alpha
 Classifier: Intended Audience :: Developers
 Classifier: License :: OSI Approved :: MIT License
@@ -127,24 +127,82 @@ print(cur.fetchall())  # [('alice', 'integer')]
 
 > `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.4)
 
-The Phase 7g.2-7g.8 wave adds a Python-native `conn.ask()` that wraps the new `sqlrite-ask` Rust crate via PyO3. Today it's available only from Rust ([`sqlrite-ask` on crates.io](https://crates.io/crates/sqlrite-ask)); the Python wrapper lands in 7g.4 and will look like:
+`Connection.ask(question)` generates SQL from a natural-language question via the configured LLM provider (Anthropic by default). `Connection.ask_run(question)` is the convenience that calls `ask()` then immediately executes the generated SQL.
 
 ```python
-# 7g.4 preview — not yet released
 import sqlrite
 
 conn = sqlrite.connect("foo.sqlrite")
-cfg  = sqlrite.AskConfig.from_env()           # SQLRITE_LLM_API_KEY etc.
-resp = conn.ask("How many users are over 30?", cfg)
-print(resp.sql)          # "SELECT COUNT(*) FROM users WHERE age > 30"
-print(resp.explanation)  # "Counts users over the age threshold."
+conn.execute("CREATE TABLE users (id INTEGER PRIMARY KEY, name TEXT, age INTEGER)")
+conn.execute("INSERT INTO users (name, age) VALUES ('alice', 30)")
 
-# Convenience:
-rows = conn.ask_run("How many users are over 30?", cfg).fetchall()
+# Reads SQLRITE_LLM_API_KEY from the environment.
+resp = conn.ask("How many users are over 30?")
+print(resp.sql)            # "SELECT COUNT(*) FROM users WHERE age > 30"
+print(resp.explanation)    # "Counts users over the age threshold."
+
+# Caller decides whether to run the SQL — ask() does NOT auto-execute.
+cur = conn.cursor()
+cur.execute(resp.sql)
+print(cur.fetchall())      # [(1,)]
+
+# Or one-shot:
+rows = conn.ask_run("How many users are over 30?").fetchall()
 ```
 
+#### Configuration
+
+Three precedence layers — explicit-wins:
+
+1. **Per-call config**: `conn.ask("...", sqlrite.AskConfig(api_key="..."))`
+2. **Per-connection config**: `conn.set_ask_config(cfg)` — applies to all subsequent `ask()` / `ask_run()` calls on this connection
+3. **Environment vars** (zero-config fallback): `SQLRITE_LLM_PROVIDER` / `_API_KEY` / `_MODEL` / `_MAX_TOKENS` / `_CACHE_TTL`
+
+```python
+# Path 1: env (zero config) — same env vars as REPL/Desktop
+resp = conn.ask("how many users?")
+
+# Path 2: explicit per-call (highest precedence)
+cfg = sqlrite.AskConfig(
+    api_key="sk-ant-...",
+    model="claude-haiku-4-5",
+    max_tokens=512,
+    cache_ttl="1h",        # "5m" (default) | "1h" | "off"
+)
+resp = conn.ask("how many users?", cfg)
+
+# Path 3: per-connection (set once, reuse)
+conn.set_ask_config(cfg)
+resp = conn.ask("how many users?")     # uses cfg
+resp = conn.ask("count by age")        # uses cfg
+
+# Or build from env explicitly:
+cfg = sqlrite.AskConfig.from_env()
+```
+
+#### Defaults
+
+`provider="anthropic"`, `model="claude-sonnet-4-6"`, `max_tokens=1024`, `cache_ttl="5m"`. The schema dump goes inside an Anthropic prompt-cache breakpoint — repeat asks against the same DB hit the cache (verify via `resp.usage.cache_read_input_tokens`).
+
+#### Errors
+
+Missing API key → `sqlrite.SQLRiteError("missing API key (set SQLRITE_LLM_API_KEY ...)")`. API errors (4xx/5xx) bubble up as `SQLRiteError` with the status code + Anthropic's structured error message. `ask_run()` on an empty SQL response (model declined to generate) raises with the model's explanation rather than executing the empty string.
+
+#### What `AskResponse` carries
+
+```python
+resp.sql              # str — generated SQL, ready to execute (or '' if model declined)
+resp.explanation      # str — one-sentence rationale (may be empty)
+resp.usage.input_tokens
+resp.usage.output_tokens
+resp.usage.cache_creation_input_tokens
+resp.usage.cache_read_input_tokens
+```
+
+`AskConfig.__repr__` and `AskResponse.__repr__` deliberately don't include the API key — printing config in logs won't leak it.
+
 ## API surface
 
 | Function / Method                | Purpose                                          |

{sqlrite-0.1.19 → sqlrite-0.1.21}/README.md

@@ -270,8 +270,9 @@ Lockstep versioning — one dispatch bumps every product to the same `vX.Y.Z`. T
 - [x] **7d — HNSW ANN index** *(v0.1.13–15)*: `CREATE INDEX … USING hnsw (col)`; recall@10 ≥ 0.95 at default `M=16, ef_construction=200, ef_search=50`; persisted as a `KIND_HNSW` cell tree
 - [x] **7e — JSON column type + path queries** *(v0.1.16)*: `JSON` / `JSONB` columns stored as canonical text; `json_extract` / `json_type` / `json_array_length` / `json_object_keys`; `$.key`, `[N]`, chained JSONPath subset
 - [x] **7g.1 — `sqlrite-ask` crate** *(v0.1.18)*: foundational natural-language → SQL via the [Anthropic API](https://docs.anthropic.com/) (Sonnet 4.6 by default), prompt-cached schema dump, sync `ureq` HTTP.
-- [x] **7g.2 — REPL `.ask` + dep-direction flip** *(this wave)*: `.ask <question>` meta-command with `Run? [Y/n]` confirmation. The wiring required dropping the engine dep from `sqlrite-ask` (cargo cycle) — `sqlrite-ask` is now pure over `&str` schemas; the `Connection`/`Database` integration moved to the engine's new `ask` feature. Public surface for callers: `use sqlrite::{Connection, ConnectionAskExt}`.
-- [ ] **7g.3-7g.8** — per-product `ask()` adapters: desktop "Ask" button, Python/Node/Go/WASM SDKs, MCP `ask` tool
+- [x] **7g.2 — REPL `.ask` + dep-direction flip** *(v0.1.19)*: `.ask <question>` meta-command with `Run? [Y/n]` confirmation. The wiring required dropping the engine dep from `sqlrite-ask` (cargo cycle) — `sqlrite-ask` is now pure over `&str` schemas; the `Connection`/`Database` integration moved to the engine's new `ask` feature. Public surface for callers: `use sqlrite::{Connection, ConnectionAskExt}`.
+- [x] **7g.3 — Desktop "Ask…" button** *(this wave)*: composer panel above the editor textarea; click → type a natural-language question → submit → generated SQL drops into the editor for review before Run. Schema introspection + LLM HTTP call run in the Tauri Rust backend, so the API key never crosses into the webview.
+- [ ] **7g.4-7g.8** — per-product `ask()` adapters: Python/Node/Go/WASM SDKs, MCP `ask` tool
 - [ ] **7h** — MCP server adapter (`sqlrite-mcp` binary)
 - [ ] *(deferred to Phase 8)* Full-text search with BM25 + hybrid retrieval
 

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

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

{sqlrite-0.1.19 → sqlrite-0.1.21}/desktop/src/App.svelte

@@ -31,6 +31,19 @@
   let errorMessage = $state<string | null>(null);
   let running = $state<boolean>(false);
 
+  // Phase 7g.3 — Ask… composer state. The composer is a small panel
+  // that slides in above the editor when the user clicks "Ask…".
+  // Submitting calls the `ask_sql` Tauri command (which runs schema
+  // introspection + the LLM call server-side, so the API key stays
+  // out of the webview), then drops the generated SQL into the
+  // editor for the user to review + run.
+  let askVisible = $state<boolean>(false);
+  let askQuestion = $state<string>("");
+  let askExplanation = $state<string | null>(null);
+  let askInputRef = $state<HTMLTextAreaElement | null>(null);
+  let asking = $state<boolean>(false);
+  type AskResult = { sql: string; explanation: string };
+
   // Editor refs and derived line numbers for the gutter. We derive a
   // dense `[1, 2, …, n]` array so Svelte's {#each} iterates every slot
   // — a sparse `Array(n)` would skip indices.
@@ -280,6 +293,67 @@
     }
   }
 
+  // Phase 7g.3 — Ask composer handlers.
+
+  /** Toggle the Ask composer. Focuses the question input on open. */
+  async function onAskClick() {
+    askVisible = !askVisible;
+    if (askVisible) {
+      // Clear any prior explanation when reopening, but preserve the
+      // question — the user might want to tweak + retry rather than
+      // retype from scratch.
+      askExplanation = null;
+      errorMessage = null;
+      await tick();
+      askInputRef?.focus();
+    }
+  }
+
+  /** Submit the natural-language question to the backend. */
+  async function onAskSubmit() {
+    const question = askQuestion.trim();
+    if (!question) return;
+    asking = true;
+    errorMessage = null;
+    askExplanation = null;
+    try {
+      const resp = await invoke<AskResult>("ask_sql", { question });
+      if (resp.sql.trim().length === 0) {
+        // Model declined to generate SQL for this schema. Surface
+        // its rationale in the same slot we'd use for a successful
+        // explanation; don't touch the editor.
+        askExplanation =
+          resp.explanation || "(model declined to generate SQL)";
+      } else {
+        // Drop the generated SQL into the editor (don't auto-run —
+        // user reviews + clicks Run themselves). Stash the
+        // explanation so the user can see why they got that query.
+        sql = resp.sql;
+        askExplanation = resp.explanation || null;
+        // Move focus back to the editor so Cmd/Ctrl+Enter just works.
+        await tick();
+        textareaRef?.focus();
+      }
+    } catch (err) {
+      errorMessage = String(err);
+    } finally {
+      asking = false;
+    }
+  }
+
+  /** Cmd/Ctrl+Enter in the question input submits. Esc closes. */
+  function onAskKey(e: KeyboardEvent) {
+    if ((e.metaKey || e.ctrlKey) && e.key === "Enter") {
+      e.preventDefault();
+      onAskSubmit();
+      return;
+    }
+    if (e.key === "Escape") {
+      e.preventDefault();
+      askVisible = false;
+    }
+  }
+
   onMount(() => {
     refreshTables();
   });
@@ -347,6 +421,41 @@
 
     <section class="main">
       <div class="editor">
+        {#if askVisible}
+          <div class="ask-panel">
+            <div class="ask-header">
+              <span class="ask-title">Ask</span>
+              <span class="ask-hint">
+                Natural-language → SQL · Submit: ⌘↵ · Close: Esc
+              </span>
+              <button
+                class="ask-close"
+                onclick={() => (askVisible = false)}
+                aria-label="Close Ask panel"
+              >×</button>
+            </div>
+            <textarea
+              bind:this={askInputRef}
+              bind:value={askQuestion}
+              onkeydown={onAskKey}
+              placeholder="e.g. How many users are over 30?"
+              rows="2"
+              spellcheck="false"
+            ></textarea>
+            <div class="ask-actions">
+              {#if askExplanation}
+                <span class="ask-explanation">{askExplanation}</span>
+              {:else}
+                <span class="ask-explanation muted">
+                  Generated SQL replaces the editor contents — review before running.
+                </span>
+              {/if}
+              <button onclick={onAskSubmit} disabled={asking || !askQuestion.trim()}>
+                {asking ? "Generating…" : "Generate SQL"}
+              </button>
+            </div>
+          </div>
+        {/if}
         <div class="editor-surface">
           <div class="gutter" bind:this={gutterRef} aria-hidden="true">
             {#each lineNumbers as n (n)}
@@ -366,6 +475,9 @@
           <span class="shortcut-hint">
             Run: ⌘↵ · Comment: ⌘/{hasSelection ? " · selection only" : ""}
           </span>
+          <button class="ask-button" onclick={onAskClick} disabled={asking}>
+            {askVisible ? "Hide Ask" : "Ask…"}
+          </button>
           <button onclick={onRunSql} disabled={running}>
             {#if running}Running…{:else if hasSelection}Run selection{:else}Run{/if}
           </button>

{sqlrite-0.1.19 → sqlrite-0.1.21}/desktop/src/app.css

@@ -267,6 +267,102 @@ button:disabled {
   user-select: none;
 }
 
+/* Phase 7g.3 — `Ask…` button distinguishes itself with a subtle
+ * accent so users notice the new feature without it shouting. The
+ * normal `Run` button keeps its existing primary styling. */
+.ask-button {
+  margin-right: 8px;
+  background: transparent;
+  color: var(--fg);
+  border: 1px solid var(--border);
+}
+.ask-button:hover:not(:disabled) {
+  background: var(--panel-2);
+  border-color: var(--accent);
+}
+
+/* The Ask composer slides in above the editor surface. Visually it
+ * shares the editor's panel background but is set off by a bottom
+ * border so users can see where it ends and the editor begins. */
+.ask-panel {
+  background: var(--panel-2);
+  border-bottom: 1px solid var(--border);
+  padding: 10px 12px 12px;
+  display: flex;
+  flex-direction: column;
+  gap: 8px;
+}
+
+.ask-header {
+  display: flex;
+  align-items: center;
+  gap: 12px;
+}
+
+.ask-title {
+  font-weight: 600;
+  font-size: 13px;
+  color: var(--fg);
+}
+
+.ask-hint {
+  flex: 1;
+  color: var(--fg-muted);
+  font-family: var(--mono);
+  font-size: 11px;
+  user-select: none;
+}
+
+/* Subtle close button — visually a hairline so it doesn't compete
+ * with the Generate button below. */
+.ask-close {
+  width: 24px;
+  height: 24px;
+  padding: 0;
+  background: transparent;
+  border: 1px solid var(--border);
+  color: var(--fg-muted);
+  font-size: 14px;
+  line-height: 1;
+}
+.ask-close:hover {
+  color: var(--fg);
+  border-color: var(--accent);
+}
+
+.ask-panel textarea {
+  background: var(--panel);
+  color: var(--fg);
+  border: 1px solid var(--border);
+  border-radius: 4px;
+  padding: 8px 10px;
+  font-family: var(--mono);
+  font-size: 13px;
+  line-height: 1.4;
+  resize: vertical;
+  min-height: 48px;
+  outline: none;
+}
+.ask-panel textarea:focus {
+  border-color: var(--accent);
+}
+
+.ask-actions {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 12px;
+}
+
+.ask-explanation {
+  flex: 1;
+  font-size: 12px;
+  color: var(--fg);
+}
+.ask-explanation.muted {
+  color: var(--fg-muted);
+}
+
 .output {
   flex: 1;
   min-height: 0;

{sqlrite-0.1.19 → sqlrite-0.1.21}/docs/desktop.md

@@ -125,6 +125,7 @@ The `Mutex` isn't a concurrency optimization — it's a correctness requirement.
 | `list_tables()` | Sidebar data — one entry per user table with column metadata. |
 | `table_rows(name, limit)` | Seed the result grid with up to `limit` rows from `name`. |
 | `execute_sql(sql)` | Run one SQL statement through `process_command`. Returns structured rows for SELECTs, a status string for everything else. |
+| `ask_sql(question)` | **Phase 7g.3** — Natural-language → SQL via the configured LLM (Anthropic by default). Reads `AskConfig::from_env()` and calls `sqlrite::ask::ask_with_database` against the locked engine `Database`. Schema introspection + LLM HTTP call run in the Tauri Rust backend so **the API key never crosses into the webview** — same security story as Q9's WASM JS-callback shape, applied here as a natural side effect of how Tauri's command bridge works. Returns `{ sql, explanation }`; the frontend pastes `sql` into the editor for the user to review + run. Requires `SQLRITE_LLM_API_KEY` in the process environment (Tauri inherits the parent shell's env). |
 
 ### Command / response types
 
@@ -162,6 +163,7 @@ One Svelte component — [`App.svelte`](../desktop/src/App.svelte) — renders t
   - **Line numbers**: rendered in a gutter on the left of the textarea; derived from the text content (`sql.split("\n").length`) and kept scroll-synced with the textarea via an `onscroll` handler. Font size and line height are locked between the gutter and the textarea so every line number aligns with its row.
   - **Cmd/Ctrl + Enter** — run the query. If the textarea has a non-empty selection, only the selected substring runs; otherwise the full editor contents run. Matches DataGrip / DBeaver / pgAdmin behavior. The Run button label flips to **Run selection** and the shortcut hint shows "selection only" when a selection is active so the state is visible without clicking.
   - **Cmd/Ctrl + /** — toggle SQL line comment (`-- `) on the current line or on every line of the selection. Matches VS Code / Sublime / IntelliJ convention.
+  - **Ask…** *(Phase 7g.3)* — opens a slide-in composer panel above the editor. Type a natural-language question, hit Cmd/Ctrl+Enter (or click "Generate SQL"), and the [`ask_sql`](#commands) Tauri command returns generated SQL + a one-sentence rationale. The SQL replaces the editor textarea; the rationale shows in the panel. **Generated SQL is not auto-executed** — the user reviews and clicks Run themselves. An empty SQL response (model declined the question against this schema) surfaces the model's explanation in the same slot. Esc closes the composer. Requires `SQLRITE_LLM_API_KEY` set in the environment Tauri was launched from; absence surfaces a clean "missing API key" error in the existing error slot.
 
 The textarea starts with a short comment-only placeholder so clicking Run before typing any SQL doesn't error.
 

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

@@ -251,8 +251,8 @@ let rows = conn.execute(&resp.sql)?;
 
 - **✅ 7g.1 — `sqlrite-ask` crate (foundational, ~750 LOC code + tests).** New separate crate (not feature-gated on the engine) so the engine stays pure-SQL with no HTTP / async deps. Owns: provider adapters (Anthropic in 7g.1; OpenAI / Ollama follow-ups), prompt construction, schema introspection helper that walks `Database.tables` directly (typed walk — cheaper + more robust than reflecting through `sqlrite_master`), the `AskResponse` type, configuration loading from env (`SQLRITE_LLM_PROVIDER` / `_API_KEY` / `_MODEL` / `_MAX_TOKENS` / `_CACHE_TTL`) or a passed config struct. Depends on `sqlrite-engine` for the schema introspection. Public API: `ask()` free function, `ConnectionAskExt::ask` trait extension on `sqlrite::Connection`, `AskConfig::from_env()`, `AskResponse { sql, explanation, usage }`. Default model `claude-sonnet-4-6` per the cost-quality NL→SQL sweet spot. Sync `ureq` HTTP (rejected reqwest::blocking — pulls tokio in even on the blocking path); JSON request/response shapes hand-rolled in serde_json (~120 LOC) — there is no official Anthropic Rust SDK, and rolling our own matches Q5's "build it yourself" theme. Schema dump goes inside a `<schema>...</schema>` block with `cache_control: ephemeral` so repeat asks against the same DB hit Anthropic's prompt cache (5-min TTL default; 1-hour TTL via `CacheTtl::OneHour`). Output parsing is tolerant — strict JSON, fenced JSON, or JSON-with-leading-prose all parse — because real LLM output drifts even with strict prompts. 30 tests pass (26 unit + 4 integration via `tiny_http` localhost mock).
 - **✅ 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 (~150 LOC).** New "Ask" button + prompt input + inline SQL preview in the editor. Calls into `sqlrite-ask` from a Tauri command; the command lives in `desktop/src-tauri/`. Schema introspection runs server-side; HTTP call also server-side (so the API key stays in the app process, not the webview).
-- **7g.4 — Python SDK (~80 LOC).** PyO3 wrapper around `sqlrite-ask`. `Connection.ask(question)` returns a Python object with `.sql` and `.explanation`. `Connection.ask_run(question)` is the convenience that calls `execute` after.
+- **✅ 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.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).

{sqlrite-0.1.19 → sqlrite-0.1.21}/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. Per-product adapters in 7g.3-7g.8 cover desktop, Python, 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). 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.
 - **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.19 → sqlrite-0.1.21}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "maturin"
 
 [project]
 name = "sqlrite"
-version = "0.1.19"
+version = "0.1.21"
 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.19 → sqlrite-0.1.21}/sdk/python/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "sqlrite-python"
-version = "0.1.19"
+version = "0.1.21"
 authors = ["Joao Henrique Machado Silva <joaoh82@gmail.com>"]
 edition = "2024"
 rust-version = "1.85"

{sqlrite-0.1.19 → sqlrite-0.1.21}/sdk/python/README.md

@@ -102,24 +102,82 @@ print(cur.fetchall())  # [('alice', 'integer')]
 
 > `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.4)
 
-The Phase 7g.2-7g.8 wave adds a Python-native `conn.ask()` that wraps the new `sqlrite-ask` Rust crate via PyO3. Today it's available only from Rust ([`sqlrite-ask` on crates.io](https://crates.io/crates/sqlrite-ask)); the Python wrapper lands in 7g.4 and will look like:
+`Connection.ask(question)` generates SQL from a natural-language question via the configured LLM provider (Anthropic by default). `Connection.ask_run(question)` is the convenience that calls `ask()` then immediately executes the generated SQL.
 
 ```python
-# 7g.4 preview — not yet released
 import sqlrite
 
 conn = sqlrite.connect("foo.sqlrite")
-cfg  = sqlrite.AskConfig.from_env()           # SQLRITE_LLM_API_KEY etc.
-resp = conn.ask("How many users are over 30?", cfg)
-print(resp.sql)          # "SELECT COUNT(*) FROM users WHERE age > 30"
-print(resp.explanation)  # "Counts users over the age threshold."
+conn.execute("CREATE TABLE users (id INTEGER PRIMARY KEY, name TEXT, age INTEGER)")
+conn.execute("INSERT INTO users (name, age) VALUES ('alice', 30)")
 
-# Convenience:
-rows = conn.ask_run("How many users are over 30?", cfg).fetchall()
+# Reads SQLRITE_LLM_API_KEY from the environment.
+resp = conn.ask("How many users are over 30?")
+print(resp.sql)            # "SELECT COUNT(*) FROM users WHERE age > 30"
+print(resp.explanation)    # "Counts users over the age threshold."
+
+# Caller decides whether to run the SQL — ask() does NOT auto-execute.
+cur = conn.cursor()
+cur.execute(resp.sql)
+print(cur.fetchall())      # [(1,)]
+
+# Or one-shot:
+rows = conn.ask_run("How many users are over 30?").fetchall()
 ```
 
+#### Configuration
+
+Three precedence layers — explicit-wins:
+
+1. **Per-call config**: `conn.ask("...", sqlrite.AskConfig(api_key="..."))`
+2. **Per-connection config**: `conn.set_ask_config(cfg)` — applies to all subsequent `ask()` / `ask_run()` calls on this connection
+3. **Environment vars** (zero-config fallback): `SQLRITE_LLM_PROVIDER` / `_API_KEY` / `_MODEL` / `_MAX_TOKENS` / `_CACHE_TTL`
+
+```python
+# Path 1: env (zero config) — same env vars as REPL/Desktop
+resp = conn.ask("how many users?")
+
+# Path 2: explicit per-call (highest precedence)
+cfg = sqlrite.AskConfig(
+    api_key="sk-ant-...",
+    model="claude-haiku-4-5",
+    max_tokens=512,
+    cache_ttl="1h",        # "5m" (default) | "1h" | "off"
+)
+resp = conn.ask("how many users?", cfg)
+
+# Path 3: per-connection (set once, reuse)
+conn.set_ask_config(cfg)
+resp = conn.ask("how many users?")     # uses cfg
+resp = conn.ask("count by age")        # uses cfg
+
+# Or build from env explicitly:
+cfg = sqlrite.AskConfig.from_env()
+```
+
+#### Defaults
+
+`provider="anthropic"`, `model="claude-sonnet-4-6"`, `max_tokens=1024`, `cache_ttl="5m"`. The schema dump goes inside an Anthropic prompt-cache breakpoint — repeat asks against the same DB hit the cache (verify via `resp.usage.cache_read_input_tokens`).
+
+#### Errors
+
+Missing API key → `sqlrite.SQLRiteError("missing API key (set SQLRITE_LLM_API_KEY ...)")`. API errors (4xx/5xx) bubble up as `SQLRiteError` with the status code + Anthropic's structured error message. `ask_run()` on an empty SQL response (model declined to generate) raises with the model's explanation rather than executing the empty string.
+
+#### What `AskResponse` carries
+
+```python
+resp.sql              # str — generated SQL, ready to execute (or '' if model declined)
+resp.explanation      # str — one-sentence rationale (may be empty)
+resp.usage.input_tokens
+resp.usage.output_tokens
+resp.usage.cache_creation_input_tokens
+resp.usage.cache_read_input_tokens
+```
+
+`AskConfig.__repr__` and `AskResponse.__repr__` deliberately don't include the API key — printing config in logs won't leak it.
+
 ## API surface
 
 | Function / Method                | Purpose                                          |