Metadata-Version: 2.5
Name: sqlsaber
Version: 0.78.1
Summary: SQLsaber - Open-source agentic SQL assistant
License-File: LICENSE
Requires-Python: >=3.12
Requires-Dist: aiomysql>=0.2.0
Requires-Dist: aiosqlite>=0.21.0
Requires-Dist: asyncpg>=0.30.0
Requires-Dist: cyclopts>=3.22.1
Requires-Dist: duckdb>=0.9.2
Requires-Dist: genai-prices>=0.0.57
Requires-Dist: httpx>=0.28.1
Requires-Dist: keyring>=25.6.0
Requires-Dist: keyrings-cryptfile; sys_platform == 'linux'
Requires-Dist: platformdirs>=4.0.0
Requires-Dist: pydantic-ai[cohere,groq,huggingface,mistral,xai]<3,>=2.9
Requires-Dist: saber-tui>=0.6.0
Requires-Dist: sqlglot[c]>=30.1.0
Requires-Dist: structlog>=25.4.0
Requires-Dist: tabulate>=0.9.0
Description-Content-Type: text/markdown

# SQLsaber

[![PyPI](https://img.shields.io/pypi/v/sqlsaber.svg)](https://pypi.org/project/sqlsaber/)
[![Docs](https://img.shields.io/badge/docs-sqlsaber.com-blue)](https://sqlsaber.com)

SQLsaber is an open-source agentic SQL assistant. Ask questions about databases, SQLite or DuckDB files, CSVs, and Parquet files in plain English from your terminal or from Python. SQLsaber reads your schema, writes SQL, runs read-only queries by default, and explains the results.

The CLI and TUI use the `SQLSaber` conversation lifecycle. Clients own input and presentation. `SQLSaber` owns agent behavior, completed history, and thread lifecycle.

[![SQLsaber demo showing a natural language database query in the terminal](https://asciinema.org/a/1265197.svg)](https://asciinema.org/a/1265197)

SQLsaber appears in an ACM Conference on AI and Agentic Systems '26 paper. [Read the paper](https://dl.acm.org/doi/10.1145/3786335.3813217).

## Quickstart

```bash
# Recommended if you have uv
uv tool install sqlsaber

# If you do not have uv
curl -LsSf https://uvx.sh/sqlsaber/install.sh | sh
```

On Windows without uv:

```powershell
powershell -ExecutionPolicy ByPass -c "irm https://uvx.sh/sqlsaber/install.ps1 | iex"
```

Try SQLsaber with the sample SQLite database:

```bash
curl -L -o legislators.db https://github.com/SarthakJariwala/sqlsaber/raw/refs/heads/main/legislators.db

saber -d ./legislators.db "How many VPs became president by election in the 20th century?"
```

Or connect your own database:

```bash
saber db add analytics
saber "Show me revenue by month"
```

On first launch, SQLsaber walks you through connecting a database and setting up authentication.

## Use it with your data

```bash
# Interactive mode
saber

# Single question
saber "show me users who signed up this week"

# Pipe from stdin
echo "top 10 customers by revenue" | saber

# Use a saved database connection
saber -d analytics "count active subscriptions"

# Use a connection string directly
saber -d "postgresql://user:pass@localhost:5432/mydb" "count users"

# Query local files
saber -d ./customers.csv "How many customers are from each state?"
saber -d ./orders.parquet "What is total revenue?"
saber -d ./warehouse.duckdb "Show me the latest partition"

# Join CSV and Parquet files using DuckDB
saber -d ./customers.csv -d ./orders.parquet "Revenue by customer"

# Connect several databases in one session
saber -d sales -d analytics "Compare last month's revenue to web sessions"
```

## Why SQLsaber?

- **No context switching.** Stay in your terminal, ask questions, and get answers.
- **Schema-aware.** Discovers tables, columns, indexes, comments, and relationships.
- **Safe by default.** Runs read-only queries unless you pass `--allow-dangerous`.
- **Works with your stack.** PostgreSQL, MySQL, SQLite, DuckDB, CSV, and Parquet files.
- **Remembers your work.** Resume previous analysis with conversation threads.
- **Learns your business context.** Store KPI definitions, SQL patterns, and domain notes in a searchable knowledge base.
- **Flexible model support.** Anthropic, OpenAI, Google, Groq, xAI, Mistral, Cohere, Hugging Face, and other supported providers.

## Common workflows

| Workflow | Command |
| --- | --- |
| Explore data interactively | `saber` |
| Ask a one-off question | `saber "monthly active users"` |
| Analyze a CSV | `saber -d ./customers.csv "customers by state"` |
| Compare several databases | `saber -d sales -d analytics "compare revenue to traffic"` |
| Save a KPI definition | `saber knowledge add "Revenue KPI" "Recognized revenue from shipped orders only"` |
| Resume previous analysis | `saber threads list` then `saber threads resume <id>` |
| Automate a thread follow-up | `saber --thread <id> "compare with last quarter"` |
| Use deeper reasoning | `saber --thinking "analyze retention by cohort"` |

## Knowledge base

Save reusable business context so SQLsaber can answer consistently:

```bash
saber knowledge add \
  "Revenue KPI" \
  "Recognized revenue from shipped orders only" \
  --sql "SELECT SUM(amount) FROM orders WHERE status = 'shipped'" \
  --source "finance-wiki"

saber knowledge search "revenue shipped orders"
```

Knowledge entries are scoped per database and are discovered automatically when relevant.

## Optional plugins

Install official plugins alongside SQLsaber:

```bash
# Render charts in your terminal
uv tool install --with sqlsaber-viz sqlsaber

# Delegate multi-step analysis to a sandboxed notebook agent
uv tool install --with sqlsaber-notebook sqlsaber

# Run one-off Python snippets in a remote sandbox
uv tool install --with sqlsaber-sandbox sqlsaber

# Install all official analysis plugins
uv tool install --with sqlsaber-viz,sqlsaber-notebook,sqlsaber-sandbox sqlsaber
```

## Python SDK

Use the same `SQLSaber` conversation lifecycle from Python scripts, notebooks, web apps, or pipelines. A second `saber.query()` on the same instance uses the prior completed history automatically:

```python
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("Top 5 customers by revenue")
        print(result.text)
        print(result.usage)

        follow_up = await saber.query("Now show the same customers by country")
        print(follow_up.text)


asyncio.run(main())
```

Or compose SQLsaber's tools into an agent you own:

```python
from pydantic_ai import Agent
from sqlsaber import SqlTools

sql = SqlTools(database="sqlite:///my.db")
agent = Agent(
    "anthropic:claude-sonnet-4-6",
    instructions="You are my analytics copilot.",
    capabilities=[sql],
)

async with agent:  # opens and closes connections owned by SqlTools
    result = await agent.run("Top 5 customers by revenue")
```

See the [Capabilities guide](https://sqlsaber.com/sdk/capabilities/) for multi-database use, knowledge search, custom capabilities, and lifecycle details.

## How it works

1. **Discovery.** Lists tables and identifies relevant ones based on your question.
2. **Schema analysis.** Introspects only the tables needed.
3. **Knowledge retrieval.** Searches saved KPI definitions and SQL patterns when useful.
4. **Query generation.** Writes SQL tailored to your database dialect.
5. **Execution.** Runs the query with safety checks.
6. **Results.** Formats the output with an explanation.

## Documentation

Full docs at [sqlsaber.com](https://sqlsaber.com):

- [Installation](https://sqlsaber.com/installation/)
- [Getting started](https://sqlsaber.com/guides/getting-started/)
- [Database setup](https://sqlsaber.com/guides/database-setup/)
- [Running queries](https://sqlsaber.com/guides/queries/)
- [Multiple databases](https://sqlsaber.com/guides/multi-database/)
- [Knowledge base](https://sqlsaber.com/guides/knowledge/)
- [Plugins](https://sqlsaber.com/guides/plugins/)
- [Python SDK](https://sqlsaber.com/sdk/overview/)
- [Command reference](https://sqlsaber.com/reference/commands/)

## Contributing

Open an issue before large changes.

If you find SQLsaber useful, a star on GitHub helps others discover it.

## License

Apache-2.0. See [LICENSE](./LICENSE).
