Analyst-in-a-Box

This page is a showcase. Analyst-in-a-Box runs on your own computer: clone the repository and run uv run analyst-in-a-box, or double-click run.bat. Every screenshot below is the real app, captured after the input in its caption was typed or loaded.

An AI back office for a small business that runs on your own computer, with no GPU, no account and no model required. It is for the owner or small team of a shop or wholesaler who has orders in a spreadsheet or database and no analyst.

Connect a database or drop in a spreadsheet, then ask questions in English or Roman Urdu and see the SQL that answered them, forecast demand with totals that add up, get odd orders and refunds flagged with reasons, score customers with a points scorecard and a fairness panel, push refunds and credit-limit changes through approval gates with a tamper-evident audit trail, and watch the KPIs on a dashboard. A language model is optional and its output is always checked.

What it does

Ask your data in English or Roman Urdu: chart, table and the SQL that ran, editable, read-only and exportable as CSV.
Data: bundled sample business, SQLite, PostgreSQL, CSV/TSV/Excel upload or pasted CSV, with a schema browser and three steps for your own sheet (sign in, add it, match its columns); a shop's own product codes and delivery or fee lines are recognised.
Forecasts: weekly demand per product and category, reconciled so the levels add up; the model of each level is chosen by a backtest that includes the same weeks a year earlier, and every model is scored against seasonal naive.
Fraud and anomalies: robust z-score and rule checks on orders, refunds and trading days, every alert with its reasons, one click to open a review ticket.
Customer risk: a points scorecard with reason codes per customer and a fairness panel. It needs about 17 months of orders and at least 10 customers with refunds to learn from; with less, the page says what is missing.
Workflows: refund and credit-limit tickets, PIN sign-in, approval gates that depend on the amount, four-eyes rule, and a hash-chained audit trail with Verify.
Dashboard: revenue, orders, order value, active customers and refund rate with sparklines; CSV export of any result and of the audit trail.
Plain words: terms such as MinT, MASE, robust z-score, Gini and information value are underlined with a one-line meaning where they appear, and listed on the About page.

Gallery

Every picture is a real screenshot of the running app, taken by scripts/gallery.py (headless Edge, dark mode, sample data, a temporary data folder); the same text is in docs/gallery/CAPTIONS.md.

Home

02-tryit-1 — Try-it, example 1: input `top 5 products by revenue last quarter`. Output: SQL, a 5-row table and bar chart; "last quarter" is the newest quarter in the data.

03-tryit-2 — Try-it, example 2: input `monthly revenue in 2011`. Output: a 12-month table and a line chart from SQL with a 2011 filter.

04-tryit-3 — Try-it, example 3: input `is mahine sab se zyada bikne wali cheez` (Roman Urdu). Output: understood as "this month's top product"; 1 row (VINTAGE DOILY JUMBO BAG RED, £3,274.04) with its bar.

05-tryit-4 — Try-it, example 4: input `revenue by country`. Output: 32 countries ranked by net revenue; the chart is horizontal bars with whole country names, the 12 largest drawn and "20 more in the table", with the SQL.

06-home-phone — Home at phone width (390 px): content first. Sign-in sits behind one Sign in button, and the eight pages are a labelled 4 x 2 tab grid.

Data

09-data-paste-csv — Paste CSV: top is the example rows typed into the paste box (3 data rows); bottom is the result after Import, the new `pasted_sales` table with its columns, types and rows.

Ask

10-ask-english — Ask in English: `Top 10 products by revenue in 2011`. Output: bar chart, table, and the editable SQL that ran; marked as built-in parser, read-only checked.

11-ask-roman-urdu — Ask in Roman Urdu: `har mahine ki bikri` (sales every month). Output: the badge "Roman Urdu understood", a 25-month line chart and table.

12-ask-refused-write — A write attempt: after a one-row question, the SQL box is edited to `DELETE FROM orders` and run. Output: refused, "only SELECT is permitted, got Delete", marked "not run"; the earlier result is cleared, not left under the refusal, and the SQL stays editable.

Forecasts

13-forecast — Forecasts: horizon set to 13 weeks and Run forecast pressed. Output: totals add up (yes), 47 of 61 series beat seasonal naive in the backtest, a plain "In short" line, the total charted against the same weeks last year (271,654 forecast against 281,795 a year earlier, with the Christmas drop and the closed New Year week), the model backtest by level and origin (MAE and MASE for seasonal naive, the old ETS/TSB, each seasonal model and the one chosen), the reconciliation backtest, and every series with last year, its own forecast and the reconciled one.

Fraud & anomalies

