sqlrite 0.1.16__tar.gz → 0.1.17__tar.gz

{sqlrite-0.1.16 → 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.16 → 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"
@@ -3735,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.16"
+version = "0.1.17"
 dependencies = [
  "serde",
  "serde_json",
@@ -3749,7 +3828,7 @@ dependencies = [
 
 [[package]]
 name = "sqlrite-engine"
-version = "0.1.16"
+version = "0.1.17"
 dependencies = [
  "clap",
  "env_logger",
@@ -3765,7 +3844,7 @@ dependencies = [
 
 [[package]]
 name = "sqlrite-ffi"
-version = "0.1.16"
+version = "0.1.17"
 dependencies = [
  "cbindgen",
  "sqlrite-engine",
@@ -3773,7 +3852,7 @@ dependencies = [
 
 [[package]]
 name = "sqlrite-nodejs"
-version = "0.1.16"
+version = "0.1.17"
 dependencies = [
  "napi",
  "napi-build",
@@ -3783,7 +3862,7 @@ dependencies = [
 
 [[package]]
 name = "sqlrite-python"
-version = "0.1.16"
+version = "0.1.17"
 dependencies = [
  "pyo3",
  "sqlrite-engine",
@@ -3863,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"
@@ -4373,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"
@@ -4696,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"
@@ -5000,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"
@@ -5230,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"
@@ -5724,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.16 → 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.16"
+version = "0.1.17"
 authors = ["Joao Henrique Machado Silva <joaoh82@gmail.com>"]
 edition = "2024"
 rust-version = "1.85"

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sqlrite
-Version: 0.1.16
+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.16 → 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.16 → sqlrite-0.1.17}/desktop/package.json

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

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

@@ -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.

{sqlrite-0.1.16 → sqlrite-0.1.17}/docs/release-plan.md

@@ -72,19 +72,27 @@ GitHub Releases by product ("show me every Python release").
 |-----------------|------------------------|--------------------------------------------------|
 | Rust engine     | `sqlrite-vX.Y.Z`       | crates.io + GitHub Release                       |
 | C FFI shim      | `sqlrite-ffi-vX.Y.Z`   | GitHub Release (per-platform tarballs)           |
+| `sqlrite-ask`   | `sqlrite-ask-vX.Y.Z`   | crates.io + GitHub Release                       |
 | Python SDK      | `sqlrite-py-vX.Y.Z`    | PyPI + GitHub Release                            |
 | Node.js SDK     | `sqlrite-node-vX.Y.Z`  | npm (`@joaoh82/sqlrite`) + GitHub Release        |
 | Go SDK          | `sdk/go/vX.Y.Z`        | Git tag (no registry) + GitHub Release assets    |
 | WASM            | `sqlrite-wasm-vX.Y.Z`  | npm (`@joaoh82/sqlrite-wasm`) + GitHub Release   |
 | Desktop app     | `sqlrite-desktop-vX.Y.Z` | GitHub Release (unsigned installers)           |
-| **Meta**        | `vX.Y.Z`               | GitHub Release (links to the other seven; acts as the "this was release 0.2.0" anchor) |
+| **Meta**        | `vX.Y.Z`               | GitHub Release (links to the other eight; acts as the "this was release 0.2.0" anchor) |
 
-All eight tags point at the same commit — the merge commit of the
+All nine tags point at the same commit — the merge commit of the
 release PR. The meta tag is the umbrella release users can link to
-in announcements; the seven per-product tags are for tooling
+in announcements; the eight per-product tags are for tooling
 (crates.io, Go module proxy, npm dist-tags, etc.) that expects a
 specific format.
 
+> **`sqlrite-ask` joined the lockstep wave in v0.1.17 (Phase 7g.1).** Gets
+> its own tag and crates.io publish but ships in lockstep with everything
+> else — same version every wave. `publish-ask` runs after `publish-crate`
+> in `release.yml` because crates.io rejects publishes whose path-deps
+> haven't yet resolved at the same version. `sqlrite-mcp` (Phase 7h) will
+> add a ninth product line on the same pattern.
+
 ## Version bumping: exact file list
 
 The release workflow edits these files in a single commit (the
@@ -95,6 +103,7 @@ matching new value:
 |------------------------------------------|---------------------------------------------|
 | `Cargo.toml` (root)                      | `[package].version`                         |
 | `sqlrite-ffi/Cargo.toml`                 | `[package].version`                         |
+| `sqlrite-ask/Cargo.toml`                 | `[package].version`                         |
 | `sdk/python/Cargo.toml`                  | `[package].version`                         |
 | `sdk/python/pyproject.toml`              | `[project].version`                         |
 | `sdk/nodejs/Cargo.toml`                  | `[package].version`                         |

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

@@ -476,7 +476,7 @@ Approved sub-phases (Q1–Q10 resolved):
 - **✅ 7d — HNSW ANN index** — three PRs: 7d.1 (algorithm w/ recall@10 ≥ 0.95), 7d.2 (SQL integration + query optimizer), 7d.3 (persistence + DELETE/UPDATE rebuild). `CREATE INDEX … USING hnsw (col)`; fixed defaults `M=16, ef_construction=200, ef_search=50` (Q2). New `KIND_HNSW` cell tag.
 - **✅ 7e — JSON column type + path queries** — `JSON` data type stored as canonical text (validated via `serde_json::from_str` at INSERT/UPDATE time; SQLite-JSON1-style — Q3 scope correction since bincode was removed in Phase 3c). Functions: `json_extract` / `json_type` / `json_array_length` / `json_object_keys`. Path subset supports `$`, `.key`, `[N]`, chained. `json_object_keys` returns a JSON-array text rather than a table-valued result (no set-returning functions in the executor yet).
 - **7f — ~~Full-text search with BM25~~** — **deferred to Phase 8** (Q1).
-- **7g — `ask()` API across the product surface** — natural-language → SQL via Anthropic API (Q4), Anthropic-first then OpenAI + Ollama follow-ups. Foundational 7g.1 introduces a new `sqlrite-ask` crate (Q10 — separate crate, not a feature flag). 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.
+- **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.
 - **7h — MCP server adapter** — new `sqlrite-mcp` binary, hand-rolled JSON-RPC + tool framework (Q5).
 
 Total scope budget: ~3-4 kLOC of new Rust across the wave. Each sub-phase ships as its own PR + release wave through the Phase 6 pipeline. The Phase 7 wave will likely close out **v0.2.0** (first minor bump after the 0.1.x Phase 6 cycle). Two new product lines added to lockstep versioning: `sqlrite-ask` and `sqlrite-mcp`.

{sqlrite-0.1.16 → sqlrite-0.1.17}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "maturin"
 
 [project]
 name = "sqlrite"
-version = "0.1.16"
+version = "0.1.17"
 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.16 → sqlrite-0.1.17}/scripts/bump-version.sh

@@ -5,11 +5,12 @@
 # Usage:
 #     scripts/bump-version.sh 0.2.0
 #
-# Rewrites the version field in every manifest that carries one (seven
-# Cargo.toml / pyproject.toml files, plus three JSON manifests — ten
-# files total). Then you run `cargo build` yourself to refresh
-# Cargo.lock. Idempotent: running twice with the same version is a
-# no-op; running twice with different versions lands on the second.
+# Rewrites the version field in every manifest that carries one
+# (eight Cargo.toml / pyproject.toml files, plus three JSON manifests
+# — eleven files total). Then you run `cargo build` yourself to
+# refresh Cargo.lock. Idempotent: running twice with the same version
+# is a no-op; running twice with different versions lands on the
+# second.
 #
 # Used by:
 #   - `release-pr.yml` GitHub Actions workflow as the version-bump
@@ -67,6 +68,7 @@ cd "$REPO_ROOT"
 TOML_FILES=(
     "Cargo.toml"
     "sqlrite-ffi/Cargo.toml"
+    "sqlrite-ask/Cargo.toml"
     "sdk/python/Cargo.toml"
     "sdk/python/pyproject.toml"
     "sdk/nodejs/Cargo.toml"

{sqlrite-0.1.16 → sqlrite-0.1.17}/sdk/go/README.md

@@ -82,6 +82,64 @@ defer ro.Close()
 // Reads work; any Exec throws with "read-only" in the message.
 ```
 
+### Vector columns + KNN (Phase 7a–7d)
+
+`VECTOR(N)` storage class plus `vec_distance_l2` / `vec_distance_cosine` / `vec_distance_dot` distance functions. Vector literals are JSON-style bracket arrays `[0.1, 0.2, ...]`. Today the Go side bridges them as text — `database/sql` doesn't yet have a typed accessor for vectors:
+
+```go
+db.Exec(`CREATE TABLE docs (id INTEGER PRIMARY KEY, embedding VECTOR(384))`)
+db.Exec(`INSERT INTO docs (id, embedding) VALUES (1, [0.1, 0.2, ..., 0.0])`)
+
+rows, _ := db.Query(`
+    SELECT id FROM docs
+     ORDER BY vec_distance_l2(embedding, [0.1, 0.2, ..., 0.0])
+     LIMIT 10
+`)
+defer rows.Close()
+for rows.Next() {
+    var id int64
+    rows.Scan(&id)
+}
+```
+
+For larger collections, build an HNSW index — the executor uses it automatically:
+
+```go
+db.Exec(`CREATE INDEX idx_docs_emb ON docs USING hnsw (embedding)`)
+```
+
+### JSON columns (Phase 7e)
+
+`JSON` (and `JSONB` as an alias) columns are validated at INSERT/UPDATE time. Read with `json_extract` / `json_type` / `json_array_length` / `json_object_keys`. Path subset: `$`, `.key`, `[N]`, chained.
+
+```go
+db.Exec(`CREATE TABLE events (id INTEGER PRIMARY KEY, payload JSON)`)
+db.Exec(`INSERT INTO events (payload) VALUES ('{"user": {"name": "alice"}, "score": 42}')`)
+
+var name string
+db.QueryRow(`SELECT json_extract(payload, '$.user.name') FROM events`).Scan(&name)
+fmt.Println(name) // alice
+```
+
+> `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 `sqlrite.Ask(db, ...)` / `sqlrite.AskRun(db, ...)` that wrap the new [`sqlrite-ask`](https://crates.io/crates/sqlrite-ask) Rust crate through cgo. Today it's available only from Rust; the Go wrapper lands in 7g.6 and will look like:
+
+```go
+// 7g.6 preview — not yet released
+import "github.com/joaoh82/rust_sqlite/sdk/go"
+
+cfg := sqlrite.AskConfigFromEnv()                // SQLRITE_LLM_API_KEY etc.
+resp, err := sqlrite.Ask(db, "How many users are over 30?", cfg)
+fmt.Println(resp.SQL)         // "SELECT COUNT(*) FROM users WHERE age > 30"
+fmt.Println(resp.Explanation) // "Counts users over the age threshold."
+
+// Convenience:
+rows, _ := sqlrite.AskRun(db, "How many users are over 30?", cfg)
+```
+
 ## API surface
 
 | Symbol                                  | Purpose                                        |

{sqlrite-0.1.16 → sqlrite-0.1.17}/sdk/python/Cargo.toml

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

{sqlrite-0.1.16 → sqlrite-0.1.17}/sdk/python/README.md

@@ -62,6 +62,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                                          |