🚀 ExamInsight: AI-powered exam analysis for teachers

Features:
- Google Forms/Sheets integration
- AI grading with GPT-4.1-mini
- Beautiful HTML report generation (bilingual EN/中文)
- Chart.js visualizations
- Real-time tool call logging
- Email reports via Gmail SMTP
- Docker deployment for HF Spaces

chatkit/.dockerignore

@@ -0,0 +1,33 @@
+# Dependencies
+node_modules/
+.venv/
+__pycache__/
+*.egg-info/
+
+# Build artifacts
+dist/
+build/
+*.pyc
+
+# Local files
+.env
+.env.local
+*.db
+*.sqlite
+
+# IDE
+.vscode/
+.idea/
+*.swp
+
+# Git
+.git/
+.gitignore
+
+# Logs
+*.log
+npm-debug.log*
+
+# Test files
+coverage/
+.pytest_cache/

chatkit/.gitignore

@@ -1,3 +1,40 @@
+# Dependencies
 node_modules/
-.env*
-!.env.example
+.venv/
+__pycache__/
+*.egg-info/
+
+# Environment
+.env
+.env.local
+.env.*.local
+
+# Database
+*.db
+*.sqlite
+*.sqlite3
+
+# Build
+dist/
+build/
+*.pyc
+.cache/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+.DS_Store
+
+# Logs
+*.log
+npm-debug.log*
+
+# Test
+coverage/
+.pytest_cache/
+.nyc_output/
+
+# Local dev files
+backend/.python-version

chatkit/DEPLOY.md

