X-101: Agentic BI System

An agent-assisted Business Intelligence system that converts datasets + natural language queries into validated insights and renderable dashboards.

🎯 Overview

X-101 is a compiler-like system that:

• Input: User-uploaded dataset (CSV/XLSX) + natural language query
• Output: Validated Insight JSON + dashboard definition OR structured error

The system is designed around determinism and correctness. It will never guess and will fail loudly on ambiguity.

🏗️ Architecture

Dataset + Query
      ↓
Orchestrator Agent (Intent Classification)
      ↓
Schema Intelligence Agent (Column Profiling)
      ↓
Metrics Agent (Metric Mapping)
      ↓
Validator Agent (Final Validation)
      ↓
Insight JSON → Frontend Renderer → Dashboard

Four Strictly-Scoped Agents

Agent	Responsibility	Constraints
Orchestrator	Identity intent, control flow	No data inspection, no schema reasoning
Schema Intel	Profile columns, classify fact/dimension	No column invention, no fuzzy matching
Metrics	Map to supported metrics	No custom metrics, no guessing
Validator	Final validation authority	No partial passes, no retries

Supported Metrics (Hardcoded)

• churn - Customer churn analysis
• retention - Customer retention analysis
• active_users - User activity analysis
• revenue - Revenue/transaction analysis

🚀 Quick Start

Prerequisites

• Python 3.11+
• Node.js 18+
• OpenRouter API key (get one here)

Backend Setup

# Navigate to backend
cd backend

# Create virtual environment
python -m venv venv
venv\Scripts\activate  # Windows
# source venv/bin/activate  # macOS/Linux

# Install dependencies
pip install -r requirements.txt

# Copy environment file and add your API key
copy ..\.env.example ..\.env
# Edit .env and add your OPENROUTER_API_KEY

# Run the server
python -m uvicorn main:app --reload --host 0.0.0.0 --port 8000

Frontend Setup

# Navigate to frontend
cd frontend

# Install dependencies
npm install

# Run development server
npm run dev

Generate Test Data

# From project root
python scripts/generate_test_data.py

This creates three test datasets in test_data/:

• churn_data.csv - Customer churn data
• activity_data.csv - User activity data
• revenue_data.csv - Transaction data

📡 API Reference

POST /api/analyze

Upload a dataset and analyze with a natural language query.

Request:

Content-Type: multipart/form-data

file: <CSV or XLSX file>
query: "Build a churn dashboard"

Success Response:

{
  "success": true,
  "data": {
    "metric": "churn",
    "time_grain": "monthly",
    "facts": ["monthly_revenue", "churned"],
    "dimensions": ["subscription_plan", "country"],
    "time_column": "signup_date",
    "charts": [
      {
        "type": "line",
        "x": "signup_date",
        "y": "churn_rate",
        "title": "Churn Rate Over Time"
      }
    ],
    "assumptions": ["Churn defined as no activity in last 30 days"],
    "confidence": 0.85
  }
}

Error Response:

{
  "success": false,
  "error": {
    "code": "UNSUPPORTED_INTENT",
    "message": "Unable to map query to a supported analytical goal",
    "details": {
      "query": "...",
      "supported_goals": ["churn", "retention", "active_users", "revenue"]
    }
  }
}

GET /api/supported

Get supported features.

GET /api/health

Health check endpoint.

📁 Project Structure

x101/
├── backend/
│   ├── agents/           # Four agent implementations
│   │   ├── orchestrator.py
│   │   ├── schema_intel.py
│   │   ├── metrics.py
│   │   ├── validator.py
│   │   └── llm_client.py  # LiteLLM wrapper
│   ├── models/           # Pydantic models
│   │   ├── insight.py    # InsightJSON schema
│   │   └── errors.py     # Structured errors
│   ├── pipeline/         # Pipeline coordinator
│   ├── utils/            # File handling, logging
│   ├── config.py         # Configuration
│   ├── main.py           # FastAPI app
│   └── requirements.txt
├── frontend/
│   ├── app/              # Next.js App Router
│   ├── components/       # React components
│   ├── lib/              # API client
│   └── package.json
├── scripts/
│   └── generate_test_data.py
├── test_data/            # Generated test datasets
└── .env.example

⚙️ Configuration

All settings are configured via environment variables (.env file):

Variable	Description	Default
OPENROUTER_API_KEY	OpenRouter API key	(required)
DEFAULT_MODEL	LLM model to use	openrouter/mistralai/mistral-7b-instruct
CONFIDENCE_THRESHOLD	Minimum confidence score	0.75
MAX_DIMENSION_CARDINALITY	Max unique values per dimension	100
MAX_FILE_SIZE_MB	Max upload file size	50
ENABLE_REPLAY_LOGGING	Enable determinism logs	true

Supported LLM Models (via LiteLLM)

# OpenRouter (free tier)
DEFAULT_MODEL=openrouter/mistralai/mistral-7b-instruct
DEFAULT_MODEL=openrouter/meta-llama/llama-3-8b-instruct

# Google
DEFAULT_MODEL=gemini/gemini-1.5-flash

# OpenAI
DEFAULT_MODEL=openai/gpt-4o

# Anthropic
DEFAULT_MODEL=anthropic/claude-3-sonnet

🎨 Supported Chart Types

• line - Time series trends
• bar - Categorical comparisons
• pie - Distribution/proportion
• area - Cumulative trends
• scatter - Correlation analysis
• heatmap - Matrix visualization
• funnel - Conversion flows
• radial_bar - Radial comparisons

🔒 Design Philosophy

X-101 is not designed to sound intelligent.
X-101 is designed to be right or silent.

A correct refusal is a success.

Principles

1. Correctness over convenience - Never guess, fail loudly
2. Determinism - Same input always produces same output
3. No hidden state - All inputs/outputs are logged
4. Fail fast - Reject early, don't paper over issues
5. Frontend is dumb - Pure renderer, no AI logic

📄 License

MIT