Module ask 

Engine-side glue for the sqlrite-ask crate — natural-language → SQL.

Compiled only when the ask feature is enabled (default-on for the CLI binary, off for the WASM SDK and any default-features = false library embedding).

Why this lives in the engine, not in sqlrite-ask

Earlier (v0.1.18) sqlrite-ask itself owned the Connection integration — it imported sqlrite-engine and exposed ConnectionAskExt. That worked for library callers, but when the engine’s REPL binary tried to depend on sqlrite-ask to wire up the .ask meta-command we hit a hard cargo error:

cyclic package dependency: package `sqlrite-ask` depends on itself.
Cycle: sqlrite-ask → sqlrite-engine → sqlrite-ask

Optional / feature-gated deps don’t escape this — cargo’s static cycle detection counts every potential edge in the graph. The structural fix was to flip the dep direction: keep sqlrite-ask pure (operates on &str schemas), put the engine integration here. The dep flow is now one-way: sqlrite-engine[ask] → sqlrite-ask. No cycle.

What’s here

• schema::dump_schema_for_database — walks Database.tables alphabetically, emits CREATE TABLE … (…); text the LLM grounds on. Determinism matters for prompt caching.
• ConnectionAskExt — extension trait adding Connection::ask that handles schema introspection + sqlrite_ask::ask_with_schema in one call.
• Free functions ask / ask_with_database / ask_with_provider / ask_with_database_and_provider — for callers who don’t want to bring the trait into scope, or who hold a &Database directly (the REPL binary does this).

Modules

schema

Schema introspection — turn an open Connection (or raw Database) into the textual schema dump the LLM uses to ground its SQL generation.

Structs

AnthropicProvider

Anthropic Messages API client. Stateless — one struct, many complete() calls. The agent (ureq client) is reused across calls so connection-pool / TLS-session-cache benefits accrue when the same AnthropicProvider makes repeat calls.

AskConfig

Knobs for an ask() call. Construct directly, or via AskConfig::from_env to pull defaults from the environment.

AskResponse

Result returned from a successful [ask] call.

Request

One LLM call’s worth of input. Mirrors the Anthropic Messages request shape because it’s the most expressive of the three providers we’ll support; OpenAI and Ollama adapters convert to their native shapes inside their own complete impls.

Response

What every provider returns. We keep this minimal — text is the raw string the model produced (the caller parses it), usage surfaces token counts so callers can verify cache hits.

Usage

Token-usage breakdown. Names match Anthropic’s API field names so the mapping stays obvious; OpenAI’s prompt_tokens / completion_tokens will fan into input_tokens / output_tokens when that adapter lands.

Enums

AskError

Errors ask() can return. Includes every failure mode along the path: config / network / API / parsing.

CacheTtl

Cache-TTL knob exposed on AskConfig.

ProviderKind

Which LLM provider [ask] talks to. Anthropic-only in 7g.1; the enum is here so adding OpenAI/Ollama later doesn’t break the AskConfig shape.

Traits

ConnectionAskExt

Extension trait adding Connection::ask to crate::Connection. Bring it into scope with use sqlrite::ConnectionAskExt; (the engine re-exports it at the crate root).

Provider

A single one-shot call. Sync because every supported provider has a sync HTTPS entry point and ask() itself is sync (matches the engine’s surface — Connection::execute etc. are all sync).

Functions

ask

Free-function form of ConnectionAskExt::ask. Equivalent — pick whichever shape reads better at the call site.

ask_with_database

Same as ask, but takes the engine’s &Database directly.

ask_with_database_and_provider

Lower-level entry taking &Database and a provider. Canonical inner function — the others reduce to this one.

ask_with_provider

Lower-level entry — same flow as ask but you supply the provider. For test harnesses + advanced callers driving custom backends.