I Built an Offline AI Agent That Answers Business Questions With File-and-Line Proof

Last quarter I asked a general-purpose AI chatbot: "Which product should I restock first?" I pointed it at three CSV exports — sales, inventory, and customer feedback. It answered confidently: SKU-A, because "it appears to be selling well."

SKU-A was fine. The real problem was SKU-C: selling 100 units a week with only 6.3 days of stock left against a 14-day supplier lead time. In ten days that SKU is out of stock, and every week of outage costs roughly 100 units of revenue. The chatbot couldn't see that, because it never actually joined the files — it skimmed the column names and guessed.

That failure is what DecisionLens is built to prevent.

What DecisionLens does

DecisionLens is an offline, zero-dependency decision agent written in pure Python standard library. You point it at a folder of CSV files and ask a question in plain English. It answers — and every single claim it makes carries an evidence citation: source file, row number, and field name.

$ python -m decisionlens ask --data examples/ --question "Which SKU should I restock first? Why?"

DECISION: Reorder SKU-C now — it stocks out in ~6 days.

Evidence:
  [E1] sales/sales.csv:42        sku=SKU-C  units_sold=100  (4-week trailing avg)
  [E2] inventory/inventory.csv:7  sku=SKU-C  on_hand=90     days_of_cover=6.3
  [E3] inventory/inventory.csv:7  sku=SKU-C  supplier_lead_time_days=14
  [E4] feedback/feedback.csv:19   sku=SKU-C  mentions="still out of stock" (3 recent)

Action: place a PO for >= 300 units of SKU-C today; expedite the supplier.

No number appears in the answer that isn't traceable to a cell you can open and check. If the agent can't prove something, it says so instead of guessing.

The agent loop

DecisionLens runs a classic perceive → reason → explain cycle, kept deliberately small so every step is auditable:

1. PERCEIVE — load every CSV in the data folder, infer column types, build an index of metrics (units, prices, dates, SKUs).
2. INDEX — normalize units and periods so weekly sales, stock on hand, and lead times are comparable.
3. RETRIEVE — match the question against the index to find the relevant rows across all files.
4. REASON — apply decision rules (e.g. days-of-cover vs. lead time) with explicit arithmetic, never vibes.
5. EXPLAIN — attach file + row + field citations to each claim.
6. ACT — emit a concrete recommended action with quantities.

It answers questions like: which SKU stocks out first, which channel is quietly declining, what changed month over month and why, and a full business overview.

Why evidence citations matter

For an agent that feeds real decisions, "probably right" isn't good enough. Three properties fall out of the citation design:

• Verifiable — a manager can audit any claim in seconds by opening the cited row.
• Debuggable — when the agent is wrong, you see exactly which row or rule misled it.
• Honest — the agent physically cannot state a number it didn't read from a file.

That last property is the one general-purpose chat assistants keep failing.

It ships with evals

Anyone can claim their agent is smart, so DecisionLens ships an eval suite instead of adjectives:

$ python eval.py
PASS  restock_rule_identifies_lowest_cover_sku
PASS  restock_action_includes_quantity
PASS  channel_ranking_uses_net_revenue
PASS  trend_attribution_cites_evidence
PASS  overview_mentions_all_sources
PASS  evidence_citations_include_row_numbers
PASS  unknown_question_does_not_hallucinate
PASS  offline_no_network_calls
8/8 assertions passed.

Note the last two: the agent must admit when it doesn't know, and the test suite asserts the code makes zero network calls. It runs on air-gapped machines — your data never leaves the room.

Tech stack

• Pure Python standard library (csv, argparse, datetime) — no pip install, no API keys, no cloud.
• Under 1,000 lines, readable end to end.
• HTML report output for sharing decisions with non-technical stakeholders.

Try it

The repo is github.com/Zhiyilang/decisionlens with three example datasets (retail sales, inventory, customer feedback) and the full eval suite. Clone it, run python eval.py, then ask it your own questions against your own CSVs.

I built DecisionLens as my entry for the Open Agent Hackathon 2026 (Track 02: explainable multi-source reasoning). The thesis is simple: an agent that shows its work is worth more than an agent that sounds sure.

If you've ever been burned by a confident AI answer that turned out to be invented, tell me your story in the comments — I'm collecting failure modes for the next iteration.