How amandev17/verbadb works
VerbaDB lets people ask questions about databases and build or modify private SQLite sandboxes using natural language. The main workflow runs from the browser through the FastAPI server and an agent loop, which calls Gemini and dispatches database tools; guarded query results and sandbox change diffs return to the UI. Separate paths manage read-only shared/user connections and sandbox snapshots, undo, and prompt history. The README documents these capabilities; some module relationships below are supported by the source index rather than fully sampled implementations.
Main entry points: manager.py Database manager · agent.py Agent loop · server.py HTTP and SSE API · sandbox.py Sandbox changes and undo
Components 20
Web interface
- Web UI
verbadb/static/app.js - Theme controls
verbadb/static/theme.js - HTTP and SSE API
verbadb/server.py
Agent and model
- Agent loop
verbadb/agent.py - Prompt construction
verbadb/prompts.py - Gemini adapter
verbadb/llm.py
Database access
- Read-only tools
verbadb/tools.py - Sandbox tools
verbadb/sandbox_tools.py - Schema inspection
verbadb/introspect.py - Query execution
verbadb/executor.py - Query safety guard
verbadb/guard.py - Database manager
verbadb/manager.py - Read-only connections
verbadb/connections.py - Sandbox changes and undo
verbadb/sandbox.py
Workspace state
- Application settings
verbadb/config.py - Workspace data store
verbadb/store.py - Demo data
verbadb/demo_data.py
Other components
- Browser user
- Gemini API
- External databases
Connections 27
- Browser user → Web UI: uses
README.md - Web UI → HTTP and SSE API: sends requests
README.md - HTTP and SSE API → Agent loop: streams questions
verbadb/server.py - HTTP and SSE API → Database manager: manages databases
verbadb/server.py - HTTP and SSE API → Gemini adapter: configures
verbadb/server.py - Web UI → Theme controls: switches theme
README.md - Agent loop → Gemini adapter: requests turns
verbadb/agent.py - Gemini adapter → Gemini API: calls
README.md - Agent loop → Database manager: resolves database
verbadb/agent.py - Agent loop → Read-only tools: dispatches reads
verbadb/agent.py - Agent loop → Sandbox tools: dispatches changes
verbadb/agent.py - Agent loop → Prompt construction: builds instructions
verbadb/agent.py - Read-only tools → Schema inspection: describes schema
verbadb/tools.py - Read-only tools → Query execution: runs queries
verbadb/tools.py - Query execution → Query safety guard: validates queries
verbadb/executor.py - Sandbox tools → Sandbox changes and undo: applies changes
verbadb/sandbox_tools.py - Sandbox tools → Database manager: creates databases
verbadb/sandbox_tools.py - Database manager → Read-only connections: opens read-only
verbadb/manager.py - Database manager → Sandbox changes and undo: opens sandboxes
verbadb/manager.py - Database manager → Workspace data store: stores workspace data
verbadb/manager.py - Database manager → Schema inspection: inspects databases
verbadb/manager.py - Database manager → Demo data: loads demo data
verbadb/manager.py - Read-only connections → Query safety guard: installs query hook
verbadb/connections.py - Read-only connections → External databases: connects read-only
README.md - Sandbox changes and undo → Query safety guard: validates changes
verbadb/sandbox.py - Sandbox changes and undo → External databases: uses SQLite files
README.md - HTTP and SSE API → Application settings: loads configuration
verbadb/server.py