ScriptorDB

**An open-source AI agent that connects databases, files, and the web, then uses tools to analyze information and take actions safely.


---

What The Agent Actually Does

🔍 Reads Your Schema So You Don't Have To

The agent inspects your database structure automatically. You never need to paste CREATE TABLE statements or explain your column names. It knows your tables, columns, types, and foreign keys before it writes a single query.

💬 Answers Follow-Up Questions

This isn't a one-shot SQL generator. The agent remembers context across your conversation. Ask "top customers," then "what did they buy," then "plot a monthly trend" — it maintains state and builds on previous answers.

🧠 Writes SQL, Runs It, Explains Results

You ask in English. The agent:

1. Reads the relevant schema
2. Generates the correct SQL
3. Executes it safely
4. Returns a human-readable answer — not just a raw table dump

You: "Which products had revenue drop last quarter?"
Agent: "Based on your orders and products tables, here are the 3 products
        with declining Q-over-Q revenue..."

📊 Analyzes & Visualizes Data

Beyond SQL, the agent can run Python code in a sandbox to compute statistics, generate charts with matplotlib, or export results to Excel — all from natural language requests.

📥 Import CSV & Excel

Read CSV and Excel files and import them directly into the database. All changes can be undone.

🛡️ Guardrails Around Writes

Read-only queries run through dedicated read tools. When the agent needs to modify data, it routes through write tools that enforce validation rules:

• DELETE and UPDATE must include a WHERE clause.
• DROP operations require confirm_drop=True.
• DROP DATABASE and dangerous Python patterns (os.system, subprocess, eval, etc.) are rejected.
• Every tool call is logged with a trace ID.
• Write operations are recorded in an undo log and can be reverted.

🗄️ MySQL Support

ScriptorDB works with local SQLite files out of the box, but you can also connect to remote MySQL databases with zero configuration overhead.

• One-click switch — Open the Database Connection modal in the sidebar, select MySQL, fill in host/port/user/database/password, and click "Test & Save." The connection is live immediately.
• Secure credential storage — MySQL passwords are stored in the OS system keyring, never in workspace files or logs.
• Seamless switching — Toggle between SQLite and MySQL at any time. Your MySQL connection details are preserved when you switch back to SQLite.

👤 Human Approval for High-Risk Operations

High-risk mutations — such as importing large CSV/Excel files — are paused and surfaced in the web UI for explicit approval before execution. You review the pending tool call, choose to approve or deny, and the agent resumes or cancels accordingly.

🌐 Web Crawling — Ask Questions About Any Web Page

Paste a URL, and the agent fetches and analyzes the page content alongside your database. No copy-pasting, no switching tabs.

• URL + question in one prompt — Type your question, paste a URL, and the agent crawls the page as Markdown, then answers using both the page content and your database context.
• Built on crawl4ai — Pages are rendered and extracted to clean Markdown (up to 50K characters), preserving headings, tables, and text structure.

🖥️ Browser Control — Let the Agent Drive a Real Browser (Under Development)

The agent can launch a Chromium browser, navigate pages, interact with elements, extract data, and take screenshots — all driven by natural language.Browser functionality can be enabled/disabled per workspace.

• Full Playwright integration — Headless or visible Chrome. Navigate, click, fill forms, press keys, scroll, go back/forward.
• DOM querying — Extract text, attributes, and image sources from any element via CSS selectors.
• JavaScript execution — Run arbitrary JS in the page context and get results back.
• Cookie management — Get, set, and clear cookies for authenticated sessions.
• State tracking — Navigation history, action log, and screenshot snapshots with a 30-second TTL.

🔍 Search Session History

Session history is searchable so you can quickly find past questions and results across long-running conversations.

↩️ Undo & Session History

Every run that changes data is grouped into an undo log. From the CLI or the web UI you can list those groups and revert the database to a previous state. Sessions persist with a 24-hour TTL, so you can close the app and pick up where you left off.

