DataBrief AI

Bounded spreadsheet intelligence system for turning CSV/XLSX business data into grounded reports, computed findings, and exportable analysis artifacts.

DataBrief AI transforms spreadsheet uploads into structured business reports through deterministic profiling, semantic role detection, controlled Python generation, bounded execution, repair attempts, groundedness checks, and exportable artifacts.

Live Demo · Case Study · Architecture Notes

Portfolio prototype: this project demonstrates a bounded analytics workflow architecture. It is not production SaaS. Generated code is statically checked and executed with resource limits, but production use would require OS-level isolation.

_{A real run on the bundled examples/sample_ecommerce.csv (synthetic data). Every metric links back to the computed artifact it came from.}

30-second summary

DataBrief AI is a bounded analytics workflow that turns messy spreadsheet files into structured business analysis.

The system:

Accepts CSV/XLSX uploads.
Profiles the dataset deterministically.
Detects semantic roles such as revenue, quantity, date, region, category, and status.
Routes the dataset into a known analysis mode.
Generates a structured analysis plan.
Creates Python from controlled templates.
Validates generated code before execution.
Runs analysis with resource limits.
Repairs recoverable failures within strict limits.
Generates a grounded business report from computed outputs only.
Exports the report, findings, and generated script.

The project is not an open-ended data science agent. It is a controlled workflow that uses AI-style generation inside deterministic boundaries.

How generation works today: analysis code is produced from controlled templates selected by the profile and routing stages, so runs are deterministic and reproducible. No external model is called at runtime. Language-model generation would sit behind the same validation, execution and grounding gates.

Evidence

Verified on the current main:

Check	Result
Backend test suite (`pytest -q`)	176 passing across 22 test modules: profiling, semantic roles, routing, planner, codegen, sandbox, repair and retry runners, groundedness, report generation, exports, API safety
Frontend lint (`eslint --max-warnings=0`)	Clean
Type checking (`tsc --noEmit`)	Clean
Production build (`next build`)	Passes

CI runs the same checks on every push (.github/workflows/ci.yml).

Screenshots

Grounded findings: each one cites its source	Charts rendered from executed analysis

What this proves

This project demonstrates that I can:

Design bounded AI analytics workflows where generation is constrained by validation and execution controls.
Turn raw spreadsheet data into structured metrics, findings, charts, limitations, and reports.
Combine deterministic profiling, semantic role detection, planning, code generation, sandbox-aware execution, and grounded report writing.
Build full-stack data products with a Next.js frontend and FastAPI backend.
Create failure-aware systems with repair limits instead of uncontrolled retry loops.
Structure AI-assisted analytics around computed evidence rather than unsupported claims.
Communicate technical limitations clearly instead of overselling prototype safety.

Why this exists

Business teams constantly receive messy spreadsheets and need fast answers:

What are the key metrics?
What changed?
What looks abnormal?
What should we investigate next?
What limitations does the data have?

Generic AI tools can summarize spreadsheets, but they often blur calculated facts, assumptions, and unsupported business claims.

DataBrief AI is designed around a stricter idea:

Analytics outputs should be computed, validated, and grounded before they are written into a report.

The system does not use open-ended agent autonomy. It uses a predictable workflow where each stage has a specific responsibility, bounded execution, and explicit failure behavior.

The point is not to maximize autonomy. The point is to make spreadsheet intelligence more reliable, inspectable, and useful.

What it does

Upload and validation

Upload CSV or XLSX files.
Validate file type and size.
Parse spreadsheet data into a usable analysis format.
Reject unsupported or invalid files early.

Dataset profiling

Profile dataset structure.
Detect column types.
Identify missing values.
Identify duplicates.
Capture sample rows.
Summarize basic dataset quality.

Semantic understanding

Detect semantic column roles such as revenue, quantity, date, status, region, category, and identifier.
Route the dataset as sales, ecommerce, finance, or generic.
Generate a deterministic analysis plan based on detected structure and dataset type.

Controlled analysis generation

Generate Python from controlled templates.
Validate generated code before execution.
Reject disallowed imports and suspicious code patterns.
Prevent the generated script from behaving like a general-purpose code interpreter.

Bounded execution

Execute analysis in a bounded subprocess.
Enforce timeout and resource controls.
Strip down the execution environment.
Store run artifacts under an isolated run directory.
Avoid exposing host filesystem paths in API responses.

