sqlsaber 0.10.0__tar.gz → 0.47.1__tar.gz

sqlsaber-0.47.1/.github/workflows/claude-code-review.yml

@@ -0,0 +1,77 @@
+name: Claude Code Review
+
+on:
+  pull_request:
+    types: [opened, synchronize]
+    # Optional: Only run on specific file changes
+    # paths:
+    #   - "src/**/*.ts"
+    #   - "src/**/*.tsx"
+    #   - "src/**/*.js"
+    #   - "src/**/*.jsx"
+
+jobs:
+  claude-review:
+    # Optional: Filter by PR author
+    # if: |
+    #   github.event.pull_request.user.login == 'external-contributor' ||
+    #   github.event.pull_request.user.login == 'new-developer' ||
+    #   github.event.pull_request.author_association == 'FIRST_TIME_CONTRIBUTOR'
+
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      pull-requests: read
+      issues: read
+      id-token: write
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 1
+
+      - name: Run Claude Code Review
+        id: claude-review
+        uses: anthropics/claude-code-action@beta
+        with:
+          claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
+
+          # Optional: Specify model (defaults to Claude Sonnet 4, uncomment for Claude Opus 4)
+          # model: "claude-opus-4-20250514"
+
+          # Direct prompt for automated review (no @claude mention needed)
+          direct_prompt: |
+            Please review this pull request and provide feedback on:
+            - Code quality and best practices
+            - Potential bugs or issues
+            - Performance considerations
+            - Security concerns
+            - Test coverage
+
+            Be constructive and helpful in your feedback.
+
+          # Optional: Use sticky comments to make Claude reuse the same comment on subsequent pushes to the same PR
+          # use_sticky_comment: true
+
+          # Optional: Customize review based on file types
+          # direct_prompt: |
+          #   Review this PR focusing on:
+          #   - For TypeScript files: Type safety and proper interface usage
+          #   - For API endpoints: Security, input validation, and error handling
+          #   - For React components: Performance, accessibility, and best practices
+          #   - For tests: Coverage, edge cases, and test quality
+
+          # Optional: Different prompts for different authors
+          # direct_prompt: |
+          #   ${{ github.event.pull_request.author_association == 'FIRST_TIME_CONTRIBUTOR' &&
+          #   'Welcome! Please review this PR from a first-time contributor. Be encouraging and provide detailed explanations for any suggestions.' ||
+          #   'Please provide a thorough code review focusing on our coding standards and best practices.' }}
+
+          # Optional: Add specific tools for running tests or linting
+          # allowed_tools: "Bash(npm run test),Bash(npm run lint),Bash(npm run typecheck)"
+
+        # Optional: Skip review for certain conditions
+        if: |
+          !contains(github.event.pull_request.title, '[skip-review]') &&
+          !contains(github.event.pull_request.title, '[WIP]')

sqlsaber-0.47.1/.github/workflows/claude.yml

@@ -0,0 +1,64 @@
+name: Claude Code
+
+on:
+  issue_comment:
+    types: [created]
+  pull_request_review_comment:
+    types: [created]
+  issues:
+    types: [opened, assigned]
+  pull_request_review:
+    types: [submitted]
+
+jobs:
+  claude:
+    if: |
+      (github.event_name == 'issue_comment' && contains(github.event.comment.body, '@claude')) ||
+      (github.event_name == 'pull_request_review_comment' && contains(github.event.comment.body, '@claude')) ||
+      (github.event_name == 'pull_request_review' && contains(github.event.review.body, '@claude')) ||
+      (github.event_name == 'issues' && (contains(github.event.issue.body, '@claude') || contains(github.event.issue.title, '@claude')))
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      pull-requests: read
+      issues: read
+      id-token: write
+      actions: read # Required for Claude to read CI results on PRs
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 1
+
+      - name: Run Claude Code
+        id: claude
+        uses: anthropics/claude-code-action@beta
+        with:
+          claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
+
+          # This is an optional setting that allows Claude to read CI results on PRs
+          additional_permissions: |
+            actions: read
+          
+          # Optional: Specify model (defaults to Claude Sonnet 4, uncomment for Claude Opus 4)
+          # model: "claude-opus-4-20250514"
+          
+          # Optional: Customize the trigger phrase (default: @claude)
+          # trigger_phrase: "/claude"
+          
+          # Optional: Trigger when specific user is assigned to an issue
+          # assignee_trigger: "claude-bot"
+          
+          # Optional: Allow Claude to run specific commands
+          # allowed_tools: "Bash(npm install),Bash(npm run build),Bash(npm run test:*),Bash(npm run lint:*)"
+          
+          # Optional: Add custom instructions for Claude to customize its behavior for your project
+          # custom_instructions: |
+          #   Follow our coding standards
+          #   Ensure all new code has tests
+          #   Use TypeScript for new files
+          
+          # Optional: Custom environment variables for Claude
+          # claude_env: |
+          #   NODE_ENV: test
+

