dbagent-cli 0.10.0__tar.gz → 0.11.1__tar.gz

dbagent_cli-0.11.1/PKG-INFO

@@ -0,0 +1,291 @@
+Metadata-Version: 2.4
+Name: dbagent-cli
+Version: 0.11.1
+Summary: The Privacy-First AI Database Copilot, Schema Graph Introspector & Post-Commit Recovery Engine (CLI)
+Author: Santhosh Gupta
+License: MIT
+Project-URL: Homepage, https://github.com/santhoshgupta/dbagent-cli
+Project-URL: Documentation, https://github.com/santhoshgupta/dbagent-cli#readme
+Project-URL: Repository, https://github.com/santhoshgupta/dbagent-cli.git
+Project-URL: Issues, https://github.com/santhoshgupta/dbagent-cli/issues
+Keywords: database,sql,ai,llm,copilot,postgresql,mysql,sqlite,duckdb,mongodb,cli,introspection
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: System Administrators
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Database
+Classifier: Topic :: Database :: Front-Ends
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: typer>=0.9.0
+Requires-Dist: rich>=13.0.0
+Requires-Dist: prompt-toolkit>=3.0.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: sqlalchemy>=2.0.0
+Requires-Dist: requests>=2.28.0
+Requires-Dist: httpx>=0.24.0
+Requires-Dist: python-dotenv>=1.0.0
+Provides-Extra: postgres
+Requires-Dist: psycopg2-binary>=2.9.0; extra == "postgres"
+Provides-Extra: mysql
+Requires-Dist: pymysql>=1.0.0; extra == "mysql"
+Provides-Extra: mongo
+Requires-Dist: pymongo>=4.0.0; extra == "mongo"
+Provides-Extra: duckdb
+Requires-Dist: duckdb>=0.9.0; extra == "duckdb"
+Provides-Extra: all
+Requires-Dist: psycopg2-binary>=2.9.0; extra == "all"
+Requires-Dist: pymysql>=1.0.0; extra == "all"
+Requires-Dist: pymongo>=4.0.0; extra == "all"
+Requires-Dist: duckdb>=0.9.0; extra == "all"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.20.0; extra == "dev"
+Requires-Dist: build>=1.0.0; extra == "dev"
+Requires-Dist: twine>=4.0.0; extra == "dev"
+
+# ⚡ DB-Agent (`dbagent-cli`)
+
+> **The Privacy-First AI Database Copilot, Schema Graph Introspector & Post-Commit Recovery Engine**  
+> *Author: Santhosh Gupta | 100% Free, Standalone, Works 100% Offline (Ollama) or with Cloud AI (Claude 3.7 / GPT-4o / DeepSeek / Gemini / Groq).*
+
+[![PyPI Version](https://img.shields.io/pypi/v/dbagent-cli.svg)](https://pypi.org/project/dbagent-cli/)
+[![Python Versions](https://img.shields.io/pypi/pyversions/dbagent-cli.svg)](https://pypi.org/project/dbagent-cli/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Database Support](https://img.shields.io/badge/Databases-Postgres%20%7C%20MySQL%20%7C%20SQLite%20%7C%20DuckDB%20%7C%20MSSQL%20%7C%20Oracle%20%7C%20MongoDB-blue.svg)](https://pypi.org/project/dbagent-cli/)
+
+---
+
+## 🌟 What is DB-Agent?
+
+**DB-Agent** is an enterprise-ready, privacy-first database AI copilot that translates plain English into dialect-precise SQL, explores schemas on-demand (<30ms), enforces strict multi-tier safety guardrails, and captures pre-write snapshots allowing you to safely rollback database modifications days or weeks after `COMMIT`.
+
+```text
+"Show me the top 10 customers by order value"
+                      ↓
+           [ DB-Agent CLI Engine ]
+   (Targeted Schema Sub-Graph + AST Safety)
+                      ↓
+  SELECT c.customer_id, c.first_name, SUM(o.total_amount) AS total_spend
+  FROM customers c
+  JOIN orders o ON c.customer_id = o.customer_id
+  GROUP BY c.customer_id, c.first_name
+  ORDER BY total_spend DESC LIMIT 10;
+                      ↓
+            ⚡ Executed in 0.4s
+  ┌─────────────┬────────────┬─────────────┐
+  │ customer_id │ first_name │ total_spend │
+  ├─────────────┼────────────┼─────────────┤
+  │ 1           │ Alice      │ $3,450.00   │
+  │ 3           │ Claire     │ $2,198.50   │
+  └─────────────┴────────────┴─────────────┘
+```
+
+---
+
+## 🚀 5-Second Instant Trial (Zero Setup Required)
+
+Want to test DB-Agent without configuring a database or API keys?
+
+```bash
+# 1. Install DB-Agent
+pip install "dbagent-cli[all]"
+
+# 2. Launch built-in demo e-commerce database with interactive AI copilot
+db-agent demo
+```
+
+---
+
+## ⚡ 3-Minute Quickstart
+
+### 1. Install
+```bash
+pip install --upgrade "dbagent-cli[all]"
+```
+
+### 2. Configure AI Backend (1-Click Setup)
+```bash
+db-agent setup
+```
+Choose from 8 built-in providers:
+- **Local Ollama** (100% private, 100% offline with `qwen2.5-coder`, `llama3.3`, `deepseek-r1`)
+- **Google Gemini** (`gemini-3.6-flash`, `gemini-2.5-flash`)
+- **Anthropic Claude** (`claude-3-7-sonnet-20250219`, `claude-3-5-sonnet`)
+- **OpenAI ChatGPT** (`gpt-4o`, `gpt-4.5-preview`, `o3-mini`)
+- **DeepSeek AI** (`deepseek-chat` V3, `deepseek-reasoner` R1)
+- **Mistral AI** (`codestral-latest`, `mistral-large-latest`)
+- **Groq** (`llama-3.3-70b-versatile`)
+- **OpenRouter** (`meta-llama/llama-3.3-70b-instruct`)
+
+### 3. Connect Your Database
+```bash
+# Interactive guided connection
+db-agent connect
+
+# Or connect directly with an alias
+db-agent connect postgresql://user:password@localhost:5432/app_db --alias prod_db
+```
+
+### 4. Ask Plain English Questions
+```bash
+# One-off query:
+db-agent ask "count active users grouped by country" --db prod_db
+
+# CI/CD machine-readable JSON export:
+db-agent ask "count orders by status" --db prod_db --format json
+
+# Interactive Claude-Style Shell with live streaming & prompt queuing:
+db-agent chat --db prod_db
+```
+
+---
+
+## 📊 Database Compatibility Matrix
+
+| Database Engine | Introspection | Direct Queries | Multi-Hop JOINs | Transactions | 30-Day Recovery | Status |
+| :--- | :---: | :---: | :---: | :---: | :---: | :--- |
+| **PostgreSQL / CockroachDB** | ✓ | ✓ | ✓ | ✓ | ✓ | **Fully Supported** |
+| **MySQL / MariaDB** | ✓ | ✓ | ✓ | ✓ | ✓ | **Fully Supported** |
+| **SQLite** | ✓ | ✓ | ✓ | ✓ | ✓ | **Fully Supported** |
+| **DuckDB** | ✓ | ✓ | ✓ | ✓ | ✓ | **Fully Supported** |
+| **Microsoft SQL Server** | ✓ | ✓ | ✓ | ✓ | ✓ | **Fully Supported** |
+| **Oracle Database** | ✓ | ✓ | ✓ | ✓ | ✓ | **Fully Supported** |
+| **MongoDB** | ✓ (JSON) | ✓ (Filters) | N/A | ✓ | N/A | **Document Supported** |
+
+---
+
+## 🪟 Interactive Viewing & Data Grid Suite
+
+When querying wide enterprise tables with 20 to 60+ columns, DB-Agent provides 5 flexible viewing tools:
+
+| View Mode | In-Chat Command | Description |
+|---|---|---|
+| **Desktop GUI Grid** | `:window` / `:grid` | Native desktop window with horizontal/vertical scrolling, live search filters, and CSV export. |
+| **Browser Virtual Table** | `:web` / `:browser` | Self-contained HTML virtual data grid opened in default browser. |
+| **Horizontal Column Paging**| `:page <n>` | Browse wide column sets in clean horizontal slices (`:page 1`, `:page 2`). |
+| **Vertical Record Cards** | `:card` / `:v` | Renders rows as expanded vertical record cards. |
+| **Responsive Zoom View** | `:wide` | Expands across full terminal width. |
+
+---
+
+## 🛡️ 5 Operational Safety Tiers
+
+| Mode | Reads | Writes | DDL | Confirmation | Best For |
+| :--- | :---: | :---: | :---: | :---: | :--- |
+| **`SAFE`** | Allowed | **Blocked** | **Blocked** | None | Read-only analysis |
+| **`READ_ONLY`** | Allowed | **Blocked** | **Blocked** | None | **Production Environments** (5s timeout, 1,000 row cap) |
+| **`CONFIRM`** (Default) | Allowed | Allowed | Allowed | **Required** | Day-to-day development |
+| **`SANDBOX`** | Allowed | Uncommitted | Uncommitted | None | Dry-run testing with before/after diffs |
+| **`ADMIN`** | Allowed | Allowed | Allowed | None | Advanced DBAs |
+
+---
+
+## ⏪ Long-Term Post-Commit Recovery Engine
+
+Unlike standard database transactions that only protect uncommitted sessions, DB-Agent captures **pre-write row snapshots** before modifying data:
+
+```text
+User: "Update inactive customers to ACTIVE where created_at > '2025-01-01'"
+AI:   Modifying 42 rows. Capturing pre-write snapshot...
+      ✓ Change committed successfully (Change ID: CS-20260831-001)
+
+... 10 days later ...
+
+User: db-agent rollback CS-20260831-001 --db my_db
+AI:   Checking concurrency conflicts... No conflicting writes detected.
+      ✓ Restored 42 rows to their exact original state.
+```
+
+---
+
+## ⚡ Performance Benchmarks (`db-agent benchmark`)
+
+Reproducible benchmark metrics measured on standard hardware:
+
+```text
+Benchmark Category                   Latency / Metric        Rating
+─────────────────────────────────────────────────────────────────────────────
+Cold Schema Scan (6 tables)          12.4 ms                 ⚡ Ultra Fast (<50ms)
+Cached Schema Load                   0.08 ms                 ⚡ Sub-Millisecond
+Schema Cache Speedup                 155x faster             🚀 Verified
+BFS Multi-Hop Join Routing (3 hops)  0.15 ms                 ⚡ Sub-Millisecond
+Query Result Cache Hit               0.02 ms                 ⚡ Instant
+Process Memory Footprint             28.4 MB                 🟢 Lightweight
+```
+
+Run benchmarks locally:
+```bash
+db-agent benchmark
+```
+
+---
+
+## 🔌 Plugin & Extensibility Architecture
+
+Extend DB-Agent with custom database connectors or AI providers via standard Python entry points:
+
+```python
+# my_connector.py
+from dbagent.connectors.base import BaseConnector
+
+class ClickHouseConnector(BaseConnector):
+    # Implement test_connection, inspect_schema, execute_query
+    pass
+```
+
+In your package `pyproject.toml`:
+```toml
+[project.entry-points."dbagent.connectors"]
+clickhouse = "my_package:ClickHouseConnector"
+```
+
+---
+
+## 📖 CLI Command Reference
+
+| Command | Usage | Description |
+| :--- | :--- | :--- |
+| `demo` | `db-agent demo` | Instant zero-setup trial on sample e-commerce database. |
+| `ask` | `db-agent ask "prompt" --db alias` | Translates natural language to SQL and executes. |
+| `chat` | `db-agent chat --db alias` | Interactive AI copilot terminal REPL shell. |
+| `connect` | `db-agent connect <url> --alias name`| Tests credentials and saves database profile. |
+| `doctor` | `db-agent doctor --db alias` | Runs connectivity, schema, index, and latency health checks. |
+| `benchmark`| `db-agent benchmark` | Runs reproducible latency and memory benchmark suite. |
+| `examples` | `db-agent examples` | Displays categorized copy-paste prompt recipes. |
+| `rollback` | `db-agent rollback <id>` | Safely reverts post-commit write changes. |
+| `changes` | `db-agent changes` | Lists recorded write ChangeSets and recovery status. |
+| `scan` | `db-agent scan --db alias -o doc.md`| Introspects full schema and exports Markdown data catalog. |
+| `optimize` | `db-agent optimize "<sql>"` | Analyzes EXPLAIN query plan and suggests indexes. |
+| `path` | `db-agent path table1 table2` | Finds shortest foreign-key join path between tables. |
+| `define` | `db-agent define term "definition"` | Teaches business terminology to semantic dictionary. |
+| `setup` | `db-agent setup` | 1-Click AI configuration wizard. |
+| `use` | `db-agent use <provider>` | Switches active AI provider (`claude`, `openai`, `gemini`, `ollama`...). |
+
+---
+
+## 🔒 Privacy & Security First
+
+- **Zero Credentials Sent to AI**: DB hostnames, usernames, passwords, and data rows **never** leave your machine. Only schema DDL is sent to the LLM.
+- **100% Offline with Ollama**: Run completely air-gapped with local LLMs.
+- **Sensitive Data Masking**: Automatic regex masking of emails (`a***@b.com`), passwords (`**********`), and cards.
+- **Append-Only Audit Logs**: Records all queries and execution durations in `~/.dbagent/audit.jsonl`.
+
+---
+
+## 📄 License & Community
+
+- **License**: [MIT License](LICENSE)
+- **Author**: Santhosh Gupta
+- **Documentation & Recipes**: [examples/](examples/)
+- **Contributing**: [CONTRIBUTING.md](CONTRIBUTING.md)
+- **Security Policy**: [SECURITY.md](SECURITY.md)
+- **Privacy Policy**: [PRIVACY.md](PRIVACY.md)

dbagent_cli-0.11.1/README.md

@@ -0,0 +1,237 @@
+# ⚡ DB-Agent (`dbagent-cli`)
+
+> **The Privacy-First AI Database Copilot, Schema Graph Introspector & Post-Commit Recovery Engine**  
+> *Author: Santhosh Gupta | 100% Free, Standalone, Works 100% Offline (Ollama) or with Cloud AI (Claude 3.7 / GPT-4o / DeepSeek / Gemini / Groq).*
+
+[![PyPI Version](https://img.shields.io/pypi/v/dbagent-cli.svg)](https://pypi.org/project/dbagent-cli/)
+[![Python Versions](https://img.shields.io/pypi/pyversions/dbagent-cli.svg)](https://pypi.org/project/dbagent-cli/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Database Support](https://img.shields.io/badge/Databases-Postgres%20%7C%20MySQL%20%7C%20SQLite%20%7C%20DuckDB%20%7C%20MSSQL%20%7C%20Oracle%20%7C%20MongoDB-blue.svg)](https://pypi.org/project/dbagent-cli/)
+
+---
+
+## 🌟 What is DB-Agent?
+
+**DB-Agent** is an enterprise-ready, privacy-first database AI copilot that translates plain English into dialect-precise SQL, explores schemas on-demand (<30ms), enforces strict multi-tier safety guardrails, and captures pre-write snapshots allowing you to safely rollback database modifications days or weeks after `COMMIT`.
+
+```text
+"Show me the top 10 customers by order value"
+                      ↓
+           [ DB-Agent CLI Engine ]
+   (Targeted Schema Sub-Graph + AST Safety)
+                      ↓
+  SELECT c.customer_id, c.first_name, SUM(o.total_amount) AS total_spend
+  FROM customers c
+  JOIN orders o ON c.customer_id = o.customer_id
+  GROUP BY c.customer_id, c.first_name
+  ORDER BY total_spend DESC LIMIT 10;
+                      ↓
+            ⚡ Executed in 0.4s
+  ┌─────────────┬────────────┬─────────────┐
+  │ customer_id │ first_name │ total_spend │
+  ├─────────────┼────────────┼─────────────┤
+  │ 1           │ Alice      │ $3,450.00   │
+  │ 3           │ Claire     │ $2,198.50   │
+  └─────────────┴────────────┴─────────────┘
+```
+
+---
+
+## 🚀 5-Second Instant Trial (Zero Setup Required)
+
+Want to test DB-Agent without configuring a database or API keys?
+
+```bash
+# 1. Install DB-Agent
+pip install "dbagent-cli[all]"
+
+# 2. Launch built-in demo e-commerce database with interactive AI copilot
+db-agent demo
+```
+
+---
+
+## ⚡ 3-Minute Quickstart
+
+### 1. Install
+```bash
+pip install --upgrade "dbagent-cli[all]"
+```
+
+### 2. Configure AI Backend (1-Click Setup)
+```bash
+db-agent setup
+```
+Choose from 8 built-in providers:
+- **Local Ollama** (100% private, 100% offline with `qwen2.5-coder`, `llama3.3`, `deepseek-r1`)
+- **Google Gemini** (`gemini-3.6-flash`, `gemini-2.5-flash`)
+- **Anthropic Claude** (`claude-3-7-sonnet-20250219`, `claude-3-5-sonnet`)
+- **OpenAI ChatGPT** (`gpt-4o`, `gpt-4.5-preview`, `o3-mini`)
+- **DeepSeek AI** (`deepseek-chat` V3, `deepseek-reasoner` R1)
+- **Mistral AI** (`codestral-latest`, `mistral-large-latest`)
+- **Groq** (`llama-3.3-70b-versatile`)
+- **OpenRouter** (`meta-llama/llama-3.3-70b-instruct`)
+
+### 3. Connect Your Database
+```bash
+# Interactive guided connection
+db-agent connect
+
+# Or connect directly with an alias
+db-agent connect postgresql://user:password@localhost:5432/app_db --alias prod_db
+```
+
+### 4. Ask Plain English Questions
+```bash
+# One-off query:
+db-agent ask "count active users grouped by country" --db prod_db
+
+# CI/CD machine-readable JSON export:
+db-agent ask "count orders by status" --db prod_db --format json
+
+# Interactive Claude-Style Shell with live streaming & prompt queuing:
+db-agent chat --db prod_db
+```
+
+---
+
+## 📊 Database Compatibility Matrix
+
+| Database Engine | Introspection | Direct Queries | Multi-Hop JOINs | Transactions | 30-Day Recovery | Status |
+| :--- | :---: | :---: | :---: | :---: | :---: | :--- |
+| **PostgreSQL / CockroachDB** | ✓ | ✓ | ✓ | ✓ | ✓ | **Fully Supported** |
+| **MySQL / MariaDB** | ✓ | ✓ | ✓ | ✓ | ✓ | **Fully Supported** |
+| **SQLite** | ✓ | ✓ | ✓ | ✓ | ✓ | **Fully Supported** |
+| **DuckDB** | ✓ | ✓ | ✓ | ✓ | ✓ | **Fully Supported** |
+| **Microsoft SQL Server** | ✓ | ✓ | ✓ | ✓ | ✓ | **Fully Supported** |
+| **Oracle Database** | ✓ | ✓ | ✓ | ✓ | ✓ | **Fully Supported** |
+| **MongoDB** | ✓ (JSON) | ✓ (Filters) | N/A | ✓ | N/A | **Document Supported** |
+
+---
+
+## 🪟 Interactive Viewing & Data Grid Suite
+
+When querying wide enterprise tables with 20 to 60+ columns, DB-Agent provides 5 flexible viewing tools:
+
+| View Mode | In-Chat Command | Description |
+|---|---|---|
+| **Desktop GUI Grid** | `:window` / `:grid` | Native desktop window with horizontal/vertical scrolling, live search filters, and CSV export. |
+| **Browser Virtual Table** | `:web` / `:browser` | Self-contained HTML virtual data grid opened in default browser. |
+| **Horizontal Column Paging**| `:page <n>` | Browse wide column sets in clean horizontal slices (`:page 1`, `:page 2`). |
+| **Vertical Record Cards** | `:card` / `:v` | Renders rows as expanded vertical record cards. |
+| **Responsive Zoom View** | `:wide` | Expands across full terminal width. |
+
+---
+
+## 🛡️ 5 Operational Safety Tiers
+
+| Mode | Reads | Writes | DDL | Confirmation | Best For |
+| :--- | :---: | :---: | :---: | :---: | :--- |
+| **`SAFE`** | Allowed | **Blocked** | **Blocked** | None | Read-only analysis |
+| **`READ_ONLY`** | Allowed | **Blocked** | **Blocked** | None | **Production Environments** (5s timeout, 1,000 row cap) |
+| **`CONFIRM`** (Default) | Allowed | Allowed | Allowed | **Required** | Day-to-day development |
+| **`SANDBOX`** | Allowed | Uncommitted | Uncommitted | None | Dry-run testing with before/after diffs |
+| **`ADMIN`** | Allowed | Allowed | Allowed | None | Advanced DBAs |
+
+---
+
+## ⏪ Long-Term Post-Commit Recovery Engine
+
+Unlike standard database transactions that only protect uncommitted sessions, DB-Agent captures **pre-write row snapshots** before modifying data:
+
+```text
+User: "Update inactive customers to ACTIVE where created_at > '2025-01-01'"
+AI:   Modifying 42 rows. Capturing pre-write snapshot...
+      ✓ Change committed successfully (Change ID: CS-20260831-001)
+
+... 10 days later ...
+
+User: db-agent rollback CS-20260831-001 --db my_db
+AI:   Checking concurrency conflicts... No conflicting writes detected.
+      ✓ Restored 42 rows to their exact original state.
+```
+
+---
+
+## ⚡ Performance Benchmarks (`db-agent benchmark`)
+
+Reproducible benchmark metrics measured on standard hardware:
+
+```text
+Benchmark Category                   Latency / Metric        Rating
+─────────────────────────────────────────────────────────────────────────────
+Cold Schema Scan (6 tables)          12.4 ms                 ⚡ Ultra Fast (<50ms)
+Cached Schema Load                   0.08 ms                 ⚡ Sub-Millisecond
+Schema Cache Speedup                 155x faster             🚀 Verified
+BFS Multi-Hop Join Routing (3 hops)  0.15 ms                 ⚡ Sub-Millisecond
+Query Result Cache Hit               0.02 ms                 ⚡ Instant
+Process Memory Footprint             28.4 MB                 🟢 Lightweight
+```
+
+Run benchmarks locally:
+```bash
+db-agent benchmark
+```
+
+---
+
+## 🔌 Plugin & Extensibility Architecture
+
+Extend DB-Agent with custom database connectors or AI providers via standard Python entry points:
+
+```python
+# my_connector.py
+from dbagent.connectors.base import BaseConnector
+
+class ClickHouseConnector(BaseConnector):
+    # Implement test_connection, inspect_schema, execute_query
+    pass
+```
+
+In your package `pyproject.toml`:
+```toml
+[project.entry-points."dbagent.connectors"]
+clickhouse = "my_package:ClickHouseConnector"
+```
+
+---
+
+## 📖 CLI Command Reference
+
+| Command | Usage | Description |
+| :--- | :--- | :--- |
+| `demo` | `db-agent demo` | Instant zero-setup trial on sample e-commerce database. |
+| `ask` | `db-agent ask "prompt" --db alias` | Translates natural language to SQL and executes. |
+| `chat` | `db-agent chat --db alias` | Interactive AI copilot terminal REPL shell. |
+| `connect` | `db-agent connect <url> --alias name`| Tests credentials and saves database profile. |
+| `doctor` | `db-agent doctor --db alias` | Runs connectivity, schema, index, and latency health checks. |
+| `benchmark`| `db-agent benchmark` | Runs reproducible latency and memory benchmark suite. |
+| `examples` | `db-agent examples` | Displays categorized copy-paste prompt recipes. |
+| `rollback` | `db-agent rollback <id>` | Safely reverts post-commit write changes. |
+| `changes` | `db-agent changes` | Lists recorded write ChangeSets and recovery status. |
+| `scan` | `db-agent scan --db alias -o doc.md`| Introspects full schema and exports Markdown data catalog. |
+| `optimize` | `db-agent optimize "<sql>"` | Analyzes EXPLAIN query plan and suggests indexes. |
+| `path` | `db-agent path table1 table2` | Finds shortest foreign-key join path between tables. |
+| `define` | `db-agent define term "definition"` | Teaches business terminology to semantic dictionary. |
+| `setup` | `db-agent setup` | 1-Click AI configuration wizard. |
+| `use` | `db-agent use <provider>` | Switches active AI provider (`claude`, `openai`, `gemini`, `ollama`...). |
+
+---
+
+## 🔒 Privacy & Security First
+
+- **Zero Credentials Sent to AI**: DB hostnames, usernames, passwords, and data rows **never** leave your machine. Only schema DDL is sent to the LLM.
+- **100% Offline with Ollama**: Run completely air-gapped with local LLMs.
+- **Sensitive Data Masking**: Automatic regex masking of emails (`a***@b.com`), passwords (`**********`), and cards.
+- **Append-Only Audit Logs**: Records all queries and execution durations in `~/.dbagent/audit.jsonl`.
+
+---
+
+## 📄 License & Community
+
+- **License**: [MIT License](LICENSE)
+- **Author**: Santhosh Gupta
+- **Documentation & Recipes**: [examples/](examples/)
+- **Contributing**: [CONTRIBUTING.md](CONTRIBUTING.md)
+- **Security Policy**: [SECURITY.md](SECURITY.md)
+- **Privacy Policy**: [PRIVACY.md](PRIVACY.md)

{dbagent_cli-0.10.0 → dbagent_cli-0.11.1}/dbagent/__init__.py

@@ -2,5 +2,5 @@
 DB-Agent: Universal Database Introspection and Script Generation AI Agent (CLI).
 """
 
-__version__ = "0.10.0"
+__version__ = "0.11.1"
 __author__ = "Santhosh Gupta"

{dbagent_cli-0.10.0 → dbagent_cli-0.11.1}/dbagent/agent/doctor.py

@@ -53,6 +53,10 @@ class DatabaseDoctor:
         llm_provider: Optional[BaseLLMProvider] = None,
         security_mode: str = "CONFIRM",
     ) -> DoctorReport:
+        import sys
+        from pathlib import Path
+        from dbagent import __version__
+
         t0 = time.time()
         success, msg = connector.test_connection()
         conn_latency_ms = (time.time() - t0) * 1000
@@ -65,6 +69,32 @@ class DatabaseDoctor:
 
         report = DoctorReport(database_name=db_name, dialect=dialect)
 
+        # 0. Runtime Environment & Permissions
+        py_ver = f"{sys.version_info.major}.{sys.version_info.minor}.{sys.version_info.micro}"
+        report.checks.append(DiagnosticCheck(
+            name="Runtime & CLI",
+            status="OK",
+            message=f"Python {py_ver} • dbagent-cli v{__version__}",
+        ))
+
+        # Check local directories
+        home_dbagent = Path.home() / ".dbagent"
+        try:
+            home_dbagent.mkdir(parents=True, exist_ok=True)
+            (home_dbagent / ".perm_check").write_text("ok", encoding="utf-8")
+            (home_dbagent / ".perm_check").unlink()
+            report.checks.append(DiagnosticCheck(
+                name="Storage & Cache Permissions",
+                status="OK",
+                message=f"Directory '{home_dbagent}' is writable",
+            ))
+        except Exception as e:
+            report.checks.append(DiagnosticCheck(
+                name="Storage & Cache Permissions",
+                status="WARN",
+                message=f"Directory permission warning: {str(e)}",
+            ))
+
         # 1. Connection check
         if success:
             report.checks.append(DiagnosticCheck(

{dbagent_cli-0.10.0 → dbagent_cli-0.11.1}/dbagent/agent/generator.py

@@ -59,6 +59,10 @@ Generate ONLY the raw executable SQL query for the given database. No markdown f
    - Check the column data type and sample values shown in the schema.
    - If the column is VARCHAR(1) or CHAR(1) or text, check if values use 'Y'/'N', 'YES'/'NO', '1'/'0', 'ACTIVE'/'INACTIVE', 'TRUE'/'FALSE'.
    - If sample values show 'Y'/'N' (or if it's a single-character VARCHAR/CHAR column), use `active = 'Y'` or `active IN ('Y', '1', 'true', 'TRUE')` for active/enabled status.
+10. For Deletions & Cascading Mapping Cleanup (when deleting a record/user without foreign key constraint violations):
+   - For PostgreSQL: Use a single Common Table Expression (CTE) with data-modifying statements deleting from all child, mapping, activity, profile, and preference tables first, and finally deleting from the parent table (e.g. `WITH target AS (SELECT pk_user_id FROM ivis_user WHERE ...), del_act AS (DELETE FROM user_activity WHERE user_id IN (SELECT pk_user_id FROM target)), del_map AS (DELETE FROM ivis_user_access WHERE fk_user_id IN (SELECT pk_user_id FROM target)) DELETE FROM ivis_user WHERE pk_user_id IN (SELECT pk_user_id FROM target);`).
+   - For MySQL / SQLite: Generate clean, ordered DELETE statements deleting referencing child records before the parent record.
+   - Always delete from all referencing tables present in the schema to avoid foreign key violations.
 """
 
 

{dbagent_cli-0.10.0 → dbagent_cli-0.11.1}/dbagent/agent/pipeline.py

@@ -160,6 +160,9 @@ class QueryPipeline:
 
         # 2. Targeted on-demand table introspection with automatic junction expansion
         target_names = list(set(exact + fuzzy))
+        is_delete_or_mapping = any(w in user_prompt.lower() for w in ["delete", "remove", "drop", "cascade", "mapping", "map", "link", "clean", "without any mappings"])
+        max_tables_limit = 25 if is_delete_or_mapping else 12
+
         if target_names:
             try:
                 all_table_names = self.connector.get_table_names()
@@ -174,24 +177,29 @@ class QueryPipeline:
                     t_lower = t.lower()
                     if t in target_names:
                         continue
-                    is_map = any(m in t_lower for m in ["_map", "mapping", "_rel", "_junction", "_link", "_access", "_config"])
+                    is_map = any(m in t_lower for m in ["_map", "mapping", "_rel", "_junction", "_link", "_access", "_config", "_preference", "_profile", "_activity", "_log"])
                     matches_stem = any(s in t_lower for s in stems)
-                    if (is_map and matches_stem) or sum(1 for s in stems if s in t_lower) >= 2:
-                        if t not in target_names:
-                            target_names.append(t)
-                    if len(target_names) >= 12:
+                    if is_delete_or_mapping:
+                        if matches_stem or (is_map and matches_stem) or sum(1 for s in stems if s in t_lower) >= 1:
+                            if t not in target_names:
+                                target_names.append(t)
+                    else:
+                        if (is_map and matches_stem) or sum(1 for s in stems if s in t_lower) >= 2:
+                            if t not in target_names:
+                                target_names.append(t)
+                    if len(target_names) >= max_tables_limit:
                         break
             except Exception:
                 pass
 
             targeted = self.connector.inspect_schema(table_names=target_names, include_samples=True, max_samples=2)
             retriever = ContextRetriever(targeted)
-            return retriever.retrieve_context(user_prompt, exact_tables=exact, fuzzy_tables=fuzzy, max_tables=12)
+            return retriever.retrieve_context(user_prompt, exact_tables=exact, fuzzy_tables=fuzzy, max_tables=max_tables_limit)
 
         # 3. Fallback: inspect targeted
-        targeted = self.connector.inspect_targeted(user_prompt, max_tables=12, include_samples=True)
+        targeted = self.connector.inspect_targeted(user_prompt, max_tables=max_tables_limit, include_samples=True)
         retriever = ContextRetriever(targeted)
-        return retriever.retrieve_context(user_prompt, exact_tables=exact, fuzzy_tables=fuzzy, max_tables=12)
+        return retriever.retrieve_context(user_prompt, exact_tables=exact, fuzzy_tables=fuzzy, max_tables=max_tables_limit)
 
     def run(
         self,