14-alerts-detail — Fraud and anomalies filtered to high severity: 25 matching, under a note that says in plain words how alerts are found and scored. Each alert lists its reasons with the numbers, e.g. a 10,953.50 refund 5.7 robust deviations above the typical refund and larger than all the customer ever bought.

Customer risk

15-risk-fairness — Customer risk page: scorecard metrics (Gini, cut-off and information value underlined with their meaning) and the fairness panel by country group and tenure band, with disparate impact against the four-fifths screen.

16-risk-customer — One decision with reasons: a DECLINE customer opened from the list. Output: score 496 against cut-off 539, points per feature, ranked reason codes, and the credit-limit ticket form.

Workflows

19-workflows-first-approval — First approval: Bilal Ahmed (manager) opens the ticket, types a comment and approves. The first gate turns done and the decision and audit entry appear; Amna cannot approve her own ticket.

20-workflows-second-approval — Second person: Sana Malik (a different manager) approves with a comment. Both gates are done, status approved, and Execute is offered; the audit shows the fully-approved entry.

21-workflows-audit-verify — Audit verify, after executing the ticket: pressing Verify reports "Audit intact: 8 entries, signed head ok, 1 ticket checked against the trail"; the executed refund shows in the ledger.

Dashboard

Export

About

Inputs

Feature	Upload from the computer	Paste	Hint and example
Data (spreadsheets)	file picker or drag and drop; .csv, .tsv, .txt, .xlsx, .xlsm; 40 MB, 1,000,000 rows, 500 columns; progress bar, clear errors	paste CSV text	header-row format shown, Load example button
Data (databases)	SQLite file path	PostgreSQL URL	placeholder shows both forms
Ask your data	not applicable (a question is text)	type or paste a question or SQL	example chips, input hint
Dashboard, forecasts, fraud, risk, workflows	read what is in the active source	not applicable	an empty or non-business source points to Data

Importing needs a manager sign-in. The in-app About & guide page (also the ? button) covers what it is, how to use each feature with its expected input and output, privacy, the roadmap and the maker.

Tech stack

Backend: Python 3.11+, FastAPI, Uvicorn, SQLite, optional PostgreSQL
SQL safety: sqlglot parses every query; only a single SELECT runs, on a read-only connection
Forecasting: demand-forecast-platform (ETS, TSB for intermittent demand, MinT/bottom-up/top-down reconciliation, rolling-origin backtests), plus a scaled seasonal naive and a one-year seasonal index chosen per level by the backtest
Risk scoring: credit-risk-engine (WoE binning, points scorecard, reason codes, fairness metrics)
Uploads: CSV/TSV, Excel via openpyxl
Security: PBKDF2-hashed PINs, approval policy enforced server-side, SHA-256 hash-chained audit log
Frontend: vanilla JavaScript, HTML and CSS with SVG charts, no build step; light and dark themes
Optional LLM: Ollama, Anthropic or any OpenAI-compatible API; generated SQL goes through the same read-only checks
Tooling: uv, pytest, ruff, Playwright for the UI audit and gallery

Run it

uv run analyst-in-a-box        # starts the server and opens http://127.0.0.1:8780

or double-click run.bat (or the "Analyst-in-a-Box" desktop shortcut). The first run builds the sample database in about ten seconds. Options: --port, --no-browser, --db FILE, --reset-pin "Name". Data lives in ~/.analyst-in-a-box (set ANALYST_HOME to move it). Python 3.11+ and uv; everything runs on the CPU and offline.

Optional language model (never required), set before launching:

ANALYST_LLM=ollama     ANALYST_LLM_MODEL=qwen2.5-coder:7b          # CPU Ollama on localhost:11434
ANALYST_LLM=anthropic  ANTHROPIC_API_KEY=...                       # ANALYST_LLM_MODEL defaults to claude-haiku-4-5
ANALYST_LLM=openai     OPENAI_API_KEY=...  ANALYST_OPENAI_BASE_URL=...

Signing in. Reading, asking and exporting need no sign-in. Anything that changes state (tickets and their approvals, dismissing alerts, uploads, adding or removing a data source) needs a name and a PIN. On the first start after this version the app gives each of the four people a random 8-character PIN, stores only salted PBKDF2 hashes, and writes the PINs once to pins.txt in the data folder: hand each person their own line and delete the file. A lost PIN is replaced with analyst-in-a-box --reset-pin "Bilal Ahmed"; anyone can change their own PIN from the sidebar. Five wrong PINs lock that name for 60 seconds.

PostgreSQL needs the optional driver: uv sync --extra postgres.