Metadata-Version: 2.4
Name: dbagent-cli
Version: 0.2.0
Summary: Universal Database Introspection and Script Generation AI Agent (CLI)
Author: Santhosh Gupta
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: 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"

# ⚡ DB-Agent

> **Universal Database AI CLI — Ask in plain English, get database results instantly.**  
> *Author: Santhosh Gupta | 100% Free, Standalone, and works Offline (Ollama) or with Free Cloud AI (Gemini / Groq).*

[![PyPI Version](https://img.shields.io/pypi/v/dbagent-cli.svg)](https://pypi.org/project/dbagent-cli/)
[![Python Version](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)

---

## 🚀 2-Minute Quickstart

### Step 1: Install from PyPI
Open your terminal (PowerShell, Command Prompt, or Bash) and run:

```bash
pip install "dbagent-cli[all]"
```

---

### Step 2: Run 1-Click AI Setup

```bash
db-agent setup
```

The interactive wizard gives you 3 options:
1. **Local Offline AI (Ollama)**: Automatically downloads and installs local Ollama and the `qwen2.5-coder` model. Zero API keys, 100% private, works offline.
2. **Free Cloud AI (Gemini / Groq)**: Enter your free API key for instant cloud processing.
3. **Normal Database CLI**: Use standard database tools (connect, scan, raw SQL) without AI.

---

### Step 3: Connect Your Database & Save an Alias

```bash
db-agent connect postgresql://user:password@localhost:5432/mydb --alias my_db
```
*(Supports PostgreSQL, MySQL, SQLite, SQL Server, Oracle, DuckDB, and MongoDB).*

---

### Step 4: Ask Questions in Plain English!

```bash
# 1. Ask a question and get instant live results table
db-agent ask "list top 10 recent users" --db my_db

# 2. Or start the interactive database shell
db-agent chat --db my_db
```

---

## 📖 Complete Command Reference

| Command | How to Use | When to Use |
|---|---|---|
| **`ask`** | `db-agent ask "show top 10 users" --db my_db` | **Primary query tool.** Translates English to SQL, executes automatically, and shows live results. |
| **`chat`** | `db-agent chat --db my_db` | **Interactive terminal shell.** Type questions, inspect tables, and switch models on the fly. |
| **`connect`** | `db-agent connect <url> --alias my_db` | **Save connection.** Validates credentials in `< 0.1s` and saves an alias name. |
| **`scan`** | `db-agent scan --db my_db --export db.md` | **Schema catalog.** Discovers tables, columns, relations, indexes, and exports to Markdown/JSON. |
| **`use`** | `db-agent use gemini` | **Switch AI provider.** Switch default AI between `ollama`, `gemini`, `groq`, and `openrouter`. |
| **`run`** | `db-agent run "SELECT * FROM users" --db my_db` | **Direct SQL execution.** Run raw SQL directly with formatted table output. |
| **`generate`**| `db-agent generate "ETL pipeline" --db my_db -o etl.py` | **Code generation.** Export SQL, Alembic migrations, Python ETL, or FastAPI REST APIs to files. |
| **`setup`** | `db-agent setup` | **AI setup wizard.** 1-click installer for local Ollama or cloud provider configuration. |
| **`config`** | `db-agent config` | **Settings wizard.** Configure API keys, default models, and database profiles. |
| **`profiles`**| `db-agent profiles` | **Saved databases.** List all configured database aliases and connection URLs. |
| **`models`** | `db-agent models` | **Engine health check.** Check Online/Offline status of local and cloud models. |
| **`guide`** | `db-agent guide` | **In-terminal reference.** Display interactive command cheatsheet. |

---

## 💬 Interactive Chat Shell (`db-agent chat`)

Launch the interactive REPL with `db-agent chat --db <alias>`.

Inside the chat session, you can ask questions in plain English or use built-in `:` commands:

```text
db-agent> list top 10 users with email and created_time from ivis_users
┌─────┬──────────────────────────┬─────────────────────────────┐
│ id  │ email                    │ created_time                │
├─────┼──────────────────────────┼─────────────────────────────┤
│ 101 │ john.doe@example.com     │ 2026-08-28 17:30:00+00:00   │
│ 102 │ jane.smith@example.com   │ 2026-08-28 17:15:00+00:00   │
└─────┴──────────────────────────┴─────────────────────────────┘
```

### In-Chat Special Commands:

* **`:help`** — Show all in-chat commands.
* **`:tables`** — List all tables in the connected database.
* **`:table <name>`** — Inspect table columns, primary keys, data types, and sample rows.
* **`:fk <name>`** — View all mapped foreign keys and related tables (incoming and outgoing).
* **`:provider <name>`** — Switch AI provider on the fly (`ollama`, `gemini`, `groq`, `openrouter`).
* **`:model <name>`** — Switch active model name on the fly (e.g. `:model gemini-3.6-flash`).
* **`:models`** — View active AI engine and available models.
* **`:explain`** — View the SQL query and table matches generated for your last question.
* **`:history`** — View the history of queries executed in this session.
* **`:auto` / `:noauto`** — Toggle automatic execution of read queries.
* **`:run`** — Re-execute the last generated SQL query.
* **`:export <file>`** — Save the last generated SQL to a file.
* **`:exit`** — Exit the chat session.

---

## 🔌 Supported Databases & Connection Examples

DB-Agent supports all major relational and NoSQL databases:

| Database | Connection URL Format |
|---|---|
| **PostgreSQL** | `postgresql://user:pass@localhost:5432/dbname` |
| **MySQL / MariaDB** | `mysql+pymysql://user:pass@localhost:3306/dbname` |
| **SQLite** | `sqlite:///path/to/database.db` or just `database.db` |
| **Microsoft SQL Server** | `mssql+pyodbc://user:pass@server/dbname?driver=ODBC+Driver+17+for+SQL+Server` |
| **Oracle** | `oracle+cx_oracle://user:pass@localhost:1521/?service_name=ORCLPDB1` |
| **DuckDB** | `duckdb:///path/to/analytics.duckdb` |
| **MongoDB** | `mongodb://user:pass@localhost:27017/dbname` |

---

## 🤖 Supported AI Providers (100% Free Options)

| Provider | Type | API Key Needed? | Speed | Setup |
|---|---|---|---|---|
| **Ollama** | Local & Offline | **No** (Zero keys) | Fast (Local GPU/CPU) | `db-agent setup` |
| **Google Gemini** | Cloud (Free Tier) | Free key at [aistudio.google.com](https://aistudio.google.com/apikey) | Very Fast | `db-agent config` |
| **Groq** | Cloud (Free Tier) | Free key at [console.groq.com](https://console.groq.com) | Ultra-Fast | `db-agent config` |
| **OpenRouter** | Cloud (Free Models) | Free key at [openrouter.ai](https://openrouter.ai) | Standard | `db-agent config` |

### Switch Providers Anytime:

```bash
# Switch to Google Gemini
db-agent use gemini

# Switch to local Ollama (Offline)
db-agent use ollama

# Switch to Groq
db-agent use groq
```

---

## 🛡️ Safety & Auto-Execution Rules

* **Read Queries (`SELECT`, `SHOW`, `EXPLAIN`)**: Automatically executed for high productivity.
* **Write/DDL Queries (`INSERT`, `UPDATE`, `DELETE`, `DROP`, `ALTER`)**: DB-Agent detects destructive statements and **prompts you for explicit confirmation** before running. Pass `--force` to bypass confirmation if desired.

---

## 📄 License

MIT License © 2026 Santhosh Gupta.
