sqlrite 0.1.18__tar.gz → 0.1.20__tar.gz

{sqlrite-0.1.18 → sqlrite-0.1.20}/Cargo.lock

@@ -3804,11 +3804,10 @@ dependencies = [
 
 [[package]]
 name = "sqlrite-ask"
-version = "0.1.18"
+version = "0.1.20"
 dependencies = [
  "serde",
  "serde_json",
- "sqlrite-engine",
  "thiserror 2.0.18",
  "tiny_http",
  "ureq",
@@ -3816,7 +3815,7 @@ dependencies = [
 
 [[package]]
 name = "sqlrite-desktop"
-version = "0.1.18"
+version = "0.1.20"
 dependencies = [
  "serde",
  "serde_json",
@@ -3828,7 +3827,7 @@ dependencies = [
 
 [[package]]
 name = "sqlrite-engine"
-version = "0.1.18"
+version = "0.1.20"
 dependencies = [
  "clap",
  "env_logger",
@@ -3839,12 +3838,13 @@ dependencies = [
  "rustyline-derive",
  "serde_json",
  "sqlparser",
+ "sqlrite-ask",
  "thiserror 2.0.18",
 ]
 
 [[package]]
 name = "sqlrite-ffi"
-version = "0.1.18"
+version = "0.1.20"
 dependencies = [
  "cbindgen",
  "sqlrite-engine",
@@ -3852,7 +3852,7 @@ dependencies = [
 
 [[package]]
 name = "sqlrite-nodejs"
-version = "0.1.18"
+version = "0.1.20"
 dependencies = [
  "napi",
  "napi-build",
@@ -3862,7 +3862,7 @@ dependencies = [
 
 [[package]]
 name = "sqlrite-python"
-version = "0.1.18"
+version = "0.1.20"
 dependencies = [
  "pyo3",
  "sqlrite-engine",

{sqlrite-0.1.18 → sqlrite-0.1.20}/Cargo.toml

@@ -9,7 +9,7 @@
 # wasm32-unknown-unknown. `cargo build --workspace` on a native host
 # would fail on a wasm-only crate; wasm-pack drives that build
 # separately.
-members = [".", "sdk/python"]
+members = [".", "sqlrite-ask", "sdk/python"]
 resolver = "3"
 
 [package]
@@ -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.18"
+version = "0.1.20"
 authors = ["Joao Henrique Machado Silva <joaoh82@gmail.com>"]
 edition = "2024"
 rust-version = "1.85"
@@ -47,13 +47,14 @@ name = "sqlrite"
 path = "src/lib.rs"
 
 # Binary target — the interactive REPL. Needs the `cli` feature
-# (default-on) so rustyline/clap/env_logger are pulled in; a
+# (rustyline/clap/env_logger) AND the `ask` feature (sqlrite-ask
+# integration for the `.ask` meta-command). Both are default-on; a
 # `--no-default-features` build (e.g. for WASM or a minimal
 # embedding) skips the bin entirely via `required-features`.
 [[bin]]
 name = "sqlrite"
 path = "src/main.rs"
-required-features = ["cli"]
+required-features = ["cli", "ask"]
 
 # Phase 5a quickstart — the canonical "how do I use this as a library?"
 # walkthrough. Run with `cargo run --example quickstart`. Lives under
@@ -72,8 +73,21 @@ path = "examples/rust/quickstart.rs"
 # `default-features = false` so rustyline, clap, env_logger, and
 # fs2 don't try to compile against wasm32-unknown-unknown (none of
 # them support that target).
-default = ["cli", "file-locks"]
+default = ["cli", "ask", "file-locks"]
 cli = ["dep:rustyline", "dep:rustyline-derive", "dep:env_logger", "dep:clap"]
+# Phase 7g.2: optional engine integration with the `sqlrite-ask`
+# natural-language → SQL crate. Adds `sqlrite::ConnectionAskExt::ask`
+# (and the schema-introspection helper that powers it) when enabled.
+# The core LLM/HTTP machinery still lives in `sqlrite-ask` itself —
+# this feature is just the thin engine-side glue (extension trait +
+# schema dump). Exists as a feature so library-only embedders
+# (Tauri without ask, the WASM SDK, lean SDK builds) don't pay the
+# `sqlrite-ask` weight by default.
+#
+# The CLI binary requires both `cli` and `ask` (see required-features
+# on the `[[bin]]` section) — `.ask` is part of the standard REPL
+# surface as of Phase 7g.2.
+ask = ["dep:sqlrite-ask"]
 file-locks = ["dep:fs2"]
 
 [dependencies]
@@ -104,3 +118,16 @@ clap = { version = "4.6", features = ["cargo"], optional = true }
 # fs2 wraps POSIX flock / Windows LockFileEx — neither exists on
 # wasm32-unknown-unknown.
 fs2 = { version = "0.4", optional = true }
+
+# Phase 7g.2: REPL `.ask` command. Optional + gated under the `cli`
+# feature because library-only embedders shouldn't have to pull in
+# the LLM stack (HTTP / TLS / extra serde derives) just to use the
+# engine. WASM builds skip it via `default-features = false` per
+# Q9's JS-callback shape — they do prompt construction in-page but
+# never make the HTTP call themselves.
+#
+# `version = "0.1"` is required for `cargo publish` — the engine
+# crate publishes to crates.io, and a path-only dep without a
+# version field fails the manifest verification step. See PR #58
+# retrospective in docs/roadmap.md.
+sqlrite-ask = { version = "0.1", path = "sqlrite-ask", optional = true }

{sqlrite-0.1.18 → sqlrite-0.1.20}/PKG-INFO

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

{sqlrite-0.1.18 → sqlrite-0.1.20}/README.md

@@ -155,12 +155,13 @@ Expressions in `WHERE` and `UPDATE`'s `SET` RHS:
 | `.open FILENAME` | working — opens an existing `.sqlrite` file or creates a fresh one; **auto-save is enabled from this point on** |
 | `.save FILENAME` | working — explicit flush (rarely needed once `.open` is in play) |
 | `.tables` | working |
+| `.ask <QUESTION>` | working — natural-language → SQL via the configured LLM (Anthropic by default). Prints generated SQL + rationale, prompts `Run? [Y/n]`, runs through the same pipeline as a typed statement on confirm. Requires `SQLRITE_LLM_API_KEY` in the environment. *Phase 7g.2.* |
 | `.read FILENAME` | later |
 | `.ast QUERY` | later |
 
 #### Natural-language → SQL (`sqlrite-ask`)
 
-*Phase 7g.1.* The companion crate [`sqlrite-ask`](sqlrite-ask/) turns a natural-language question into a SQL query against your database, using the [Anthropic API](https://docs.anthropic.com/) for the actual generation.
+*Phase 7g.1 / 7g.2.* The companion crate [`sqlrite-ask`](sqlrite-ask/) — pure-Rust over `&str` schemas + questions — provides the LLM-talking machinery. The engine integrates it via the `ask` feature (default-on), exposing `Connection::ask` for ergonomic library use:
 
 ```toml
 [dependencies]
@@ -169,8 +170,8 @@ sqlrite-ask    = "0.1"
 ```
 
 ```rust
-use sqlrite::Connection;
-use sqlrite_ask::{AskConfig, ConnectionAskExt};
+use sqlrite::{Connection, ConnectionAskExt};
+use sqlrite_ask::AskConfig;
 
 let conn = Connection::open("foo.sqlrite")?;
 let cfg  = AskConfig::from_env()?;          // SQLRITE_LLM_API_KEY etc.
@@ -182,7 +183,7 @@ println!("Why: {}",          resp.explanation);
 
 **Defaults:** `claude-sonnet-4-6`, `max_tokens: 1024`, schema dump cached for 5 minutes via Anthropic prompt caching (configurable to 1h or off via `AskConfig::cache_ttl`). Bring your own API key — set `SQLRITE_LLM_API_KEY` or pass it on `AskConfig`.
 
-Per-product `ask()` wrappers (`.ask` REPL command, desktop "Ask" button, `conn.ask()` in the Python / Node / Go SDKs, and the MCP `ask` tool) ship in **7g.2-7g.8** as follow-up sub-phases. WASM gets a JS-callback shape so the API key never enters the browser. See [`docs/phase-7-plan.md`](docs/phase-7-plan.md) §7g for the full surface plan.
+In the REPL: `.ask <question>`. From an open `Connection` (this section). Per-product wrappers — desktop "Ask" button, `conn.ask()` in the Python / Node / Go SDKs, MCP `ask` tool, WASM with a JS-callback shape so the API key never enters the browser — ship in **7g.3-7g.8** as follow-up sub-phases. See [`docs/phase-7-plan.md`](docs/phase-7-plan.md) §7g for the full surface plan.
 
 ### Roadmap
 
@@ -268,8 +269,10 @@ Lockstep versioning — one dispatch bumps every product to the same `vX.Y.Z`. T
 - [x] **7c — Bounded-heap top-k optimization** *(v0.1.12)*
 - [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** *(this wave)*: foundational natural-language → SQL via the [Anthropic API](https://docs.anthropic.com/) (Sonnet 4.6 by default), prompt-cached schema dump, sync `ureq` HTTP. Public surface: `sqlrite_ask::ask(conn, q, &cfg)` or `conn.ask(q, &cfg)` via `ConnectionAskExt`.
-- [ ] **7g.2-7g.8** — per-product `ask()` adapters: REPL `.ask`, desktop "Ask" button, Python/Node/Go/WASM SDKs, MCP `ask` tool
+- [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** *(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.18 → sqlrite-0.1.20}/desktop/package.json

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

{sqlrite-0.1.18 → sqlrite-0.1.20}/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.18 → sqlrite-0.1.20}/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.18 → sqlrite-0.1.20}/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.18 → sqlrite-0.1.20}/docs/embedding.md

@@ -71,19 +71,21 @@ See [Phase 4f notes in roadmap.md](roadmap.md) for the snapshot semantics and th
 - **Parameter binding.** `stmt.query(&[&"alice"])` is the intended shape but the current implementation takes no arguments — use string interpolation for now. Parameter binding lands with the cursor refactor.
 - **Cursor abstraction.** The Pager still eagerly loads every row at open time; `Rows` today wraps an in-memory `Vec`. Phase 5a's follow-up refactor streams rows through the B-Tree on demand — same public API, much lower memory for big SELECTs.
 
-### Natural-language → SQL via `sqlrite-ask` (Phase 7g.1)
+### Natural-language → SQL — `sqlrite::ask` + `sqlrite-ask`
 
-The companion crate [`sqlrite-ask`](../sqlrite-ask/) layers a natural-language → SQL helper on top of the engine. Engine stays pure-SQL with no HTTP / TLS / async deps; anyone who doesn't need `ask()` can ignore the crate entirely.
+*Phases 7g.1 + 7g.2.* The companion crate [`sqlrite-ask`](../sqlrite-ask/) provides the LLM-talking machinery (provider adapters, prompt construction, response parsing) over a deliberately small surface — `&str` schema in, generated SQL out. The engine wraps it under a new `ask` feature (default-on) so library users get the ergonomic `Connection::ask` form without composing the schema dump themselves.
 
 ```toml
 [dependencies]
+# `ask` is a default feature on sqlrite-engine; opt out with
+# default-features = false if you don't want the LLM stack pulled in.
 sqlrite-engine = "0.1"
 sqlrite-ask    = "0.1"
 ```
 
 ```rust
-use sqlrite::Connection;
-use sqlrite_ask::{AskConfig, AskResponse, ConnectionAskExt};
+use sqlrite::{Connection, ConnectionAskExt};
+use sqlrite_ask::{AskConfig, AskResponse};
 
 let conn = Connection::open("foo.sqlrite")?;
 let cfg  = AskConfig::from_env()?;          // reads SQLRITE_LLM_API_KEY etc.
@@ -105,18 +107,20 @@ let mut conn = conn;  // need &mut for execute
 let _ = conn.execute(&resp.sql)?;
 ```
 
-**What `sqlrite-ask` provides:**
+**Where what lives:**
+
+| Crate | Provides |
+|---|---|
+| `sqlrite-engine` (with `ask` feature) | `sqlrite::ConnectionAskExt`, `sqlrite::ask::ask` / `ask_with_database` / `ask_with_provider` / `ask_with_database_and_provider`, `sqlrite::ask::schema::dump_schema_for_connection` / `_for_database`. Pure engine-side glue: dump schema → call into `sqlrite-ask`. |
+| `sqlrite-ask` | `ask_with_schema` / `ask_with_schema_and_provider`, `AskConfig`, `AskResponse`, `AskError`, `Provider` trait + `AnthropicProvider`. Pure `&str` inputs, no engine dep — keeps the LLM stack independently testable + plugable. |
+
+**Provider:** Anthropic only in 7g.1; the `Provider` trait lets OpenAI / Ollama slot in without touching consumers. `AnthropicProvider` does sync `ureq` POSTs to `/v1/messages`. **Defaults:** `claude-sonnet-4-6`, `max_tokens: 1024`, 5-minute prompt-cache TTL on the schema dump (configurable via `AskConfig::cache_ttl` / `SQLRITE_LLM_CACHE_TTL`).
 
-- `ask(conn, question, config) -> AskResponse` — free function entry point.
-- `Connection::ask(question, config)` via the `ConnectionAskExt` trait — same flow, method syntax.
-- `AskConfig::from_env()` — reads `SQLRITE_LLM_PROVIDER` / `_API_KEY` / `_MODEL` / `_MAX_TOKENS` / `_CACHE_TTL` with sensible defaults.
-- `AnthropicProvider` — sync `ureq` POST to `https://api.anthropic.com/v1/messages`. The crate is provider-pluggable (a `Provider` trait + `Request` / `Response` types), with OpenAI and Ollama follow-ups planned for later 7g sub-phases.
-- Schema-aware prompt construction — walks `Database.tables` deterministically (alphabetical) and emits a `<schema>...</schema>` block with `cache_control: ephemeral`, so the schema dump is served from Anthropic's prompt cache after the first call.
-- Output parser tolerant to fenced JSON (`` ```json … ``` ``) or JSON-with-leading-prose, in addition to strict JSON.
+**Why the split** (Phase 7g.2 retro): the REPL binary needed to import the LLM crate to wire up `.ask`, but `sqlrite-ask` 0.1.18 imported `sqlrite-engine` for the `Connection` integration. That's a cargo cycle (`engine[bin] → sqlrite-ask → engine[lib]`) — even with `optional = true`, the static cycle detector rejects the graph. Flipping the dep direction broke it: `sqlrite-ask` is pure now, the engine carries the integration weight behind a feature flag. See `docs/roadmap.md` for the full retrospective.
 
-**Defaults:** `claude-sonnet-4-6`, `max_tokens: 1024`, 5-minute prompt-cache TTL. Configurable via `AskConfig`.
+**REPL surface** *(7g.2)*: type `.ask <question>` at the prompt. Prints generated SQL + rationale, asks `Run? [Y/n]`, executes through the same `process_command` pipeline as a typed statement on confirm. Requires `SQLRITE_LLM_API_KEY`.
 
-**Per-product wrappers ship in 7g.2-7g.8** — REPL `.ask`, desktop "Ask" button, Python/Node/Go SDKs `conn.ask()`, WASM SDK with a JS-callback shape (so the API key stays out of the browser tab), and the MCP `ask` tool.
+**Per-product wrappers ship in 7g.3-7g.8** — desktop "Ask" button, Python/Node/Go SDKs `conn.ask()`, WASM SDK with a JS-callback shape (so the API key stays out of the browser tab), and the MCP `ask` tool.
 
 ## The C FFI (Phase 5b)
 

{sqlrite-0.1.18 → sqlrite-0.1.20}/docs/phase-7-plan.md

@@ -250,8 +250,8 @@ let rows = conn.execute(&resp.sql)?;
 **Layered design.** The work splits into one library layer + several thin adapters:
 
 - **✅ 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` (~80 LOC).** Thin. Calls `sqlrite-ask`, prints the generated SQL, prompts `Y/n`, runs if confirmed. Most of the file is the rustyline integration.
-- **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.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 (~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.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)`.

{sqlrite-0.1.18 → sqlrite-0.1.20}/docs/roadmap.md

@@ -476,13 +476,15 @@ 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()` free function + `ConnectionAskExt` trait + `AskConfig::from_env()`, sync `ureq` POST to `/v1/messages`, schema-aware prompt with prompt-caching on the schema dump (Sonnet 4.6 default; configurable). Thin per-product adapters in 7g.2-7g.8 cover REPL, 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). Per-product adapters in 7g.4-7g.8 cover 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.
 - **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`.
 
 > **v0.1.17 partial-publish retrospective** *(2026-04-29)* — first wave to ship `sqlrite-ask` as a brand-new product line. 23/25 jobs succeeded — `sqlrite-engine 0.1.17` landed on crates.io alongside Python / Node / Go / WASM / FFI / Desktop, and the umbrella `v0.1.17` tag exists. Two jobs failed: `publish-ask` and the `finalize` step that depends on it. Root cause: `cargo publish` rejects path-deps that don't carry a `version` requirement, with `error: dependency 'sqlrite-engine' does not specify a version`. We hit it because `sqlrite-ask` is the **first crate-besides-the-engine to actually publish to crates.io** — `sqlrite-ffi` only ships GitHub Release tarballs, so it never tripped the same check. Fixed in PR #58 by adding `version = "0.1"` (caret-compatible across 0.1.x — no per-release update) to the path-dep declaration. Verified locally with `cargo publish -p sqlrite-ask --dry-run --allow-dirty`. **`sqlrite-ask 0.1.17` will not exist on crates.io** per the never-reuse-a-version policy; the next canary cuts `v0.1.18` and ships `sqlrite-ask` for the first time there. Tags `sqlrite-ask-v0.1.17` and `v0.1.17` stay on `main` per the never-reuse-a-tag policy.
 
+> **v0.1.19 dep-direction flip retrospective** *(2026-04-30)* — Phase 7g.2 wired the REPL's `.ask` meta-command, which required the engine binary to call into `sqlrite-ask`. That created a cargo cycle: `sqlrite-engine[bin] → sqlrite-ask → sqlrite-engine[lib]` (because `sqlrite-ask` 0.1.18 imported `sqlrite::Connection` for `ConnectionAskExt`). Cargo's static cycle detection counts every edge in the graph regardless of features, so `optional = true` didn't help — the cycle is rejected even when nobody actually exercises both directions at once. The fix flipped the dep direction structurally: `sqlrite-ask` 0.1.19 dropped `sqlrite-engine` entirely and became pure over `&str` schemas (canonical API: `ask_with_schema(schema_dump, question, &cfg)`). The engine integration (`schema::dump_schema_for_database`, `ConnectionAskExt`, `ask`, `ask_with_database`) moved into a new `sqlrite::ask` module gated by a fresh `ask` feature on `sqlrite-engine`. Default-on for the CLI binary; off for the WASM SDK and any `default-features = false` lib embedding. **Breaking change for `sqlrite-ask` 0.1.18 callers:** `use sqlrite_ask::ConnectionAskExt` becomes `use sqlrite::ConnectionAskExt` (after enabling the engine's `ask` feature). API method signature unchanged. The 0.1.18 crate had been live ~30 minutes with no known adopters at the time of the flip. Lesson: when a "thin per-product wrapper" sub-phase introduces a new edge in the dep graph, sketch out the full graph BEFORE writing code — would have caught the cycle in design rather than mid-implementation.
+
 ## Phase 8 — Full-text search + hybrid retrieval *(deferred from Phase 7 per Q1)*
 
 Adds the FTS5-style inverted-index machinery that Phase 7 deliberately skipped, plus a small hybrid-ranking convenience function (`bm25_score(...)` × `vec_distance_cosine(...)`) so RAG callers can do BM25 + vector search in a single query. Why deferred: ~600-800 LOC of its own, orthogonal to the AI-era theme, and Phase 7 was already large. Why we'll come back to it: hybrid search (lexical + semantic) is the modern standard for RAG retrieval — vector-only retrieval misses keyword-grounded queries. Will likely close out v0.3.0.

{sqlrite-0.1.18 → sqlrite-0.1.20}/pyproject.toml

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

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