Overview

SQLsaber ships a small public Python API (the SDK) for running natural-language queries from Python code. SQLSaber is the canonical conversation lifecycle used by the CLI and TUI. It is not a separate embedded wrapper. Clients own input and presentation, while SQLSaber owns agent behavior, completed history, thread lifecycle, and managed resources.

The SDK exposes its primary agent and capability building blocks from the top-level sqlsaber package:

Export	Purpose
SQLSaber	Canonical conversation lifecycle for the CLI, TUI, and SDK.
SQLSaberOptions	Typed options bag used to configure a SQLSaber session.
ModelOverides	Per-tool model/API-key overrides (see Advanced).
SqlTools	SQL capability for composing with your own pydantic-ai agent.
Knowledge	Database-scoped knowledge search capability.
ArtifactStore	Protocol for immutable artifact publication and authorized retrieval.
FilesystemArtifactStore	Durable private local artifact store for CLI/server development.
InMemoryArtifactStore	Explicit in-memory artifact store for tests and short-lived workflows.
StoredArtifact / LoadedArtifact	Serializable descriptor and verified artifact bytes.
QueryResultStore	Protocol for private complete SQL result storage and retrieval.
InMemoryQueryResultStore	Session-local SDK default and test implementation.
FilesystemQueryResultStore	Durable private local implementation (the CLI uses this explicitly).
StoredQueryResult / LoadedQueryResult	Serializable descriptor and verified complete result bytes.

See Capabilities to use SQLsaber inside your own agent or add your capabilities to its managed agent. See Results & Streaming for artifact publishing.

Installation

The SDK is included with the main package — no extra install required.

uv add sqlsaber
# or
pip install sqlsaber

Quickstart

Create a SQLSaberOptions, open a SQLSaber session, and await a query. The result behaves like a string containing the agent’s answer.

import asyncio

from sqlsaber import SQLSaber, SQLSaberOptions


async def main() -> None:
    options = SQLSaberOptions(database="sqlite:///my.db")

    async with SQLSaber(options=options) as saber:
        result = await saber.query("Show me the top 5 users by order count")
        print(result.text)        # the agent's text answer
        print(result.usage)       # token usage for the run

        follow_up = await saber.query("Now group those users by country")
        print(follow_up.text)     # the same conversation continues


if __name__ == "__main__":
    asyncio.run(main())

Note

query() is asynchronous, so call it inside an async function (e.g. via asyncio.run). The SQLSaber constructor is keyword-only — always pass options=....

Use the conversation lifecycle

A SQLSaber instance keeps the completed history for its conversation. A second query() on the same instance uses that history automatically.

Use these methods for common lifecycle tasks:

• SQLSaber.info returns immutable metadata such as database names, model details, thinking state, dangerous mode, and the current thread ID. Access it as saber.info.
• saber.set_thinking(enabled=..., level=...) changes reasoning controls for later queries and returns the new ThinkingState.
• await saber.list_tables() returns TableInfo values for every managed database.
• await saber.draft_handoff(goal) creates a handoff draft from the conversation’s history.
• await saber.end_thread() marks the current persisted thread as ended.
• await saber.new_thread() ends the current persisted thread, clears conversation history, and returns the previous thread ID.
• await SQLSaber.resume(thread_id, options=options) restores a persisted thread. See Advanced for resume errors and storage details.

Managing the connection

SQLSaber owns a live database connection. Use it as an async context manager (async with) so the connection is closed automatically, or call await saber.close() yourself:

options = SQLSaberOptions(database="sqlite:///my.db")
saber = SQLSaber(options=options)
try:
    result = await saber.query("How many orders shipped last week?")
finally:
    await saber.close()

Credentials

By default the SDK reuses the credentials you configured for the CLI (via saber auth) and any provider environment variables such as ANTHROPIC_API_KEY. You can also pass keys explicitly in code — see Credentials & Models.

Where to next?

1. Configuration — every SQLSaberOptions field.
2. Credentials & Models — auth and model selection.
3. Results & Streaming — read SQL, usage, and stream events.
4. Advanced — tool overrides, custom prompts, write access, and more.