sqlrite 0.1.15__tar.gz → 0.1.17__tar.gz

{sqlrite-0.1.15 → sqlrite-0.1.17}/.github/workflows/release.yml

@@ -126,6 +126,7 @@ jobs:
           TAGS=(
             "sqlrite-v$V"
             "sqlrite-ffi-v$V"
+            "sqlrite-ask-v$V"
             "sqlrite-desktop-v$V"
             "sqlrite-py-v$V"
             "sqlrite-node-v$V"
@@ -199,6 +200,73 @@ jobs:
             See the umbrella release [v${{ needs.detect.outputs.version }}](../../releases/tag/v${{ needs.detect.outputs.version }}) for the full changelog.
           generate_release_notes: true
 
+  # ---------------------------------------------------------------------------
+  # Step 3a': publish the `sqlrite-ask` crate (Phase 7g.1) — natural-
+  # language → SQL adapter built on top of the engine. Same shape as
+  # `publish-crate` above; separate job so a registry hiccup on one
+  # doesn't block the other and re-runs are surgical.
+  #
+  # Crate name on crates.io: `sqlrite-ask`. Library name (the `use`
+  # path): `sqlrite_ask`. No alias-renaming this time — the short
+  # name was available unlike `sqlrite` (see Phase 6d retrospective
+  # for why the engine had to rename).
+  publish-ask:
+    name: Publish sqlrite-ask crate to crates.io
+    needs: [detect, tag-all, publish-crate]
+    if: needs.detect.outputs.should_release == 'true'
+    runs-on: ubuntu-latest
+    environment: release
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: dtolnay/rust-toolchain@stable
+
+      - uses: Swatinem/rust-cache@v2
+        with:
+          shared-key: publish-ask
+
+      - name: cargo publish
+        env:
+          CARGO_REGISTRY_TOKEN: ${{ secrets.CRATES_IO_TOKEN }}
+        # `--no-verify` mirrors `publish-crate` — Release-PR CI
+        # already validated this commit.
+        #
+        # `needs: [..., publish-crate]` is load-bearing: sqlrite-ask
+        # depends on sqlrite-engine, and crates.io rejects publishes
+        # whose path-deps haven't yet resolved to a published version
+        # at the same number. Sequencing makes the dep visible by the
+        # time we publish.
+        run: cargo publish -p sqlrite-ask --no-verify
+
+      - name: GitHub Release
+        uses: softprops/action-gh-release@v2
+        with:
+          tag_name: sqlrite-ask-v${{ needs.detect.outputs.version }}
+          name: sqlrite-ask v${{ needs.detect.outputs.version }}
+          body: |
+            Published to crates.io: https://crates.io/crates/sqlrite-ask/${{ needs.detect.outputs.version }}
+
+            Natural-language → SQL adapter for SQLRite. Anthropic-first; OpenAI / Ollama follow-ups.
+
+            ```toml
+            [dependencies]
+            sqlrite-engine = "${{ needs.detect.outputs.version }}"
+            sqlrite-ask    = "${{ needs.detect.outputs.version }}"
+            ```
+
+            ```rust
+            use sqlrite::Connection;
+            use sqlrite_ask::{AskConfig, ConnectionAskExt};
+
+            let conn = Connection::open("foo.sqlrite")?;
+            let cfg  = AskConfig::from_env()?;        // SQLRITE_LLM_API_KEY etc.
+            let resp = conn.ask("How many users are over 30?", &cfg)?;
+            println!("Generated SQL: {}", resp.sql);
+            ```
+
+            See the umbrella release [v${{ needs.detect.outputs.version }}](../../releases/tag/v${{ needs.detect.outputs.version }}) for the full changelog.
+          generate_release_notes: true
+
   # ---------------------------------------------------------------------------
   # Step 3b: build `libsqlrite_c` for each supported platform and
   # upload the tarballs to the `sqlrite-ffi-v<V>` GitHub Release.
@@ -1223,7 +1291,7 @@ jobs:
   # config if we add one later.
   finalize:
     name: Finalize umbrella release
-    needs: [detect, publish-crate, publish-ffi, publish-desktop, publish-python, publish-nodejs, publish-wasm, publish-go]
+    needs: [detect, publish-crate, publish-ask, publish-ffi, publish-desktop, publish-python, publish-nodejs, publish-wasm, publish-go]
     if: needs.detect.outputs.should_release == 'true'
     runs-on: ubuntu-latest
     steps:

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

@@ -106,6 +106,12 @@ dependencies = [
  "object",
 ]
 
+[[package]]
+name = "ascii"
+version = "1.1.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d92bec98840b8f03a5ff5413de5293bfcd8bf96467cf5452609f939ec6f5de16"
+
 [[package]]
 name = "atk"
 version = "0.18.2"
@@ -396,6 +402,12 @@ dependencies = [
  "windows-link 0.2.1",
 ]
 
+[[package]]
+name = "chunked_transfer"
+version = "1.5.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6e4de3bc4ea267985becf712dc6d9eed8b04c953b3fcfb339ebc87acd9804901"
+
 [[package]]
 name = "clap"
 version = "4.6.1"
@@ -1557,6 +1569,12 @@ version = "1.10.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "6dbf3de79e51f3d586ab4cb9d5c3e2c14aa28ed23d180cf89b4df0454a69cc87"
 
+[[package]]
+name = "httpdate"
+version = "1.0.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "df3b46402a9d5adb4c86a0cf463f42e19994e3ee891101b1841f30a545cb49a9"
+
 [[package]]
 name = "hyper"
 version = "1.9.0"
@@ -3267,6 +3285,20 @@ dependencies = [
  "windows-sys 0.60.2",
 ]
 
+[[package]]
+name = "ring"
+version = "0.17.14"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a4689e6c2294d81e88dc6261c768b63bc4fcdb852be6d1352498b114f61383b7"
+dependencies = [
+ "cc",
+ "cfg-if",
+ "getrandom 0.2.17",
+ "libc",
+ "untrusted",
+ "windows-sys 0.52.0",
+]
+
 [[package]]
 name = "rustc-hash"
 version = "2.1.2"
@@ -3295,6 +3327,41 @@ dependencies = [
  "windows-sys 0.61.2",
 ]
 
+[[package]]
+name = "rustls"
+version = "0.23.40"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ef86cd5876211988985292b91c96a8f2d298df24e75989a43a3c73f2d4d8168b"
+dependencies = [
+ "log",
+ "once_cell",
+ "ring",
+ "rustls-pki-types",
+ "rustls-webpki",
+ "subtle",
+ "zeroize",
+]
+
+[[package]]
+name = "rustls-pki-types"
+version = "1.14.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "30a7197ae7eb376e574fe940d068c30fe0462554a3ddbe4eca7838e049c937a9"
+dependencies = [
+ "zeroize",
+]
+
+[[package]]
+name = "rustls-webpki"
+version = "0.103.13"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "61c429a8649f110dddef65e2a5ad240f747e85f7758a6bccc7e5777bd33f756e"
+dependencies = [
+ "ring",
+ "rustls-pki-types",
+ "untrusted",
+]
+
 [[package]]
 name = "rustversion"
 version = "1.0.22"
@@ -3511,6 +3578,7 @@ version = "1.0.149"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "83fc039473c5595ace860d8c4fafa220ff474b3fc6bfdb4293327f1a37e94d86"
 dependencies = [
+ "indexmap 2.14.0",
  "itoa",
  "memchr",
  "serde",
@@ -3734,9 +3802,21 @@ dependencies = [
  "recursive",
 ]
 
+[[package]]
+name = "sqlrite-ask"
+version = "0.1.17"
+dependencies = [
+ "serde",
+ "serde_json",
+ "sqlrite-engine",
+ "thiserror 2.0.18",
+ "tiny_http",
+ "ureq",
+]
+
 [[package]]
 name = "sqlrite-desktop"
-version = "0.1.15"
+version = "0.1.17"
 dependencies = [
  "serde",
  "serde_json",
@@ -3748,7 +3828,7 @@ dependencies = [
 
 [[package]]
 name = "sqlrite-engine"
-version = "0.1.15"
+version = "0.1.17"
 dependencies = [
  "clap",
  "env_logger",
@@ -3757,13 +3837,14 @@ dependencies = [
  "prettytable-rs",
  "rustyline",
  "rustyline-derive",
+ "serde_json",
  "sqlparser",
  "thiserror 2.0.18",
 ]
 
 [[package]]
 name = "sqlrite-ffi"
-version = "0.1.15"
+version = "0.1.17"
 dependencies = [
  "cbindgen",
  "sqlrite-engine",
@@ -3771,7 +3852,7 @@ dependencies = [
 
 [[package]]
 name = "sqlrite-nodejs"
-version = "0.1.15"
+version = "0.1.17"
 dependencies = [
  "napi",
  "napi-build",
@@ -3781,7 +3862,7 @@ dependencies = [
 
 [[package]]
 name = "sqlrite-python"
-version = "0.1.15"
+version = "0.1.17"
 dependencies = [
  "pyo3",
  "sqlrite-engine",
@@ -3861,6 +3942,12 @@ version = "0.11.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "7da8b5736845d9f2fcb837ea5d9e2628564b3b043a70948a3f0b778838c5fb4f"
 
+[[package]]
+name = "subtle"
+version = "2.6.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "13c2bddecc57b384dee18652358fb23172facb8a2c51ccc10d74c157bdea3292"
+
 [[package]]
 name = "swift-rs"
 version = "1.0.7"
@@ -4371,6 +4458,18 @@ dependencies = [
  "time-core",
 ]
 
+[[package]]
+name = "tiny_http"
+version = "0.12.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "389915df6413a2e74fb181895f933386023c71110878cd0825588928e64cdc82"
+dependencies = [
+ "ascii",
+ "chunked_transfer",
+ "httpdate",
+ "log",
+]
+
 [[package]]
 name = "tinystr"
 version = "0.8.3"
@@ -4694,6 +4793,30 @@ version = "0.2.4"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "7264e107f553ccae879d21fbea1d6724ac785e8c3bfc762137959b5802826ef3"
 
+[[package]]
+name = "untrusted"
+version = "0.9.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8ecb6da28b8a351d773b68d5825ac39017e680750f980f3a1a85cd8dd28a47c1"
+
+[[package]]
+name = "ureq"
+version = "2.12.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "02d1a66277ed75f640d608235660df48c8e3c19f3b4edb6a263315626cc3c01d"
+dependencies = [
+ "base64 0.22.1",
+ "flate2",
+ "log",
+ "once_cell",
+ "rustls",
+ "rustls-pki-types",
+ "serde",
+ "serde_json",
+ "url",
+ "webpki-roots 0.26.11",
+]
+
 [[package]]
 name = "url"
 version = "2.5.8"
@@ -4998,6 +5121,24 @@ dependencies = [
  "system-deps",
 ]
 
+[[package]]
+name = "webpki-roots"
+version = "0.26.11"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "521bc38abb08001b01866da9f51eb7c5d647a19260e00054a8c7fd5f9e57f7a9"
+dependencies = [
+ "webpki-roots 1.0.7",
+]
+
+[[package]]
+name = "webpki-roots"
+version = "1.0.7"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "52f5ee44c96cf55f1b349600768e3ece3a8f26010c05265ab73f945bb1a2eb9d"
+dependencies = [
+ "rustls-pki-types",
+]
+
 [[package]]
 name = "webview2-com"
 version = "0.38.2"
@@ -5228,6 +5369,15 @@ dependencies = [
  "windows-targets 0.42.2",
 ]
 
+[[package]]
+name = "windows-sys"
+version = "0.52.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "282be5f36a8ce781fad8c8ae18fa3f9beff57ec1b52cb3de0789201425d9a33d"
+dependencies = [
+ "windows-targets 0.52.6",
+]
+
 [[package]]
 name = "windows-sys"
 version = "0.59.0"
@@ -5722,6 +5872,12 @@ dependencies = [
  "synstructure",
 ]
 
+[[package]]
+name = "zeroize"
+version = "1.8.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b97154e67e32c85465826e8bcc1c59429aaaf107c1e4a9e53c8d8ccd5eff88d0"
+
 [[package]]
 name = "zerotrie"
 version = "0.2.4"

{sqlrite-0.1.15 → sqlrite-0.1.17}/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.15"
+version = "0.1.17"
 authors = ["Joao Henrique Machado Silva <joaoh82@gmail.com>"]
 edition = "2024"
 rust-version = "1.85"
@@ -82,6 +82,14 @@ log = "0.4"
 sqlparser = "0.61"
 thiserror = "2.0"
 prettytable-rs = "0.10"
+# Phase 7e: JSON column type. `serde_json` powers both the validation
+# step at INSERT time (parse-and-discard to confirm the text is valid
+# JSON) and the path extraction inside the json_extract / json_type
+# / json_array_length / json_object_keys SQL functions. `preserve_order`
+# keeps object keys in insertion order so json_object_keys output is
+# stable; without it, BTreeMap-backed Maps would alphabetically sort,
+# which surprises callers re-serializing the same JSON.
+serde_json = { version = "1", features = ["preserve_order"] }
 
 # CLI-only deps (feature-gated). `optional = true` + the `cli`
 # feature above means these only land in the dep graph when

{sqlrite-0.1.15 → sqlrite-0.1.17}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sqlrite
-Version: 0.1.15
+Version: 0.1.17
 Classifier: Development Status :: 3 - Alpha
 Classifier: Intended Audience :: Developers
 Classifier: License :: OSI Approved :: MIT License
@@ -87,6 +87,64 @@ conn = sqlrite.connect_read_only("foo.sqlrite")
 # connections on the same file coexist (shared OS lock).
 ```
 
+### Vector columns + KNN (Phase 7a–7d)
+
+The engine ships with a fixed-dimension `VECTOR(N)` storage class and three distance functions (`vec_distance_l2`, `vec_distance_cosine`, `vec_distance_dot`). Plain `cursor.execute(...)` is all you need from Python — values come back as Python lists of floats.
+
+```python
+cur.execute("CREATE TABLE docs (id INTEGER PRIMARY KEY, embedding VECTOR(384))")
+cur.execute("INSERT INTO docs (id, embedding) VALUES (1, [0.1, 0.2, ..., 0.0])")  # 384 floats
+cur.execute("""
+    SELECT id FROM docs
+     ORDER BY vec_distance_l2(embedding, [0.1, 0.2, ..., 0.0])
+     LIMIT 10
+""")
+for row in cur:
+    print(row)
+```
+
+For larger collections, build an HNSW index — the executor will use it automatically when the `WHERE`/`ORDER BY` shape matches:
+
+```python
+cur.execute("CREATE INDEX idx_docs_emb ON docs USING hnsw (embedding)")
+```
+
+### JSON columns (Phase 7e)
+
+`JSON` (and `JSONB` as an alias) columns store text, validated at INSERT/UPDATE time. Read with `json_extract` / `json_type` / `json_array_length` / `json_object_keys`. Path subset: `$`, `.key`, `[N]`, chained.
+
+```python
+cur.execute("CREATE TABLE events (id INTEGER PRIMARY KEY, payload JSON)")
+cur.execute(
+    "INSERT INTO events (payload) VALUES "
+    "('{\"user\": {\"name\": \"alice\"}, \"score\": 42}')"
+)
+cur.execute(
+    "SELECT json_extract(payload, '$.user.name'), json_type(payload, '$.score') FROM events"
+)
+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*)
+
+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:
+
+```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."
+
+# Convenience:
+rows = conn.ask_run("How many users are over 30?", cfg).fetchall()
+```
+
 ## API surface
 
 | Function / Method                | Purpose                                          |

{sqlrite-0.1.15 → sqlrite-0.1.17}/README.md

@@ -158,6 +158,32 @@ Expressions in `WHERE` and `UPDATE`'s `SET` RHS:
 | `.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.
+
+```toml
+[dependencies]
+sqlrite-engine = "0.1"
+sqlrite-ask    = "0.1"
+```
+
+```rust
+use sqlrite::Connection;
+use sqlrite_ask::{AskConfig, ConnectionAskExt};
+
+let conn = Connection::open("foo.sqlrite")?;
+let cfg  = AskConfig::from_env()?;          // SQLRITE_LLM_API_KEY etc.
+let resp = conn.ask("How many users are over 30?", &cfg)?;
+println!("Generated SQL: {}", resp.sql);
+println!("Why: {}",          resp.explanation);
+// Caller decides whether to run resp.sql — the library deliberately doesn't.
+```
+
+**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.
+
 ### Roadmap
 
 The project is staged in phases, each independently shippable. A finished phase is committed to `main` before the next one starts.
@@ -236,10 +262,16 @@ Lockstep versioning — one dispatch bumps every product to the same `vX.Y.Z`. T
 - [ ] macOS Apple Developer ID cert → `codesign` + `notarytool` in `tauri-action`
 - [ ] Windows code-signing cert → `signtool` in `tauri-action`
 
-**Phase 7 — AI-era extensions** *(research)*
-- [ ] Vector / embedding column type with an ANN index
-- [ ] Natural-language → SQL front-end that emits queries against this engine
-- [ ] Other agent-era ideas as they emerge
+**Phase 7 — AI-era extensions** *(in progress — full plan in [`docs/phase-7-plan.md`](docs/phase-7-plan.md))*
+- [x] **7a — `VECTOR(N)` column type** *(v0.1.10)*: dense f32 vectors with bracket-array literal syntax (`[0.1, 0.2, ...]`); file format bumped to v4
+- [x] **7b — Distance functions** *(v0.1.11)*: `vec_distance_l2/cosine/dot` + `ORDER BY <expr> LIMIT k` so KNN queries work end-to-end
+- [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
+- [ ] **7h** — MCP server adapter (`sqlrite-mcp` binary)
+- [ ] *(deferred to Phase 8)* Full-text search with BM25 + hybrid retrieval
 
 **Possible extras** *(no committed phase)*
 - Joins (`INNER`, `LEFT OUTER`, `CROSS` — SQLite does not support `RIGHT`/`FULL OUTER`)

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

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

{sqlrite-0.1.15 → sqlrite-0.1.17}/docs/embedding.md

@@ -71,6 +71,53 @@ 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)
+
+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.
+
+```toml
+[dependencies]
+sqlrite-engine = "0.1"
+sqlrite-ask    = "0.1"
+```
+
+```rust
+use sqlrite::Connection;
+use sqlrite_ask::{AskConfig, AskResponse, ConnectionAskExt};
+
+let conn = Connection::open("foo.sqlrite")?;
+let cfg  = AskConfig::from_env()?;          // reads SQLRITE_LLM_API_KEY etc.
+let resp: AskResponse = conn.ask("How many users are over 30?", &cfg)?;
+
+println!("Generated SQL: {}", resp.sql);
+println!("Rationale: {}",     resp.explanation);
+println!("Tokens: in={}, out={}, cache_hit={}",
+    resp.usage.input_tokens,
+    resp.usage.output_tokens,
+    resp.usage.cache_read_input_tokens);
+
+// Caller decides whether to execute the generated SQL — the library
+// does NOT auto-execute. SDK convenience wrappers (Python's
+// `conn.ask_run()`, Node's `db.askRun()`, etc.) add a one-shot
+// generate-and-execute helper, but the default Rust API is
+// "generate, return, let me decide".
+let mut conn = conn;  // need &mut for execute
+let _ = conn.execute(&resp.sql)?;
+```
+
+**What `sqlrite-ask` provides:**
+
+- `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.
+
+**Defaults:** `claude-sonnet-4-6`, `max_tokens: 1024`, 5-minute prompt-cache TTL. Configurable via `AskConfig`.
+
+**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.
+
 ## The C FFI (Phase 5b)
 
 The `sqlrite-ffi/` crate wraps the Rust API in a C ABI that every non-Rust SDK binds against. Build the shared library:

{sqlrite-0.1.15 → sqlrite-0.1.17}/docs/phase-7-plan.md

@@ -170,14 +170,14 @@ SELECT id, title FROM docs ORDER BY embedding <-> [0.1, ...] LIMIT 10;
 
 ---
 
-### 7e — JSON column type + path queries
+### ✅ 7e — JSON column type + path queries
 
-**What.** New `JSON` data type. Store as bincoded `serde_json::Value` (or as a parsed AST — see open questions). Support a small set of extraction functions:
+**What.** New `JSON` data type. Stored as canonical UTF-8 text and validated at INSERT/UPDATE time via `serde_json::from_str`. The four path-extraction functions parse on demand:
 
 - `json_extract(col, '$.path')` — returns the value at the path, NULL if absent
-- `json_array_length(col, '$.path')` — array length, NULL for non-array
-- `json_object_keys(col, '$.path')` — TEXT array of keys, NULL for non-object
-- `json_type(col, '$.path')` — `'null'`, `'bool'`, `'number'`, `'string'`, `'array'`, `'object'`
+- `json_array_length(col, '$.path')` — array length, NULL for non-array, errors for non-array-with-path-resolved
+- `json_object_keys(col, '$.path')` — JSON-array text of keys (see scope-correction note in Q3 below; SQLite's set-returning shape requires features we don't have)
+- `json_type(col, '$.path')` — `'null'` / `'true'` / `'false'` / `'integer'` / `'real'` / `'text'` / `'array'` / `'object'` (matches SQLite JSON1 conventions)
 
 **Why this matters for AI-era specifically.** LLM tool-call outputs are JSON. RAG citation arrays are JSON. Agent scratchpads are JSON. Storing them as TEXT and re-parsing on every query is wasteful.
 
@@ -249,7 +249,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, ~400 LOC).** New separate crate (not feature-gated on the engine) so the engine stays pure-SQL with no HTTP / async deps. Owns: provider adapters (Anthropic / OpenAI / Ollama), prompt construction, schema introspection helper that walks `sqlrite_master`, the `AskResponse` type, configuration loading from env or a passed config struct. Depends on `sqlrite-engine` for the schema introspection.
+- **✅ 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.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.
@@ -378,6 +378,10 @@ Q1–Q10 were resolved by the project owner on 2026-04-26. Each question keeps i
 ### Q3. JSON storage format
 
 > **Decided: bincoded `serde_json::Value`** for the MVP. JSON indexing remains a future phase.
+>
+> **Scope correction (2026-04-28, during 7e implementation):** Q3's "bincoded `Value`" answer was settled before remembering that bincode was removed from the engine in Phase 3c (cell-based encoding replaced it). Rather than re-add bincode for one column type, **7e ships JSON-as-canonical-text** — same as SQLite's JSON1 extension. INSERT/UPDATE call `serde_json::from_str` to validate; the four `json_*` functions re-parse on demand. Trade-off: ~2× storage vs. binary, plus per-call parse overhead — both acceptable for MVP and consistent with SQLite's choice. JSONB-style binary indexing remains a future-phase optimization, but doesn't block 7e.
+>
+> One additional 7e divergence from the original plan: `json_object_keys` is supposed to be a *table-valued function* (one row per key, like SQLite's). We don't yet support set-returning functions in the executor, so 7e returns the keys as a JSON-array text instead. Caller can iterate via `json_array_length` + `json_extract` indexing. Documented in `docs/supported-sql.md` so users see the divergence up front.
 
 - **bincoded `serde_json::Value`:** one-line implementation, fast read/write, opaque on disk.
 - **Parsed AST as cell-encoded structure:** more code, but lets us index into JSON without a full deserialize.