sqlrite 0.1.20__tar.gz → 0.1.21__tar.gz

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

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

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

@@ -27,7 +27,7 @@ resolver = "3"
 # `package =` key so the import name stays `sqlrite` internally:
 #     sqlrite = { package = "sqlrite-engine", path = "…" }
 name = "sqlrite-engine"
-version = "0.1.20"
+version = "0.1.21"
 authors = ["Joao Henrique Machado Silva <joaoh82@gmail.com>"]
 edition = "2024"
 rust-version = "1.85"

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

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

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

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

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

@@ -252,7 +252,7 @@ let rows = conn.execute(&resp.sql)?;
 - **✅ 7g.1 — `sqlrite-ask` crate (foundational, ~750 LOC code + tests).** New separate crate (not feature-gated on the engine) so the engine stays pure-SQL with no HTTP / async deps. Owns: provider adapters (Anthropic in 7g.1; OpenAI / Ollama follow-ups), prompt construction, schema introspection helper that walks `Database.tables` directly (typed walk — cheaper + more robust than reflecting through `sqlrite_master`), the `AskResponse` type, configuration loading from env (`SQLRITE_LLM_PROVIDER` / `_API_KEY` / `_MODEL` / `_MAX_TOKENS` / `_CACHE_TTL`) or a passed config struct. Depends on `sqlrite-engine` for the schema introspection. Public API: `ask()` free function, `ConnectionAskExt::ask` trait extension on `sqlrite::Connection`, `AskConfig::from_env()`, `AskResponse { sql, explanation, usage }`. Default model `claude-sonnet-4-6` per the cost-quality NL→SQL sweet spot. Sync `ureq` HTTP (rejected reqwest::blocking — pulls tokio in even on the blocking path); JSON request/response shapes hand-rolled in serde_json (~120 LOC) — there is no official Anthropic Rust SDK, and rolling our own matches Q5's "build it yourself" theme. Schema dump goes inside a `<schema>...</schema>` block with `cache_control: ephemeral` so repeat asks against the same DB hit Anthropic's prompt cache (5-min TTL default; 1-hour TTL via `CacheTtl::OneHour`). Output parsing is tolerant — strict JSON, fenced JSON, or JSON-with-leading-prose all parse — because real LLM output drifts even with strict prompts. 30 tests pass (26 unit + 4 integration via `tiny_http` localhost mock).
 - **✅ 7g.2 — REPL `.ask` + structural refactor.** New `MetaCommand::Ask(String)` variant + `handle_ask` that calls `sqlrite::ask::ask_with_database`, prints the generated SQL + rationale, prompts `Run? [Y/n] ` via rustyline (Ctrl-C / EOF map to skip — paranoid default for LLM-generated SQL), and pipes through `process_command` if confirmed. The thin REPL part itself is ~120 LOC. **Required a bigger structural fix that 7g.1 didn't anticipate:** wiring the binary to call into `sqlrite-ask` created a cargo cycle (`sqlrite-engine[bin] → sqlrite-ask → sqlrite-engine[lib]`) that even `optional = true` doesn't break — cargo's static cycle detection includes all potential edges. Resolution: flipped the dep direction. `sqlrite-ask` is now pure (no engine dep, canonical API takes a `&str` schema dump + `&str` question). Schema introspection + the `Connection`/`Database` integration (`ConnectionAskExt`, `ask`, `ask_with_database`, `ask_with_provider`, `ask_with_database_and_provider`) moved into `sqlrite-engine` itself under a new `ask` feature (default-on for the CLI binary, off for `--no-default-features` / WASM). Public API for end users is unchanged in spirit: `use sqlrite::{Connection, ConnectionAskExt}` instead of `use sqlrite_ask::ConnectionAskExt`. Net effect — `sqlrite-ask` shrunk + got easier to test in isolation; the engine carries the integration weight, scoped behind a feature flag so SDK / WASM / Tauri builds opt in. 30+ tests pass on both sides (sqlrite-ask: 20 unit + 4 integration; engine ask module: 6 schema + 3 .ask parser).
 - **✅ 7g.3 — Desktop UI "Ask…" button.** New "Ask…" button in the editor toolbar plus a slide-in composer panel above the editor surface (question textarea + "Generate SQL" button + explanation slot). Submitting calls a new `ask_sql` Tauri command that reads `AskConfig::from_env()` server-side, locks the engine's `Database`, calls `sqlrite::ask::ask_with_database` (so the schema dump + LLM HTTP call stay in the Rust backend — the API key never crosses into the webview). Generated SQL drops into the editor textarea for the user to review + Run themselves; the rationale shows in the panel; an empty SQL response (model declined) surfaces the model's explanation in the same slot. Cmd/Ctrl+Enter in the question textarea submits; Esc closes. ~110 LOC of Svelte + ~30 LOC of Rust + ~85 LOC of CSS. As a side benefit, ergonomic re-exports added on `sqlrite::ask::*` (`AskConfig`, `AskResponse`, `AskError`, `Provider`, etc.) so library callers don't have to add `sqlrite-ask` as a direct dep alongside the engine.
