Overview

The SQLsaber Python API runs natural-language queries from Python. SQLSaber is the conversation lifecycle used by the CLI and TUI. It is not a separate wrapper. Clients own input and presentation. SQLSaber owns agent behavior, completed history, thread lifecycle, and managed resources.

Primary exports from the sqlsaber package:

Export	Purpose
SQLSaber	Conversation lifecycle for the CLI, TUI, and SDK.
SQLSaberOptions	Typed options bag for a SQLSaber session.
SqlTools	SQL capability for an agent you own.
Knowledge	Database-scoped knowledge search capability.
ArtifactStore	Protocol for immutable artifact publication and authorized retrieval.
FilesystemArtifactStore	Durable private local artifact store for CLI and server development.
InMemoryArtifactStore	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 to add capabilities to the managed agent. See Build an agent that keeps complete SQL results to store and reload complete execute_sql rows. See Results and streaming for artifact publishing.

Installation

The SDK ships in the main package. No extra install is 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 that holds 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, for example through 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.

• 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; include the bundled handoff capability in your options.
• 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.

Close the connection

SQLSaber owns a live database connection. Use it as an async context manager so the connection closes 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 with saber auth, and any provider environment variables such as ANTHROPIC_API_KEY. Pass keys in code when you do not want CLI or keyring storage. See Credentials and models.

Next steps

1. Configuration for every SQLSaberOptions field
2. Credentials and models for auth and model selection
3. Results and streaming for SQL, usage, and stream events
4. Advanced for capability models, custom prompts, and write access