Voice and text interface for any SQLite database - fully local with a human-in-the-loop approval gate on every mutation.
The users of SQLite databases either type their queries by hand or don't interact with their databases at all. In addition, once natural language is given access to the database, there is no turning back from a destructive action taken due to misunderstanding or a typo.
VocalOps transforms voice or text input into database operations on any SQLite database, without any schema or configuration changes. All mutations are generated as a preview and are executed only with explicit user approval. All committed changes are logged and can be reverted. It works offline using Ollama for $0, with no API keys required.
The router LLM handles both tool selection and read-query generation - the same local or Boost model takes care of both tasks, so no dedicated SQL-specialist LLM is needed by default. Every mutation is held behind an interrupt_before checkpoint in the LangGraph state machine and only executes after explicit user approval - the undo action goes through the same gate. LLM-generated WHERE subqueries are checked for schema validity before preview or commit. Mutations always run on the local Ollama model, even in Boost mode, so the safety-critical write path never depends on a cloud key. Failure modes are reported honestly rather than failing silently: empty/no-tool-call completions, GraphRecursionError, schema drift since init, and read-only tables all return a specific error message.
VocalOps never modifies its own repository folder while running. All state - conversation history, undo log, schema manifest, vector index, LangGraph checkpoints - lives in ~/.vocalops/, in a per-database sidecar folder determined by hashing the file path of the database (not its contents). If you connect orders.db and library.db, they get separate subfolders; CLI and web share the same sidecar folder for a given database.
- Schema agnostic: works with any SQLite database with zero configuration changes
- Voice input with VAD auto-stop and editable transcript echo before sending
- Full mutation safety pipeline: propose -> preview -> approve -> commit -> undo (undo requires approval)
- Per-session UUID isolation with persistent SqliteSaver checkpointing (shared between CLI and web)
- Honest failure guard: unclear or unresolved requests receive a specific rephrase prompt, never a silent empty response
- Read-only table detection: composite-key and WITHOUT ROWID tables are detected at
init, never silently attempted - Two operating modes: Local-Only ($0, offline) and Boost (cloud keys optional)
- Web UI with streaming output, approval panel, schema browser, history panel, and database switcher
- CLI with rich table display for query results
/metricsendpoint in Prometheus format (HITL decisions, schema drift, mutation rows)- Eval harness: three test suites, MLflow provenance tagging
| Component | Local-Only ($0, offline) | Boost (optional) |
|---|---|---|
| Speech-to-text | faster-whisper (CPU) | Deepgram |
| Router LLM | qwen2.5:7b-instruct (Ollama) | llama-3.1-8b-instant (Groq) |
| Mutations | always local (Ollama) | always local (Ollama) |
| Embeddings | nomic-embed-text (Ollama) | nomic-embed-text (Ollama) |
| Cost | $0 | pay-per-use API calls |
Mutations and embeddings always run locally regardless of mode - the safety-critical path never leaves your machine.
Scores are non-deterministic:
| Eval suite | Cases | Local (qwen2.5:7b-instruct) |
Boost (llama-3.1-8b-instant) |
|---|---|---|---|
Combined harness (run_eval.py) |
50 | 72% (36/50) | not measured |
Rigorous held-out (run_rigorous_eval.py) |
30 | 83% (25/30) | 90% (27/30) |
Hard held-out (run_hard_eval.py) |
14 | 79% (11/14) | 57% (8/14)* |
- 16 GB RAM recommended
- 8 GB RAM works -
setupautomatically falls back tollama3.2:3b-instructif the qwen2.5:7b smoke test fails - ~8 GB disk for Ollama models
# one-time setup
pip install -e .
vocalops setup
vocalops init --db path/to/your.db
# CLI
vocalops chat
# Web UI (two terminals)
uvicorn vocalops.main:app --host 0.0.0.0 --port 8000
cd vocalops-frontend && npm install && npm run dev
# open http://localhost:5173
The entire fine-tuning pipeline is implemented: a synthetic data generator (2000 examples across 8 domains), an executing verifier (2000/2000 pass rate), and an Unsloth QLoRA training script and Modelfile. Get it with vocalops setup --with-finetune. To use it for mutation proposals, set mutation_finetune: true in ~/.vocalops/global_config.yaml (default is false - the router model handles mutations). Measure against your eval suite before enabling in production; subquery-WHERE cases are the expected win, simple single-row updates may regress.
- Backend: FastAPI, LangGraph, LangChain, SQLite
- Agent: Groq / Ollama, faster-whisper / Deepgram, ChromaDB
- Frontend: React, Vite
- Observability: Prometheus-format
/metricsendpoint, MLflow - DevOps: Docker, docker-compose, DVC, GitHub Actions
MIT - see LICENSE