joaoh82 / rust_sqlite / 25211457852

69%

push

github

Phase 7g.4: Python SDK conn.ask() / ask_run() / AskConfig (#64)

PyO3 wrappers for natural-language → SQL via the engine's `sqlrite::ask`
module. Mirrors the same shape the REPL .ask command and the desktop
Ask… button use, with idiomatic Python ergonomics on top.

## Public surface

```python
import sqlrite

conn = sqlrite.connect("foo.sqlrite")

# Path 1: env var (zero config — same env as REPL/Desktop)
resp = conn.ask("How many users are over 30?")

# Path 2: explicit per-call config (overrides env)
cfg = sqlrite.AskConfig(
    api_key="sk-ant-...",
    model="claude-haiku-4-5",
    max_tokens=512,
    cache_ttl="1h",
)
resp = conn.ask("How many users?", cfg)

# Path 3: per-connection config (set once, reuse)
conn.set_ask_config(cfg)
resp = conn.ask("How many users?")
resp2 = conn.ask("count by age")

# Convenience: generate + execute in one call
rows = conn.ask_run("list active users").fetchall()

# Inspect the response
print(resp.sql)               # str
print(resp.explanation)       # str
print(resp.usage.input_tokens, resp.usage.cache_read_input_tokens)
```

## What's new

  * `sqlrite.AskConfig(provider=..., api_key=..., model=...,
    max_tokens=..., cache_ttl=..., base_url=...)` — constructor +
    `AskConfig.from_env()` static method.
  * `sqlrite.AskResponse` — `.sql`, `.explanation`, `.usage`.
  * `sqlrite.AskUsage` — `.input_tokens`, `.output_tokens`,
    `.cache_creation_input_tokens`, `.cache_read_input_tokens`.
  * `Connection.ask(question, config=None)` — generates SQL,
    does NOT execute. Returns `AskResponse`.
  * `Connection.ask_run(question, config=None)` — generates AND
    executes; returns a `Cursor` you can `.fetchall()` / iterate.
    Empty SQL response (model declined) raises with the model's
    explanation rather than executing the empty string.
  * `Connection.set_ask_config(config)` — per-connection config
    storage. Pass None to clear.

## Config resolution (precedence: high → low)

  1. Per-call `config` arg on `a... (continued)

0 of 103 new or added lines in 1 file covered. (0.0%)

5496 of 9434 relevant lines covered (58.26%)

1.19 hits per line