A self-hosted, privacy-first ChatBI platform. Ask questions in plain language and get SQL, tables, and charts over your own databases — without your data ever leaving your infrastructure.
简体中文 | English
Most "chat with your data" tools funnel your queries and schema through a third-party API. bossy is built for the opposite case — teams (finance, banking, analytics) who need a natural-language BI surface on their own terms:
- 🔒 Self-hosted & private. Runs entirely on your infrastructure. Your schemas, queries, and results never touch a vendor you didn't choose.
- 🧠 Bring-your-own-LLM. Use a fully local model via Ollama (zero data egress), or any OpenAI-/Anthropic-compatible endpoint. Keys are encrypted at rest.
- 🧱 Determinism where it matters. bossy doesn't just hand a question to an LLM and hope for SQL. A rule-based semantic layer, SQL guard, and EXPLAIN-based cost gate wrap every LLM step — so the safe, predictable parts stay predictable.
- 🗂️ Metadata-first RAG. Retrieval is grounded in your curated table/column/metric metadata (vector + BM25 + rerank), not raw DDL dumps.
- 🔌 Multi-datasource. Route a single question across multiple business databases; bossy picks the right source and join path.
- 🧰 Built-in workbench. Curate metadata, relationships, and metric definitions through a UI — no YAML required.
- 🏦 Ships with a realistic demo. A synthetic banking/financial dataset (7 domains) generated locally with Faker — no real customer data, ready to explore on
make init.
- Natural-language → SQL over PostgreSQL, with read-only execution enforced.
- Hybrid retrieval (vector + BM25 + cross-encoder rerank) over metadata, semantic definitions, and historical SQL.
- Semantic layer that maps business terms (metrics/dimensions) to columns deterministically.
- SQL safety guard — syntax/field/permission validation plus row-count and scan-cost limits before any query runs.
- Automatic visualization — derives an appropriate chart spec from the result shape.
- Agent pipeline with 8 specialized LLM roles (intent, planning, SQL gen/rewrite, insight, …) you can tune per role.
- One-click analysis — generate a business overview and improvement suggestions across your whole metadata catalog.
- Settings UI for LLM providers, RAG tuning, and metadata management.
A request flows through a pipeline that mixes deterministic stages (rule-based, no prompt) and LLM agent roles (where language understanding is required). The deterministic stages are the guardrails; the LLM roles are the ones you can customize.
flowchart TD
Q[User question] --> Intent{Intent layer}
Intent -->|chitchat / off-topic| Chit[Chitchat agent]
Intent -->|definition / metadata| RAG[RAG / metadata-QA]
Intent -->|data query| Ctx[Context retrieval<br/>vector + BM25 + rerank]
Ctx --> Sem[Semantic layer<br/>metric / dimension match]
Sem --> Plan[Planning agent<br/>table + join path]
Plan --> SQLGen[SQL generation agent]
SQLGen --> Guard[SQL guard<br/>syntax / field / permission]
Guard -->|fail| Rewrite[SQL rewrite agent]
Rewrite --> Guard
Guard --> Perf[Performance gate<br/>EXPLAIN + cost rules]
Perf --> Exec[Read-only execution]
Exec --> Viz[Visualization<br/>chart spec]
Exec --> Insight[Insight agent<br/>plain-language summary]
Viz --> Resp[Response: table + chart + explanation]
Insight --> Resp
| Layer | Stage | Type | What it does |
|---|---|---|---|
| Intent | Intent recognition | 🤖 LLM | Parses the question into a structured intent (metrics, dimensions, time, routing) |
| Intent | Chitchat | 🤖 LLM | Handles greetings / off-topic / non-data conversation |
| Context | Metadata QA | 🤖 LLM | Answers definition / metadata questions via RAG (no SQL) |
| Context | Retrieval | ⚙️ Deterministic | Vector + BM25 + rerank over metadata & historical SQL |
| Semantic | Semantic parsing | ⚙️ Deterministic | Matches business terms to the semantic layer |
| Planning | Query planning | 🤖 LLM | Picks tables and join paths |
| SQL | SQL generation | 🤖 LLM | Writes PostgreSQL from the plan + schema |
| SQL | SQL rewrite | 🤖 LLM | Fixes SQL flagged by the guard |
| Validation | SQL guard | ⚙️ Deterministic | Validates syntax / fields / permissions |
| Performance | Cost gate | ⚙️ Deterministic | EXPLAIN + rules assess execution risk |
| Tooling | Execution | ⚙️ Deterministic | Runs the SQL read-only against the target database |
| Result | Insight | 🤖 LLM | Interprets results in business language |
| Result | Visualization | ⚙️ Deterministic | Derives a chart spec |
- Docker (for PostgreSQL + ChromaDB containers)
- uv (Python) and Bun (frontend) — or standard
python/npm - Ollama running locally on
:11434(embeddings/rerank; optional local LLM)
git clone https://github.com/ProjAnvil/Bossy.git
cd Bossy
cp .env.example .env # adjust DB / ports / Ollama URL as needed
make install # uv sync (backend) + bun install (frontend)
make up # start postgres + chromadb containers
make init # pull embedding model + load demo fixtures + build the index
make start # launch backend (:8000) + frontend (:3000)Then open http://localhost:3000. Go to Settings → LLM providers to add a provider key (or point it at a local Ollama model), and start asking questions.
The demo dataset is synthetic — generated locally with Faker across 7 banking domains (core, customer, loan, payment, rewards, risk, wealth). It contains no real customer data.
| Command | Description |
|---|---|
make up / make down |
Start / stop dependency containers |
make install |
Install backend + frontend dependencies |
make init |
Start deps, pull embedding model, load fixtures, build index |
make start / stop / restart / status |
Manage backend + frontend processes |
make fixture |
(Re)generate demo fixtures (BOSSY_FIXTURE_SCALE=full|dev) |
make reindex |
Rebuild the retrieval index |
make fe-build |
Build static frontend assets into frontend/out |
make backend-test |
Run the backend test suite |
bossy reads its runtime config from environment variables (.env). LLM providers, embeddings, and rerankers are configured at runtime through the Settings UI, not env vars.
| Variable | Default | Description |
|---|---|---|
BOSSY_HOME |
~/.bossy |
Data directory (metadata DB, logs, run PIDs) |
BOSSY_DB_HOST / BOSSY_DB_PORT |
localhost / 5432 |
Business PostgreSQL host / port |
BOSSY_DB_USER / BOSSY_DB_PASSWORD |
bossy / bossy |
Business DB credentials |
BOSSY_API_HOST / BOSSY_API_PORT |
0.0.0.0 / 8000 |
Backend API bind address |
BOSSY_API_TOKEN |
empty | Optional bearer token for API auth |
BOSSY_FIXTURE_SCALE |
dev |
Demo fixture scale: dev (small) or full |
CHROMA_HOST / CHROMA_PORT |
localhost / 8001 |
ChromaDB vector store |
OLLAMA_BASE_URL |
http://localhost:11434 |
Ollama (embeddings / rerank / optional local LLM) |
BOSSY_CORS_ORIGINS |
http://localhost:3000 |
Comma-separated allowed CORS origins |
BOSSY_SQL_STATEMENT_TIMEOUT_MS |
30000 |
Per-query timeout |
BOSSY_SQL_MAX_ROWS |
1000 |
Maximum rows returned |
BOSSY_SQL_MAX_SCAN_ROWS |
1000000 |
Maximum rows scanned (cost guard) |
bossy/
├── backend/app/
│ ├── api/routes/ # FastAPI routers: chat, config, meta, retrieval
│ ├── core/ # config, errors, paths, security (key encryption)
│ ├── graph/ # orchestration: bi_chat, rag_chat, datasource_selector
│ ├── llm/ # agent registry, prompts, model factory, embeddings, reranker
│ ├── meta/ # metadata models/repo, analysis, datasource mgmt, seed
│ ├── retrieval/ # RAG pipeline + indexer (ChromaDB)
│ ├── sql/ # guard, executor, performance (cost gate)
│ ├── store/ # chroma, postgres, sqlite adapters
│ └── fixtures/ # synthetic banking demo generator (7 domains)
├── frontend/
│ ├── app/ # Next.js routes
│ ├── components/ # chat UI, metadata workbench, settings panels, ECharts
│ └── lib/ # API client, pipeline parsing, chart specs, metadata types
├── docker-compose.yml
├── Makefile
└── Dockerfile
Contributions are welcome! Please open an issue first to discuss larger changes, then send a pull request against main.
- Backend tests:
cd backend && uv run pytest -q - Frontend type-check:
cd frontend && bunx tsc --noEmit - Keep code comments in English; user-facing demo content may remain localized.
Released under the MIT License — © 2026 Yuhao Chen.