DataBrief AI

Bounded AI analytics workflow for CSV/XLSX business reports.

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.

---

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.

---

What it does

• Upload CSV or XLSX files.
• Validate file type and size.
• Profile dataset structure, column types, missing values, duplicates, and sample rows.
• 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.
• Generate Python from a controlled template.
• Validate generated code before execution.
• Reject disallowed imports and suspicious code patterns.
• Execute analysis in a bounded subprocess.
• Evaluate execution success or failure.
• Apply up to 2 bounded repair attempts for recoverable failures.
• Validate computed summary artifacts.
• Generate a grounded business report from computed outputs only.
• Export the 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"]

Loading

---

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, 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 deterministic 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.

---

Workflow stages

upload
  -> validate file
  -> profile dataset
  -> detect semantic roles
  -> route dataset type
  -> generate analysis plan
  -> generate Python from controlled template
  -> validate code
  -> execute in bounded subprocess
  -> evaluate result
  -> repair if recoverable
  -> validate summary artifact
  -> generate grounded report
  -> store run metadata
  -> export artifacts

---

Output artifacts

Each successful run can produce:

Artifact	Format	Purpose
Business report	Markdown	Human-readable summary, findings, recommendations, and limitations
Structured findings	JSON	Machine-readable outputs and computed findings
Generated analysis	Python	Reproducible script used for the run
Chart artifacts	SVG / generated files	Visual support when chart generation succeeds

---

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

---

Repository structure

app/
  Next.js frontend

backend/
  FastAPI API and workflow services

backend/services/
  profiling, routing, planning, code generation,
  sandbox execution, evaluation, repair, reporting,
  groundedness checks, run storage

backend/tests/
  backend tests, semantic quality checks, planner tests,
  sandbox tests, export checks

examples/
  synthetic demo datasets

docs/
  case study, architecture notes, screenshots

---

API surface

Method	Route	Purpose
GET	/health	Backend health check
POST	/api/upload	Upload CSV/XLSX and run the workflow
GET	/api/runs/{run_id}	Poll run status
GET	/api/runs/{run_id}/artifacts/{name}	Retrieve generated artifact
GET	/api/runs/{run_id}/export/report.md	Download Markdown report
GET	/api/runs/{run_id}/export/findings.json	Download structured findings
GET	/api/runs/{run_id}/export/analysis.py	Download generated analysis script

API responses intentionally omit host filesystem paths.

---

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

1. Open the live demo or run the project locally.
2. Upload examples/sample_ecommerce.csv.
3. Review the generated metrics, findings, charts, recommendations, and limitations.
4. Download:
   • report.md
   • findings.json
   • analysis.py
5. 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.

---

Scripts

Command	Purpose
npm run dev	Start Next.js frontend
npm run build	Build frontend
npm run lint	Run ESLint
npm run typecheck	Run TypeScript type check
pytest -q	Run backend test suite
python3 -m compileall backend	Check Python syntax

Targeted backend tests:

pytest backend/tests/test_semantic_quality.py backend/tests/test_semantic_profile.py backend/tests/test_planner.py -q

XLSX tests require openpyxl.

---

Deployment

This repository uses Vercel services to deploy the frontend and FastAPI backend from one repo.

vercel.json configures:

Service	Framework	Route
Frontend	Next.js	/
Backend	FastAPI	/backend

Backend deployment settings:

Setting	Value
Memory	1024 MB
Max duration	60 seconds

Recommended Vercel environment variables:

Variable	Value
NEXT_PUBLIC_API_BASE_URL	/backend
DATABRIEF_ENV	production
DATABRIEF_MAX_UPLOAD_MB	5
DATABRIEF_CORS_ORIGINS	https://<your-domain>.vercel.app

Vercel is suitable for the live demo, not durable artifact storage. Serverless request-size, memory, timeout, and ephemeral-filesystem limits still apply.

---

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.

---

Portfolio relevance

This project demonstrates:

• bounded workflow design
• deterministic profiling and routing
• controlled code generation
• sandbox-aware execution
• failure classification
• bounded repair loops
• grounded report generation
• artifact exports
• explicit limitations
• productized analytics UX

The project is valuable because it shows how AI-style analytics can be made more reliable by surrounding generation with deterministic structure, validation, execution controls, and honest reporting boundaries.

---

License

No license file is currently included.