sqlsaber 0.38.0__tar.gz → 0.47.1__tar.gz

{sqlsaber-0.38.0 → sqlsaber-0.47.1}/AGENTS.md

@@ -7,13 +7,15 @@
   - `tools/`: SQL, introspection, registry.
   - `database/`: connection, resolver, schema utilities.
   - `memory/`, `conversation/`: state and persistence.
-  - `config/`: settings, API keys, OAuth, DB configs.
+  - `config/`: settings, API keys, DB configs.
 - Tests: `tests/` mirror modules (`test_cli/`, `test_tools/`, …).
 - Docs & assets: `docs/`, `sqlsaber.gif`, `sqlsaber.svg`.
 
 ## Build, Test, and Development Commands
 - Install (editable): `uv sync`
 - Lint: `uv run ruff check .`
+- Type check (all): `uvx ty check src/`
+- Type check (targeted): `uvx ty check <file>`
 - Format: `uv run ruff format .`
 - Tests (all): `uv run pytest -q`
 - Tests (targeted): `uv run pytest tests/test_tools -q`
@@ -23,7 +25,8 @@
 Note: Prefer `uv run ruff ...` over `uvx ruff ...` to avoid hitting user-level uv caches that may be restricted in sandboxed environments.
 
 ## Coding Style & Naming Conventions
-- Python 3.12+, 4‑space indent, use modern type hints.
+- Python 3.12+, 4‑space indent, strictly use modern (3.12+) type hints approach.
+  - Type check must pass without errors always.
 - Ruff is the linter/formatter; code must be clean and formatted.
 - Naming: modules/files `snake_case.py`; classes `PascalCase`; functions/vars `snake_case`; constants `UPPER_SNAKE`.
 - Keep public CLI surfaces in `cli/`; factor reusable logic into modules under `sqlsaber/`.
@@ -33,12 +36,4 @@ Note: Prefer `uv run ruff ...` over `uvx ruff ...` to avoid hitting user-level u
 - Place tests under `tests/`, name files `test_*.py` and mirror package layout.
 - Include tests for new behavior and bug fixes; prefer async tests for async code.
 - Use fixtures from `tests/conftest.py` where possible.
-
-## Commit & Pull Request Guidelines
-- Commits: short, imperative; prefer conventional prefixes (e.g., `feat:`, `fix:`, `docs:`). Reference issues/PRs when relevant.
-- PRs must: describe the change and rationale, include tests, pass `ruff` and `pytest`, and update docs/README for user‑visible changes.
-- For CLI UX changes, include before/after samples (command + output snippet).
-
-## Security & Configuration Tips
-- Never commit secrets. Configure via CLI: `saber db add` and `saber models set` (credentials stored via system keyring).
-- Queries run read‑only by default; avoid introducing mutating behavior in tools without explicit safeguards.
+- Tests must pass without errors always.

{sqlsaber-0.38.0 → sqlsaber-0.47.1}/CLAUDE.md

@@ -3,6 +3,8 @@
 - **Run Python**: `uv run python`
 - **Run tests**: `uv run python -m pytest`
 - **Run single test**: `uv run python -m pytest tests/test_path/test_file.py::test_function`
+- **Type check (all)**: `uvx ty check src/`
+- **Type check (targeted)**: `uvx ty check <file>`
 - **Lint**: `uv run ruff check --fix`
 - **Format**: `uv run ruff format`
 
@@ -16,6 +18,7 @@
 
 - **Imports**: stdlib → 3rd party → local, use relative imports within modules
 - **Naming**: snake_case functions/vars, PascalCase classes, UPPER_SNAKE constants, `_private` methods
-- **Types**: Always use modern type hints (3.12+), async functions for I/O
+- **Types**: Always use ONLY modern type hints (3.12+), async functions for I/O
+  - Type check must pass without errors always
 - **Errors**: Use try/finally for cleanup
 - **Docstrings**: Triple-quoted with Args/Returns sections

sqlsaber-0.47.1/PKG-INFO

