Your data, analyzed by a team of AI agents.
Connect a data file or a database and watch specialized agents clean it, form hypotheses,
debate them, and visualize what matters — then ask follow-ups in plain English.
Website · Docs · Report a bug
A real run on the bundled Sales dataset — unedited.
Insight Orchestra is an open-source AI data analyst you can self-host — think Julius AI or ChatGPT's data analysis, but running on your own hardware, with your choice of LLM, where your data never leaves your machine. Upload a data file — CSV, TSV, Excel, JSON, or Parquet — or connect a PostgreSQL, MySQL, SQLite, or DuckDB database, and a 4-agent pipeline cleans the data, generates evidence-backed hypotheses, scores them in an LLM-refereed debate, and builds interactive Plotly charts. Then keep asking questions in plain English: an NLQ agent writes pandas code and executes it in a locked-down sandbox — or, for a connected database, writes and runs read-only SQL directly, joining across tables as needed.
It works with your choice of LLM — OpenAI, Anthropic, or DeepSeek in the cloud, or fully local and private with Ollama.
Prerequisites: Docker & Docker Compose v2 · Git · 4 GB RAM (8 GB recommended for local LLMs)
One line, clones into ./insight-orchestra and runs the setup wizard:
curl -fsSL https://raw.githubusercontent.com/laban254/insight-orchestra/main/install.sh | bashOr clone it yourself first:
git clone https://github.com/laban254/insight-orchestra.git
cd insight-orchestra
./setup.shThe script asks which LLM provider to use (Ollama by default — local, private, no API key needed), writes backend/.env, starts the containers, and pulls the Ollama model automatically. Run it again any time; it won't clobber an existing backend/.env without asking.
Images are pulled prebuilt from GitHub Container Registry, so there's no local build to sit through. To pin a specific release instead of tracking latest:
IO_IMAGE_TAG=v1.0.0 ./setup.shTo build from source instead — for development, or on a platform we don't publish images for — use ./setup.sh --build. See Contributing for the development workflow.
Fully non-interactive (works with either path above — pass the flags after bash -s -- for the curl one-liner):
./setup.sh --provider ollama -y # local, no API key
./setup.sh --provider openai --api-key sk-... -y # or anthropic / deepseek
# equivalent, without cloning first:
curl -fsSL https://raw.githubusercontent.com/laban254/insight-orchestra/main/install.sh | bash -s -- --provider ollama -ySomething not working? ./setup.sh doctor checks Docker, ports, config, and running services. Prefer to configure backend/.env by hand instead? See the Setup Guide.
Once ./setup.sh finishes:
| Service | URL |
|---|---|
| Frontend | http://localhost:8501 |
| Backend API | http://localhost:8000 |
| Swagger Docs | http://localhost:8000/docs |
Pick one of the five bundled demo datasets, upload your own file (CSV, TSV, Excel, JSON, or Parquet), or connect a PostgreSQL/MySQL/SQLite/DuckDB database — the pipeline runs automatically either way.
The pipeline runs the moment you upload or select a dataset. Results — narrative, ranked insights, charts, suggested follow-ups — appear in the chat as the first message.
| Stage | Agent | Function |
|---|---|---|
| 1 | Data Janitor | Removes duplicates; imputes missing values (median for numeric, mode for categorical); flags bias (>30% missing); detects outliers via IQR |
| 2 | Hypothesis Bot | Builds descriptive statistics + correlations, then asks the LLM to generate 5–8 specific, directional, evidence-backed insights referencing actual column names and numbers |
| 3 | Debate Manager | LLM scores each hypothesis on confidence and business_value (0–1) using the real data stats as evidence; sorts by combined score; selects consensus winner |
| 4 | Viz Whiz | Asks the LLM which columns best illustrate the top insight; falls back to regex extraction then structured heuristics; generates up to 6 Plotly charts |
| 5 | Insight Summarizer | LLM writes a 3–5 sentence narrative summarising all findings; generates 4–5 specific follow-up questions using actual column names |
Each stage streams real-time progress to the UI via SSE. See the Agent Pipeline Guide for the full breakdown.
- Natural Language Queries — the NLQ agent generates pandas code, executes it in the RestrictedPython sandbox, and returns results + optional Plotly charts
- Four LLM Providers — OpenAI, Anthropic, DeepSeek, or Ollama (any locally-hosted model); switch provider/model at runtime, no restart needed
- Multiple File Formats — upload CSV, TSV, Excel (
.xlsx), JSON, or Parquet; each is sniffed for encoding, delimiter, and date columns on the way in - Multi-Database Support — PostgreSQL, MySQL, SQLite, and DuckDB, all read-only, connected through the UI (BigQuery has an experimental endpoint; see the API Reference). Includes a JOIN-capable natural-language SQL agent that answers questions directly against a connected database, across every table in scope, without materializing a table first
- Sandboxed Code Execution — no file I/O, no network access, no dangerous imports; configurable timeout
- Real-Time Agent Progress — SSE streaming shows each agent's status, output, and duration
- Workspace, Share & Export — pin and compare charts, workspace history saved server-side (reopen past runs from any browser), one-click read-only share links (72 h TTL), export as an interactive HTML report, PDF, Markdown summary, or Q&A CSV
- Optional Auth & Access Control — off by default for local/single-user use; turn on
AUTH_ENABLEDfor login, role-based access (admin/member/viewer), OIDC SSO, self-service API keys, and an audit log — see API Reference - 5 Demo Datasets — try it without bringing your own data
| Document | Purpose |
|---|---|
| Setup Guide | Docker and local development setup, troubleshooting |
| Architecture | System design, component breakdown, data flow |
| Agent Pipeline | Deep dive into all 4 agents + NLQ agent |
| API Reference | All REST endpoints with request/response examples |
Have a request or want to influence priorities? Open an issue.
Contributions are welcome — the Contributing Guide covers the development workflow, code style, and how to add a new agent to the pipeline.
If Insight Orchestra is useful to you, consider starring the repo — it helps others find the project.
Apache 2.0 — see LICENSE.
Author: @laban254