📁 Workspace Isolation Out Of The Box

Every project lives in its own workspace — a self-contained bundle of database path, LLM provider, model, API key, and session history. Run five SQLite projects side by side and switch between them with one command. The agent only ever sees the active workspace's database, so nothing crosses the line.

---

Quick Start

uv sync                              # backend
npm install                          # concurrently
cd frontend && npm install && cd ..  # UI

npm run dev

That's it. Backend at http://localhost:8000, UI at http://localhost:5173. Create workspaces, plug in your API key, and start asking — all from the web interface. A CLI is available for scripting; run uv run python main.py --help to see it.

---

Works With Any OpenAI-Compatible Provider

OpenAI, Anthropic, Google, Groq, Mistral, OpenRouter, NVIDIA NIM, Together — or any third-party relay with an OpenAI-compatible endpoint. Switch providers in one setting without rewriting prompts.

Provider	Example model string
OpenAI	openai:gpt-5.5
Anthropic	anthropic:claude-sonnet-4-6
Google	google:gemini-3.5-flash
Groq	groq:kimi-2.6
Mistral	mistral:mistral-medium-3.5
OpenRouter	openrouter:deepseek-v4-pro
NVIDIA NIM	openai:kimi-k2.6
Together	openai:gpt-5.5

Use uv run python main.py models to see the live model list for a provider, or pass a substring like --model gpt-5.5 and the agent will fuzzy-match it.

---

What Could Go Wrong — And Why You Don't Have to Worry

Fear	Plain-English Meaning	How You're Protected
AI turns into a backstabber	A clever prompt tricks it into leaking data or deleting tables	Read/write tools are separate; validators reject dangerous SQL/DDL. All tool calls are logged.
AI formats your hard drive	It runs code outside its lane and wrecks files	Python execution is restricted to a sandbox and dangerous patterns are blocked. File paths cannot escape the workspace outputs directory.
Your API keys get stolen	Keys accidentally end up in logs, git, or screenshots	Keys live in the OS keychain. Never in repo files or .env.
Locked into one LLM vendor	You can't switch providers without rewriting everything	provider:model naming means one-line swaps.
You can't take back a bad change	The agent modifies data and you need to recover	Every write run is recorded in an undo log and can be reverted from the CLI or web UI.

---

🤝 Commercial Partners / API Providers Wanted （Hasn't started yet）

ScriptorDB is designed to route users to API providers and relays. If you operate a stable API relay, token-resale platform, or self-hosted model endpoint, we are open to revenue-sharing partnerships.

Email: justinlee@aivault.dev

---

Architecture

ScriptorDB/
├── agents/              # Pydantic AI agent, toolsets, audit/undo hooks
├── browser/             # Playwright browser automation: launch, navigate, interact, query, screenshot
├── cli/                 # Typer commands: setup, ask, interactive, serve, workspace, undo
├── config/              # Settings, workspace registry, model resolution, secrets, global defaults
├── frontend/            # React 19 + Vite + TypeScript + HeroUI + Tailwind CSS v4
├── server/              # FastAPI app + routers: chat (SSE), sessions, schema, models, settings, files, undo
├── tools/               # SQLite queries, DDL/DML validators, Python sandbox, export, visualization, undo log
├── tests/               # pytest suite using TestModel (zero real LLM calls)
├── main.py              # Entry point: no args → menu; args → Typer CLI
├── pyproject.toml       # uv project config
└── package.json         # Concurrent dev scripts for backend + frontend

---

Roadmap

• Multi-provider LLM agent with SQLite tools
• Workspace-based config and key isolation
• CLI, FastAPI backend, and React frontend
• Session persistence with TTL
• Undo log for write operations
• Browser control — Playwright-powered browser automation (in progress, core tools available)
• Fine-grained permission model per workspace
• Query result diffing and rollback snapshots
• Built-in prompt-injection test harness

---

License

Apache License 2.0