@@ -0,0 +1,149 @@
+Metadata-Version: 2.4
+Name: sqlsaber
+Version: 0.47.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: 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: prompt-toolkit>3.0.51
+Requires-Dist: pydantic-ai
+Requires-Dist: questionary>=2.1.0
+Requires-Dist: rich>=13.7.0
+Requires-Dist: sqlglot[rs]>=27.20.0
+Requires-Dist: structlog>=25.4.0
+Requires-Dist: tabulate>=0.9.0
+Description-Content-Type: text/markdown
+
+# SQLsaber
+
+> SQLsaber is an open-source agentic SQL assistant. Think Claude Code but for SQL.
+
+**Ask questions about your data in plain English. SQLsaber writes SQL queries, executes them, and explains the results.**
+
+![demo](./sqlsaber.gif)
+
+SQLsaber reads your schema, writes SQL, executes it, and explains the results—all from a single natural language prompt.
+
+```bash
+$ saber "How many orders were placed last month?"
+
+# SQLsaber will:
+# 1. Discover relevant tables (orders, order_items, etc.)
+# 2. Analyze their schema
+# 3. Generate and run SQL
+# 4. Return results with explanation
+```
+
+## Why SQLsaber?
+
+- **No context switching** — Stay in your terminal, ask questions, get answers
+- **Schema-aware** — Automatically introspects your database; no manual setup
+- **Safe by default** — Read-only queries; won't modify your data
+- **Works with your stack** — PostgreSQL, MySQL, SQLite, DuckDB, and CSV files
+
+## Install
+
+```bash
+# Recommended
+uv tool install sqlsaber
+
+# Or with pipx
+pipx install sqlsaber
+```
+
+Then run:
+
+```bash
+saber
+```
+
+On first launch, SQLsaber walks you through connecting a database and setting up authentication.
+
+## Quick Examples
+
+```bash
+# Interactive mode
+saber
+
+# Single query
+saber "show me users who signed up this week"
+
+# Pipe from stdin
+echo "top 10 customers by revenue" | saber
+
+# Use a specific database
+saber -d mydb "count active subscriptions"
+```
+
+## Features
+
+| Feature | Description |
+|---------|-------------|
+| **Schema introspection** | Discovers tables, columns, and relationships automatically |
+| **Conversation memory** | Add context like "dates are stored as Unix timestamps" |
+| **Thread history** | Resume past conversations with `saber threads resume` |
+| **Extended thinking** | Enable `--thinking` for complex analytical queries |
+| **Multiple AI providers** | Anthropic, OpenAI, Google, Groq (Claude Sonnet 4 by default) |
+
+## Configuration
+
+### Add a database
+
+```bash
+saber db add mydb
+# Prompts for connection details
+```
+
+Or pass a connection string directly:
+
+```bash
+saber -d "postgresql://user:pass@localhost:5432/mydb" "count users"
+```
+
+### Change AI model
+
+```bash
+saber models set
+```
+
+### Add memory (context for your database)
+
+```bash
+saber memory add "customer_id in orders table references users.id"
+saber memory add "all timestamps are UTC"
+```
+
+## How It Works
+
+1. **Discovery** — Lists tables and identifies relevant ones based on your question
+2. **Schema analysis** — Introspects only the tables needed
+3. **Query generation** — Writes SQL tailored to your database dialect
+4. **Execution** — Runs read-only queries with safety checks
+5. **Results** — Formats output with explanations
+
+## 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/)
+- [Command Reference](https://sqlsaber.com/reference/commands/)
+
+## Contributing
+
+Contributions welcome! Please open an issue first to discuss changes.
+
+If you find SQLsaber useful, a ⭐ on GitHub helps others discover it.
+
+## License
+
+Apache-2.0 — see [LICENSE](./LICENSE)

sqlsaber-0.47.1/README.md

@@ -0,0 +1,125 @@
+# SQLsaber
+
+> SQLsaber is an open-source agentic SQL assistant. Think Claude Code but for SQL.
+
+**Ask questions about your data in plain English. SQLsaber writes SQL queries, executes them, and explains the results.**
+
+![demo](./sqlsaber.gif)
+
+SQLsaber reads your schema, writes SQL, executes it, and explains the results—all from a single natural language prompt.
+
+```bash
+$ saber "How many orders were placed last month?"
+
+# SQLsaber will:
+# 1. Discover relevant tables (orders, order_items, etc.)
+# 2. Analyze their schema
+# 3. Generate and run SQL
+# 4. Return results with explanation
+```
+
+## Why SQLsaber?
+
+- **No context switching** — Stay in your terminal, ask questions, get answers
+- **Schema-aware** — Automatically introspects your database; no manual setup
+- **Safe by default** — Read-only queries; won't modify your data
+- **Works with your stack** — PostgreSQL, MySQL, SQLite, DuckDB, and CSV files
+
+## Install
+
+```bash
+# Recommended
+uv tool install sqlsaber
+
+# Or with pipx
+pipx install sqlsaber
+```
+
+Then run:
+
+```bash
+saber
+```
+
+On first launch, SQLsaber walks you through connecting a database and setting up authentication.
+
+## Quick Examples
+
+```bash
+# Interactive mode
+saber
+
+# Single query
+saber "show me users who signed up this week"
+
+# Pipe from stdin
+echo "top 10 customers by revenue" | saber
+
+# Use a specific database
+saber -d mydb "count active subscriptions"
+```
+
+## Features
+
+| Feature | Description |
+|---------|-------------|
+| **Schema introspection** | Discovers tables, columns, and relationships automatically |
+| **Conversation memory** | Add context like "dates are stored as Unix timestamps" |
+| **Thread history** | Resume past conversations with `saber threads resume` |
+| **Extended thinking** | Enable `--thinking` for complex analytical queries |
+| **Multiple AI providers** | Anthropic, OpenAI, Google, Groq (Claude Sonnet 4 by default) |
+
+## Configuration
+
+### Add a database
+
+```bash
+saber db add mydb
+# Prompts for connection details
+```
+
+Or pass a connection string directly:
+
+```bash
+saber -d "postgresql://user:pass@localhost:5432/mydb" "count users"
+```
+
+### Change AI model
+
+```bash
+saber models set
+```
+
+### Add memory (context for your database)
+
+```bash
+saber memory add "customer_id in orders table references users.id"
+saber memory add "all timestamps are UTC"
+```
+
+## How It Works
+
+1. **Discovery** — Lists tables and identifies relevant ones based on your question
+2. **Schema analysis** — Introspects only the tables needed
+3. **Query generation** — Writes SQL tailored to your database dialect
+4. **Execution** — Runs read-only queries with safety checks
+5. **Results** — Formats output with explanations
+
+## 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/)
+- [Command Reference](https://sqlsaber.com/reference/commands/)
+
+## Contributing
+
+Contributions welcome! Please open an issue first to discuss changes.
+
+If you find SQLsaber useful, a ⭐ on GitHub helps others discover it.
+
+## License
+
+Apache-2.0 — see [LICENSE](./LICENSE)

{sqlsaber-0.38.0 → sqlsaber-0.47.1}/docs/astro.config.mjs

@@ -10,6 +10,17 @@ export default defineConfig({
 		starlight({
 			title: "SQLsaber",
 			customCss: ["./src/styles/global.css"],
+			head: [
+				{
+					tag: "script",
+					attrs: {
+						defer: true,
+						src: "https://umami.sarthakjariwala.com/script.js",
+						"data-website-id": "72be4739-0d77-4d79-be5b-cf31a62bca87",
+						"data-domains": "sqlsaber.com",
+					},
+				},
+			],
 			social: [
 				{
 					icon: "github",

{sqlsaber-0.38.0 → sqlsaber-0.47.1}/docs/src/content/docs/changelog.md

@@ -9,6 +9,116 @@ All notable changes to SQLsaber will be documented here.
 
 ---
 
+### v0.47.1
+
+#### Fixed
+
+- Fixed rendering of update text
+
+---
+
+### v0.47.0 - 2026-01-12
+
+#### Added
+
+- CLI: allow multiple CSVs via repeated `-d` (each CSV becomes its own DuckDB view)
+- CLI: `saber threads resume` now accepts multiple `-d` CSVs
+- Python API: `SQLSaber(database=[...])` now accepts multiple CSVs
+- CSV view names are derived from file stems; collisions are suffixed (`_2`, `_3`, ...)
+
+---
+
+### v0.46.1
+
+#### Fixed
+
+- Fixed rendering of update text
+
+---
+
+### v0.46.0 - 2026-01-11
+
+#### Added
+
+- Python API: add `memory` parameter to inject session context (accepts text or a file path)
+- Agent: prefer passed `memory` over saved database memories
+
+---
+
+### v0.45.0 - 2026-01-11
+
+#### Added
+
+- New version check on startup
+
+---
+
+### v0.44.0 - 2026-01-10
+
+#### Removed
+
+- Removed Anthropic OAuth (Claude Pro/Max subscription) authentication support; Anthropic now requires an API key.
+
+#### Changed
+
+- `saber auth setup` / onboarding now configure API keys only
+- `saber auth reset` now removes stored API keys only
+
+---
+
+### v0.43.0 - 2025-01-08
+
+#### Added
+
+- `saber threads export` command to export thread transcripts as shareable HTML files
+  - Dark and light theme support with toggle button
+  - Syntax highlighting for SQL queries
+  - Renders markdown content with code blocks, tables, and formatting
+  - Tool results displayed as collapsible sections with formatted tables
+  - Schema introspection results show columns, types, keys, and comments
+  - Includes thread metadata: database, model, timestamps
+  - Usage: `saber threads export <thread-id> [-o output.html]`
+
+---
+
+### v0.42.0 - 2025-01-05
+
+#### Added
+
+- Session usage summary displayed on exit
+  - Shows input context size (current tokens), total output tokens generated
+  - Displays request count and tool call count
+  - Summary shown when exiting via `/exit`, `/quit`, or Ctrl+D
+  - Also displayed after single-query (non-interactive) mode
+
+---
+
+### v0.41.0 - 2025-12-25
+
+#### Changed
+
+- Simplified event stream handling in agent and API modules
+
+### v0.40.0 - 2025-12-24
+
+#### Added
+
+- `--allow-dangerous` flag to enable INSERT/UPDATE/DELETE and DDL operations
+  - Allows a restricted set of DML operations: INSERT, UPDATE, DELETE, MERGE, REPLACE
+  - Allows non-destructive DDL operations: CREATE, ALTER
+  - Always blocks dangerous operations: DROP, TRUNCATE, transaction control, GRANT/REVOKE
+  - Works in both single query and interactive modes
+
+### v0.39.0 - 2025-12-15
+
+#### Added
+
+- Python API now supports `model_name` and `api_key` parameters for programmatic model configuration
+  - Override configured model: `SQLSaber(database="...", model_name="anthropic:claude-sonnet-4-20250514")`
+  - Override configured model and API key: `SQLSaber(database="...", model_name="anthropic:claude-sonnet-4-20250514", api_key="sk-...")`
+  - Falls back to OAuth if `api_key` is not provided but OAuth is configured
+
+
 ### v0.38.0 - 2025-12-01
 
 #### Changed

{sqlsaber-0.38.0 → sqlsaber-0.47.1}/docs/src/content/docs/guides/authentication.mdx

@@ -3,15 +3,15 @@ title: Authentication
 description: Configure LLM provider authentication for SQLsaber
 ---
 
-import { Aside } from '@astrojs/starlight/components';
+import { Aside } from "@astrojs/starlight/components";
 
 SQLsaber supports multiple LLM providers.
 
 ### Providers
 
-SQLsaber supports the following LLM providers and authentication methods:
+SQLsaber supports the following LLM providers:
 
-- **Anthropic** - API key or Claude Pro/Max subscription
+- **Anthropic** - API key
 - **OpenAI** - API key
 - **Google** - API key
 - **Groq** - API key
@@ -20,7 +20,8 @@ SQLsaber supports the following LLM providers and authentication methods:
 - **Hugging Face** - API key
 
 <Aside type="note">
-    API keys and OAuth tokens securely using your operating system's credentials store.
+  SQLsaber stores API keys securely using your operating system's credentials
+  store.
 </Aside>
 
 ### Quick Setup
@@ -32,25 +33,14 @@ saber auth setup
 ```
 
 This interactive command will:
+
 1. Let you choose your AI provider
-2. Guide you through the authentication process
+2. Prompt you for an API key (or use an existing environment variable)
 3. Securely store your credentials
 
 #### Anthropic
 
-SQLsaber uses Claude Sonnet 4 by default and supports two authentication methods:
-
-##### Claude Pro/Max subscription (Recommended)
-
-> If you have a Claude Pro or Max subscription, you can use it with SQLsaber:
-
-1. Run the setup:
-   ```bash
-   saber auth setup
-   ```
-2. Choose "Anthropic" as your provider
-3. Select "Claude Pro/Max (OAuth)" as the authentication method
-4. Follow the browser-based OAuth flow
+SQLsaber uses Claude Sonnet 4 by default.
 
 ##### API Key
 
@@ -60,13 +50,9 @@ SQLsaber uses Claude Sonnet 4 by default and supports two authentication methods
    saber auth setup
    ```
 3. Choose "Anthropic" as your provider
-4. Select "API key" as the authentication method
-5. Enter your API key when prompted
-
-<Aside type="note">
-Follow the same steps for setting up other providers.
-</Aside>
+4. Enter your API key when prompted
 
+<Aside type="note">Follow the same steps for setting up other providers.</Aside>
 
 ### Managing Authentication
 
@@ -79,8 +65,9 @@ saber auth status
 ```
 
 This shows:
-- Currently configured providers
-- Authentication methods (API key vs OAuth)
+
+- Configured providers
+- Whether a provider is configured via environment variable or keychain
 
 #### Reset Authentication
 
@@ -91,8 +78,9 @@ saber auth reset
 ```
 
 This will:
+
 1. Ask you to select which provider to reset
-2. Remove API keys from your OS credentials store
+2. Remove the stored API key from your OS credentials store
 
 ### Multiple Providers
 
@@ -103,6 +91,7 @@ You can configure multiple providers and switch between them when selecting mode
 You can also use environment variables for setting API keys.
 
 Example:
+
 ```bash
 # Anthropic
 export ANTHROPIC_API_KEY="your-api-key"

{sqlsaber-0.38.0 → sqlsaber-0.47.1}/docs/src/content/docs/guides/database-setup.mdx

@@ -106,18 +106,19 @@ saber db remove my-database
 
 ### Security
 
-#### Read-only Access
+#### Read-only by Default
 
-> **If you are using SQLsaber with a production database, we recommend setting up a read-only role for your database and using those credentials to setup connection in SQLsaber.**
+SQLsaber blocks all write operations (INSERT, UPDATE, DELETE, DDL) by default. Only SELECT queries are allowed unless you explicitly enable dangerous mode with `--allow-dangerous`.
+
+Even in dangerous mode, destructive operations like DROP, TRUNCATE, and GRANT/REVOKE are always blocked.
 
-While SQLsaber ensures, via checks before executing queries, that only read queries are executed and in our testing have observed that LLMs follow the system prompt of only generating read queries, there is no guarantee that this is fool-proof.
+#### Read-only Database Role
 
-<Aside type="tip">
-If you have a read-replica of your production database, consider using those credentials to setup connection.
+> **If you are using SQLsaber with a production database, we recommend setting up a read-only role for your database and using those credentials to setup connection in SQLsaber.**
 
-In addition to the read-only role, this will provide additional layer of security and ensure no data modifying queries are executed.
+SQLsaber uses AST-based validation (via sqlglot) to analyze every query before execution. This catches write operations in nested queries, CTEs, subqueries, and dialect-specific dangerous functions. However, no validation is fool-proof.
 
-</Aside>
+**The most secure approach is to create a read-only database role and use those credentials with SQLsaber.** This provides database-level enforcement that cannot be bypassed regardless of what queries are generated.
 
 <Aside type="note">
   For development setups, this isn't required but is a good practice if you wish