DecisionLens: An Offline AI Decision Agent with Evidence Traceability

When an AI Recommendation Goes Wrong

A quarter ago, someone asked a general-purpose AI chatbot: "Which product should I prioritize for restocking?" and provided three CSV files — sales, inventory, and customer feedback. The chatbot confidently answered: SKU-A, because "it seems to be selling well."

The problem was, SKU-A was fine. The real risk was SKU-C — selling 100 units per week, with only 6.3 days of inventory remaining and a supplier lead time of 14 days. That meant a stockout in ten days, translating to roughly 100 units of lost revenue per week. The chatbot completely missed this because it never actually cross-referenced the files — it just skimmed the column names and made an educated guess.

This is exactly the failure mode DecisionLens was built to prevent.

What Is DecisionLens

DecisionLens is an offline, zero-dependency decision agent written entirely in Python's standard library. Point it at a folder of CSV files, ask a question in natural language, and it gives you an answer — with every claim backed by evidence citations: 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.

Every number in the output traces back to a specific cell you can open and verify. If the agent can't prove something, it says so directly — it doesn't fabricate.

An Auditable Agent Loop

DecisionLens runs a classic Perceive → Reason → Explain loop, deliberately kept lean so every step is auditable:

1. PERCEIVE — Load every CSV in the data folder, infer column types, and build a metrics index (sales, price, dates, SKUs).
2. INDEX — Normalize units and time periods so weekly sales, on-hand inventory, and lead times are directly comparable.
3. RETRIEVE — Match the question against the index and find relevant rows across all files.
4. REASON — Apply decision rules (e.g., days of cover vs. lead time) using explicit arithmetic — not gut feel.
5. EXPLAIN — Attach a file + row number + field citation to every claim.
6. ACT — Produce a recommended action with a specific quantity.

It can answer questions like: which SKU stocks out first, which channel is quietly declining, what changed month-over-month and why, and full business overviews.

This Perceive → Reason → Explain pattern is often referred to as a simplified variant of the ReAct (Reasoning + Acting) framework in the AI agent space. The standard ReAct framework, proposed by Yao et al. in 2022, allows language models to interleave reasoning traces with concrete actions — but it fundamentally relies on the internal reasoning capabilities of large language models, making it difficult to guarantee traceable data sources at every step. DecisionLens takes a different path: it bypasses language models entirely, replacing probabilistic reasoning with deterministic algorithms. Every calculation is an explicit arithmetic operation (e.g., on_hand ÷ weekly_sales = days_of_cover) rather than a neural network's implicit activations. This makes the entire reasoning chain conceptually equivalent to a spreadsheet formula that can be manually reviewed line by line, rather than a black box that requires trust. Agents of this kind — centered on rule engines with interpretability as the primary constraint — are sometimes called modern lightweight implementations of Symbolic AI or Rule-Based Expert Systems.

Why Evidence Citations Matter

For an agent supporting real decisions, "probably correct" isn't good enough. Evidence citations deliver three critical properties:

• Verifiable — Managers can audit any claim in seconds by opening the cited row.
• Debuggable — When the agent is wrong, you can pinpoint exactly which row of data or which rule led it astray.
• Honest — The agent is physically incapable of stating a number it didn't actually read from the files.

That last point is precisely where general-purpose chat assistants keep failing. They can sound very confident, but they cannot guarantee that claims are strictly bound to the underlying data.

Evals Instead of Adjectives

Anyone can claim their agent is "smart," so DecisionLens ships with an eval suite instead of marketing copy:

$ 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.

The last two are worth highlighting: the agent must honestly admit when it doesn't know the answer, and the test suite asserts that the code makes zero network calls. This means it can run on a physically isolated machine — your data never leaves the room. This is directly appealing for data-sovereignty-sensitive contexts like finance and healthcare.

The eval suite here is essentially a set of Behavioral Tests, also known as End-to-End Assertions (E2E Assertions) — an increasingly important practice in AI system quality assurance. Unlike traditional software tests, AI system outputs are non-deterministic, so you can't assert "output equals some fixed string." Instead, you assert that "the output satisfies some semantic property" — such as "citations include row numbers" or "no specific numbers appear when the question is unknown." The unknown_question_does_not_hallucinate test is especially critical: it targets the most notorious flaw of large language models — hallucination, where a model confidently generates plausible-sounding but factually incorrect content when it doesn't know the answer. Encoding "no hallucination" as an automatically runnable assertion means developers can verify this safety property hasn't been broken every time they change the code — a highly practical engineering norm for production AI systems. The offline_no_network_calls assertion directly addresses air-gapped environment compliance requirements: in regulated industries like finance, defense, and healthcare, prohibiting data transmission to external servers is often a legal mandate.

Tech Stack and Open Source

DecisionLens takes a deliberately restrained engineering approach:

• Pure Python standard library (csv, argparse, datetime) — no pip installs, no API keys, no cloud dependencies.
• Under 1,000 lines of code — readable from start to finish.
• HTML report output for sharing decision results with non-technical stakeholders.

The project repository is at github.com/Zhiyilang/decisionlens, with three example datasets (retail sales, inventory, customer feedback) and the full eval suite. Clone it, run python eval.py, and start asking questions about your own CSVs.

The author submitted DecisionLens as an entry to the Open Agent Hackathon 2026 (Track 02: Interpretable Multi-Source Reasoning). The core argument is simple: an agent that shows its reasoning is more valuable than one that merely sounds confident.

A Closing Observation

At a time when large models are widely criticized for hallucination, DecisionLens takes a contrarian path: no parameter bloat, no cloud connection — just "traceability" enforced as a hard constraint. This design philosophy is a reminder that the real bar for enterprise AI isn't how eloquent the answer sounds, but whether you can hand that answer to an auditor with confidence. For teams that have been burned by AI answers that were delivered with conviction but conjured from thin air, small and transparent tools like this — with evidence traceability built in — may prove more practical than bigger black boxes.