Failure handling

Evaluate execution success or failure.
Classify recoverable and unrecoverable failures.
Apply up to 2 bounded repair attempts.
Stop immediately on unsafe or unrecoverable failure types.

Grounded reporting

Validate computed summary artifacts.
Generate business reports from computed outputs only.
Check report claims against available evidence.
Remove or revise unsupported claims.
Export report, findings, and generated analysis script.

What it is not

This project is intentionally scoped.

It is not:

a production SaaS analytics platform
a full BI tool
an open-ended data science agent
a general-purpose code interpreter
a secure sandbox for arbitrary untrusted code
a multi-user reporting system
a persistent data warehouse
a replacement for analyst review in high-stakes financial contexts

The current sandbox is layered and defensive, but it is not OS-isolated.

System architecture

flowchart LR
  A["Upload CSV/XLSX"] --> B["Validate file"]
  B --> C["Profile dataset"]
  C --> D["Semantic role detection"]
  D --> E["Route dataset type"]
  E --> F["Generate analysis plan"]
  F --> G["Generate Python from controlled template"]
  G --> H["Static code validation"]
  H --> I["Bounded subprocess execution"]
  I --> J["Evaluate result"]

  J -->|"success"| K["Validate summary.json"]
  J -->|"recoverable failure"| L["Bounded repair loop"]
  L --> H
  J -->|"unrecoverable failure"| M["Fail safely"]

  K --> N["Grounded report generation"]
  N --> O["Claim/evidence check"]
  O --> P["Store run metadata"]
  P --> Q["Exports: report.md, findings.json, analysis.py"]

Core design principle: bounded analytics

The project uses a workflow instead of an autonomous agent because spreadsheet analysis has a mostly predictable structure.

Stage	Role	Why it is bounded
Validation	Confirms file type, size, and parseability	Rejects bad input early
Profiling	Reads columns, types, missing values, duplicates, and sample rows	Deterministic, no model judgment required
Semantic role detection	Identifies business meaning of columns	Uses role rules before analysis
Routing	Classifies dataset type	Restricts analysis plan to known domains
Planning	Defines KPIs, questions, and charts	Plan is structured, not open-ended
Code generation	Creates Python from templates	No arbitrary code-authoring path
Static validation	Checks imports and suspicious patterns	Rejects unsafe code before execution
Execution	Runs generated script in subprocess	Timeout and stripped environment
Repair	Applies bounded fixes	Maximum 2 repair attempts
Reporting	Writes from computed outputs only	No unsupported report claims

Why not an open-ended agent?

Open-ended data agents are tempting, but this project deliberately avoids them.

Workflow is better here because:

Spreadsheet analysis follows repeatable steps.
Deterministic profiling catches obvious data issues before interpretation.
Routing reduces ambiguity before code generation.
Static validation blocks unsafe imports and suspicious patterns before execution.
Bounded repair prevents infinite analysis loops.
Grounded report generation reduces hallucinated KPIs and fake insights.

Open-ended automation would be weaker because:

It could invent metrics from thin evidence.
It could overfit to ambiguous column names.
It could produce unsupported recommendations.
It would be harder to test.
It would require stronger sandboxing and governance.

The point is not maximum autonomy. The point is reliable analysis under constraints.

Groundedness model

The report should only say what the computed data supports.

Every report claim is checked against available computed outputs and classified conceptually as:

Claim status	Meaning
`supported`	Backed by computed outputs or dataset profile
`uncertain`	Plausible but not strongly supported
`unsupported`	Removed or revised before final report

This is the central credibility layer. The report is not allowed to freely invent KPIs, trends, or recommendations.

Sandbox and execution model

Generated scripts run through a layered execution boundary.

Pre-execution controls

Python code is parsed with the standard-library ast module.
Imports are checked before subprocess execution.
Disallowed imports are rejected before the script runs.
Suspicious calls such as eval, exec, compile, and __import__ are rejected.
Suspicious os access patterns are rejected.
Hardcoded sensitive system paths are rejected.

Execution controls

Scripts run in a child subprocess.
Python is launched in isolated mode with python -I.
Environment variables are stripped down.
Wall-clock timeout is enforced.
Run artifacts are isolated under a generated run directory.
API responses do not expose host filesystem paths.

Important limitation

The current sandbox does not block network access at the OS level.