sqlsaber-0.47.1/.github/workflows/deploy-docs.yml

@@ -0,0 +1,34 @@
+name: Deploy docs to GitHub Pages
+
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+# Allow this job to clone the repo and create a page deployment
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout your repository using git
+        uses: actions/checkout@v4
+      - name: Install, build, and upload your site
+        uses: withastro/action@v3
+        with:
+          path: docs/
+
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

sqlsaber-0.47.1/.github/workflows/test.yml

@@ -0,0 +1,33 @@
+name: Tests
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+# Cancel active CI runs for a PR before starting another run
+concurrency:
+  group: ${{ github.workflow}}-${{ github.ref }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install dependencies
+        run: uv sync --locked --all-extras --dev
+
+      - name: Run tests
+        run: uv run python -m pytest

sqlsaber-0.47.1/AGENTS.md

@@ -0,0 +1,39 @@
+# Repository Guidelines
+
+## Project Structure & Module Organization
+- Source: `src/sqlsaber/`
+  - `cli/`: CLI entry (`saber`, `sqlsaber`), REPL, prompts.
+  - `agents/`: agent implementations (pydantic‑ai).
+  - `tools/`: SQL, introspection, registry.
+  - `database/`: connection, resolver, schema utilities.
+  - `memory/`, `conversation/`: state and persistence.
+  - `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`
+- Run CLI (dev): `uv run saber` or `uv run python -m sqlsaber`
+
+
+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, 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/`.
+
+## Testing Guidelines
+- Framework: `pytest` with `pytest-asyncio`.
+- 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.
+- Tests must pass without errors always.

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

@@ -3,20 +3,22 @@
 - **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`
 
 ## Architecture
 
 - **CLI App**: Agentic SQL assistant for natural language to SQL
-- **Core modules**: `agents/` (AI logic), `cli/` (commands), `clients/` (LLM clients), `database/` (connections), `mcp/` (Model Context Protocol server)
+- **Core modules**: `agents/` (AI logic), `cli/` (commands), `database/` (connections)
 - **Database support**: PostgreSQL, SQLite, MySQL via asyncpg/aiosqlite/aiomysql
-- **MCP integration**: Exposes tools via `sqlsaber-mcp` for Claude Code and other MCP clients
 
 ## Code Style
 
 - **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
-- **Errors**: Custom exception hierarchy from `LLMClientError`, use try/finally for cleanup
+- **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.47.1/docs/.gitignore

@@ -0,0 +1,24 @@
+# build output
+dist/
+# generated types
+.astro/
+
+# dependencies
+node_modules/
+
+# logs
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+pnpm-debug.log*
+
+
+# environment variables
+.env
+.env.production
+
+# macOS-specific files
+.DS_Store
+
+# jetbrains setting folder
+.idea/

sqlsaber-0.47.1/docs/.vscode/extensions.json

@@ -0,0 +1,4 @@
+{
+  "recommendations": ["astro-build.astro-vscode"],
+  "unwantedRecommendations": []
+}

sqlsaber-0.47.1/docs/.vscode/launch.json

@@ -0,0 +1,11 @@
+{
+  "version": "0.2.0",
+  "configurations": [
+    {
+      "command": "./node_modules/.bin/astro dev",
+      "name": "Development server",
+      "request": "launch",
+      "type": "node-terminal"
+    }
+  ]
+}

sqlsaber-0.47.1/docs/CLAUDE.md

@@ -0,0 +1,40 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Commands
+
+- **Development server**: `npm run dev` or `npm start`
+- **Build documentation**: `npm run build`
+- **Preview built site**: `npm run preview`
+
+## Architecture
+
+- **Documentation Site**: Built with Astro and Starlight for SQLsaber project documentation
+- **Framework**: Astro 5.x with Starlight integration for documentation structure
+- **Styling**: TailwindCSS 4.x with Starlight-specific Tailwind integration
+- **Content**: MDX files in `src/content/docs/` for documentation pages
+- **Assets**: Static images and SVGs in `src/assets/` and `public/`
+
+## Project Context
+
+This is the documentation website (`/docs`) for SQLsaber, an open-source agentic SQL assistant. The main SQLsaber Python project is in the parent directory with its own development workflow using uv/Python.
+
+Key documentation areas:
+- Landing page: `src/content/docs/index.mdx` (splash template with hero section)
+- Guides: `src/content/docs/guides/` (tutorial content)
+- Reference: `src/content/docs/reference/` (API and technical reference)
+
+## Configuration Files
+
+- `astro.config.mjs`: Main Astro configuration with Starlight integration
+- `package.json`: Node.js dependencies and scripts
+- `tsconfig.json`: TypeScript configuration for the Astro project
+- Site URL configured for https://sqlsaber.com
+
+## Content Structure
+
+- Starlight sidebar automatically generates from `src/content/docs/` structure
+- Use `.mdx` extension for components in markdown
+- Use components available via `@astrojs/starlight/components`
+- Asciinema integration for terminal recordings/demos