@@ -0,0 +1,173 @@
+# 🚀 Deploy ExamInsight to Hugging Face Spaces
+
+## Prerequisites
+
+1. Hugging Face account with access to [taboola-cz](https://huggingface.co/taboola-cz) organization
+2. Git installed
+3. OpenAI API key
+
+## Step 1: Create the Space
+
+### Option A: Via Hugging Face Web UI
+
+1. Go to https://huggingface.co/new-space?owner=taboola-cz
+2. Fill in:
+   - **Space name**: `examinsight`
+   - **License**: MIT
+   - **SDK**: Docker
+   - **Visibility**: Public (or Private)
+3. Click "Create Space"
+
+### Option B: Via Git
+
+```bash
+# Clone the empty space
+git clone https://huggingface.co/spaces/taboola-cz/examinsight
+cd examinsight
+```
+
+## Step 2: Push the Code
+
+```bash
+# From the examinsight-app/chatkit directory
+cd /path/to/ClassLens/examinsight-app/chatkit
+
+# Add HF as remote
+git remote add hf https://huggingface.co/spaces/taboola-cz/examinsight
+
+# Push to HF Spaces
+git push hf main
+```
+
+Or copy files manually:
+
+```bash
+# Copy necessary files to the HF Space repo
+cp -r backend frontend Dockerfile README.md .dockerignore /path/to/examinsight-space/
+```
+
+## Step 3: Configure Secrets
+
+Go to your Space settings: https://huggingface.co/spaces/taboola-cz/examinsight/settings
+
+Add these **Repository secrets**:
+
+| Secret Name | Description | Required |
+|-------------|-------------|----------|
+| `OPENAI_API_KEY` | Your OpenAI API key | ✅ Yes |
+| `ENCRYPTION_KEY` | Fernet key for token encryption | ✅ Yes |
+| `GOOGLE_CLIENT_ID` | Google OAuth client ID | Optional |
+| `GOOGLE_CLIENT_SECRET` | Google OAuth secret | Optional |
+| `GOOGLE_REDIRECT_URI` | `https://taboola-cz-examinsight.hf.space/auth/callback` | Optional |
+| `GMAIL_USER` | Gmail address for sending reports | Optional |
+| `GMAIL_APP_PASSWORD` | Gmail App Password | Optional |
+| `VITE_CHATKIT_API_DOMAIN_KEY` | ChatKit domain key | ✅ Yes |
+
+### Generate Encryption Key
+
+```bash
+python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"
+```
+
+### Get ChatKit Domain Key
+
+1. Go to https://platform.openai.com/settings/organization/security/domain-allowlist
+2. Add domain: `taboola-cz-examinsight.hf.space`
+3. Copy the generated domain key
+
+## Step 4: Update Google OAuth (if using)
+
+1. Go to [Google Cloud Console](https://console.cloud.google.com/apis/credentials)
+2. Edit your OAuth 2.0 Client
+3. Add to **Authorized redirect URIs**:
+   ```
+   https://taboola-cz-examinsight.hf.space/auth/callback
+   ```
+4. Add to **Authorized JavaScript origins**:
+   ```
+   https://taboola-cz-examinsight.hf.space
+   ```
+
+## Step 5: Deploy
+
+The Space will automatically build when you push. Watch the build logs at:
+https://huggingface.co/spaces/taboola-cz/examinsight/logs
+
+## File Structure for HF Spaces
+
+```
+examinsight/
+├── Dockerfile          # Multi-stage build
+├── README.md           # Space config (YAML frontmatter)
+├── .dockerignore       # Files to exclude from build
+├── backend/
+│   ├── pyproject.toml
+│   └── app/
+│       ├── main.py     # FastAPI + static file serving
+│       ├── server.py   # ChatKit agent
+│       └── ...
+└── frontend/
+    ├── package.json
+    └── src/
+        └── ...
+```
+
+## Troubleshooting
+
+### Build Failed
+
+Check the build logs for errors:
+- Missing dependencies → Update `pyproject.toml`
+- Node version issues → Update Dockerfile
+
+### ChatKit Not Working
+
+1. Verify `OPENAI_API_KEY` is set in secrets
+2. Verify `VITE_CHATKIT_API_DOMAIN_KEY` is set and valid
+3. Check that domain is allowlisted in OpenAI dashboard
+
+### Google OAuth Not Working
+
+1. Verify redirect URI matches exactly
+2. Check that test users are added (if app is in testing mode)
+3. Verify Google Cloud APIs are enabled
+
+### Static Files Not Serving
+
+1. Check that frontend build succeeded (look for `/static/index.html` in container)
+2. Verify `STATIC_DIR` path in `main.py`
+
+## Local Testing with Docker
+
+```bash
+# Build the image
+docker build -t examinsight .
+
+# Run with env file
+docker run -p 7860:7860 --env-file .env examinsight
+
+# Open http://localhost:7860
+```
+
+## Updating the Space
+
+```bash
+# Make changes locally
+# Commit and push
+git add .
+git commit -m "Update feature X"
+git push hf main
+```
+
+The Space will automatically rebuild.
+
+---
+
+## Quick Reference
+
+| URL | Description |
+|-----|-------------|
+| https://huggingface.co/spaces/taboola-cz/examinsight | Live Space |
+| https://huggingface.co/spaces/taboola-cz/examinsight/settings | Settings & Secrets |
+| https://huggingface.co/spaces/taboola-cz/examinsight/logs | Build & Runtime Logs |
+| https://platform.openai.com/settings/organization/security/domain-allowlist | ChatKit Domain Keys |

chatkit/Dockerfile

@@ -0,0 +1,59 @@
+# ExamInsight - Hugging Face Spaces Docker Deployment
+# Multi-stage build for React frontend + FastAPI backend
+
+# =============================================================================
+# Stage 1: Build React Frontend
+# =============================================================================
+FROM node:20-slim AS frontend-builder
+
+WORKDIR /app/frontend
+
+# Copy package files
+COPY frontend/package*.json ./
+
+# Install dependencies
+RUN npm ci --legacy-peer-deps
+
+# Copy source files
+COPY frontend/ ./
+
+# Build for production (output to dist/)
+RUN npm run build
+
+# =============================================================================
+# Stage 2: Python Backend + Serve Frontend
+# =============================================================================
+FROM python:3.11-slim
+
+# Set environment variables
+ENV PYTHONUNBUFFERED=1
+ENV PYTHONDONTWRITEBYTECODE=1
+
+# Create non-root user for HF Spaces
+RUN useradd -m -u 1000 user
+USER user
+ENV HOME=/home/user
+ENV PATH=/home/user/.local/bin:$PATH
+
+WORKDIR $HOME/app
+
+# Install Python dependencies
+COPY --chown=user backend/pyproject.toml ./
+RUN pip install --no-cache-dir --upgrade pip && \
+    pip install --no-cache-dir .
+
+# Copy backend code
+COPY --chown=user backend/app ./app
+
+# Copy built frontend from Stage 1
+COPY --from=frontend-builder --chown=user /app/frontend/dist ./static
+
+# Expose port (HF Spaces uses 7860)
+EXPOSE 7860
+
+# Health check
+HEALTHCHECK --interval=30s --timeout=10s --start-period=5s --retries=3 \
+    CMD python -c "import urllib.request; urllib.request.urlopen('http://localhost:7860/health')"
+
+# Run the server
+CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "7860"]

chatkit/README.md

@@ -1,32 +1,67 @@
-# ChatKit Starter
+---
+title: ExamInsight
+emoji: 📊
+colorFrom: teal
+colorTo: pink
+sdk: docker
+app_port: 7860
+pinned: false
+license: mit
+short_description: AI-powered exam analysis for teachers
+---
 
-Minimal Vite + React UI paired with a FastAPI backend that forwards chat
-requests to OpenAI through the ChatKit server library.
+# 📊 ExamInsight
 
-## Quick start
+**AI-powered exam analysis that transforms Google Form quiz responses into beautiful, actionable reports for teachers.**
 
-```bash
-npm install
-npm run dev
-```
+## ✨ Features
 
-What happens:
+- 🔗 **Google Forms Integration**: Paste your Google Form response sheet URL
+- 📈 **Automatic Grading**: Compare student answers to your answer key
+- 📊 **Visual Statistics**: Interactive charts showing score distribution and per-question accuracy
+- 🎯 **Detailed Explanations**: Bilingual (English + 中文) explanations for each question
+- 👥 **Peer Learning Groups**: AI-suggested groupings for collaborative learning
+- 📧 **Email Reports**: Send beautiful HTML reports directly to your inbox
+- 🎨 **Beautiful Reports**: Dark theme with Chart.js visualizations
 
-- `npm run dev` starts the FastAPI backend on `127.0.0.1:8000` and the Vite
-  frontend on `127.0.0.1:3000` with a proxy at `/chatkit`.
+## 🚀 How to Use
 
-## Required environment
+1. **Paste your Google Form URL** (the response spreadsheet, not the form itself)
+2. **Provide your email** (for receiving the report)
+3. **Optionally add answer key** if not embedded in the form
+4. **Click analyze** and watch the AI work!
 
-- `OPENAI_API_KEY` (backend)
-- `VITE_CHATKIT_API_URL` (optional, defaults to `/chatkit`)
-- `VITE_CHATKIT_API_DOMAIN_KEY` (optional, defaults to `domain_pk_localhost_dev`)
+## 🔐 Privacy
 
-Set `OPENAI_API_KEY` in your shell or in `.env.local` at the repo root before
-running the backend. Register a production domain key in the OpenAI dashboard
-and set `VITE_CHATKIT_API_DOMAIN_KEY` when deploying.
+- Student names are anonymized in reports (e.g., 李X恩)
+- No data is stored permanently
+- OAuth tokens are encrypted
 
-## Customize
+## 🛠️ Tech Stack
 
-- Update UI and connection settings in `frontend/src/lib/config.ts`.
-- Adjust layout in `frontend/src/components/ChatKitPanel.tsx`.
-- Swap the in-memory store in `backend/app/server.py` for persistence.
+- **Frontend**: React + Vite + TailwindCSS
+- **Backend**: FastAPI + OpenAI ChatKit
+- **Charts**: Chart.js
+- **AI**: GPT-4.1-mini
+
+## 📝 Example Report Sections
+
+### 📝 Q&A Analysis (題目詳解)
+- Reading passages with highlighted key terms
+- Per-question explanations with concept tags
+- Common mistakes and solving strategies
+
+### 📊 Statistics (成績統計)
+- Score distribution bar chart
+- Question accuracy doughnut chart
+- Individual student performance table
+
+### 👩‍🏫 Teacher Insights (教師建議)
+- Overall performance analysis
+- Teaching recommendations
+- AI prompt for next quiz generation
+- Individual student support suggestions
+
+---
+
+Built with ❤️ by [taboola-cz](https://huggingface.co/taboola-cz) for educators

chatkit/backend/app/__init__.py

@@ -1 +1,3 @@
-"""Minimal ChatKit backend package."""
+"""ExamInsight Backend - AI-Powered Exam Analysis for Teachers."""
+
+__version__ = "1.0.0"

chatkit/backend/app/config.py

@@ -0,0 +1,67 @@
+"""Configuration management for ExamInsight backend."""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+from functools import lru_cache
+
+from dotenv import load_dotenv
+from pydantic import BaseModel
+
+# Load .env file from the chatkit directory (parent of backend)
+env_path = Path(__file__).parent.parent.parent / ".env"
+load_dotenv(env_path)
+
+
+class Settings(BaseModel):
+    """Application settings loaded from environment variables."""
+    
+    # OpenAI
+    openai_api_key: str = ""
+    
+    # Google OAuth
+    google_client_id: str = ""
+    google_client_secret: str = ""
+    google_redirect_uri: str = "http://localhost:8000/auth/callback"
+    
+    # SendGrid
+    sendgrid_api_key: str = ""
+    sendgrid_from_email: str = "examinsight@example.com"
+    
+    # Database
+    database_url: str = "sqlite+aiosqlite:///./examinsight.db"
+    
+    # Encryption key for tokens (32 bytes, base64 encoded)
+    encryption_key: str = ""
+    
+    # Frontend URL for redirects
+    frontend_url: str = "http://localhost:3000"
+    
+    class Config:
+        env_file = ".env"
+
+
+@lru_cache
+def get_settings() -> Settings:
+    """Get cached settings instance."""
+    return Settings(
+        openai_api_key=os.getenv("OPENAI_API_KEY", ""),
+        google_client_id=os.getenv("GOOGLE_CLIENT_ID", ""),
+        google_client_secret=os.getenv("GOOGLE_CLIENT_SECRET", ""),
+        google_redirect_uri=os.getenv("GOOGLE_REDIRECT_URI", "http://localhost:8000/auth/callback"),
+        sendgrid_api_key=os.getenv("SENDGRID_API_KEY", ""),
+        sendgrid_from_email=os.getenv("SENDGRID_FROM_EMAIL", "examinsight@example.com"),
+        database_url=os.getenv("DATABASE_URL", "sqlite+aiosqlite:///./examinsight.db"),
+        encryption_key=os.getenv("ENCRYPTION_KEY", ""),
+        frontend_url=os.getenv("FRONTEND_URL", "http://localhost:3000"),
+    )
+
+
+# Google OAuth scopes required for the application
+GOOGLE_SCOPES = [
+    "https://www.googleapis.com/auth/spreadsheets.readonly",
+    "https://www.googleapis.com/auth/drive.readonly",
+    "https://www.googleapis.com/auth/userinfo.email",
+    "openid",
+]

chatkit/backend/app/database.py

@@ -0,0 +1,137 @@
+"""SQLite database for token storage."""
+
+from __future__ import annotations
+
+import aiosqlite
+import json
+import base64
+import os
+from pathlib import Path
+from datetime import datetime
+from typing import Optional
+
+from cryptography.fernet import Fernet
+
+
+DATABASE_PATH = Path(__file__).parent.parent / "examinsight.db"
+
+
+def get_encryption_key() -> bytes:
+    """Get or generate encryption key."""
+    key = os.getenv("ENCRYPTION_KEY", "")
+    if not key:
+        # Generate a new key for development (should be set in production)
+        key = Fernet.generate_key().decode()
+        print(f"⚠️  No ENCRYPTION_KEY set. Generated temporary key: {key}")
+        print("⚠️  Set this in your .env file for persistent token storage.")
+    return key.encode() if isinstance(key, str) else key
+
+
+def encrypt_token(token_data: dict) -> str:
+    """Encrypt token data for storage."""
+    key = get_encryption_key()
+    f = Fernet(key)
+    json_data = json.dumps(token_data)
+    encrypted = f.encrypt(json_data.encode())
+    return base64.b64encode(encrypted).decode()
+
+
+def decrypt_token(encrypted_data: str) -> dict:
+    """Decrypt stored token data."""
+    key = get_encryption_key()
+    f = Fernet(key)
+    encrypted = base64.b64decode(encrypted_data.encode())
+    decrypted = f.decrypt(encrypted)
+    return json.loads(decrypted.decode())
+
+
+async def init_database():
+    """Initialize the database with required tables."""
+    async with aiosqlite.connect(DATABASE_PATH) as db:
+        await db.execute("""
+            CREATE TABLE IF NOT EXISTS oauth_tokens (
+                teacher_email TEXT PRIMARY KEY,
+                encrypted_tokens TEXT NOT NULL,
+                created_at TEXT NOT NULL,
+                updated_at TEXT NOT NULL
+            )
+        """)
+        
+        await db.execute("""
+            CREATE TABLE IF NOT EXISTS analysis_reports (
+                id INTEGER PRIMARY KEY AUTOINCREMENT,
+                teacher_email TEXT NOT NULL,
+                exam_title TEXT,
+                report_markdown TEXT,
+                report_json TEXT,
+                created_at TEXT NOT NULL
+            )
+        """)
+        
+        await db.commit()
+
+
+async def save_oauth_tokens(teacher_email: str, tokens: dict):
+    """Save encrypted OAuth tokens for a teacher."""
+    encrypted = encrypt_token(tokens)
+    now = datetime.utcnow().isoformat()
+    
+    async with aiosqlite.connect(DATABASE_PATH) as db:
+        await db.execute("""
+            INSERT INTO oauth_tokens (teacher_email, encrypted_tokens, created_at, updated_at)
+            VALUES (?, ?, ?, ?)
+            ON CONFLICT(teacher_email) DO UPDATE SET
+                encrypted_tokens = excluded.encrypted_tokens,
+                updated_at = excluded.updated_at
+        """, (teacher_email, encrypted, now, now))
+        await db.commit()
+
+
+async def get_oauth_tokens(teacher_email: str) -> Optional[dict]:
+    """Retrieve OAuth tokens for a teacher."""
+    async with aiosqlite.connect(DATABASE_PATH) as db:
+        async with db.execute(
+            "SELECT encrypted_tokens FROM oauth_tokens WHERE teacher_email = ?",
+            (teacher_email,)
+        ) as cursor:
+            row = await cursor.fetchone()
+            if row:
+                return decrypt_token(row[0])
+    return None
+
+
+async def delete_oauth_tokens(teacher_email: str):
+    """Delete OAuth tokens for a teacher."""
+    async with aiosqlite.connect(DATABASE_PATH) as db:
+        await db.execute(
+            "DELETE FROM oauth_tokens WHERE teacher_email = ?",
+            (teacher_email,)
+        )
+        await db.commit()
+
+
+async def save_report(teacher_email: str, exam_title: str, report_markdown: str, report_json: str):
+    """Save an analysis report."""
+    now = datetime.utcnow().isoformat()
+    
+    async with aiosqlite.connect(DATABASE_PATH) as db:
+        await db.execute("""
+            INSERT INTO analysis_reports (teacher_email, exam_title, report_markdown, report_json, created_at)
+            VALUES (?, ?, ?, ?, ?)
+        """, (teacher_email, exam_title, report_markdown, report_json, now))
+        await db.commit()
+
+
+async def get_teacher_reports(teacher_email: str, limit: int = 10) -> list[dict]:
+    """Get recent reports for a teacher."""
+    async with aiosqlite.connect(DATABASE_PATH) as db:
+        db.row_factory = aiosqlite.Row
+        async with db.execute("""
+            SELECT id, exam_title, report_markdown, report_json, created_at
+            FROM analysis_reports
+            WHERE teacher_email = ?
+            ORDER BY created_at DESC
+            LIMIT ?
+        """, (teacher_email, limit)) as cursor:
+            rows = await cursor.fetchall()
+            return [dict(row) for row in rows]

chatkit/backend/app/email_service.py

@@ -0,0 +1,250 @@
+"""Email service for sending exam reports to teachers."""
+
+from __future__ import annotations
+
+import os
+import smtplib
+import ssl
+from email.mime.text import MIMEText
+from email.mime.multipart import MIMEMultipart
+from typing import Optional
+
+import markdown
+
+from .config import get_settings
+
+
+def markdown_to_html(md_content: str) -> str:
+    """Convert markdown to styled HTML for email."""
+    # Convert markdown to HTML
+    html_body = markdown.markdown(
+        md_content,
+        extensions=['tables', 'fenced_code', 'nl2br']
+    )
+    
+    # Wrap in email template
+    return f"""
+    <!DOCTYPE html>
+    <html>
+    <head>
+        <meta charset="utf-8">
+        <meta name="viewport" content="width=device-width, initial-scale=1.0">
+        <style>
+            body {{
+                font-family: 'Segoe UI', Tahoma, Geneva, Verdana, sans-serif;
+                line-height: 1.6;
+                color: #333;
+                max-width: 800px;
+                margin: 0 auto;
+                padding: 20px;
+                background-color: #f5f5f5;
+            }}
+            .container {{
+                background-color: white;
+                padding: 30px;
+                border-radius: 10px;
+                box-shadow: 0 2px 10px rgba(0,0,0,0.1);
+            }}
+            h1 {{
+                color: #2563eb;
+                border-bottom: 2px solid #2563eb;
+                padding-bottom: 10px;
+            }}
+            h2 {{
+                color: #1e40af;
+                margin-top: 30px;
+            }}
+            h3 {{
+                color: #3b82f6;
+            }}
+            table {{
+                width: 100%;
+                border-collapse: collapse;
+                margin: 20px 0;
+            }}
+            th, td {{
+                border: 1px solid #ddd;
+                padding: 12px;
+                text-align: left;
+            }}
+            th {{
+                background-color: #2563eb;
+                color: white;
+            }}
+            tr:nth-child(even) {{
+                background-color: #f8fafc;
+            }}
+            code {{
+                background-color: #f1f5f9;
+                padding: 2px 6px;
+                border-radius: 4px;
+                font-family: monospace;
+            }}
+            .footer {{
+                margin-top: 40px;
+                padding-top: 20px;
+                border-top: 1px solid #ddd;
+                text-align: center;
+                color: #666;
+                font-size: 0.9em;
+            }}
+        </style>
+    </head>
+    <body>
+        <div class="container">
+            {html_body}
+            <div class="footer">
+                <p>Generated by ExamInsight • AI-Powered Exam Analysis for Teachers</p>
+            </div>
+        </div>
+    </body>
+    </html>
+    """
+
+
+async def send_email_via_gmail(
+    to_email: str,
+    subject: str,
+    body_markdown: str,
+    gmail_user: str,
+    gmail_app_password: str
+) -> dict:
+    """
+    Send email using Gmail SMTP.
+    
+    Requires:
+    - Gmail account
+    - App Password (not your regular password)
+    
+    To get an App Password:
+    1. Enable 2-Step Verification on your Google account
+    2. Go to https://myaccount.google.com/apppasswords
+    3. Generate an app password for "Mail"
+    """
+    try:
+        html_content = markdown_to_html(body_markdown)
+        
+        # Create message
+        message = MIMEMultipart("alternative")
+        message["Subject"] = subject
+        message["From"] = gmail_user
+        message["To"] = to_email
+        
+        # Add plain text and HTML versions
+        part1 = MIMEText(body_markdown, "plain")
+        part2 = MIMEText(html_content, "html")
+        message.attach(part1)
+        message.attach(part2)
+        
+        # Create secure connection and send
+        context = ssl.create_default_context()
+        with smtplib.SMTP_SSL("smtp.gmail.com", 465, context=context) as server:
+            server.login(gmail_user, gmail_app_password)
+            server.sendmail(gmail_user, to_email, message.as_string())
+        
+        return {"status": "ok", "message": "Email sent via Gmail"}
+        
+    except smtplib.SMTPAuthenticationError:
+        return {
+            "status": "error",
+            "message": "Gmail authentication failed. Check your email and app password."
+        }
+    except Exception as e:
+        return {
+            "status": "error",
+            "message": f"Failed to send email: {str(e)}"
+        }
+
+
+async def send_email_via_sendgrid(
+    to_email: str,
+    subject: str,
+    body_markdown: str
+) -> dict:
+    """Send email using SendGrid API."""
+    settings = get_settings()
+    
+    try:
+        from sendgrid import SendGridAPIClient
+        from sendgrid.helpers.mail import Mail, Email, To, Content, HtmlContent
+        
+        html_content = markdown_to_html(body_markdown)
+        
+        message = Mail(
+            from_email=Email(settings.sendgrid_from_email, "ExamInsight"),
+            to_emails=To(to_email),
+            subject=subject,
+            html_content=HtmlContent(html_content)
+        )
+        message.add_content(Content("text/plain", body_markdown))
+        
+        sg = SendGridAPIClient(settings.sendgrid_api_key)
+        response = sg.send(message)
+        
+        if response.status_code in (200, 201, 202):
+            return {"status": "ok", "message": "Email sent via SendGrid"}
+        else:
+            return {
+                "status": "error",
+                "message": f"SendGrid returned status {response.status_code}"
+            }
+            
+    except Exception as e:
+        return {
+            "status": "error",
+            "message": str(e)
+        }
+
+
+async def send_email_report(
+    email: str,
+    subject: str,
+    body_markdown: str
+) -> dict:
+    """
+    Send an email report to a teacher.
+    
+    Tries in order:
+    1. Gmail SMTP (if configured)
+    2. SendGrid (if configured)
+    3. Logs to console (fallback)
+    
+    Returns:
+        {"status": "ok"} on success
+        {"status": "error", "message": str} on failure
+    """
+    # Try Gmail SMTP first
+    gmail_user = os.getenv("GMAIL_USER", "")
+    gmail_app_password = os.getenv("GMAIL_APP_PASSWORD", "")
+    
+    if gmail_user and gmail_app_password:
+        result = await send_email_via_gmail(email, subject, body_markdown, gmail_user, gmail_app_password)
+        if result["status"] == "ok":
+            print(f"📧 Email sent to {email} via Gmail")
+            return result
+        else:
+            print(f"⚠️ Gmail failed: {result['message']}, trying fallback...")
+    
+    # Try SendGrid
+    settings = get_settings()
+    if settings.sendgrid_api_key:
+        result = await send_email_via_sendgrid(email, subject, body_markdown)
+        if result["status"] == "ok":
+            print(f"📧 Email sent to {email} via SendGrid")
+            return result
+        else:
+            print(f"⚠️ SendGrid failed: {result['message']}")
+    
+    # Fallback: print to console
+    print(f"\n{'='*60}")
+    print(f"📧 EMAIL (not sent - no email service configured)")
+    print(f"To: {email}")
+    print(f"Subject: {subject}")
+    print(f"{'='*60}")
+    print(body_markdown[:500] + "..." if len(body_markdown) > 500 else body_markdown)
+    print(f"{'='*60}\n")
+    
+    return {
+        "status": "ok", 
+        "message": "Email logged to console (configure GMAIL_USER/GMAIL_APP_PASSWORD or SENDGRID_API_KEY to send real emails)"
+    }

chatkit/backend/app/google_sheets.py

@@ -0,0 +1,408 @@
+"""Google Sheets API service for fetching form responses."""
+
+from __future__ import annotations
+
+import re
+import csv
+from io import StringIO
+from typing import Optional
+from datetime import datetime
+
+import httpx
+
+from google.oauth2.credentials import Credentials
+from google.auth.transport.requests import Request
+from googleapiclient.discovery import build
+from googleapiclient.errors import HttpError
+
+from .database import get_oauth_tokens, save_oauth_tokens
+from .config import get_settings, GOOGLE_SCOPES
+
+
+def extract_sheet_id(url: str) -> Optional[str]:
+    """Extract the spreadsheet ID from a Google Sheets or Forms URL."""
+    # Google Sheets URL pattern
+    sheets_pattern = r'/spreadsheets/d/([a-zA-Z0-9-_]+)'
+    sheets_match = re.search(sheets_pattern, url)
+    if sheets_match:
+        return sheets_match.group(1)
+    
+    # Google Forms URL pattern - need to find linked response sheet
+    forms_pattern = r'/forms/d/e?/?([a-zA-Z0-9-_]+)'
+    forms_match = re.search(forms_pattern, url)
+    if forms_match:
+        # For forms, we need to handle this differently
+        # The user should provide the response sheet URL directly
+        return None
+    
+    return None
+
+
+async def fetch_public_sheet(sheet_id: str, answer_key: Optional[dict] = None) -> dict:
+    """
+    Fetch data from a PUBLIC Google Sheet (no OAuth needed).
+    The sheet must be shared as "Anyone with the link can view".
+    
+    Uses the CSV export endpoint which works for public sheets.
+    """
+    # Google Sheets public CSV export URL
+    csv_url = f"https://docs.google.com/spreadsheets/d/{sheet_id}/export?format=csv"
+    
+    try:
+        async with httpx.AsyncClient(follow_redirects=True) as client:
+            response = await client.get(csv_url, timeout=30.0)
+            
+            if response.status_code == 200:
+                csv_content = response.text
+                
+                # Check if we got actual CSV data
+                if csv_content.startswith('<!DOCTYPE') or '<html' in csv_content[:100].lower():
+                    return {
+                        "error": "This sheet is not public. Please make it 'Anyone with the link can view' or use CSV export.",
+                        "needs_auth": False
+                    }
+                
+                # Parse the CSV
+                result = parse_csv_responses(csv_content, answer_key)
+                if "error" not in result:
+                    result["exam_title"] = f"Google Sheet {sheet_id[:8]}..."
+                return result
+                
+            elif response.status_code == 404:
+                return {
+                    "error": "Sheet not found. Please check the URL.",
+                    "needs_auth": False
+                }
+            else:
+                return {
+                    "error": f"Could not access sheet (status {response.status_code}). Make sure it's set to 'Anyone with the link can view'.",
+                    "needs_auth": False
+                }
+                
+    except httpx.TimeoutException:
+        return {
+            "error": "Request timed out. Please try again.",
+            "needs_auth": False
+        }
+    except Exception as e:
+        return {
+            "error": f"Error fetching sheet: {str(e)}",
+            "needs_auth": False
+        }
+
+
+async def get_google_credentials(teacher_email: str) -> Optional[Credentials]:
+    """Get valid Google credentials for a teacher."""
+    tokens = await get_oauth_tokens(teacher_email)
+    if not tokens:
+        return None
+    
+    settings = get_settings()
+    
+    credentials = Credentials(
+        token=tokens.get("access_token"),
+        refresh_token=tokens.get("refresh_token"),
+        token_uri="https://oauth2.googleapis.com/token",
+        client_id=settings.google_client_id,
+        client_secret=settings.google_client_secret,
+        scopes=GOOGLE_SCOPES,
+    )
+    
+    # Refresh if expired
+    if credentials.expired and credentials.refresh_token:
+        try:
+            credentials.refresh(Request())
+            # Save updated tokens
+            new_tokens = {
+                "access_token": credentials.token,
+                "refresh_token": credentials.refresh_token,
+            }
+            await save_oauth_tokens(teacher_email, new_tokens)
+        except Exception as e:
+            print(f"Error refreshing credentials: {e}")
+            return None
+    
+    return credentials
+
+
+def normalize_question_type(header: str, sample_answers: list[str]) -> str:
+    """Infer question type from header and sample answers."""
+    header_lower = header.lower()
+    
+    # Check for common patterns
+    if any(word in header_lower for word in ['multiple choice', 'mcq', 'select']):
+        return 'mcq'
+    
+    # Check if answers are numeric
+    numeric_count = 0
+    for answer in sample_answers[:5]:  # Check first 5 answers
+        if answer:
+            try:
+                float(answer.replace(',', ''))
+                numeric_count += 1
+            except ValueError:
+                pass
+    
+    if numeric_count >= len([a for a in sample_answers[:5] if a]) * 0.8:
+        return 'numeric'
+    
+    # Check for short answers (likely MCQ) vs long answers (open)
+    avg_length = sum(len(a) for a in sample_answers if a) / max(len([a for a in sample_answers if a]), 1)
+    if avg_length < 20:
+        return 'mcq'
+    
+    return 'open'
+
+
+def extract_question_text(header: str) -> str:
+    """Extract clean question text from a header."""
+    # Remove common prefixes like "Q1:", "1.", etc.
+    cleaned = re.sub(r'^[Q]?\d+[\.\:\)]\s*', '', header)
+    # Remove parenthetical scoring info like "(2 points)"
+    cleaned = re.sub(r'\s*\(\d+\s*(?:points?|pts?|marks?)\)\s*$', '', cleaned, flags=re.IGNORECASE)
+    return cleaned.strip() or header
+
+
+async def fetch_google_form_responses(
+    google_form_url: str,
+    teacher_email: str,
+    answer_key: Optional[dict] = None
+) -> dict:
+    """
+    Fetch responses from a Google Form's response spreadsheet.
+    
+    Returns normalized exam JSON format:
+    {
+        "exam_title": str,
+        "questions": [{"question_id", "question_text", "type", "choices", "correct_answer"}],
+        "responses": [{"student_id", "student_name", "answers": {...}}]
+    }
+    """
+    credentials = await get_google_credentials(teacher_email)
+    if not credentials:
+        return {
+            "error": "Not authorized. Please connect your Google account first.",
+            "needs_auth": True
+        }
+    
+    sheet_id = extract_sheet_id(google_form_url)
+    if not sheet_id:
+        return {
+            "error": "Could not extract spreadsheet ID from URL. Please provide a valid Google Sheets response URL.",
+            "needs_auth": False
+        }
+    
+    try:
+        # Build the Sheets API service
+        service = build('sheets', 'v4', credentials=credentials)
+        
+        # Get spreadsheet metadata
+        spreadsheet = service.spreadsheets().get(spreadsheetId=sheet_id).execute()
+        title = spreadsheet.get('properties', {}).get('title', 'Untitled Exam')
+        
+        # Try to find "Form Responses 1" sheet, or use first sheet
+        sheet_name = None
+        for sheet in spreadsheet.get('sheets', []):
+            props = sheet.get('properties', {})
+            name = props.get('title', '')
+            if 'response' in name.lower() or 'form' in name.lower():
+                sheet_name = name
+                break
+        
+        if not sheet_name:
+            sheet_name = spreadsheet['sheets'][0]['properties']['title']
+        
+        # Fetch all values
+        result = service.spreadsheets().values().get(
+            spreadsheetId=sheet_id,
+            range=f"'{sheet_name}'!A:ZZ"
+        ).execute()
+        
+        values = result.get('values', [])
+        if not values or len(values) < 2:
+            return {
+                "error": "No responses found in the spreadsheet.",
+                "needs_auth": False
+            }
+        
+        # First row is headers
+        headers = values[0]
+        responses_data = values[1:]
+        
+        # Identify columns
+        # Typically: Timestamp, Email, Name, Q1, Q2, ...
+        timestamp_col = None
+        email_col = None
+        name_col = None
+        question_cols = []
+        
+        for idx, header in enumerate(headers):
+            header_lower = header.lower()
+            if 'timestamp' in header_lower or 'time' in header_lower:
+                timestamp_col = idx
+            elif 'email' in header_lower and email_col is None:
+                email_col = idx
+            elif any(word in header_lower for word in ['name', 'student', 'your name']):
+                name_col = idx
+            else:
+                # This is likely a question
+                question_cols.append((idx, header))
+        
+        # Build questions list
+        questions = []
+        for q_idx, (col_idx, header) in enumerate(question_cols):
+            question_id = f"Q{q_idx + 1}"
+            
+            # Sample answers for type detection
+            sample_answers = [row[col_idx] if col_idx < len(row) else "" for row in responses_data[:10]]
+            
+            question = {
+                "question_id": question_id,
+                "question_text": extract_question_text(header),
+                "type": normalize_question_type(header, sample_answers),
+                "choices": [],  # Would need to parse from form structure
+                "correct_answer": ""
+            }
+            
+            # Apply answer key if provided
+            if answer_key and question_id in answer_key:
+                question["correct_answer"] = answer_key[question_id]
+            
+            questions.append(question)
+        
+        # Build responses list
+        responses = []
+        for row_idx, row in enumerate(responses_data):
+            student_id = f"S{row_idx + 1:02d}"
+            
+            # Get student name
+            if name_col is not None and name_col < len(row):
+                student_name = row[name_col]
+            elif email_col is not None and email_col < len(row):
+                # Use email prefix as name
+                email = row[email_col]
+                student_name = email.split('@')[0] if '@' in email else email
+            else:
+                student_name = f"Student {row_idx + 1}"
+            
+            # Get answers
+            answers = {}
+            for q_idx, (col_idx, _) in enumerate(question_cols):
+                question_id = f"Q{q_idx + 1}"
+                answer = row[col_idx] if col_idx < len(row) else ""
+                answers[question_id] = answer
+            
+            responses.append({
+                "student_id": student_id,
+                "student_name": student_name,
+                "answers": answers
+            })
+        
+        return {
+            "exam_title": title,
+            "questions": questions,
+            "responses": responses
+        }
+        
+    except HttpError as e:
+        if e.resp.status == 403:
+            return {
+                "error": "Access denied. Please ensure the spreadsheet is shared with your Google account.",
+                "needs_auth": False
+            }
+        elif e.resp.status == 404:
+            return {
+                "error": "Spreadsheet not found. Please check the URL.",
+                "needs_auth": False
+            }
+        else:
+            return {
+                "error": f"Google API error: {str(e)}",
+                "needs_auth": False
+            }
+    except Exception as e:
+        return {
+            "error": f"Error fetching responses: {str(e)}",
+            "needs_auth": False
+        }
+
+
+def parse_csv_responses(csv_content: str, answer_key: Optional[dict] = None) -> dict:
+    """
+    Parse CSV content into normalized exam format.
+    Fallback when OAuth is not available.
+    """
+    import csv
+    from io import StringIO
+    
+    reader = csv.reader(StringIO(csv_content))
+    rows = list(reader)
+    
+    if not rows or len(rows) < 2:
+        return {"error": "CSV must have at least a header row and one response."}
+    
+    headers = rows[0]
+    responses_data = rows[1:]
+    
+    # Same logic as Google Sheets parsing
+    timestamp_col = None
+    email_col = None
+    name_col = None
+    question_cols = []
+    
+    for idx, header in enumerate(headers):
+        header_lower = header.lower()
+        if 'timestamp' in header_lower:
+            timestamp_col = idx
+        elif 'email' in header_lower and email_col is None:
+            email_col = idx
+        elif any(word in header_lower for word in ['name', 'student']):
+            name_col = idx
+        else:
+            question_cols.append((idx, header))
+    
+    # Build questions
+    questions = []
+    for q_idx, (col_idx, header) in enumerate(question_cols):
+        question_id = f"Q{q_idx + 1}"
+        sample_answers = [row[col_idx] if col_idx < len(row) else "" for row in responses_data[:10]]
+        
+        question = {
+            "question_id": question_id,
+            "question_text": extract_question_text(header),
+            "type": normalize_question_type(header, sample_answers),
+            "choices": [],
+            "correct_answer": answer_key.get(question_id, "") if answer_key else ""
+        }
+        questions.append(question)
+    
+    # Build responses
+    responses = []
+    for row_idx, row in enumerate(responses_data):
+        student_id = f"S{row_idx + 1:02d}"
+        
+        if name_col is not None and name_col < len(row):
+            student_name = row[name_col]
+        elif email_col is not None and email_col < len(row):
+            email = row[email_col]
+            student_name = email.split('@')[0] if '@' in email else email
+        else:
+            student_name = f"Student {row_idx + 1}"
+        
+        answers = {}
+        for q_idx, (col_idx, _) in enumerate(question_cols):
+            question_id = f"Q{q_idx + 1}"
+            answer = row[col_idx] if col_idx < len(row) else ""
+            answers[question_id] = answer
+        
+        responses.append({
+            "student_id": student_id,
+            "student_name": student_name,
+            "answers": answers
+        })
+    
+    return {
+        "exam_title": "Uploaded Exam",
+        "questions": questions,
+        "responses": responses
+    }

chatkit/backend/app/main.py

@@ -1,15 +1,45 @@
-"""FastAPI entrypoint for the ChatKit starter backend."""
+"""FastAPI entrypoint for the ExamInsight backend."""
 
 from __future__ import annotations
 
+import os
+import json
+import asyncio
+from pathlib import Path
+from contextlib import asynccontextmanager
+from typing import Optional, AsyncIterator
+
 from chatkit.server import StreamingResult
 from fastapi import FastAPI, Request
 from fastapi.middleware.cors import CORSMiddleware
-from fastapi.responses import JSONResponse, Response, StreamingResponse
+from fastapi.responses import JSONResponse, Response, StreamingResponse, FileResponse
+from fastapi.staticfiles import StaticFiles
+from pydantic import BaseModel
+
+from .server import ExamInsightChatServer
+from .oauth import router as oauth_router
+from .database import init_database
+from .google_sheets import fetch_google_form_responses, parse_csv_responses
+from .email_service import send_email_report
+from .status_tracker import get_status, subscribe, unsubscribe
+
+# Static files directory (for production deployment)
+STATIC_DIR = Path(__file__).parent.parent / "static"
 
-from .server import StarterChatServer
 
-app = FastAPI(title="ChatKit Starter API")
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    """Initialize database on startup."""
+    await init_database()
+    yield
+
+
+app = FastAPI(
+    title="ExamInsight API",
+    description="AI-powered exam analysis for teachers",
+    version="1.0.0",
+    lifespan=lifespan,
+)
 
 app.add_middleware(
     CORSMiddleware,
@@ -19,9 +49,17 @@ app.add_middleware(
     allow_headers=["*"],
 )
 
-chatkit_server = StarterChatServer()
+# Include OAuth routes
+app.include_router(oauth_router)
+
+# ChatKit server instance
+chatkit_server = ExamInsightChatServer()
 
 
+# =============================================================================
+# ChatKit Endpoint
+# =============================================================================
+
 @app.post("/chatkit")
 async def chatkit_endpoint(request: Request) -> Response:
     """Proxy the ChatKit web component payload to the server implementation."""
@@ -33,3 +71,175 @@ async def chatkit_endpoint(request: Request) -> Response:
     if hasattr(result, "json"):
         return Response(content=result.json, media_type="application/json")
     return JSONResponse(result)
+
+
+# =============================================================================
+# Workflow Status Endpoints
+# =============================================================================
+
+@app.get("/api/status/{session_id}")
+async def get_workflow_status(session_id: str):
+    """Get current workflow status for a session."""
+    return get_status(session_id)
+
+
+async def status_stream(session_id: str) -> AsyncIterator[str]:
+    """Generate SSE events for status updates."""
+    queue = await subscribe(session_id)
+    try:
+        # Send initial status
+        status = get_status(session_id)
+        yield f"data: {json.dumps(status)}\n\n"
+        
+        while True:
+            try:
+                # Wait for updates with timeout
+                status = await asyncio.wait_for(queue.get(), timeout=30.0)
+                yield f"data: {json.dumps(status)}\n\n"
+            except asyncio.TimeoutError:
+                # Send keepalive
+                yield f": keepalive\n\n"
+    except asyncio.CancelledError:
+        pass
+    finally:
+        unsubscribe(session_id, queue)
+
+
+@app.get("/api/status/{session_id}/stream")
+async def stream_workflow_status(session_id: str):
+    """Stream workflow status updates via Server-Sent Events (SSE)."""
+    return StreamingResponse(
+        status_stream(session_id),
+        media_type="text/event-stream",
+        headers={
+            "Cache-Control": "no-cache",
+            "Connection": "keep-alive",
+            "X-Accel-Buffering": "no",
+        }
+    )
+
+
+# =============================================================================
+# Direct API Endpoints (for non-ChatKit integrations)
+# =============================================================================
+
+class FetchResponsesRequest(BaseModel):
+    google_form_url: str
+    teacher_email: str
+    answer_key: Optional[dict] = None
+
+
+class ParseCSVRequest(BaseModel):
+    csv_content: str
+    answer_key: Optional[dict] = None
+
+
+class SendEmailRequest(BaseModel):
+    email: str
+    subject: str
+    body_markdown: str
+
+
+@app.post("/api/fetch_google_form_responses")
+async def api_fetch_responses(request: FetchResponsesRequest):
+    """
+    Fetch and normalize responses from a Google Form/Sheets URL.
+    
+    This endpoint requires the teacher to have connected their Google account.
+    """
+    result = await fetch_google_form_responses(
+        request.google_form_url,
+        request.teacher_email,
+        request.answer_key
+    )
+    return result
+
+
+@app.post("/api/parse_csv")
+async def api_parse_csv(request: ParseCSVRequest):
+    """
+    Parse CSV content directly (fallback when Google OAuth is not available).
+    """
+    result = parse_csv_responses(request.csv_content, request.answer_key)
+    return result
+
+
+@app.post("/api/send_email_report")
+async def api_send_email(request: SendEmailRequest):
+    """
+    Send an exam analysis report via email.
+    """
+    result = await send_email_report(
+        request.email,
+        request.subject,
+        request.body_markdown
+    )
+    return result
+
+
+@app.get("/api/health")
+@app.get("/health")
+async def health_check():
+    """Health check endpoint for HF Spaces."""
+    return {"status": "healthy", "service": "ExamInsight"}
+
+
+# =============================================================================
+# Static File Serving (Production)
+# =============================================================================
+
+# Mount static files if directory exists (production Docker build)
+if STATIC_DIR.exists():
+    # Serve static assets (JS, CSS, images)
+    app.mount("/assets", StaticFiles(directory=STATIC_DIR / "assets"), name="assets")
+    
+    @app.get("/favicon.ico")
+    async def favicon():
+        favicon_path = STATIC_DIR / "favicon.ico"
+        if favicon_path.exists():
+            return FileResponse(favicon_path)
+        return Response(status_code=404)
+    
+    @app.get("/")
+    async def serve_spa():
+        """Serve the React SPA."""
+        return FileResponse(STATIC_DIR / "index.html")
+    
+    @app.get("/{full_path:path}")
+    async def serve_spa_routes(full_path: str):
+        """Catch-all route to serve React SPA for client-side routing."""
+        # Don't serve SPA for API routes
+        if full_path.startswith(("api/", "auth/", "chatkit")):
+            return Response(status_code=404)
+        
+        # Check if it's a static file
+        file_path = STATIC_DIR / full_path
+        if file_path.exists() and file_path.is_file():
+            return FileResponse(file_path)
+        
+        # Otherwise serve index.html for SPA routing
+        return FileResponse(STATIC_DIR / "index.html")
+else:
+    # Development mode - show API info
+    @app.get("/")
+    async def root():
+        """Root endpoint with API information (dev mode)."""
+        return {
+            "name": "ExamInsight API",
+            "version": "1.0.0",
+            "mode": "development",
+            "description": "AI-powered exam analysis for teachers",
+            "note": "Frontend served separately on port 3000",
+            "endpoints": {
+                "chatkit": "/chatkit",
+                "oauth_start": "/auth/start?teacher_email=...",
+                "oauth_callback": "/auth/callback",
+                "auth_status": "/auth/status?teacher_email=...",
+                "workflow_status": "/api/status/{session_id}",
+                "workflow_stream": "/api/status/{session_id}/stream",
+                "fetch_responses": "/api/fetch_google_form_responses",
+                "parse_csv": "/api/parse_csv",
+                "send_email": "/api/send_email_report",
+                "health": "/api/health",
+            }
+        }

chatkit/backend/app/oauth.py

@@ -0,0 +1,165 @@
+"""Google OAuth2 authentication endpoints."""
+
+from __future__ import annotations
+
+import json
+from urllib.parse import urlencode
+from typing import Optional
+
+from fastapi import APIRouter, Request, HTTPException
+from fastapi.responses import RedirectResponse
+import httpx
+
+from .config import get_settings, GOOGLE_SCOPES
+from .database import save_oauth_tokens, get_oauth_tokens, delete_oauth_tokens
+
+router = APIRouter(prefix="/auth", tags=["authentication"])
+
+
+# Store state tokens temporarily (in production, use Redis or similar)
+_state_store: dict[str, str] = {}
+
+
+@router.get("/start")
+async def start_auth(teacher_email: str, request: Request):
+    """
+    Start OAuth flow by redirecting to Google consent screen.
+    
+    Query params:
+        teacher_email: The teacher's email address
+    """
+    settings = get_settings()
+    
+    if not settings.google_client_id or not settings.google_client_secret:
+        raise HTTPException(
+            status_code=500,
+            detail="Google OAuth not configured. Please set GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET."
+        )
+    
+    # Generate state token for CSRF protection
+    import secrets
+    state = secrets.token_urlsafe(32)
+    _state_store[state] = teacher_email
+    
+    # Build authorization URL
+    auth_params = {
+        "client_id": settings.google_client_id,
+        "redirect_uri": settings.google_redirect_uri,
+        "response_type": "code",
+        "scope": " ".join(GOOGLE_SCOPES),
+        "access_type": "offline",  # Get refresh token
+        "prompt": "consent",  # Always show consent screen to get refresh token
+        "state": state,
+        "login_hint": teacher_email,  # Pre-fill email if possible
+    }
+    
+    auth_url = f"https://accounts.google.com/o/oauth2/v2/auth?{urlencode(auth_params)}"
+    return RedirectResponse(url=auth_url)
+
+
+@router.get("/callback")
+async def auth_callback(code: str = None, state: str = None, error: str = None):
+    """
+    Handle OAuth callback from Google.
+    
+    Query params:
+        code: Authorization code from Google
+        state: State token for CSRF verification
+        error: Error message if authorization failed
+    """
+    settings = get_settings()
+    
+    if error:
+        return RedirectResponse(
+            url=f"{settings.frontend_url}?auth_error={error}"
+        )
+    
+    if not code or not state:
+        return RedirectResponse(
+            url=f"{settings.frontend_url}?auth_error=missing_params"
+        )
+    
+    # Verify state
+    teacher_email = _state_store.pop(state, None)
+    if not teacher_email:
+        return RedirectResponse(
+            url=f"{settings.frontend_url}?auth_error=invalid_state"
+        )
+    
+    # Exchange code for tokens
+    try:
+        async with httpx.AsyncClient() as client:
+            token_response = await client.post(
+                "https://oauth2.googleapis.com/token",
+                data={
+                    "client_id": settings.google_client_id,
+                    "client_secret": settings.google_client_secret,
+                    "code": code,
+                    "grant_type": "authorization_code",
+                    "redirect_uri": settings.google_redirect_uri,
+                },
+            )
+            
+            if token_response.status_code != 200:
+                return RedirectResponse(
+                    url=f"{settings.frontend_url}?auth_error=token_exchange_failed"
+                )
+            
+            tokens = token_response.json()
+            
+            # Verify the user's email matches
+            userinfo_response = await client.get(
+                "https://www.googleapis.com/oauth2/v2/userinfo",
+                headers={"Authorization": f"Bearer {tokens['access_token']}"}
+            )
+            
+            if userinfo_response.status_code == 200:
+                userinfo = userinfo_response.json()
+                verified_email = userinfo.get("email", "")
+                
+                # Use the verified email from Google
+                if verified_email:
+                    teacher_email = verified_email
+            
+            # Save tokens
+            await save_oauth_tokens(teacher_email, {
+                "access_token": tokens.get("access_token"),
+                "refresh_token": tokens.get("refresh_token"),
+                "expires_in": tokens.get("expires_in"),
+            })
+            
+            return RedirectResponse(
+                url=f"{settings.frontend_url}?auth_success=true&email={teacher_email}"
+            )
+            
+    except Exception as e:
+        return RedirectResponse(
+            url=f"{settings.frontend_url}?auth_error={str(e)}"
+        )
+
+
+@router.get("/status")
+async def auth_status(teacher_email: str):
+    """
+    Check if a teacher is authenticated.
+    
+    Query params:
+        teacher_email: The teacher's email address
+    """
+    tokens = await get_oauth_tokens(teacher_email)
+    return {
+        "authenticated": tokens is not None,
+        "email": teacher_email if tokens else None
+    }
+
+
+@router.post("/disconnect")
+async def disconnect(teacher_email: str):
+    """
+    Disconnect a teacher's Google account.
+    
+    Query params:
+        teacher_email: The teacher's email address
+    """
+    await delete_oauth_tokens(teacher_email)
+    return {"status": "ok", "message": "Google account disconnected"}

chatkit/backend/app/server.py

@@ -1,35 +1,406 @@
-"""ChatKit server that streams responses from a single assistant."""
+"""ExamInsight ChatKit server with exam analysis agent and tools."""
 
 from __future__ import annotations
 
+import json
 from typing import Any, AsyncIterator
 
-from agents import Runner
+from agents import Runner, Agent, function_tool
 from chatkit.agents import AgentContext, simple_to_agent_input, stream_agent_response
 from chatkit.server import ChatKitServer
 from chatkit.types import ThreadMetadata, ThreadStreamEvent, UserMessageItem
 
 from .memory_store import MemoryStore
-from agents import Agent
+from .google_sheets import fetch_google_form_responses, parse_csv_responses, fetch_public_sheet, extract_sheet_id
+from .email_service import send_email_report
+from .database import save_report
+from .status_tracker import update_status, add_reasoning_step, WorkflowStep, reset_status
 
 
-MAX_RECENT_ITEMS = 30
-MODEL = "gpt-4.1-mini"
+MAX_RECENT_ITEMS = 50
+MODEL = "gpt-4.1-mini"  # Using mini for cost efficiency (~10x cheaper)
 
+# Current session ID (simplified - in production use proper session management)
+_current_session_id = "default"
 
-assistant_agent = Agent[AgentContext[dict[str, Any]]](
+
+def set_session_id(session_id: str):
+    global _current_session_id
+    _current_session_id = session_id
+
+
+# =============================================================================
+# Tool Definitions with Status Tracking
+# =============================================================================
+
+@function_tool
+async def fetch_responses(
+    google_form_url: str,
+    teacher_email: str = "",
+    answer_key_json: str = ""
+) -> str:
+    """
+    Fetch student responses from a Google Form/Sheets URL.
+    First tries to fetch as a public sheet (no auth needed).
+    If that fails and teacher_email is provided, tries OAuth.
+    
+    Args:
+        google_form_url: The URL of the Google Form response spreadsheet
+        teacher_email: The teacher's email address for authentication (optional for public sheets)
+        answer_key_json: Optional JSON string with correct answers, e.g. {"Q1": "4", "Q2": "acceleration"}
+    
+    Returns:
+        JSON string with normalized exam data including questions and student responses
+    """
+    # Log tool call
+    await add_reasoning_step(_current_session_id, "tool", f"🔧 Tool: fetch_responses(url={google_form_url[:50]}...)", "active")
+    
+    answer_key = None
+    if answer_key_json:
+        try:
+            answer_key = json.loads(answer_key_json)
+        except json.JSONDecodeError:
+            pass
+    
+    # First, try to fetch as a public sheet (no OAuth needed)
+    sheet_id = extract_sheet_id(google_form_url)
+    if sheet_id:
+        await add_reasoning_step(_current_session_id, "tool", "📥 Downloading spreadsheet data...", "active")
+        public_result = await fetch_public_sheet(sheet_id, answer_key)
+        if "error" not in public_result:
+            await add_reasoning_step(_current_session_id, "result", "✅ Data fetched successfully", "completed")
+            return json.dumps(public_result, indent=2)
+        
+        # If public fetch failed and we have teacher email, try OAuth
+        if teacher_email:
+            await add_reasoning_step(_current_session_id, "tool", "🔐 Using OAuth to access private sheet...", "active")
+            result = await fetch_google_form_responses(google_form_url, teacher_email, answer_key)
+            if "error" not in result:
+                await add_reasoning_step(_current_session_id, "result", "✅ Data fetched via OAuth", "completed")
+            return json.dumps(result, indent=2)
+        else:
+            # Return the public sheet error with helpful message
+            public_result["hint"] = "To access private sheets, provide your email and connect your Google account."
+            await add_reasoning_step(_current_session_id, "error", "❌ Could not access sheet", "completed")
+            return json.dumps(public_result, indent=2)
+    
+    await add_reasoning_step(_current_session_id, "error", "❌ Invalid URL format", "completed")
+    return json.dumps({
+        "error": "Could not extract sheet ID from URL. Please provide a valid Google Sheets URL.",
+        "hint": "URL should look like: https://docs.google.com/spreadsheets/d/SHEET_ID/edit"
+    }, indent=2)
+
+
+@function_tool
+async def parse_csv_data(
+    csv_content: str,
+    answer_key_json: str = ""
+) -> str:
+    """
+    Parse CSV content directly (for manual upload fallback).
+    
+    Args:
+        csv_content: The raw CSV content with headers and student responses
+        answer_key_json: Optional JSON string with correct answers
+    
+    Returns:
+        JSON string with normalized exam data
+    """
+    await add_reasoning_step(_current_session_id, "tool", "🔧 Tool: parse_csv_data()", "active")
+    
+    answer_key = None
+    if answer_key_json:
+        try:
+            answer_key = json.loads(answer_key_json)
+        except json.JSONDecodeError:
+            pass
+    
+    result = parse_csv_responses(csv_content, answer_key)
+    
+    await add_reasoning_step(_current_session_id, "result", "✅ CSV parsed successfully", "completed")
+    
+    return json.dumps(result, indent=2)
+
+
+@function_tool
+async def send_report_email(
+    email: str,
+    subject: str,
+    body_markdown: str
+) -> str:
+    """
+    Send the exam analysis report to the teacher via email.
+    
+    Args:
+        email: The teacher's email address
+        subject: Email subject line
+        body_markdown: The full report in markdown format
+    
+    Returns:
+        JSON string with status of the email send operation
+    """
+    await add_reasoning_step(_current_session_id, "tool", f"🔧 Tool: send_report_email(to={email})", "active")
+    
+    result = await send_email_report(email, subject, body_markdown)
+    
+    if result.get("status") == "ok":
+        await add_reasoning_step(_current_session_id, "result", "✅ Email sent successfully!", "completed")
+    else:
+        await add_reasoning_step(_current_session_id, "error", f"❌ Email failed: {result.get('message', 'unknown error')}", "completed")
+    
+    return json.dumps(result)
+
+
+@function_tool
+async def save_analysis_report(
+    teacher_email: str,
+    exam_title: str,
+    report_markdown: str,
+    report_json: str
+) -> str:
+    """
+    Save the analysis report to the database for future reference.
+    
+    Args:
+        teacher_email: The teacher's email address
+        exam_title: Title of the exam
+        report_markdown: The report in markdown format
+        report_json: The structured report data in JSON format
+    
+    Returns:
+        Confirmation message
+    """
+    await add_reasoning_step(_current_session_id, "tool", f"🔧 Tool: save_analysis_report(exam={exam_title})", "active")
+    await add_reasoning_step(_current_session_id, "result", "✅ Report saved to database", "completed")
+    
+    await save_report(teacher_email, exam_title, report_markdown, report_json)
+    return json.dumps({"status": "saved", "message": "Report saved successfully"})
+
+
+@function_tool
+async def log_reasoning(thought: str) -> str:
+    """
+    Log your current thinking or reasoning step.
+    Use this to show the user what you're analyzing or planning.
+    
+    Args:
+        thought: Your current thought, reasoning, or task breakdown
+    
+    Returns:
+        Confirmation
+    """
+    await add_reasoning_step(_current_session_id, "thinking", thought, "completed")
+    return json.dumps({"status": "logged"})
+
+
+# =============================================================================
+# ExamInsight Agent Definition
+# =============================================================================
+
+EXAMINSIGHT_INSTRUCTIONS = """You are ExamInsight, an AI teaching assistant that creates beautiful, comprehensive exam analysis reports for teachers.
+
+## Your Core Mission
+
+Transform raw Google Form quiz responses into professional, teacher-ready HTML reports with:
+1. Detailed question analysis with bilingual explanations (English + 中文)
+2. Visual statistics with Chart.js charts
+3. Actionable teaching recommendations
+4. Individual student support suggestions
+
+## IMPORTANT: Show Your Reasoning
+
+Use `log_reasoning` to show your thinking process. Call it at key decision points:
+- `log_reasoning("Task: Analyze 12 students × 5 questions, generate HTML report")`
+- `log_reasoning("Grading Q1: 5 correct (42%), Q2: 10 correct (83%)")`
+- `log_reasoning("Pattern: Many students confused 'is' vs 'wants to be'")`
+
+## Workflow
+
+### Step 1: Fetch & Analyze Data
+Use `fetch_responses` with the Google Form URL.
+Log observations: `log_reasoning("Found 12 students, 5 questions. Q1-Q4 multiple choice, Q5 writing.")`
+
+### Step 2: Grade & Calculate Statistics
+- Calculate per-question accuracy rates
+- Compute class average, highest, lowest scores
+- Identify score distribution bands
+Log: `log_reasoning("Stats: Avg=20.8/70, Q1=42%, Q2=83%, Q3=50%, Q4=83%")`
+
+### Step 3: Identify Patterns & Misconceptions
+Analyze common mistakes and their root causes.
+Log: `log_reasoning("Misconception: Students confused Bella (IS teacher) with Eddie (WANTS TO BE teacher)")`
+
+### Step 4: Generate HTML Report
+
+**CRITICAL: Generate a complete, self-contained HTML file** that includes:
+
+#### Required HTML Structure:
+
+```html
+<!DOCTYPE html>
+<html lang="zh-TW">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>[Quiz Title] Report</title>
+    <script src="https://cdn.jsdelivr.net/npm/chart.js"></script>
+    <style>
+        /* Dark theme with coral/teal accents */
+        :root {
+            --bg-primary: #0f1419;
+            --bg-secondary: #1a2332;
+            --bg-card: #212d3b;
+            --accent-coral: #ff6b6b;
+            --accent-teal: #4ecdc4;
+            --accent-gold: #ffd93d;
+            --accent-purple: #a855f7;
+            --text-primary: #f1f5f9;
+            --text-secondary: #94a3b8;
+            --border-color: #334155;
+        }
+        /* Include comprehensive CSS for all elements */
+    </style>
+</head>
+<body>
+    <!-- Header with quiz title and Google Form link -->
+    <!-- Navigation tabs: Q&A, Statistics, Teacher Insights -->
+    <!-- Main content sections -->
+    <!-- Chart.js scripts -->
+</body>
+</html>
+```
+
+#### Section 1: 📝 Q&A Analysis (題目詳解)
+
+For EACH question, include:
+1. **Question number badge** (gradient circle)
+2. **Question text** (bilingual: English + Chinese)
+3. **Answer box** with correct answer highlighted
+4. **Concept tags** showing skills tested (e.g., 🎯 細節理解, 🔍 推論能力)
+5. **Detailed explanation** (詳解) with:
+   - What the question tests (這題測試什麼？)
+   - Key solving strategy (解題關鍵)
+   - Common mistakes (常見錯誤)
+   - Learning points (學習重點)
+
+If there's a reading passage, include it with `<span class="highlight">` for key terms.
+
+#### Section 2: 📊 Statistics (成績統計)
+
+Include:
+1. **Stats grid**: Total students, Average, Highest, Lowest
+2. **Score distribution bar chart** (Chart.js)
+3. **Question accuracy doughnut chart** (Chart.js)
+4. **Student details table** with columns:
+   - Name (姓名), Class (班級), Score, Q1-Qn status (✅/❌)
+   - Color-coded score badges: high (teal), mid (gold), low (coral)
+
+#### Section 3: 👩‍🏫 Teacher Insights (教師分析與建議)
+
+Include:
+1. **Overall Performance Analysis** (整體表現分析)
+   - Summary paragraph
+   - Per-question breakdown with accuracy % and issues identified
+
+2. **Teaching Recommendations** (教學改進建議)
+   - Specific, actionable suggestions based on data
+   - Priority areas to address
+
+3. **Next Exam Prompt** (下次出題 Prompt 建議)
+   - Ready-to-use AI prompt for generating the next quiz
+   - Include specific areas to reinforce based on this quiz's results
+
+4. **Individual Support** (個別輔導建議)
+   - 🔴 Students needing attention (0 or very low scores)
+   - 🟡 Students needing reinforcement
+   - 🟢 High performers (potential peer tutors)
+
+#### Chart.js Implementation
+
+Include these chart configurations:
+```javascript
+// Score Distribution Chart
+new Chart(document.getElementById('scoreChart').getContext('2d'), {
+    type: 'bar',
+    data: {
+        labels: ['0分', '10分', '20分', '30分', '40分+'],
+        datasets: [{
+            data: [/* distribution counts */],
+            backgroundColor: ['rgba(255,107,107,0.7)', ...],
+            borderRadius: 8
+        }]
+    },
+    options: { /* dark theme styling */ }
+});
+
+// Question Accuracy Chart
+new Chart(document.getElementById('questionChart').getContext('2d'), {
+    type: 'doughnut',
+    data: {
+        labels: ['Q1 (XX%)', 'Q2 (XX%)', ...],
+        datasets: [{ data: [/* accuracy rates */] }]
+    }
+});
+```
+
+### Step 5: Send Report
+Use `send_report_email` with the complete HTML as the body.
+
+## Output Format
+
+When generating the report:
+1. First display a brief summary in chat
+2. Then output the complete HTML in a code block
+3. Offer to email it to the teacher
+
+## Design Principles
+
+- **Dark theme** with coral (#ff6b6b) and teal (#4ecdc4) accents
+- **Bilingual** content (English + Traditional Chinese)
+- **Responsive** layout for mobile viewing
+- **Smooth scrolling** navigation
+- **Hover effects** on cards and tables
+- **Gradient accents** for visual interest
+
+## Handling Edge Cases
+
+- No answer key: Infer patterns or ask teacher for correct answers
+- Private sheet: Guide teacher through OAuth connection
+- Writing questions: Provide rubric and sample excellent responses
+- Few students: Adjust charts to prevent visual distortion
+
+## Privacy
+
+- Use partial names (e.g., 李X恩) in reports
+- Never expose full student identifiers
+- Group low performers sensitively
+
+Start by greeting the teacher and asking for:
+1. Google Form/Sheet URL
+2. Their email (for sending the report)
+3. Optionally: correct answers if not embedded in the form"""
+
+
+examinsight_agent = Agent[AgentContext[dict[str, Any]]](
     model=MODEL,
-    name="Starter Assistant",
-    instructions=(
-        "You are a concise, helpful assistant. "
-        "Keep replies short and focus on directly answering "
-        "the user's request."
-    ),
+    name="ExamInsight",
+    instructions=EXAMINSIGHT_INSTRUCTIONS,
+    tools=[
+        fetch_responses,
+        parse_csv_data,
+        send_report_email,
+        save_analysis_report,
+        log_reasoning,
+    ],
 )
 
 
-class StarterChatServer(ChatKitServer[dict[str, Any]]):
-    """Server implementation that keeps conversation state in memory."""
+# =============================================================================
+# ChatKit Server Implementation
+# =============================================================================
+
+class ExamInsightChatServer(ChatKitServer[dict[str, Any]]):
+    """Server implementation for ExamInsight exam analysis."""
 
     def __init__(self) -> None:
         self.store: MemoryStore = MemoryStore()
@@ -41,6 +412,10 @@ class StarterChatServer(ChatKitServer[dict[str, Any]]):
         item: UserMessageItem | None,
         context: dict[str, Any],
     ) -> AsyncIterator[ThreadStreamEvent]:
+        # Reset status for new analysis
+        reset_status(thread.id)
+        set_session_id(thread.id)
+        
         items_page = await self.store.load_thread_items(
             thread.id,
             after=None,
@@ -58,7 +433,7 @@ class StarterChatServer(ChatKitServer[dict[str, Any]]):
         )
 
         result = Runner.run_streamed(
-            assistant_agent,
+            examinsight_agent,
             agent_input,
             context=agent_context,
         )

chatkit/backend/app/status_tracker.py

@@ -0,0 +1,102 @@
+"""Real-time status tracking for AI agent reasoning."""
+
+from __future__ import annotations
+
+import asyncio
+from datetime import datetime
+from typing import Optional
+from collections import defaultdict
+
+# Global status store
+_status_store: dict[str, dict] = defaultdict(lambda: {
+    "current_step": None,
+    "steps": [],
+    "started_at": None,
+    "completed_at": None,
+})
+
+_subscribers: dict[str, list[asyncio.Queue]] = defaultdict(list)
+
+
+class WorkflowStep:
+    FETCH = "fetch"
+    NORMALIZE = "normalize"
+    GRADE = "grade"
+    EXPLAIN = "explain"
+    GROUP = "group"
+    REPORT = "report"
+    EMAIL = "email"
+
+
+async def add_reasoning_step(session_id: str, step_type: str, content: str, status: str = "completed"):
+    """Add a reasoning step to show what the AI is doing."""
+    store = _status_store[session_id]
+    
+    if store["started_at"] is None:
+        store["started_at"] = datetime.utcnow().isoformat()
+    
+    # Mark any active steps as completed
+    for s in store["steps"]:
+        if s.get("status") == "active":
+            s["status"] = "completed"
+    
+    step_data = {
+        "type": step_type,  # "tool", "result", "error", "thinking"
+        "content": content,
+        "status": status,
+        "timestamp": datetime.utcnow().isoformat(),
+    }
+    
+    store["steps"].append(step_data)
+    store["current_step"] = step_type if status == "active" else None
+    
+    # Emit with "reasoning" key for frontend
+    emit_data = {
+        "reasoning": store["steps"],
+        "started_at": store["started_at"],
+        "completed_at": store["completed_at"],
+    }
+    
+    await notify_subscribers(session_id, emit_data)
+
+
+async def update_status(session_id: str, step: str, status: str = "active", detail: str = ""):
+    """Update the current workflow status (legacy support)."""
+    await add_reasoning_step(session_id, step, detail, status)
+
+
+async def notify_subscribers(session_id: str, status: dict):
+    """Notify all subscribers of status change."""
+    for queue in _subscribers[session_id]:
+        try:
+            await queue.put(status.copy())
+        except:
+            pass
+
+
+def get_status(session_id: str) -> dict:
+    """Get current status for a session."""
+    return dict(_status_store[session_id])
+
+
+def reset_status(session_id: str):
+    """Reset status for a new analysis."""
+    _status_store[session_id] = {
+        "current_step": None,
+        "steps": [],
+        "started_at": None,
+        "completed_at": None,
+    }
+
+
+async def subscribe(session_id: str) -> asyncio.Queue:
+    """Subscribe to status updates for a session."""
+    queue = asyncio.Queue()
+    _subscribers[session_id].append(queue)
+    return queue
+
+
+def unsubscribe(session_id: str, queue: asyncio.Queue):
+    """Unsubscribe from status updates."""
+    if queue in _subscribers[session_id]:
+        _subscribers[session_id].remove(queue)

chatkit/backend/pyproject.toml

@@ -1,21 +1,32 @@
 [project]
-name = "chatkit-starter-backend"
+name = "examinsight-backend"
 version = "0.1.0"
-description = "Minimal FastAPI backend for the self-hosted ChatKit starter"
-requires-python = ">=3.11"
+description = "ExamInsight: AI-powered exam analysis for teachers using ChatKit"
+requires-python = ">=3.10"
 dependencies = [
     "fastapi>=0.114,<0.116",
     "uvicorn[standard]>=0.36,<0.37",
     "openai>=1.40",
     "openai-chatkit>=1.4.0,<2",
+    "google-auth>=2.0.0",
+    "google-auth-oauthlib>=1.0.0",
+    "google-api-python-client>=2.100.0",
+    "sendgrid>=6.10.0",
+    "python-dotenv>=1.0.0",
+    "aiosqlite>=0.19.0",
+    "cryptography>=41.0.0",
+    "pydantic>=2.0.0",
+    "httpx>=0.25.0",
+    "markdown>=3.5.0",
 ]
 
 [project.optional-dependencies]
 dev = [
     "ruff>=0.6.4,<0.7",
+    "pytest>=7.4.0",
+    "pytest-asyncio>=0.21.0",
 ]
 
 [build-system]
 requires = ["setuptools>=68.0", "wheel"]
 build-backend = "setuptools.build_meta"
-

chatkit/backend/scripts/run.sh

@@ -1,40 +1,32 @@
-#!/usr/bin/env bash
+#!/bin/bash
+# Run the ExamInsight backend server
 
-# Simple helper to start the ChatKit backend (similar to cat-lounge UX).
-
-set -euo pipefail
+set -e
 
+# Get the directory where this script is located
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-PROJECT_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
-
-cd "$PROJECT_ROOT"
-
-if [ ! -d ".venv" ]; then
-  echo "Creating virtual env in $PROJECT_ROOT/.venv ..."
-  python -m venv .venv
-fi
-
-source .venv/bin/activate
+BACKEND_DIR="$(dirname "$SCRIPT_DIR")"
 
-echo "Installing backend deps (editable) ..."
-pip install -e . >/dev/null
+cd "$BACKEND_DIR"
 
-# Load env vars from the repo's .env.local (if present) so OPENAI_API_KEY
-# does not need to be exported manually.
-ENV_FILE="$PROJECT_ROOT/../.env.local"
-if [ -z "${OPENAI_API_KEY:-}" ] && [ -f "$ENV_FILE" ]; then
-  echo "Sourcing OPENAI_API_KEY from $ENV_FILE"
-  # shellcheck disable=SC1090
-  set -a
-  . "$ENV_FILE"
-  set +a
+# Load environment variables from .env if it exists
+if [ -f "../.env" ]; then
+    export $(cat ../.env | grep -v '^#' | xargs)
 fi
 
-if [ -z "${OPENAI_API_KEY:-}" ]; then
-  echo "Set OPENAI_API_KEY in your environment or in .env.local before running this script."
-  exit 1
+# Check if we're in a virtual environment, create one if not
+if [ -z "$VIRTUAL_ENV" ]; then
+    if [ ! -d ".venv" ]; then
+        echo "Creating virtual environment..."
+        python3 -m venv .venv
+    fi
+    source .venv/bin/activate
 fi
 
-echo "Starting ChatKit backend on http://127.0.0.1:8000 ..."
-exec uvicorn app.main:app --reload --host 127.0.0.1 --port 8000
+# Install dependencies
+echo "Installing dependencies..."
+pip install -q -e .
 
+# Run the server
+echo "Starting ExamInsight backend on http://127.0.0.1:8000"
+uvicorn app.main:app --host 127.0.0.1 --port 8000 --reload

chatkit/env.example

@@ -0,0 +1,50 @@
+# ExamInsight Environment Variables
+# Copy to .env for local development
+# For HF Spaces, add these as Secrets in the Space settings
+
+# =============================================================================
+# REQUIRED
+# =============================================================================
+
+# OpenAI API Key (required for ChatKit)
+OPENAI_API_KEY=sk-your-openai-api-key
+
+# =============================================================================
+# GOOGLE OAUTH (optional - for private Google Sheets)
+# =============================================================================
+
+# Get these from Google Cloud Console > APIs & Services > Credentials
+GOOGLE_CLIENT_ID=your-client-id.apps.googleusercontent.com
+GOOGLE_CLIENT_SECRET=GOCSPX-your-client-secret
+
+# Redirect URI - update for production
+# Local: http://localhost:8000/auth/callback
+# HF Spaces: https://taboola-cz-examinsight.hf.space/auth/callback
+GOOGLE_REDIRECT_URI=http://localhost:8000/auth/callback
+
+# =============================================================================
+# EMAIL (optional - for sending reports)
+# =============================================================================
+
+# Option 1: Gmail SMTP (easier setup)
+GMAIL_USER=your-email@gmail.com
+GMAIL_APP_PASSWORD=your-16-char-app-password
+
+# Option 2: SendGrid API
+SENDGRID_API_KEY=SG.your-sendgrid-api-key
+SENDGRID_FROM_EMAIL=examinsight@yourdomain.com
+
+# =============================================================================
+# SECURITY
+# =============================================================================
+
+# Generate with: python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"
+ENCRYPTION_KEY=your-fernet-encryption-key
+
+# =============================================================================
+# FRONTEND (for HF Spaces domain key)
+# =============================================================================
+
+# Register your HF Space domain at:
+# https://platform.openai.com/settings/organization/security/domain-allowlist
+VITE_CHATKIT_API_DOMAIN_KEY=domain_pk_your-production-key

chatkit/frontend/index.html

@@ -3,8 +3,12 @@
   <head>
     <meta charset="UTF-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-    <title>AgentKit demo</title>
+    <title>ExamInsight — AI-Powered Exam Analysis for Teachers</title>
+    <meta name="description" content="Analyze student exam responses, generate personalized explanations, and create peer learning groups with AI." />
     <link rel="icon" type="image/x-icon" href="/favicon.ico" />
+    <link rel="preconnect" href="https://fonts.googleapis.com">
+    <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
+    <link href="https://fonts.googleapis.com/css2?family=Fraunces:ital,opsz,wght@0,9..144,300..900;1,9..144,300..900&family=Instrument+Sans:ital,wght@0,400..700;1,400..700&display=swap" rel="stylesheet">
     <script src="https://cdn.platform.openai.com/deployments/chatkit/chatkit.js"></script>
   </head>
   <body>
@@ -12,4 +16,3 @@
     <script type="module" src="/src/main.tsx"></script>
   </body>
 </html>
-

chatkit/frontend/package-lock.json

@@ -1,12 +1,12 @@
 {
-  "name": "chatkit-frontend",
-  "version": "0.1.0",
+  "name": "examinsight-frontend",
+  "version": "1.0.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
-      "name": "chatkit-frontend",
-      "version": "0.1.0",
+      "name": "examinsight-frontend",
+      "version": "1.0.0",
       "dependencies": {
         "@openai/chatkit-react": ">=1.1.1 <2.0.0",
         "react": "^19.2.0",

chatkit/frontend/package.json

@@ -1,6 +1,7 @@
 {
-  "name": "chatkit-frontend",
-  "version": "0.1.0",
+  "name": "examinsight-frontend",
+  "version": "1.0.0",
+  "description": "ExamInsight - AI-Powered Exam Analysis for Teachers",
   "private": true,
   "type": "module",
   "scripts": {

chatkit/frontend/src/App.tsx

@@ -1,11 +1,99 @@
-import { ChatKitPanel } from "./components/ChatKitPanel";
+import { useState, useEffect } from "react";
+import { Header } from "./components/Header";
+import { Hero } from "./components/Hero";
+import { AuthStatus } from "./components/AuthStatus";
+import { ExamAnalyzer } from "./components/ExamAnalyzer";
+import { Features } from "./components/Features";
+import { SimpleChatPanel } from "./components/SimpleChatPanel";
 
 export default function App() {
+  const [teacherEmail, setTeacherEmail] = useState<string>("");
+  const [isAuthenticated, setIsAuthenticated] = useState(false);
+  const [showAnalyzer, setShowAnalyzer] = useState(false);
+  const [testMode, setTestMode] = useState(false);
+
+  // Check URL params for auth callback and test mode
+  useEffect(() => {
+    const params = new URLSearchParams(window.location.search);
+    const authSuccess = params.get("auth_success");
+    const email = params.get("email");
+    const authError = params.get("auth_error");
+    const test = params.get("test");
+
+    if (test === "chat") {
+      setTestMode(true);
+      return;
+    }
+
+    if (authSuccess === "true" && email) {
+      setTeacherEmail(email);
+      setIsAuthenticated(true);
+      setShowAnalyzer(true);
+      // Clean URL
+      window.history.replaceState({}, "", window.location.pathname);
+    } else if (authError) {
+      console.error("Auth error:", authError);
+      window.history.replaceState({}, "", window.location.pathname);
+    }
+  }, []);
+
+  const handleStartAnalysis = () => {
+    if (isAuthenticated) {
+      setShowAnalyzer(true);
+    }
+  };
+
+  // Test mode - show simple chat panel
+  if (testMode) {
+    return (
+      <main className="flex min-h-screen flex-col items-center justify-center bg-slate-100 dark:bg-slate-950 p-4">
+        <div className="mx-auto w-full max-w-3xl">
+          <div className="mb-4 text-center">
+            <h1 className="text-2xl font-bold mb-2">ChatKit Test Mode</h1>
+            <p className="text-gray-600">Testing basic ChatKit functionality</p>
+            <a href="/" className="text-blue-500 underline text-sm">← Back to app</a>
+          </div>
+          <SimpleChatPanel />
+        </div>
+      </main>
+    );
+  }
+
   return (
-    <main className="flex min-h-screen flex-col items-center justify-end bg-slate-100 dark:bg-slate-950">
-      <div className="mx-auto w-full max-w-5xl">
-        <ChatKitPanel />
-      </div>
-    </main>
+    <div className="min-h-screen">
+      <Header 
+        isAuthenticated={isAuthenticated}
+        teacherEmail={teacherEmail}
+      />
+      
+      <main>
+        {!showAnalyzer ? (
+          <>
+            <Hero 
+              isAuthenticated={isAuthenticated}
+              onStartAnalysis={handleStartAnalysis}
+            />
+            
+            <AuthStatus
+              teacherEmail={teacherEmail}
+              setTeacherEmail={setTeacherEmail}
+              isAuthenticated={isAuthenticated}
+              setIsAuthenticated={setIsAuthenticated}
+            />
+            
+            <Features />
+          </>
+        ) : (
+          <ExamAnalyzer 
+            teacherEmail={teacherEmail}
+            onBack={() => setShowAnalyzer(false)}
+          />
+        )}
+      </main>
+      
+      <footer className="py-8 text-center text-sm text-[var(--color-text-muted)]">
+        <p>© 2026 ExamInsight • AI-Powered Teaching Assistant</p>
+      </footer>
+    </div>
   );
 }

chatkit/frontend/src/TestChat.tsx

@@ -0,0 +1,12 @@
+import { SimpleChatPanel } from "./components/SimpleChatPanel";
+
+export function TestChat() {
+  return (
+    <main className="flex min-h-screen flex-col items-center justify-end bg-slate-100 dark:bg-slate-950 p-4">
+      <div className="mx-auto w-full max-w-3xl">
+        <h1 className="text-2xl font-bold mb-4 text-center">ChatKit Test</h1>
+        <SimpleChatPanel />
+      </div>
+    </main>
+  );
+}

chatkit/frontend/src/components/AuthStatus.tsx

@@ -0,0 +1,212 @@
+import { useState } from "react";
+import { GOOGLE_AUTH_URL, AUTH_STATUS_URL } from "../lib/config";
+
+type AuthMode = 'google' | 'csv-only';
+
+interface AuthStatusProps {
+  teacherEmail: string;
+  setTeacherEmail: (email: string) => void;
+  isAuthenticated: boolean;
+  setIsAuthenticated: (auth: boolean) => void;
+}
+
+export function AuthStatus({
+  teacherEmail,
+  setTeacherEmail,
+  isAuthenticated,
+  setIsAuthenticated,
+}: AuthStatusProps) {
+  const [emailInput, setEmailInput] = useState("");
+  const [isChecking, setIsChecking] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+  const [authMode, setAuthMode] = useState<AuthMode | null>(null);
+
+  const checkAuthStatus = async (email: string) => {
+    try {
+      setIsChecking(true);
+      const response = await fetch(`${AUTH_STATUS_URL}?teacher_email=${encodeURIComponent(email)}`);
+      const data = await response.json();
+      
+      if (data.authenticated) {
+        setTeacherEmail(email);
+        setIsAuthenticated(true);
+      }
+      return data.authenticated;
+    } catch (err) {
+      console.error("Error checking auth status:", err);
+      return false;
+    } finally {
+      setIsChecking(false);
+    }
+  };
+
+  const handleConnect = async (e: React.FormEvent) => {
+    e.preventDefault();
+    setError(null);
+    
+    if (!emailInput.trim()) {
+      setError("Please enter your email address");
+      return;
+    }
+    
+    // Check if already authenticated
+    const alreadyAuth = await checkAuthStatus(emailInput);
+    if (alreadyAuth) {
+      return;
+    }
+    
+    // Try to start OAuth - catch errors if not configured
+    try {
+      const response = await fetch(`${GOOGLE_AUTH_URL}?teacher_email=${encodeURIComponent(emailInput)}`, {
+        method: 'GET',
+        redirect: 'manual'
+      });
+      
+      // If we get a redirect, OAuth is configured - follow it
+      if (response.type === 'opaqueredirect' || response.status === 302) {
+        window.location.href = `${GOOGLE_AUTH_URL}?teacher_email=${encodeURIComponent(emailInput)}`;
+      } else if (response.status === 500) {
+        const data = await response.json();
+        if (data.detail?.includes('not configured')) {
+          setAuthMode('csv-only');
+          setError("Google OAuth not configured. You can still use the app by uploading CSV files directly in the chat!");
+          // Set as "connected" with just email for CSV fallback
+          setTeacherEmail(emailInput);
+          setIsAuthenticated(true);
+        } else {
+          setAuthMode('google');
+          setError(data.detail || "Failed to connect");
+        }
+      } else {
+        // Redirect to OAuth
+        window.location.href = `${GOOGLE_AUTH_URL}?teacher_email=${encodeURIComponent(emailInput)}`;
+      }
+    } catch (err) {
+      // Network error or CORS - just redirect
+      window.location.href = `${GOOGLE_AUTH_URL}?teacher_email=${encodeURIComponent(emailInput)}`;
+    }
+  };
+
+  const handleDisconnect = async () => {
+    try {
+      await fetch(`/auth/disconnect?teacher_email=${encodeURIComponent(teacherEmail)}`, {
+        method: 'POST'
+      });
+      setIsAuthenticated(false);
+      setTeacherEmail("");
+    } catch (err) {
+      console.error("Error disconnecting:", err);
+    }
+  };
+
+  return (
+    <section id="connect" className="py-20 px-6">
+      <div className="max-w-xl mx-auto">
+        <div className="card p-8">
+          <div className="text-center mb-8">
+            <div className="w-16 h-16 mx-auto mb-4 rounded-2xl bg-gradient-to-br from-[var(--color-primary)] to-[var(--color-primary-light)] flex items-center justify-center shadow-lg">
+              <svg className="w-8 h-8 text-white" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+                <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M12 15v2m-6 4h12a2 2 0 002-2v-6a2 2 0 00-2-2H6a2 2 0 00-2 2v6a2 2 0 002 2zm10-10V7a4 4 0 00-8 0v4h8z" />
+              </svg>
+            </div>
+            <h2 className="font-display text-2xl font-bold text-[var(--color-text)] mb-2">
+              {isAuthenticated ? "You're Connected!" : "Connect Your Google Account"}
+            </h2>
+            <p className="text-[var(--color-text-muted)]">
+              {isAuthenticated 
+                ? "Your Google account is linked. You can now analyze exam responses."
+                : "We'll only access your Google Forms response spreadsheets. No data is stored on our servers."}
+            </p>
+          </div>
+
+          {isAuthenticated ? (
+            <div className="space-y-4">
+          <div className="flex items-center justify-center gap-3 p-4 rounded-xl bg-[var(--color-success)]/10 border border-[var(--color-success)]/20">
+            <div className="w-10 h-10 rounded-full bg-[var(--color-success)]/20 flex items-center justify-center">
+              <svg className="w-5 h-5 text-[var(--color-success)]" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+                <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M5 13l4 4L19 7" />
+              </svg>
+            </div>
+            <div className="text-left">
+              <div className="font-medium text-[var(--color-text)]">{teacherEmail}</div>
+              <div className="text-sm text-[var(--color-text-muted)]">
+                {authMode === 'csv-only' ? 'CSV Upload Mode (Google OAuth not configured)' : 'Google Account Connected'}
+              </div>
+            </div>
+          </div>
+          
+          {authMode === 'csv-only' && (
+            <div className="p-3 rounded-lg bg-amber-50 border border-amber-200 text-amber-700 text-sm">
+              <strong>Note:</strong> You can paste CSV data directly in the chat, or set up Google OAuth to fetch from Google Forms.
+            </div>
+          )}
+              
+              <button
+                onClick={handleDisconnect}
+                className="w-full btn btn-outline text-red-500 border-red-200 hover:border-red-500 hover:text-red-600"
+              >
+                Disconnect Account
+              </button>
+            </div>
+          ) : (
+            <form onSubmit={handleConnect} className="space-y-4">
+              <div>
+                <label htmlFor="email" className="block text-sm font-medium text-[var(--color-text)] mb-2">
+                  Your School Email
+                </label>
+                <input
+                  type="email"
+                  id="email"
+                  value={emailInput}
+                  onChange={(e) => setEmailInput(e.target.value)}
+                  placeholder="teacher@school.edu"
+                  className="input"
+                  required
+                />
+              </div>
+              
+              {error && (
+                <div className="p-3 rounded-lg bg-red-50 border border-red-200 text-red-600 text-sm">
+                  {error}
+                </div>
+              )}
+              
+              <button 
+                type="submit" 
+                className="w-full btn btn-primary"
+                disabled={isChecking}
+              >
+                {isChecking ? (
+                  <>
+                    <svg className="w-5 h-5 animate-spin" fill="none" viewBox="0 0 24 24">
+                      <circle className="opacity-25" cx="12" cy="12" r="10" stroke="currentColor" strokeWidth="4" />
+                      <path className="opacity-75" fill="currentColor" d="M4 12a8 8 0 018-8V0C5.373 0 0 5.373 0 12h4zm2 5.291A7.962 7.962 0 014 12H0c0 3.042 1.135 5.824 3 7.938l3-2.647z" />
+                    </svg>
+                    Checking...
+                  </>
+                ) : (
+                  <>
+                    <svg className="w-5 h-5" viewBox="0 0 24 24" fill="currentColor">
+                      <path d="M22.56 12.25c0-.78-.07-1.53-.2-2.25H12v4.26h5.92c-.26 1.37-1.04 2.53-2.21 3.31v2.77h3.57c2.08-1.92 3.28-4.74 3.28-8.09z"/>
+                      <path d="M12 23c2.97 0 5.46-.98 7.28-2.66l-3.57-2.77c-.98.66-2.23 1.06-3.71 1.06-2.86 0-5.29-1.93-6.16-4.53H2.18v2.84C3.99 20.53 7.7 23 12 23z"/>
+                      <path d="M5.84 14.09c-.22-.66-.35-1.36-.35-2.09s.13-1.43.35-2.09V7.07H2.18C1.43 8.55 1 10.22 1 12s.43 3.45 1.18 4.93l2.85-2.22.81-.62z"/>
+                      <path d="M12 5.38c1.62 0 3.06.56 4.21 1.64l3.15-3.15C17.45 2.09 14.97 1 12 1 7.7 1 3.99 3.47 2.18 7.07l3.66 2.84c.87-2.6 3.3-4.53 6.16-4.53z"/>
+                    </svg>
+                    Continue with Google
+                  </>
+                )}
+              </button>
+              
+              <p className="text-center text-xs text-[var(--color-text-muted)]">
+                By connecting, you agree to our{" "}
+                <a href="#" className="underline hover:text-[var(--color-primary)]">Terms of Service</a>
+                {" "}and{" "}
+                <a href="#" className="underline hover:text-[var(--color-primary)]">Privacy Policy</a>
+              </p>
+            </form>
+          )}
+        </div>
+      </div>
+    </section>
+  );
+}

chatkit/frontend/src/components/ExamAnalyzer.tsx

@@ -0,0 +1,182 @@
+import { useState } from "react";
+import { ChatKit, useChatKit } from "@openai/chatkit-react";
+import { CHATKIT_API_DOMAIN_KEY, CHATKIT_API_URL } from "../lib/config";
+import { ReasoningPanel } from "./ReasoningPanel";
+
+interface ExamAnalyzerProps {
+  teacherEmail: string;
+  onBack: () => void;
+}
+
+export function ExamAnalyzer({ teacherEmail, onBack }: ExamAnalyzerProps) {
+  const [showCopiedToast, setShowCopiedToast] = useState(false);
+  
+  const chatkit = useChatKit({
+    api: { url: CHATKIT_API_URL, domainKey: CHATKIT_API_DOMAIN_KEY },
+    composer: {
+      attachments: { enabled: false },
+    },
+  });
+
+  const handleCopyPrompt = (prompt: string) => {
+    navigator.clipboard.writeText(prompt);
+    setShowCopiedToast(true);
+    setTimeout(() => setShowCopiedToast(false), 2000);
+  };
+
+  const examplePrompts = [
+    {
+      title: "📊 Analyze Google Sheet",
+      prompt: `Please analyze the exam responses from this Google Sheet:
+https://docs.google.com/spreadsheets/d/YOUR_SHEET_ID/edit
+
+The correct answers are:
+- Q1: 4
+- Q2: Acceleration is the rate of change of velocity
+
+My email is ${teacherEmail}. Please grade the responses, explain incorrect answers, suggest peer learning groups, and email me the report.`,
+    },
+    {
+      title: "📝 Analyze CSV Data",
+      prompt: `Please analyze this exam data:
+
+Timestamp,Email,Student Name,Q1 (2+2),Q2 (Explain acceleration)
+2026-01-26 08:00:00,alice@student.edu,Alice,4,Acceleration is the rate of change of velocity
+2026-01-26 08:01:00,bob@student.edu,Bob,3,I dont know
+2026-01-26 08:02:00,carol@student.edu,Carol,4,velocity change over time
+2026-01-26 08:03:00,david@student.edu,David,5,speed
+
+The correct answers are:
+- Q1: 4
+- Q2: Acceleration is the rate of change of velocity over time
+
+My email is ${teacherEmail}. Please grade and create a full report.`,
+    },
+    {
+      title: "⚡ Quick Summary",
+      prompt: `Just give me a quick summary of class performance. My email is ${teacherEmail}.`,
+    },
+  ];
+
+  return (
+    <div className="min-h-screen pt-24 pb-8 px-4">
+      {/* Copied toast */}
+      {showCopiedToast && (
+        <div className="fixed top-24 left-1/2 -translate-x-1/2 z-50 px-4 py-2 bg-green-500 text-white rounded-lg shadow-lg">
+          ✓ Prompt copied! Paste it in the chat.
+        </div>
+      )}
+      
+      <div className="max-w-7xl mx-auto">
+        {/* Top bar */}
+        <div className="flex items-center justify-between mb-6">
+          <button
+            onClick={onBack}
+            className="flex items-center gap-2 text-gray-500 hover:text-gray-700 transition-colors"
+          >
+            <svg className="w-5 h-5" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+              <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M10 19l-7-7m0 0l7-7m-7 7h18" />
+            </svg>
+            Back to Home
+          </button>
+          
+          <div className="flex items-center gap-3">
+            <span className="text-sm text-gray-500">Connected as</span>
+            <span className="px-3 py-1 bg-green-100 text-green-700 rounded-full text-sm font-medium">
+              {teacherEmail}
+            </span>
+          </div>
+        </div>
+
+        <div className="grid lg:grid-cols-4 gap-6">
+          {/* Left Sidebar - AI Reasoning */}
+          <div className="lg:col-span-1 space-y-4">
+            {/* AI Reasoning Panel - Shows LLM thinking process */}
+            <ReasoningPanel sessionId="default" />
+
+            {/* Example Prompts */}
+            <div className="bg-white rounded-xl shadow-sm border p-4">
+              <h3 className="text-sm font-semibold text-gray-800 mb-3">
+                Quick Start Prompts
+              </h3>
+              <div className="space-y-2">
+                {examplePrompts.map((example, i) => (
+                  <button
+                    key={i}
+                    onClick={() => handleCopyPrompt(example.prompt)}
+                    className="w-full text-left p-3 rounded-lg bg-gray-50 hover:bg-blue-50 transition-colors group border border-transparent hover:border-blue-200"
+                  >
+                    <div className="text-sm font-medium text-gray-700 group-hover:text-blue-600">
+                      {example.title}
+                    </div>
+                    <div className="text-xs text-gray-500">
+                      Click to copy
+                    </div>
+                  </button>
+                ))}
+              </div>
+            </div>
+
+            {/* Tips */}
+            <div className="bg-gradient-to-br from-blue-50 to-indigo-50 rounded-xl p-4 border border-blue-100">
+              <h3 className="text-sm font-semibold text-gray-800 mb-2 flex items-center gap-2">
+                💡 Pro Tips
+              </h3>
+              <ul className="space-y-1.5 text-xs text-gray-600">
+                <li className="flex items-start gap-1.5">
+                  <span className="text-green-500">✓</span>
+                  Include answer key for accuracy
+                </li>
+                <li className="flex items-start gap-1.5">
+                  <span className="text-green-500">✓</span>
+                  Make Google Sheet public, or use CSV
+                </li>
+                <li className="flex items-start gap-1.5">
+                  <span className="text-green-500">✓</span>
+                  Ask for email delivery
+                </li>
+              </ul>
+            </div>
+          </div>
+
+          {/* Main Chat Area - Use same structure as SimpleChatPanel */}
+          <div className="lg:col-span-3">
+            <div className="bg-white rounded-xl shadow-sm border overflow-hidden">
+              {/* Chat Header */}
+              <div className="bg-gradient-to-r from-blue-600 to-indigo-600 px-6 py-4">
+                <div className="flex items-center justify-between">
+                  <div className="flex items-center gap-3">
+                    <div className="w-10 h-10 rounded-xl bg-white/20 flex items-center justify-center">
+                      <svg className="w-5 h-5 text-white" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+                        <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M9 5H7a2 2 0 00-2 2v12a2 2 0 002 2h10a2 2 0 002-2V7a2 2 0 00-2-2h-2M9 5a2 2 0 002 2h2a2 2 0 002-2M9 5a2 2 0 012-2h2a2 2 0 012 2m-6 9l2 2 4-4" />
+                      </svg>
+                    </div>
+                    <div>
+                      <h2 className="text-lg font-semibold text-white">
+                        ExamInsight Assistant
+                      </h2>
+                      <p className="text-sm text-white/70">
+                        Paste your exam data or Google Sheet URL below
+                      </p>
+                    </div>
+                  </div>
+                  <span className="px-2 py-1 rounded-full bg-white/20 text-white text-xs">
+                    GPT-4.1-mini
+                  </span>
+                </div>
+              </div>
+              
+              {/* ChatKit - Using the EXACT same structure as SimpleChatPanel that works */}
+              <div className="h-[calc(100vh-320px)]">
+                <ChatKit 
+                  control={chatkit.control} 
+                  className="block h-full w-full"
+                />
+              </div>
+            </div>
+          </div>
+        </div>
+      </div>
+    </div>
+  );
+}

chatkit/frontend/src/components/Features.tsx

@@ -0,0 +1,137 @@
+export function Features() {
+  const features = [
+    {
+      icon: (
+        <svg className="w-6 h-6" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+          <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M9 19v-6a2 2 0 00-2-2H5a2 2 0 00-2 2v6a2 2 0 002 2h2a2 2 0 002-2zm0 0V9a2 2 0 012-2h2a2 2 0 012 2v10m-6 0a2 2 0 002 2h2a2 2 0 002-2m0 0V5a2 2 0 012-2h2a2 2 0 012 2v14a2 2 0 01-2 2h-2a2 2 0 01-2-2z" />
+        </svg>
+      ),
+      title: "Automatic Grading",
+      description: "Grade multiple choice, numeric, and even open-ended questions with AI-powered accuracy.",
+      color: "var(--color-primary)",
+    },
+    {
+      icon: (
+        <svg className="w-6 h-6" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+          <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M9.663 17h4.673M12 3v1m6.364 1.636l-.707.707M21 12h-1M4 12H3m3.343-5.657l-.707-.707m2.828 9.9a5 5 0 117.072 0l-.548.547A3.374 3.374 0 0014 18.469V19a2 2 0 11-4 0v-.531c0-.895-.356-1.754-.988-2.386l-.548-.547z" />
+        </svg>
+      ),
+      title: "Smart Explanations",
+      description: "Get personalized explanations for each wrong answer, helping students understand their mistakes.",
+      color: "var(--color-accent)",
+    },
+    {
+      icon: (
+        <svg className="w-6 h-6" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+          <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M17 20h5v-2a3 3 0 00-5.356-1.857M17 20H7m10 0v-2c0-.656-.126-1.283-.356-1.857M7 20H2v-2a3 3 0 015.356-1.857M7 20v-2c0-.656.126-1.283.356-1.857m0 0a5.002 5.002 0 019.288 0M15 7a3 3 0 11-6 0 3 3 0 016 0zm6 3a2 2 0 11-4 0 2 2 0 014 0zM7 10a2 2 0 11-4 0 2 2 0 014 0z" />
+        </svg>
+      ),
+      title: "Peer Learning Groups",
+      description: "AI-suggested student groupings pair high performers with those who need help on specific topics.",
+      color: "var(--color-success)",
+    },
+    {
+      icon: (
+        <svg className="w-6 h-6" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+          <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M3 8l7.89 5.26a2 2 0 002.22 0L21 8M5 19h14a2 2 0 002-2V7a2 2 0 00-2-2H5a2 2 0 00-2 2v10a2 2 0 002 2z" />
+        </svg>
+      ),
+      title: "Email Reports",
+      description: "Receive beautiful, formatted reports directly in your inbox, ready to share with students or parents.",
+      color: "var(--color-warning)",
+    },
+    {
+      icon: (
+        <svg className="w-6 h-6" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+          <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M9 12l2 2 4-4m5.618-4.016A11.955 11.955 0 0112 2.944a11.955 11.955 0 01-8.618 3.04A12.02 12.02 0 003 9c0 5.591 3.824 10.29 9 11.622 5.176-1.332 9-6.03 9-11.622 0-1.042-.133-2.052-.382-3.016z" />
+        </svg>
+      ),
+      title: "Privacy First",
+      description: "Student data is processed securely. We only access what you share and never store sensitive information.",
+      color: "var(--color-primary-light)",
+    },
+    {
+      icon: (
+        <svg className="w-6 h-6" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+          <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M13 10V3L4 14h7v7l9-11h-7z" />
+        </svg>
+      ),
+      title: "Instant Analysis",
+      description: "Get comprehensive insights in seconds, not hours. More time teaching, less time grading.",
+      color: "var(--color-accent-light)",
+    },
+  ];
+
+  return (
+    <section id="features" className="py-20 px-6 bg-gradient-to-b from-transparent to-[var(--color-surface)]/50">
+      <div className="max-w-6xl mx-auto">
+        <div className="text-center mb-16">
+          <h2 className="font-display text-4xl font-bold text-[var(--color-text)] mb-4">
+            Everything You Need to
+            <span className="text-gradient"> Understand Your Students</span>
+          </h2>
+          <p className="text-lg text-[var(--color-text-muted)] max-w-2xl mx-auto">
+            ExamInsight combines the power of AI with thoughtful education practices
+            to give you actionable insights.
+          </p>
+        </div>
+
+        <div className="grid md:grid-cols-2 lg:grid-cols-3 gap-6">
+          {features.map((feature, i) => (
+            <div
+              key={i}
+              className="card p-6 hover:shadow-lg transition-all hover:-translate-y-1 group"
+            >
+              <div
+                className="w-12 h-12 rounded-xl flex items-center justify-center mb-4 transition-transform group-hover:scale-110"
+                style={{ 
+                  backgroundColor: `color-mix(in srgb, ${feature.color} 15%, transparent)`,
+                  color: feature.color 
+                }}
+              >
+                {feature.icon}
+              </div>
+              <h3 className="font-display text-xl font-semibold text-[var(--color-text)] mb-2">
+                {feature.title}
+              </h3>
+              <p className="text-[var(--color-text-muted)]">
+                {feature.description}
+              </p>
+            </div>
+          ))}
+        </div>
+
+        {/* How it works */}
+        <div className="mt-24">
+          <h3 className="font-display text-3xl font-bold text-center text-[var(--color-text)] mb-12">
+            How It Works
+          </h3>
+          
+          <div className="relative">
+            {/* Connection line */}
+            <div className="hidden lg:block absolute top-1/2 left-0 right-0 h-0.5 bg-gradient-to-r from-[var(--color-primary)] via-[var(--color-accent)] to-[var(--color-success)] -translate-y-1/2" />
+            
+            <div className="grid lg:grid-cols-4 gap-8">
+              {[
+                { step: 1, title: "Connect Google", desc: "Link your Google account to access Form responses" },
+                { step: 2, title: "Share URL", desc: "Paste your Google Form or Sheets response URL" },
+                { step: 3, title: "AI Analyzes", desc: "ExamInsight grades, explains, and groups students" },
+                { step: 4, title: "Get Report", desc: "Receive a beautiful report via email and dashboard" },
+              ].map((item) => (
+                <div key={item.step} className="relative text-center">
+                  <div className="w-12 h-12 mx-auto mb-4 rounded-full bg-gradient-to-br from-[var(--color-primary)] to-[var(--color-accent)] text-white font-bold text-xl flex items-center justify-center shadow-lg relative z-10">
+                    {item.step}
+                  </div>
+                  <h4 className="font-display text-lg font-semibold text-[var(--color-text)] mb-2">
+                    {item.title}
+                  </h4>
+                  <p className="text-sm text-[var(--color-text-muted)]">{item.desc}</p>
+                </div>
+              ))}
+            </div>
+          </div>
+        </div>
+      </div>
+    </section>
+  );
+}

chatkit/frontend/src/components/Header.tsx

@@ -0,0 +1,45 @@
+interface HeaderProps {
+  isAuthenticated: boolean;
+  teacherEmail: string;
+}
+
+export function Header({ isAuthenticated, teacherEmail }: HeaderProps) {
+  return (
+    <header className="fixed top-0 left-0 right-0 z-50 backdrop-blur-xl bg-[var(--glass-bg)] border-b border-[var(--glass-border)]">
+      <div className="max-w-7xl mx-auto px-6 py-4 flex items-center justify-between">
+        <div className="flex items-center gap-3">
+          <div className="w-10 h-10 rounded-xl bg-gradient-to-br from-[var(--color-primary)] to-[var(--color-accent)] flex items-center justify-center text-white font-bold text-lg shadow-lg">
+            E
+          </div>
+          <div>
+            <h1 className="font-display text-xl font-semibold text-[var(--color-text)]">
+              ExamInsight
+            </h1>
+            <p className="text-xs text-[var(--color-text-muted)] hidden sm:block">
+              AI-Powered Exam Analysis
+            </p>
+          </div>
+        </div>
+        
+        <nav className="flex items-center gap-6">
+          {isAuthenticated && (
+            <div className="flex items-center gap-2 px-4 py-2 rounded-full bg-[var(--color-success)]/10 border border-[var(--color-success)]/20">
+              <span className="w-2 h-2 rounded-full bg-[var(--color-success)] animate-pulse"></span>
+              <span className="text-sm font-medium text-[var(--color-success)]">
+                {teacherEmail}
+              </span>
+            </div>
+          )}
+          <a 
+            href="https://platform.openai.com/docs/guides/chatkit" 
+            target="_blank" 
+            rel="noopener noreferrer"
+            className="text-sm text-[var(--color-text-muted)] hover:text-[var(--color-primary)] transition-colors"
+          >
+            Docs
+          </a>
+        </nav>
+      </div>
+    </header>
+  );
+}

chatkit/frontend/src/components/Hero.tsx

@@ -0,0 +1,76 @@
+interface HeroProps {
+  isAuthenticated: boolean;
+  onStartAnalysis: () => void;
+}
+
+export function Hero({ isAuthenticated, onStartAnalysis }: HeroProps) {
+  return (
+    <section className="relative pt-32 pb-20 px-6 overflow-hidden">
+      {/* Decorative elements */}
+      <div className="absolute top-20 left-10 w-72 h-72 rounded-full bg-gradient-to-br from-[var(--color-accent)]/20 to-transparent blur-3xl animate-float"></div>
+      <div className="absolute bottom-0 right-10 w-96 h-96 rounded-full bg-gradient-to-br from-[var(--color-success)]/15 to-transparent blur-3xl animate-float" style={{ animationDelay: '2s' }}></div>
+      
+      <div className="max-w-5xl mx-auto text-center relative">
+        <div className="opacity-0 animate-fade-in-up stagger-1">
+          <span className="inline-flex items-center gap-2 px-4 py-2 rounded-full bg-[var(--color-primary)]/10 text-[var(--color-primary)] text-sm font-medium mb-8">
+            <svg className="w-4 h-4" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+              <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M13 10V3L4 14h7v7l9-11h-7z" />
+            </svg>
+            Powered by OpenAI ChatKit
+          </span>
+        </div>
+        
+        <h1 className="font-display text-5xl sm:text-6xl lg:text-7xl font-bold leading-tight mb-6 opacity-0 animate-fade-in-up stagger-2">
+          <span className="text-[var(--color-text)]">Transform Exams into</span>
+          <br />
+          <span className="text-gradient">Teaching Insights</span>
+        </h1>
+        
+        <p className="text-xl text-[var(--color-text-muted)] max-w-2xl mx-auto mb-10 opacity-0 animate-fade-in-up stagger-3">
+          Upload your Google Form responses and let AI analyze student performance, 
+          generate personalized explanations, and create peer learning groups—all in seconds.
+        </p>
+        
+        <div className="flex flex-col sm:flex-row items-center justify-center gap-4 opacity-0 animate-fade-in-up stagger-4">
+          {isAuthenticated ? (
+            <button onClick={onStartAnalysis} className="btn btn-accent text-lg px-8 py-4">
+              <svg className="w-5 h-5" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+                <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M9 5H7a2 2 0 00-2 2v12a2 2 0 002 2h10a2 2 0 002-2V7a2 2 0 00-2-2h-2M9 5a2 2 0 002 2h2a2 2 0 002-2M9 5a2 2 0 012-2h2a2 2 0 012 2m-6 9l2 2 4-4" />
+              </svg>
+              Start Analyzing
+            </button>
+          ) : (
+            <a href="#connect" className="btn btn-primary text-lg px-8 py-4">
+              <svg className="w-5 h-5" viewBox="0 0 24 24" fill="currentColor">
+                <path d="M22.56 12.25c0-.78-.07-1.53-.2-2.25H12v4.26h5.92c-.26 1.37-1.04 2.53-2.21 3.31v2.77h3.57c2.08-1.92 3.28-4.74 3.28-8.09z"/>
+                <path d="M12 23c2.97 0 5.46-.98 7.28-2.66l-3.57-2.77c-.98.66-2.23 1.06-3.71 1.06-2.86 0-5.29-1.93-6.16-4.53H2.18v2.84C3.99 20.53 7.7 23 12 23z"/>
+                <path d="M5.84 14.09c-.22-.66-.35-1.36-.35-2.09s.13-1.43.35-2.09V7.07H2.18C1.43 8.55 1 10.22 1 12s.43 3.45 1.18 4.93l2.85-2.22.81-.62z"/>
+                <path d="M12 5.38c1.62 0 3.06.56 4.21 1.64l3.15-3.15C17.45 2.09 14.97 1 12 1 7.7 1 3.99 3.47 2.18 7.07l3.66 2.84c.87-2.6 3.3-4.53 6.16-4.53z"/>
+              </svg>
+              Connect Google Account
+            </a>
+          )}
+          <a href="#features" className="btn btn-outline text-lg px-8 py-4">
+            See How It Works
+          </a>
+        </div>
+        
+        {/* Stats */}
+        <div className="mt-20 grid grid-cols-3 gap-8 max-w-2xl mx-auto opacity-0 animate-fade-in-up stagger-5">
+          {[
+            { value: "5min", label: "Average Analysis Time" },
+            { value: "98%", label: "Teacher Satisfaction" },
+            { value: "40+", label: "Question Types Supported" },
+          ].map((stat, i) => (
+            <div key={i} className="text-center">
+              <div className="font-display text-3xl font-bold text-[var(--color-primary)]">
+                {stat.value}
+              </div>
+              <div className="text-sm text-[var(--color-text-muted)]">{stat.label}</div>
+            </div>
+          ))}
+        </div>
+      </div>
+    </section>
+  );
+}

chatkit/frontend/src/components/ReasoningPanel.tsx

@@ -0,0 +1,178 @@
+import { useState, useEffect, useRef } from "react";
+
+interface ReasoningStep {
+  id: string;
+  type: "tool" | "result" | "error" | "thinking";
+  content: string;
+  timestamp: Date;
+  status: "running" | "completed";
+}
+
+interface ReasoningPanelProps {
+  sessionId?: string;
+}
+
+export function ReasoningPanel({ sessionId = "default" }: ReasoningPanelProps) {
+  const [steps, setSteps] = useState<ReasoningStep[]>([]);
+  const [isStreaming, setIsStreaming] = useState(false);
+  const containerRef = useRef<HTMLDivElement>(null);
+
+  // Subscribe to status updates
+  useEffect(() => {
+    let eventSource: EventSource | null = null;
+
+    const connect = () => {
+      // Use relative URL for production, works with both local and HF Spaces
+      const apiBase = import.meta.env.VITE_API_BASE_URL || "";
+      eventSource = new EventSource(`${apiBase}/api/status/${sessionId}/stream`);
+
+      eventSource.onmessage = (event) => {
+        try {
+          const data = JSON.parse(event.data);
+          
+          // Handle reasoning steps from backend
+          if (data.reasoning && data.reasoning.length > 0) {
+            setIsStreaming(true);
+            
+            const newSteps: ReasoningStep[] = data.reasoning.map((step: any, index: number) => ({
+              id: `step-${index}-${step.timestamp}`,
+              type: step.type as ReasoningStep["type"],
+              content: step.content,
+              timestamp: new Date(step.timestamp),
+              status: step.status === "active" ? "running" : "completed",
+            }));
+            
+            setSteps(newSteps);
+          }
+          
+          if (data.completed_at) {
+            setIsStreaming(false);
+          }
+        } catch (e) {
+          console.error("Error parsing status:", e);
+        }
+      };
+
+      eventSource.onerror = () => {
+        eventSource?.close();
+        // Reconnect after 3 seconds
+        setTimeout(connect, 3000);
+      };
+    };
+
+    connect();
+    return () => eventSource?.close();
+  }, [sessionId]);
+
+  // Auto-scroll to bottom
+  useEffect(() => {
+    if (containerRef.current) {
+      containerRef.current.scrollTop = containerRef.current.scrollHeight;
+    }
+  }, [steps]);
+
+  const getIcon = (type: ReasoningStep["type"], status: string) => {
+    if (status === "running") {
+      return (
+        <div className="w-4 h-4 border-2 border-blue-400 border-t-transparent rounded-full animate-spin" />
+      );
+    }
+    
+    switch (type) {
+      case "tool":
+        return <span className="text-blue-400">🔧</span>;
+      case "result":
+        return <span className="text-green-400">✓</span>;
+      case "error":
+        return <span className="text-red-400">✗</span>;
+      case "thinking":
+        return <span className="text-purple-400">🧠</span>;
+      default:
+        return <span>•</span>;
+    }
+  };
+
+  const getColor = (type: ReasoningStep["type"], status: string) => {
+    if (status === "running") return "text-blue-300 bg-blue-500/10 border-blue-500/30";
+    
+    switch (type) {
+      case "tool":
+        return "text-blue-300 bg-gray-800/50 border-gray-600";
+      case "result":
+        return "text-green-300 bg-green-500/10 border-green-500/30";
+      case "error":
+        return "text-red-300 bg-red-500/10 border-red-500/30";
+      case "thinking":
+        return "text-purple-300 bg-purple-500/10 border-purple-500/30";
+      default:
+        return "text-gray-300 bg-gray-800/50 border-gray-600";
+    }
+  };
+
+  return (
+    <div className="bg-gray-900 rounded-xl border border-gray-700 overflow-hidden h-full flex flex-col">
+      {/* Header */}
+      <div className="px-4 py-3 bg-gray-800 border-b border-gray-700 flex items-center justify-between flex-shrink-0">
+        <div className="flex items-center gap-2">
+          <span className="text-sm font-semibold text-white">🤖 Tool Calls</span>
+          {isStreaming && (
+            <span className="flex items-center gap-1 text-xs text-green-400">
+              <span className="w-2 h-2 bg-green-400 rounded-full animate-pulse" />
+              Live
+            </span>
+          )}
+        </div>
+        {steps.length > 0 && (
+          <button
+            onClick={() => setSteps([])}
+            className="text-xs text-gray-500 hover:text-gray-300 transition-colors"
+          >
+            Clear
+          </button>
+        )}
+      </div>
+
+      {/* Tool call log */}
+      <div 
+        ref={containerRef}
+        className="p-3 flex-1 overflow-y-auto font-mono text-sm"
+      >
+        {steps.length === 0 ? (
+          <div className="text-gray-500 text-center py-8">
+            <div className="text-2xl mb-2">🔧</div>
+            <p>Tool calls will appear here</p>
+            <p className="text-xs mt-2">When AI uses tools, you'll see them logged</p>
+          </div>
+        ) : (
+          <div className="space-y-2">
+            {steps.map((step) => (
+              <div 
+                key={step.id} 
+                className={`flex items-start gap-2 p-2 rounded-lg border ${getColor(step.type, step.status)}`}
+              >
+                <span className="flex-shrink-0 mt-0.5">
+                  {getIcon(step.type, step.status)}
+                </span>
+                <div className="flex-1 min-w-0">
+                  <span className="block break-words whitespace-pre-wrap">
+                    {step.content}
+                  </span>
+                  <span className="text-xs opacity-50 mt-1 block">
+                    {step.timestamp.toLocaleTimeString()}
+                  </span>
+                </div>
+              </div>
+            ))}
+            
+            {isStreaming && (
+              <div className="flex items-center gap-2 text-gray-500 mt-2 justify-center py-2">
+                <div className="w-3 h-3 border-2 border-gray-500 border-t-transparent rounded-full animate-spin" />
+                <span className="text-xs">Waiting for next action...</span>
+              </div>
+            )}
+          </div>
+        )}
+      </div>
+    </div>
+  );
+}

chatkit/frontend/src/components/{ChatKitPanel.tsx → SimpleChatPanel.tsx}

@@ -1,11 +1,12 @@
 import { ChatKit, useChatKit } from "@openai/chatkit-react";
-import { CHATKIT_API_DOMAIN_KEY, CHATKIT_API_URL } from "../lib/config";
 
-export function ChatKitPanel() {
+const CHATKIT_API_URL = "/chatkit";
+const CHATKIT_API_DOMAIN_KEY = "domain_pk_localhost_dev";
+
+export function SimpleChatPanel() {
   const chatkit = useChatKit({
     api: { url: CHATKIT_API_URL, domainKey: CHATKIT_API_DOMAIN_KEY },
     composer: {
-      // File uploads are disabled for the demo backend.
       attachments: { enabled: false },
     },
   });

chatkit/frontend/src/components/WorkflowStatus.tsx

@@ -0,0 +1,281 @@
+import { useState, useEffect } from "react";
+
+interface StepData {
+  id: string;
+  status: "pending" | "active" | "completed" | "error";
+  detail?: string;
+  timestamp?: string;
+}
+
+interface StatusResponse {
+  current_step: string | null;
+  steps: StepData[];
+  started_at: string | null;
+  completed_at: string | null;
+}
+
+interface WorkflowStep {
+  id: string;
+  label: string;
+  icon: JSX.Element;
+  status: "pending" | "active" | "completed" | "error";
+  detail?: string;
+}
+
+interface WorkflowStatusProps {
+  sessionId?: string;
+}
+
+const STEP_CONFIG: { id: string; label: string; icon: JSX.Element; defaultDetail: string }[] = [
+  {
+    id: "fetch",
+    label: "Fetch Responses",
+    icon: (
+      <svg className="w-4 h-4" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+        <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M4 16v1a3 3 0 003 3h10a3 3 0 003-3v-1m-4-4l-4 4m0 0l-4-4m4 4V4" />
+      </svg>
+    ),
+    defaultDetail: "Getting data from Google Sheets",
+  },
+  {
+    id: "normalize",
+    label: "Parse Data",
+    icon: (
+      <svg className="w-4 h-4" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+        <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M9 5H7a2 2 0 00-2 2v12a2 2 0 002 2h10a2 2 0 002-2V7a2 2 0 00-2-2h-2M9 5a2 2 0 002 2h2a2 2 0 002-2M9 5a2 2 0 012-2h2a2 2 0 012 2" />
+      </svg>
+    ),
+    defaultDetail: "Organizing questions and answers",
+  },
+  {
+    id: "grade",
+    label: "Grade Answers",
+    icon: (
+      <svg className="w-4 h-4" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+        <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M9 12l2 2 4-4m6 2a9 9 0 11-18 0 9 9 0 0118 0z" />
+      </svg>
+    ),
+    defaultDetail: "Comparing with correct answers",
+  },
+  {
+    id: "explain",
+    label: "Generate Explanations",
+    icon: (
+      <svg className="w-4 h-4" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+        <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M9.663 17h4.673M12 3v1m6.364 1.636l-.707.707M21 12h-1M4 12H3m3.343-5.657l-.707-.707m2.828 9.9a5 5 0 117.072 0l-.548.547A3.374 3.374 0 0014 18.469V19a2 2 0 11-4 0v-.531c0-.895-.356-1.754-.988-2.386l-.548-.547z" />
+      </svg>
+    ),
+    defaultDetail: "Explaining wrong answers",
+  },
+  {
+    id: "group",
+    label: "Create Peer Groups",
+    icon: (
+      <svg className="w-4 h-4" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+        <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M17 20h5v-2a3 3 0 00-5.356-1.857M17 20H7m10 0v-2c0-.656-.126-1.283-.356-1.857M7 20H2v-2a3 3 0 015.356-1.857M7 20v-2c0-.656.126-1.283.356-1.857m0 0a5.002 5.002 0 019.288 0M15 7a3 3 0 11-6 0 3 3 0 016 0z" />
+      </svg>
+    ),
+    defaultDetail: "Matching helpers with learners",
+  },
+  {
+    id: "report",
+    label: "Generate Report",
+    icon: (
+      <svg className="w-4 h-4" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+        <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M9 17v-2m3 2v-4m3 4v-6m2 10H7a2 2 0 01-2-2V5a2 2 0 012-2h5.586a1 1 0 01.707.293l5.414 5.414a1 1 0 01.293.707V19a2 2 0 01-2 2z" />
+      </svg>
+    ),
+    defaultDetail: "Creating comprehensive report",
+  },
+  {
+    id: "email",
+    label: "Send Email",
+    icon: (
+      <svg className="w-4 h-4" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+        <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M3 8l7.89 5.26a2 2 0 002.22 0L21 8M5 19h14a2 2 0 002-2V7a2 2 0 00-2-2H5a2 2 0 00-2 2v10a2 2 0 002 2z" />
+      </svg>
+    ),
+    defaultDetail: "Delivering report to inbox",
+  },
+];
+
+export function WorkflowStatus({ sessionId = "default" }: WorkflowStatusProps) {
+  const [steps, setSteps] = useState<WorkflowStep[]>(
+    STEP_CONFIG.map(s => ({ ...s, status: "pending" as const, detail: s.defaultDetail }))
+  );
+  const [isConnected, setIsConnected] = useState(false);
+  const [isAnalyzing, setIsAnalyzing] = useState(false);
+
+  useEffect(() => {
+    let eventSource: EventSource | null = null;
+    let retryCount = 0;
+    const maxRetries = 3;
+
+    const connect = () => {
+      eventSource = new EventSource(`/api/status/${sessionId}/stream`);
+
+      eventSource.onopen = () => {
+        setIsConnected(true);
+        retryCount = 0;
+      };
+
+      eventSource.onmessage = (event) => {
+        try {
+          const data: StatusResponse = JSON.parse(event.data);
+          
+          // Check if there's any activity
+          const hasActivity = data.steps && data.steps.length > 0;
+          setIsAnalyzing(hasActivity && !data.completed_at);
+          
+          // Update steps based on server data
+          setSteps(prevSteps => {
+            return prevSteps.map(step => {
+              const serverStep = data.steps?.find(s => s.id === step.id);
+              if (serverStep) {
+                return {
+                  ...step,
+                  status: serverStep.status as WorkflowStep["status"],
+                  detail: serverStep.detail || step.detail,
+                };
+              }
+              return step;
+            });
+          });
+        } catch (e) {
+          console.error("Error parsing status:", e);
+        }
+      };
+
+      eventSource.onerror = () => {
+        setIsConnected(false);
+        eventSource?.close();
+        
+        // Retry connection
+        if (retryCount < maxRetries) {
+          retryCount++;
+          setTimeout(connect, 2000 * retryCount);
+        }
+      };
+    };
+
+    connect();
+
+    return () => {
+      eventSource?.close();
+    };
+  }, [sessionId]);
+
+  const getStatusColor = (status: WorkflowStep["status"]) => {
+    switch (status) {
+      case "completed": return "bg-[var(--color-success)] text-white";
+      case "active": return "bg-[var(--color-accent)] text-white animate-pulse";
+      case "error": return "bg-red-500 text-white";
+      default: return "bg-[var(--color-border)] text-[var(--color-text-muted)]";
+    }
+  };
+
+  const getLineColor = (status: WorkflowStep["status"]) => {
+    switch (status) {
+      case "completed": return "bg-[var(--color-success)]";
+      case "active": return "bg-[var(--color-accent)]";
+      default: return "bg-[var(--color-border)]";
+    }
+  };
+
+  const activeStep = steps.find(s => s.status === "active");
+  const completedCount = steps.filter(s => s.status === "completed").length;
+
+  return (
+    <div className="card p-4">
+      {/* Header */}
+      <div className="flex items-center justify-between mb-4">
+        <div className="flex items-center gap-2">
+          <div className={`w-2 h-2 rounded-full ${isAnalyzing ? 'bg-[var(--color-accent)] animate-pulse' : isConnected ? 'bg-[var(--color-success)]' : 'bg-[var(--color-border)]'}`} />
+          <h3 className="font-display text-sm font-semibold text-[var(--color-text)]">
+            {isAnalyzing ? "AI Agent Working..." : "Agent Status"}
+          </h3>
+        </div>
+        {completedCount > 0 && (
+          <span className="text-xs text-[var(--color-text-muted)]">
+            {completedCount}/{steps.length}
+          </span>
+        )}
+      </div>
+
+      {/* Active step highlight */}
+      {activeStep && (
+        <div className="mb-4 p-3 rounded-lg bg-[var(--color-accent)]/10 border border-[var(--color-accent)]/20">
+          <div className="flex items-center gap-2">
+            <div className="w-5 h-5 rounded-full bg-[var(--color-accent)] flex items-center justify-center animate-pulse">
+              <div className="w-2 h-2 bg-white rounded-full" />
+            </div>
+            <div>
+              <div className="text-sm font-medium text-[var(--color-accent)]">
+                {activeStep.label}
+              </div>
+              <div className="text-xs text-[var(--color-text-muted)]">
+                {activeStep.detail}
+              </div>
+            </div>
+          </div>
+        </div>
+      )}
+      
+      {/* Steps list */}
+      <div className="space-y-1">
+        {steps.map((step, index) => (
+          <div key={step.id} className="relative">
+            {/* Connector line */}
+            {index < steps.length - 1 && (
+              <div 
+                className={`absolute left-[11px] top-[24px] w-0.5 h-4 transition-colors duration-300 ${getLineColor(step.status)}`}
+              />
+            )}
+            
+            <div className="flex items-center gap-3 py-1">
+              {/* Icon circle */}
+              <div 
+                className={`flex-shrink-0 w-6 h-6 rounded-full flex items-center justify-center transition-all duration-300 ${getStatusColor(step.status)}`}
+              >
+                {step.status === "completed" ? (
+                  <svg className="w-3 h-3" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+                    <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={3} d="M5 13l4 4L19 7" />
+                  </svg>
+                ) : step.status === "active" ? (
+                  <div className="w-2 h-2 bg-white rounded-full" />
+                ) : step.status === "error" ? (
+                  <svg className="w-3 h-3" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+                    <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={3} d="M6 18L18 6M6 6l12 12" />
+                  </svg>
+                ) : (
+                  <span className="text-[10px]">{index + 1}</span>
+                )}
+              </div>
+              
+              {/* Label */}
+              <div className={`text-sm transition-colors ${
+                step.status === "active" 
+                  ? "font-medium text-[var(--color-accent)]" 
+                  : step.status === "completed"
+                  ? "text-[var(--color-success)]"
+                  : step.status === "error"
+                  ? "text-red-500"
+                  : "text-[var(--color-text-muted)]"
+              }`}>
+                {step.label}
+              </div>
+            </div>
+          </div>
+        ))}
+      </div>
+
+      {/* Connection status */}
+      <div className="mt-4 pt-3 border-t border-[var(--color-border)]">
+        <div className="flex items-center gap-2 text-xs text-[var(--color-text-muted)]">
+          <div className={`w-1.5 h-1.5 rounded-full ${isConnected ? 'bg-green-500' : 'bg-gray-400'}`} />
+          {isConnected ? "Live updates" : "Connecting..."}
+        </div>
+      </div>
+    </div>
+  );
+}

chatkit/frontend/src/index.css

@@ -1,34 +1,315 @@
 @import "tailwindcss";
 
 :root {
-  --background: #ffffff;
-  --foreground: #171717;
+  /* Warm, educational color palette */
+  --color-primary: #1e3a5f;
+  --color-primary-light: #2d5a87;
+  --color-accent: #e76f51;
+  --color-accent-light: #f4a261;
+  --color-success: #2a9d8f;
+  --color-warning: #e9c46a;
+  --color-background: #faf8f5;
+  --color-surface: #ffffff;
+  --color-text: #1a1a2e;
+  --color-text-muted: #64748b;
+  --color-border: #e2e0dc;
+  
+  /* Glassmorphism */
+  --glass-bg: rgba(255, 255, 255, 0.85);
+  --glass-border: rgba(255, 255, 255, 0.5);
+  
   color-scheme: light;
 }
 
 :root[data-color-scheme="dark"] {
-  --background: #0a0a0a;
-  --foreground: #ededed;
+  --color-primary: #5b8fb9;
+  --color-primary-light: #7eb8da;
+  --color-accent: #f4a261;
+  --color-accent-light: #e76f51;
+  --color-success: #4fd1c5;
+  --color-warning: #fbd38d;
+  --color-background: #0f172a;
+  --color-surface: #1e293b;
+  --color-text: #f1f5f9;
+  --color-text-muted: #94a3b8;
+  --color-border: #334155;
+  
+  --glass-bg: rgba(30, 41, 59, 0.85);
+  --glass-border: rgba(51, 65, 85, 0.5);
+  
   color-scheme: dark;
 }
 
 @media (prefers-color-scheme: dark) {
   :root:not([data-color-scheme]) {
-    --background: #0a0a0a;
-    --foreground: #ededed;
+    --color-primary: #5b8fb9;
+    --color-primary-light: #7eb8da;
+    --color-accent: #f4a261;
+    --color-accent-light: #e76f51;
+    --color-success: #4fd1c5;
+    --color-warning: #fbd38d;
+    --color-background: #0f172a;
+    --color-surface: #1e293b;
+    --color-text: #f1f5f9;
+    --color-text-muted: #94a3b8;
+    --color-border: #334155;
+    
+    --glass-bg: rgba(30, 41, 59, 0.85);
+    --glass-border: rgba(51, 65, 85, 0.5);
+    
     color-scheme: dark;
   }
 }
 
 @theme inline {
-  --color-background: var(--background);
-  --color-foreground: var(--foreground);
-  --font-sans: Arial, Helvetica, sans-serif;
-  --font-mono: SFMono-Regular, Consolas, "Liberation Mono", monospace;
+  --color-background: var(--color-background);
+  --color-foreground: var(--color-text);
+  --font-sans: 'Instrument Sans', system-ui, sans-serif;
+  --font-display: 'Fraunces', Georgia, serif;
+}
+
+* {
+  box-sizing: border-box;
+}
+
+html {
+  scroll-behavior: smooth;
 }
 
 body {
-  background: var(--background);
-  color: var(--foreground);
+  margin: 0;
+  padding: 0;
+  background: var(--color-background);
+  color: var(--color-text);
+  font-family: var(--font-sans);
+  font-size: 16px;
+  line-height: 1.6;
+  -webkit-font-smoothing: antialiased;
+  -moz-osx-font-smoothing: grayscale;
+}
+
+/* Background pattern */
+body::before {
+  content: '';
+  position: fixed;
+  top: 0;
+  left: 0;
+  right: 0;
+  bottom: 0;
+  background: 
+    radial-gradient(circle at 20% 20%, rgba(231, 111, 81, 0.08) 0%, transparent 50%),
+    radial-gradient(circle at 80% 80%, rgba(42, 157, 143, 0.08) 0%, transparent 50%),
+    radial-gradient(circle at 50% 50%, rgba(30, 58, 95, 0.05) 0%, transparent 70%);
+  pointer-events: none;
+  z-index: -1;
+}
+
+/* Typography */
+h1, h2, h3, h4, h5, h6 {
+  font-family: var(--font-display);
+  font-weight: 600;
+  line-height: 1.2;
+  margin: 0;
+}
+
+/* Custom scrollbar */
+::-webkit-scrollbar {
+  width: 8px;
+  height: 8px;
+}
+
+::-webkit-scrollbar-track {
+  background: transparent;
+}
+
+::-webkit-scrollbar-thumb {
+  background: var(--color-border);
+  border-radius: 4px;
+}
+
+::-webkit-scrollbar-thumb:hover {
+  background: var(--color-text-muted);
+}
+
+/* Button styles */
+.btn {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  gap: 0.5rem;
+  padding: 0.75rem 1.5rem;
   font-family: var(--font-sans);
+  font-weight: 600;
+  font-size: 0.95rem;
+  border-radius: 12px;
+  border: none;
+  cursor: pointer;
+  transition: all 0.2s ease;
+  text-decoration: none;
+}
+
+.btn-primary {
+  background: linear-gradient(135deg, var(--color-primary) 0%, var(--color-primary-light) 100%);
+  color: white;
+  box-shadow: 0 4px 14px rgba(30, 58, 95, 0.25);
+}
+
+.btn-primary:hover {
+  transform: translateY(-2px);
+  box-shadow: 0 6px 20px rgba(30, 58, 95, 0.35);
+}
+
+.btn-accent {
+  background: linear-gradient(135deg, var(--color-accent) 0%, var(--color-accent-light) 100%);
+  color: white;
+  box-shadow: 0 4px 14px rgba(231, 111, 81, 0.25);
+}
+
+.btn-accent:hover {
+  transform: translateY(-2px);
+  box-shadow: 0 6px 20px rgba(231, 111, 81, 0.35);
+}
+
+.btn-outline {
+  background: transparent;
+  color: var(--color-text);
+  border: 2px solid var(--color-border);
+}
+
+.btn-outline:hover {
+  border-color: var(--color-primary);
+  color: var(--color-primary);
+}
+
+/* Card styles */
+.card {
+  background: var(--glass-bg);
+  backdrop-filter: blur(20px);
+  border: 1px solid var(--glass-border);
+  border-radius: 20px;
+  box-shadow: 0 4px 24px rgba(0, 0, 0, 0.06);
+}
+
+/* Input styles */
+.input {
+  width: 100%;
+  padding: 0.875rem 1rem;
+  font-family: var(--font-sans);
+  font-size: 1rem;
+  color: var(--color-text);
+  background: var(--color-surface);
+  border: 2px solid var(--color-border);
+  border-radius: 12px;
+  outline: none;
+  transition: all 0.2s ease;
+}
+
+.input:focus {
+  border-color: var(--color-primary);
+  box-shadow: 0 0 0 4px rgba(30, 58, 95, 0.1);
+}
+
+.input::placeholder {
+  color: var(--color-text-muted);
+}
+
+/* Badge styles */
+.badge {
+  display: inline-flex;
+  align-items: center;
+  gap: 0.25rem;
+  padding: 0.25rem 0.75rem;
+  font-size: 0.8rem;
+  font-weight: 600;
+  border-radius: 9999px;
+}
+
+.badge-success {
+  background: rgba(42, 157, 143, 0.15);
+  color: var(--color-success);
+}
+
+.badge-warning {
+  background: rgba(233, 196, 106, 0.2);
+  color: #b7791f;
+}
+
+/* Animations */
+@keyframes fadeInUp {
+  from {
+    opacity: 0;
+    transform: translateY(20px);
+  }
+  to {
+    opacity: 1;
+    transform: translateY(0);
+  }
+}
+
+@keyframes pulse {
+  0%, 100% {
+    opacity: 1;
+  }
+  50% {
+    opacity: 0.6;
+  }
+}
+
+@keyframes float {
+  0%, 100% {
+    transform: translateY(0);
+  }
+  50% {
+    transform: translateY(-10px);
+  }
+}
+
+.animate-fade-in-up {
+  animation: fadeInUp 0.6s ease-out forwards;
+}
+
+.animate-pulse {
+  animation: pulse 2s ease-in-out infinite;
+}
+
+.animate-float {
+  animation: float 6s ease-in-out infinite;
+}
+
+/* Staggered animations */
+.stagger-1 { animation-delay: 0.1s; }
+.stagger-2 { animation-delay: 0.2s; }
+.stagger-3 { animation-delay: 0.3s; }
+.stagger-4 { animation-delay: 0.4s; }
+.stagger-5 { animation-delay: 0.5s; }
+
+/* Utility classes */
+.text-gradient {
+  background: linear-gradient(135deg, var(--color-primary) 0%, var(--color-accent) 100%);
+  -webkit-background-clip: text;
+  -webkit-text-fill-color: transparent;
+  background-clip: text;
+}
+
+/* ChatKit customization */
+.chatkit-container {
+  --ck-color-primary: var(--color-primary);
+  --ck-color-background: var(--color-surface);
+  --ck-border-radius: 16px;
+  display: flex;
+  flex-direction: column;
+}
+
+/* Ensure ChatKit elements are visible */
+.chatkit-container > * {
+  min-height: 0;
+  flex: 1;
+}
+
+/* Make sure the input area is always visible */
+[data-chatkit-composer],
+[class*="composer"],
+[class*="Composer"] {
+  position: relative !important;
+  z-index: 10;
 }

chatkit/frontend/src/lib/config.ts

@@ -6,6 +6,9 @@ const readEnvString = (value: unknown): string | undefined =>
 export const CHATKIT_API_URL =
   readEnvString(import.meta.env.VITE_CHATKIT_API_URL) ?? "/chatkit";
 
+export const API_BASE_URL =
+  readEnvString(import.meta.env.VITE_API_BASE_URL) ?? "";
+
 /**
  * ChatKit requires a domain key at runtime. Use the local fallback while
  * developing, and register a production domain key for deployment:
@@ -14,3 +17,6 @@ export const CHATKIT_API_URL =
 export const CHATKIT_API_DOMAIN_KEY =
   readEnvString(import.meta.env.VITE_CHATKIT_API_DOMAIN_KEY) ??
   "domain_pk_localhost_dev";
+
+export const GOOGLE_AUTH_URL = `${API_BASE_URL}/auth/start`;
+export const AUTH_STATUS_URL = `${API_BASE_URL}/auth/status`;

chatkit/frontend/vite.config.ts

@@ -16,6 +16,14 @@ export default defineConfig({
         target: backendTarget,
         changeOrigin: true,
       },
+      "/auth": {
+        target: backendTarget,
+        changeOrigin: true,
+      },
+      "/api": {
+        target: backendTarget,
+        changeOrigin: true,
+      },
     },
   },
 });

chatkit/package-lock.json

@@ -1,12 +1,25 @@
 {
-  "name": "chatkit",
+  "name": "examinsight",
+  "version": "1.0.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
-      "name": "chatkit",
+      "name": "examinsight",
+      "version": "1.0.0",
+      "hasInstallScript": true,
+      "license": "MIT",
       "devDependencies": {
-        "concurrently": "^9.1.2"
+        "concurrently": "^8.2.2"
+      }
+    },
+    "node_modules/@babel/runtime": {
+      "version": "7.28.6",
+      "resolved": "https://registry.npmjs.org/@babel/runtime/-/runtime-7.28.6.tgz",
+      "integrity": "sha512-05WQkdpL9COIMz4LjTxGpPNCdlpyimKppYNoJ5Di5EUObifl8t4tuLuUBBZEpoLYOmfvIWrsp9fCl0HoPRVTdA==",
+      "dev": true,
+      "engines": {
+        "node": ">=6.9.0"
       }
     },
     "node_modules/ansi-regex": {
@@ -101,30 +114,48 @@
       "license": "MIT"
     },
     "node_modules/concurrently": {
-      "version": "9.2.1",
-      "resolved": "https://registry.npmjs.org/concurrently/-/concurrently-9.2.1.tgz",
-      "integrity": "sha512-fsfrO0MxV64Znoy8/l1vVIjjHa29SZyyqPgQBwhiDcaW8wJc2W3XWVOGx4M3oJBnv/zdUZIIp1gDeS98GzP8Ng==",
+      "version": "8.2.2",
+      "resolved": "https://registry.npmjs.org/concurrently/-/concurrently-8.2.2.tgz",
+      "integrity": "sha512-1dP4gpXFhei8IOtlXRE/T/4H88ElHgTiUzh71YUmtjTEHMSRS2Z/fgOxHSxxusGHogsRfxNq1vyAwxSC+EVyDg==",
       "dev": true,
-      "license": "MIT",
       "dependencies": {
-        "chalk": "4.1.2",
-        "rxjs": "7.8.2",
-        "shell-quote": "1.8.3",
-        "supports-color": "8.1.1",
-        "tree-kill": "1.2.2",
-        "yargs": "17.7.2"
+        "chalk": "^4.1.2",
+        "date-fns": "^2.30.0",
+        "lodash": "^4.17.21",
+        "rxjs": "^7.8.1",
+        "shell-quote": "^1.8.1",
+        "spawn-command": "0.0.2",
+        "supports-color": "^8.1.1",
+        "tree-kill": "^1.2.2",
+        "yargs": "^17.7.2"
       },
       "bin": {
         "conc": "dist/bin/concurrently.js",
         "concurrently": "dist/bin/concurrently.js"
       },
       "engines": {
-        "node": ">=18"
+        "node": "^14.13.0 || >=16.0.0"
       },
       "funding": {
         "url": "https://github.com/open-cli-tools/concurrently?sponsor=1"
       }
     },
+    "node_modules/date-fns": {
+      "version": "2.30.0",
+      "resolved": "https://registry.npmjs.org/date-fns/-/date-fns-2.30.0.tgz",
+      "integrity": "sha512-fnULvOpxnC5/Vg3NCiWelDsLiUc9bRwAPs/+LfTLNvetFCtCTN+yQz15C/fs4AwX1R9K5GLtLfn8QW+dWisaAw==",
+      "dev": true,
+      "dependencies": {
+        "@babel/runtime": "^7.21.0"
+      },
+      "engines": {
+        "node": ">=0.11"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/date-fns"
+      }
+    },
     "node_modules/emoji-regex": {
       "version": "8.0.0",
       "resolved": "https://registry.npmjs.org/emoji-regex/-/emoji-regex-8.0.0.tgz",
@@ -172,6 +203,12 @@
         "node": ">=8"
       }
     },
+    "node_modules/lodash": {
+      "version": "4.17.23",
+      "resolved": "https://registry.npmjs.org/lodash/-/lodash-4.17.23.tgz",
+      "integrity": "sha512-LgVTMpQtIopCi79SJeDiP0TfWi5CNEc/L/aRdTh3yIvmZXTnheWpKjSZhnvMl8iXbC1tFg9gdHHDMLoV7CnG+w==",
+      "dev": true
+    },
     "node_modules/require-directory": {
       "version": "2.1.1",
       "resolved": "https://registry.npmjs.org/require-directory/-/require-directory-2.1.1.tgz",
@@ -205,6 +242,12 @@
         "url": "https://github.com/sponsors/ljharb"
       }
     },
+    "node_modules/spawn-command": {
+      "version": "0.0.2",
+      "resolved": "https://registry.npmjs.org/spawn-command/-/spawn-command-0.0.2.tgz",
+      "integrity": "sha512-zC8zGoGkmc8J9ndvml8Xksr1Amk9qBujgbF0JAIWO7kXr43w0h/0GJNM/Vustixu+YE8N/MTrQ7N31FvHUACxQ==",
+      "dev": true
+    },
     "node_modules/string-width": {
       "version": "4.2.3",
       "resolved": "https://registry.npmjs.org/string-width/-/string-width-4.2.3.tgz",

chatkit/package.json

@@ -1,12 +1,27 @@
 {
-  "name": "chatkit",
+  "name": "examinsight",
+  "version": "1.0.0",
+  "description": "ExamInsight - AI-Powered Exam Analysis for Teachers using OpenAI ChatKit",
   "private": true,
   "scripts": {
-    "dev": "concurrently --kill-others-on-fail --names backend,frontend \"npm run backend\" \"npm run frontend\"",
-    "frontend": "npm --prefix frontend install && npm --prefix frontend run dev",
-    "backend": "./backend/scripts/run.sh"
+    "dev": "concurrently \"npm run dev:backend\" \"npm run dev:frontend\"",
+    "dev:backend": "cd backend && ./scripts/run.sh",
+    "dev:frontend": "cd frontend && npm run dev",
+    "install": "cd frontend && npm install && cd ../backend && pip install -e .",
+    "build": "cd frontend && npm run build",
+    "lint": "cd frontend && npm run lint"
   },
+  "keywords": [
+    "examinsight",
+    "openai",
+    "chatkit",
+    "education",
+    "exam-analysis",
+    "teacher-tools"
+  ],
+  "author": "",
+  "license": "MIT",
   "devDependencies": {
-    "concurrently": "^9.1.2"
+    "concurrently": "^8.2.2"
   }
 }