-- **7g.4 — Python SDK (~80 LOC).** PyO3 wrapper around `sqlrite-ask`. `Connection.ask(question)` returns a Python object with `.sql` and `.explanation`. `Connection.ask_run(question)` is the convenience that calls `execute` after.
+- **✅ 7g.4 — Python SDK `conn.ask` / `ask_run` / `AskConfig`.** PyO3 wrappers over `sqlrite::ask::*`. New `Connection.ask(question, config=None)` returns an `AskResponse` (`.sql` / `.explanation` / `.usage` with cache-hit fields). `Connection.ask_run(question, config=None)` generates SQL then immediately executes via cursor — convenience for one-shot scripts/notebooks. `Connection.set_ask_config(cfg)` stashes a per-connection config. `AskConfig(api_key=..., model=..., max_tokens=..., cache_ttl=..., base_url=...)` constructor + `AskConfig.from_env()` static method. Three precedence layers: per-call > per-connection > env > defaults. `AskConfig.__repr__` and `AskResponse.__repr__` deliberately omit the API key — printing config in logs won't leak it. Empty SQL response (model declined) on `ask_run()` raises `SQLRiteError` with the model's explanation rather than executing the empty string. ~370 LOC of Rust binding + 415 LOC of pytest tests across 20 cases (config construction, env-var parsing, error paths, full happy-path through a localhost HTTP mock built on Python's stdlib `http.server`). README rewritten — three precedence layers explained, defaults enumerated, errors documented.
 - **7g.5 — Node.js SDK (~80 LOC).** Same shape via napi-rs. `db.ask(question)` / `db.askRun(question)`.
 - **7g.6 — Go SDK (~80 LOC).** cgo wrapper. `sqlrite.Ask(db, question)` returns `(AskResponse, error)`.
 - **7g.7 — WASM SDK (~150 LOC, see Q9).** Either skipped, or implemented with a JS-side fetch hook (the WASM binary calls back into JS to make the HTTP request, since `reqwest`'s wasm32 story is messy and CORS/keys are a separate problem).

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

@@ -476,7 +476,7 @@ Approved sub-phases (Q1–Q10 resolved):
 - **✅ 7d — HNSW ANN index** — three PRs: 7d.1 (algorithm w/ recall@10 ≥ 0.95), 7d.2 (SQL integration + query optimizer), 7d.3 (persistence + DELETE/UPDATE rebuild). `CREATE INDEX … USING hnsw (col)`; fixed defaults `M=16, ef_construction=200, ef_search=50` (Q2). New `KIND_HNSW` cell tag.
 - **✅ 7e — JSON column type + path queries** — `JSON` data type stored as canonical text (validated via `serde_json::from_str` at INSERT/UPDATE time; SQLite-JSON1-style — Q3 scope correction since bincode was removed in Phase 3c). Functions: `json_extract` / `json_type` / `json_array_length` / `json_object_keys`. Path subset supports `$`, `.key`, `[N]`, chained. `json_object_keys` returns a JSON-array text rather than a table-valued result (no set-returning functions in the executor yet).
 - **7f — ~~Full-text search with BM25~~** — **deferred to Phase 8** (Q1).
-- **7g — `ask()` API across the product surface** — natural-language → SQL via Anthropic API (Q4), Anthropic-first then OpenAI + Ollama follow-ups. Foundational **✅ 7g.1** introduces a new `sqlrite-ask` crate (Q10 — separate crate, not a feature flag) — `ask_with_schema()` over `&str` inputs (Phase 7g.2 made it pure — see retrospective below), sync `ureq` POST to `/v1/messages`, schema-aware prompt with prompt-caching on the schema dump (Sonnet 4.6 default; configurable). **✅ 7g.2** wires the REPL's `.ask` meta-command (`MetaCommand::Ask(String)` + confirm-and-run UX) and adds the `sqlrite::ask` module on the engine side (gated under a new `ask` feature) carrying `ConnectionAskExt` + the schema introspection helper. **✅ 7g.3** adds the desktop "Ask…" composer (slide-in panel above the editor; Tauri command runs the LLM call in the Rust backend so the API key stays out of the webview). Per-product adapters in 7g.4-7g.8 cover Python, Node.js, Go, WASM (JS-callback shape per Q9), and the MCP `ask` tool — and fold in the SDK README catch-up for VECTOR / JSON / HNSW capabilities along the way.
+- **7g — `ask()` API across the product surface** — natural-language → SQL via Anthropic API (Q4), Anthropic-first then OpenAI + Ollama follow-ups. Foundational **✅ 7g.1** introduces a new `sqlrite-ask` crate (Q10 — separate crate, not a feature flag) — `ask_with_schema()` over `&str` inputs (Phase 7g.2 made it pure — see retrospective below), sync `ureq` POST to `/v1/messages`, schema-aware prompt with prompt-caching on the schema dump (Sonnet 4.6 default; configurable). **✅ 7g.2** wires the REPL's `.ask` meta-command (`MetaCommand::Ask(String)` + confirm-and-run UX) and adds the `sqlrite::ask` module on the engine side (gated under a new `ask` feature) carrying `ConnectionAskExt` + the schema introspection helper. **✅ 7g.3** adds the desktop "Ask…" composer (slide-in panel above the editor; Tauri command runs the LLM call in the Rust backend so the API key stays out of the webview). **✅ 7g.4** ships the Python SDK surface — `conn.ask(question, config=None)` returns an `AskResponse(.sql, .explanation, .usage)`; `conn.ask_run()` adds the one-shot generate-and-execute convenience; `AskConfig` carries the three-layer precedence (per-call > per-connection > env > defaults). Per-product adapters in 7g.5-7g.8 cover Node.js, Go, WASM (JS-callback shape per Q9), and the MCP `ask` tool — and fold in the SDK README catch-up for VECTOR / JSON / HNSW capabilities along the way.
 - **7h — MCP server adapter** — new `sqlrite-mcp` binary, hand-rolled JSON-RPC + tool framework (Q5).
 
 Total scope budget: ~3-4 kLOC of new Rust across the wave. Each sub-phase ships as its own PR + release wave through the Phase 6 pipeline. The Phase 7 wave will likely close out **v0.2.0** (first minor bump after the 0.1.x Phase 6 cycle). Two new product lines added to lockstep versioning: `sqlrite-ask` and `sqlrite-mcp`.

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

@@ -4,7 +4,7 @@ build-backend = "maturin"
 
 [project]
 name = "sqlrite"
-version = "0.1.20"
+version = "0.1.21"
 description = "Python bindings for SQLRite — a small, embeddable SQLite clone written in Rust."
 authors = [{ name = "Joao Henrique Machado Silva", email = "joaoh82@gmail.com" }]
 license = { text = "MIT" }

{sqlrite-0.1.20 → sqlrite-0.1.21}/sdk/python/Cargo.toml

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

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

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