Network-related libraries such as socket, urllib, requests, and httpx are blocked through import policy, but true production hardening would require container isolation, network namespace restrictions, seccomp, or a purpose-built execution sandbox.

Bounded repair loop

If generated analysis fails, the workflow does not freely ask an agent to “try again.”

It uses classified failure types and deterministic repair actions.

Failure type	Example repair
`missing_column`	Remove problematic column from context and regenerate
`date_parsing`	Disable date analysis
`chart_error`	Skip chart generation
`numeric_error`	Fall back to safer numeric handling
`empty_output`	Use minimal mode
`generic_runtime`	Attempt conservative repair
`import_policy`	Stop immediately
`syntax_error`	Stop immediately
`timeout`	Stop immediately

Maximum repair attempts: 2 Maximum total executions: 3

This keeps recovery useful without creating runaway automation.

Tech stack

Layer	Technology
Frontend	Next.js, React, TypeScript
Backend	FastAPI, Python
Upload handling	CSV/XLSX parsing
Analysis execution	Generated Python subprocess
Validation	AST checks, schema checks, groundedness checks
Storage	SQLite run metadata, local temporary artifacts
Deployment	Vercel frontend + FastAPI backend service
Testing	Pytest, TypeScript checks, ESLint

How to review this repo

Start here:

docs/case-study.md — project narrative, problem, system, and portfolio framing
docs/architecture.md — technical architecture and workflow notes
backend/services/ — profiling, routing, planning, execution, repair, reporting, and groundedness checks
backend/tests/ — backend validation, semantic quality, planner, sandbox, and export tests
examples/ — synthetic datasets for demo and local testing
app/ — frontend upload and report experience
vercel.json — deployment configuration for frontend and backend routing

This repo is best reviewed as a bounded analytics workflow, not as a generic spreadsheet summarizer.

Sample datasets

Synthetic demo datasets are included under examples/.

Dataset	Purpose
`sample_ecommerce.csv`	Ecommerce-style purchase lines across categories
`sample_performance.csv`	Sales rep performance records
`sample_campaigns.csv`	Marketing campaign performance data
`sample_sales.csv`	Small sales smoke-test dataset
`sample_inventory.csv`	Inventory-style dataset
`sample_support.csv`	Support ticket dataset

All example data is synthetic. No real customer or company data is included.

Demo flow

Open the live demo or run the project locally.
Upload examples/sample_ecommerce.csv.
Review the generated metrics, findings, charts, recommendations, and limitations.
Download:
- report.md
- findings.json
- analysis.py
Inspect the generated Python to see how the report was produced.

Local setup

Install frontend dependencies

npm install

Install backend dependencies

python3 -m pip install -r backend/requirements.txt

Start frontend

npm run dev

Start backend

cd backend
uvicorn main:app --reload

Open:

http://localhost:3000

Copy .env.example to .env. Defaults work for local development.

Current limitations

Portfolio prototype, not production SaaS.
No OS-level sandbox isolation.
Network is not blocked at the operating-system level.
Import policy is a defensive gate, not a complete security boundary.
SQLite run metadata is demo/local oriented.
Artifact storage is temporary and not durable across serverless invocations.
No multi-user account system.
No long-term run history.
No cross-run memory.
No multi-file or multi-sheet analysis workflow.
Demo upload size is capped.
Large datasets should be tested locally or moved to a more durable backend.
Ambiguous column names can reduce analysis quality.
True order count and average order value require an order ID column.
Return, refund, or cancellation analysis requires a status-like column.

More detail

Workflow stages, output artifacts, API surface, scripts, deployment and repository structure are in docs/REFERENCE.md.

License

MIT, the license recorded in the project setup.

Name		Name	Last commit message	Last commit date
.github/workflows		.github/workflows
app		app
backend		backend
docs		docs
evaluators		evaluators
examples		examples
exports		exports
prompts		prompts
sandbox		sandbox
tests		tests
workflows		workflows
.env.example		.env.example
.gitignore		.gitignore
AGENTS.md		AGENTS.md
CLAUDE.md		CLAUDE.md
LICENSE		LICENSE
NORTHSTAR.md		NORTHSTAR.md
README.md		README.md
eslint.config.mjs		eslint.config.mjs
package-lock.json		package-lock.json
package.json		package.json
pytest.ini		pytest.ini
tsconfig.json		tsconfig.json
vercel.json		vercel.json

Latest commit

History

Folders and files

Repository files navigation