⚡ Sheetsense

AI-Powered Excel Reporting Platform — Upload any spreadsheet, get a professional Excel report with native charts generated by AI.

Sheetsense analyzes your data schema, sends it to an LLM (OpenAI or Anthropic), and executes the AI-generated Python code to produce publication-quality Excel reports with real, editable charts — not static images.

---

✨ Features

• Bring Your Own Key — Works with OpenAI (GPT-4o) and Anthropic (Claude) APIs. Keys are sent per-request via headers, never stored on the server.
• AI-Generated Reports — The LLM analyzes your data schema and writes a custom Python/XlsxWriter script tailored to your specific dataset.
• Native Excel Charts — Bar charts, line charts, pie charts — all created with XlsxWriter's chart API. Fully editable in Excel.
• Multi-Tab Analysis — AI summary, interactive Recharts visualizations, data preview, and the generated code — all in one dashboard.
• Dark Mode — Full dark/light theme support with a polished SaaS-grade UI.
• JWT Authentication — Secure user accounts with argon2 password hashing.
• Docker Ready — One command to run the entire stack.

---

🚀 Quick Start

Prerequisites

• Docker and Docker Compose
• An API key from OpenAI or Anthropic

Run with Docker Compose

# Clone the repository
git clone https://github.com/your-username/sheetsense.git
cd sheetsense

# (Optional) Create your .env file
cp .env.example .env

# Start everything
docker-compose up --build

The app will be available at http://localhost (frontend) with the API at http://localhost:8000.

Run for Development (without Docker)

Backend:

cd backend
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate
pip install -r requirements.txt
uvicorn main:app --reload --port 8000

Frontend:

cd frontend
npm install
npm run dev

Then open http://localhost:5173.

---

⚙️ Environment Variables

Variable	Default	Description
JWT_SECRET	sheetsense-dev-secret-...	Secret key for JWT token signing. Change in production.
TOKEN_EXPIRE_HOURS	24	How long auth tokens remain valid
CORS_ORIGINS	http://localhost:80,...	Comma-separated allowed CORS origins
EXPORTS_DIR	/app/exports	Directory where generated Excel files are stored

Note: AI API keys are not environment variables. Users enter their keys in the Settings modal, and they're sent per-request via the X-AI-Token header. Keys are stored only in the user's browser localStorage.

---

🧠 How It Works

Sheetsense uses a three-step pipeline to transform raw data into professional reports:

Step 1: Schema Extraction

When you upload a file, the backend reads it with Pandas and extracts a structured schema:

├── Column names, data types, non-null counts
├── Sample values (first 5 rows)
├── Numeric vs categorical column classification
└── Row/column counts

Step 2: AI Code Generation

The schema (never the raw data) is sent to your chosen LLM with a carefully engineered prompt. The AI generates a complete Python script that:

• Creates a Summary sheet with aggregated statistics
• Writes a Data sheet with professional formatting (alternating rows, auto-width columns)
• Builds a Charts sheet with native Excel charts chosen for the specific data types
• Uses only pandas and xlsxwriter — no other dependencies

Step 3: Safe Execution

The generated code runs in a restricted exec() environment with a limited set of builtins. Only pandas, numpy, and xlsxwriter are available. No file system access, no network calls, no imports beyond the whitelist.

User's Browser                     FastAPI Backend
┌──────────────┐                  ┌──────────────────┐
│ Upload .xlsx │ ──── file ────→  │ Pandas: read +   │
│              │                  │ extract schema    │
│              │                  │         │         │
│              │                  │         ▼         │
│              │                  │ AI: generate code │ ──→ OpenAI / Anthropic
│              │                  │         │         │
│              │                  │         ▼         │
│              │                  │ exec(): build     │
│ Download     │ ←── .xlsx ─────  │ Excel with charts │
└──────────────┘                  └──────────────────┘

---

📂 Project Structure

sheetsense/
├── docker-compose.yml
├── .env.example
│
├── backend/
│   ├── Dockerfile
│   ├── requirements.txt
│   ├── main.py                  # FastAPI app, routes, middleware
│   ├── schemas.py               # Pydantic v2 models
│   └── services/
│       ├── auth.py              # JWT + argon2 authentication
│       ├── ai_engine.py         # OpenAI & Anthropic integration
│       └── report_processor.py  # Pandas analysis + safe exec
│
└── frontend/
    ├── Dockerfile
    ├── nginx.conf
    ├── package.json
    ├── vite.config.js
    ├── tailwind.config.js
    └── src/
        ├── App.jsx
        ├── main.jsx
        ├── index.css
        ├── components/
        │   ├── AuthPage.jsx         # Login / Register
        │   ├── Dashboard.jsx        # Main layout + report history
        │   ├── FileUpload.jsx       # Drag & drop with progress
        │   ├── ReportView.jsx       # Multi-tab analysis view
        │   └── SettingsModal.jsx    # AI provider configuration
        ├── hooks/
        │   └── index.js            # useAuth, useTheme, useAISettings
        ├── services/
        │   └── api.js              # API client
        └── lib/
            └── utils.js            # cn() helper

---

🔐 Security Notes

• API keys are never stored on the server. They transit via the X-AI-Token request header and are used for a single LLM call.
• Passwords are hashed with argon2, the winner of the Password Hashing Competition.
• AI-generated code runs in a sandboxed exec() with a restricted builtins whitelist. Only safe operations are permitted.
• JWT tokens are signed with HS256. Always set a strong JWT_SECRET in production.

---

🛣️ Roadmap

• PostgreSQL for persistent storage (replacing in-memory dict)
• Streaming AI responses with SSE progress
• Multi-sheet upload support
• Report templates and customization
• Plotly deep-dive tab with server-side rendering
• Rate limiting and usage quotas
• Team workspaces

---

📄 License

MIT — use it however you want.

---

Built with ⚡ by the open-source community