sqlrite 0.1.17__tar.gz → 0.1.19__tar.gz

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

@@ -3804,11 +3804,10 @@ dependencies = [
 
 [[package]]
 name = "sqlrite-ask"
-version = "0.1.17"
+version = "0.1.19"
 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.17"
+version = "0.1.19"
 dependencies = [
  "serde",
  "serde_json",
@@ -3828,7 +3827,7 @@ dependencies = [
 
 [[package]]
 name = "sqlrite-engine"
-version = "0.1.17"
+version = "0.1.19"
 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.17"
+version = "0.1.19"
 dependencies = [
  "cbindgen",
  "sqlrite-engine",
@@ -3852,7 +3852,7 @@ dependencies = [
 
 [[package]]
 name = "sqlrite-nodejs"
-version = "0.1.17"
+version = "0.1.19"
 dependencies = [
  "napi",
  "napi-build",
@@ -3862,7 +3862,7 @@ dependencies = [
 
 [[package]]
 name = "sqlrite-python"
-version = "0.1.17"
+version = "0.1.19"
 dependencies = [
  "pyo3",
  "sqlrite-engine",

{sqlrite-0.1.17 → sqlrite-0.1.19}/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.17"
+version = "0.1.19"
 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.17 → sqlrite-0.1.19}/PKG-INFO

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

{sqlrite-0.1.17 → sqlrite-0.1.19}/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,9 @@ 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** *(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
 - [ ] **7h** — MCP server adapter (`sqlrite-mcp` binary)
 - [ ] *(deferred to Phase 8)* Full-text search with BM25 + hybrid retrieval
 

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

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

{sqlrite-0.1.17 → sqlrite-0.1.19}/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.17 → sqlrite-0.1.19}/docs/phase-7-plan.md

@@ -250,7 +250,7 @@ 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.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.5 — Node.js SDK (~80 LOC).** Same shape via napi-rs. `db.ask(question)` / `db.askRun(question)`.

{sqlrite-0.1.17 → sqlrite-0.1.19}/docs/roadmap.md

@@ -476,11 +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. 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.
 - **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.17 → sqlrite-0.1.19}/pyproject.toml

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

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

sqlrite-0.1.19/sqlrite-ask/Cargo.toml

@@ -0,0 +1,63 @@
+[package]
+# Phase 7g.1 — natural-language → SQL via an LLM provider.
+#
+# This crate is intentionally kept separate from `sqlrite-engine` so
+# the engine stays pure-SQL with no HTTP / TLS / async dependencies.
+# Anyone embedding SQLRite who doesn't need `ask()` (the WASM SDK,
+# read-only build-time tooling, lean embeddings) can ignore this
+# crate entirely.
+#
+# Published to crates.io as `sqlrite-ask`. Joins the lockstep release
+# wave (`sqlrite-ask-vX.Y.Z` tag) — see `docs/release-plan.md`.
+name = "sqlrite-ask"
+version = "0.1.19"
+authors = ["Joao Henrique Machado Silva <joaoh82@gmail.com>"]
+edition = "2024"
+rust-version = "1.85"
+description = "Natural-language → SQL adapter for sqlrite-engine. Anthropic-first; OpenAI / Ollama follow-ups."
+repository = "https://github.com/joaoh82/rust_sqlite"
+license = "MIT"
+
+[lib]
+name = "sqlrite_ask"
+path = "src/lib.rs"
+
+[dependencies]
+# **No engine dep as of v0.1.19 (Phase 7g.2 structural fix).**
+# `sqlrite-ask` is now pure: takes a `&str` schema dump + a `&str`
+# question, returns generated SQL. The `Connection` / `Database`
+# integration moved to the engine itself, gated behind the engine's
+# new `ask` feature. Why: cargo's static cycle detection rejected
+# `sqlrite-engine[bin] → sqlrite-ask → sqlrite-engine[lib]` even
+# with `optional = true` on the engine side. Pure crate breaks the
+# cycle structurally.
+#
+# Migration for v0.1.18 callers: `use sqlrite_ask::ConnectionAskExt`
+# becomes `use sqlrite::ConnectionAskExt` (after enabling the
+# engine's `ask` feature). API signature unchanged. See PR #60
+# retrospective in `docs/roadmap.md`.
+
+# JSON request/response shapes for the Anthropic Messages API.
+# Could be hand-rolled but the request body has nested arrays of
+# tagged-enum content blocks — serde derives are worth the dep.
+serde = { version = "1", features = ["derive"] }
+serde_json = "1"
+
+# Sync HTTPS client. `ureq` 2.x is pure-Rust + rustls — no system
+# OpenSSL, no tokio, no async runtime. Per `ask()` call we make
+# exactly one POST to api.anthropic.com, so the sync surface is a
+# perfect fit. Rolling our own JSON types over ureq is ~120 LOC
+# vs. ~400 LOC + tokio + reqwest::blocking via an SDK.
+ureq = { version = "2", features = ["json", "tls"] }
+
+# Typed errors. (Same crate the engine uses, so consumers that
+# enable the engine's `ask` feature can layer their own thiserror
+# wrapper without version skew.)
+thiserror = "2"
+
+[dev-dependencies]
+# Throwaway tiny localhost HTTP server for the integration test
+# that exercises the real ureq path. Avoids hitting api.anthropic.com
+# from CI (no network egress + no API key in test runners). Stays
+# in `dev-dependencies` so it doesn't ship to consumers.
+tiny_http = "0.12"