initial commit

.env.example

@@ -0,0 +1,49 @@
+# Copy to .env and fill in.
+
+# --- LLM provider --------------------------------------------------------
+# 'google'    : Gemini via langchain-google-genai (FREE tier — recommended)
+# 'anthropic' : Claude via langchain-anthropic   (paid)
+LLM_PROVIDER=google
+
+# --- Google Gemini (free) ------------------------------------------------
+# Get a key at: https://aistudio.google.com/app/apikey
+# No billing required.
+GOOGLE_API_KEY=
+
+# gemini-2.5-flash-lite has the highest free-tier quota of any vision-
+# capable Gemini (15 RPM / 1000 RPD). Switch to gemini-2.5-flash or
+# gemini-1.5-flash if you prefer their output quality and accept tighter
+# rate limits.
+GRADER_MODEL_GOOGLE=gemini-2.5-flash-lite
+
+# --- Anthropic Claude (paid; only used if LLM_PROVIDER=anthropic) --------
+ANTHROPIC_API_KEY=
+GRADER_MODEL_ANTHROPIC=claude-sonnet-4-20250514
+
+# --- Database ------------------------------------------------------------
+DATABASE_URL=sqlite:///./gradeops.db
+#   DATABASE_URL=postgresql+psycopg2://gradeops:gradeops@localhost:5432/gradeops
+
+# --- OCR routing ---------------------------------------------------------
+# 'hosted' uses whatever LLM_PROVIDER above (works without GPU).
+# 'qwen_vl' uses Qwen2-VL via HuggingFace transformers (needs GPU).
+OCR_BACKEND=hosted
+
+# --- Storage -------------------------------------------------------------
+STORAGE_ROOT=./storage
+
+# --- Grader behavior -----------------------------------------------------
+# Number of independent grading passes per answer. 1 = free-tier friendly,
+# 5 = the full multi-pass design with median/max/std-dev aggregation.
+GRADER_NUM_PASSES=1
+# Critic retry limit. 0 disables the retry edge.
+GRADER_CRITIC_RETRY=0
+
+# --- Rate-limit throttling -----------------------------------------------
+# Seconds between LLM calls. 4.5 keeps us under Gemini's free-tier 15 RPM.
+# Set to 0 on paid tiers to disable throttling.
+LLM_MIN_GAP_SECONDS=4.5
+
+# --- Plagiarism ----------------------------------------------------------
+PLAGIARISM_THRESHOLD=0.82
+EMBEDDING_MODEL=sentence-transformers/all-MiniLM-L6-v2

.gitignore

@@ -0,0 +1,28 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.venv/
+venv/
+*.db
+*.sqlite
+
+# Env
+.env
+.env.local
+
+# Node
+node_modules/
+dist/
+.vite/
+
+# Storage (user data — keep out of source control)
+storage/pdfs/*
+storage/pages/*
+storage/crops/*
+!storage/pdfs/.gitkeep
+!storage/pages/.gitkeep
+!storage/crops/.gitkeep
+
+# IDE
+.vscode/

README.md

@@ -0,0 +1,223 @@
+# GradeOps
+
+> Human-in-the-loop grading pipeline for handwritten exams.
+
+GradeOps lets an instructor upload scanned answer sheets and grading rubrics, automatically transcribes each handwritten answer, runs it through a multi-step LLM grader that awards partial credit with citations, and surfaces every AI-proposed grade on a high-throughput review dashboard where teaching assistants approve, override, or flag with keyboard shortcuts.
+
+---
+
+## Stack
+
+| Layer | Tech |
+|---|---|
+| Frontend | React 18, Vite, Tailwind, Inter typography |
+| Backend | FastAPI, SQLAlchemy |
+| Database | SQLite (default) or Postgres |
+| Agentic grader | Langchain + Langgraph (Extractor → Scorer → Justifier → Critic) |
+| OCR / Vision | Gemini (free tier) or Claude vision via a swappable adapter; Qwen-VL adapter stub for HuggingFace use |
+| Plagiarism | sentence-transformers cosine similarity |
+| Storage | Local `storage/` folder behind a path abstraction (drop-in for S3) |
+
+---
+
+## Quick start
+
+### 1. Clone, create a venv, install dependencies
+
+```bash
+cd gradeops
+python -m venv .venv
+# Windows:
+.venv\Scripts\activate
+# macOS / Linux:
+source .venv/bin/activate
+
+pip install -r requirements.txt
+```
+
+### 2. Configure environment
+
+```bash
+cp .env.example .env
+```
+
+Open `.env` and set at minimum:
+
+```
+GOOGLE_API_KEY=AIzaSy...
+```
+
+Get a free Gemini API key at <https://aistudio.google.com/app/apikey> — no billing required.
+
+### 3. Initialize the database
+
+```bash
+python scripts/init_db.py
+python scripts/seed_demo.py   # optional: pre-load a sample exam + rubric
+```
+
+### 4. Run the backend
+
+```bash
+uvicorn backend.main:app --reload --port 8000
+```
+
+API docs at <http://localhost:8000/docs>.
+
+### 5. Run the frontend (new terminal)
+
+```bash
+cd frontend
+npm install
+npm run dev
+```
+
+Open <http://localhost:5173>.
+
+### 6. Optional CLI demo
+
+For a no-UI walkthrough on one image:
+
+```bash
+python scripts/run_demo.py path/to/handwritten_answer.jpg
+```
+
+---
+
+## How the grader works
+
+The grader is a 4-node agentic state machine compiled with Langgraph:
+
+```
+                ┌────────────────────────────────────────────┐
+                │                                            │
+   image ─► Extractor ─► Scorer ─► Justifier ─► Critic ─┐    │
+                            ▲                           │    │
+                            │                           │    │
+                            └─── retry with feedback ───┘    │
+                                                             │
+                                  END ◄─── pass ─────────────┘
+```
+
+- **Extractor** sees the image. Transcribes the handwriting literally and breaks it into atomic claim-steps. Never scores.
+- **Scorer** sees only the extracted claims (not the image). Maps them to rubric criteria and awards points. The image-blindness is deliberate — it is the structural defense against the grader awarding credit for things it imagines rather than what is on the page.
+- **Justifier** writes a 2–3 sentence rationale citing specific claim numbers.
+- **Critic** audits whether every awarded point is supported by a claim. If not, it sends the Scorer back with concrete feedback. Configurable retry limit; disabled by default to keep the call budget tight.
+
+For higher-confidence grading, set `GRADER_NUM_PASSES=5` in `.env`. The system will run the full graph 5 times per answer and aggregate median, max, and standard deviation. The review queue then sorts by std-dev DESC, surfacing the AI's most uncertain grades to TAs first.
+
+---
+
+## Review dashboard shortcuts
+
+| Key | Action |
+|---|---|
+| `Enter` | Approve the AI's median score |
+| `O` | Open the override input |
+| `F` | Flag for further review |
+| `J` / `→` | Next item |
+| `K` / `←` | Previous item |
+| `Esc` (in override) | Cancel |
+| `Ctrl/⌘ + Enter` (in override) | Save override |
+
+---
+
+## Configuration reference
+
+All settings live in `.env`. Key knobs:
+
+| Variable | Default | Purpose |
+|---|---|---|
+| `LLM_PROVIDER` | `google` | `google` or `anthropic` |
+| `GOOGLE_API_KEY` | — | Required for the default Google provider |
+| `GRADER_MODEL_GOOGLE` | `gemini-2.5-flash-lite` | Free-tier-friendly vision model |
+| `ANTHROPIC_API_KEY` | — | Required if `LLM_PROVIDER=anthropic` |
+| `GRADER_MODEL_ANTHROPIC` | `claude-sonnet-4-20250514` | |
+| `DATABASE_URL` | `sqlite:///./gradeops.db` | Swap to a Postgres URL when needed |
+| `OCR_BACKEND` | `hosted` | `hosted` (uses configured LLM) or `qwen_vl` (HuggingFace, needs GPU) |
+| `GRADER_NUM_PASSES` | `1` | Passes per answer; raise to 5 for variance-based review priority |
+| `GRADER_CRITIC_RETRY` | `0` | How many times the Critic may send the Scorer back |
+| `LLM_MIN_GAP_SECONDS` | `4.5` | Throttle between LLM calls; keeps free-tier RPM caps safe |
+| `PLAGIARISM_THRESHOLD` | `0.82` | Cosine similarity cutoff |
+
+---
+
+## Schema (DB tables)
+
+```
+users               role: instructor | ta
+exams               
+rubrics             versioned (v1, v2, ...); immutable on update
+papers              one row per uploaded PDF
+crops               one row per cropped answer region
+gradings            one row per grading pass
+grading_aggregates  median / max / min / std-dev per crop
+reviews             every approve / override / flag
+plagiarism_flags    pairs of crops above similarity threshold
+audit_log           append-only; every row stamped with rubric_ver + prompt_ver + model_ver
+```
+
+Every grading and every review writes an audit row, stamped with the rubric, prompt, and model versions in effect at the time. The audit log is the source of truth for traceability.
+
+---
+
+## Project layout
+
+```
+gradeops/
+├── backend/
+│   ├── main.py                    FastAPI app
+│   ├── config.py · db.py · schemas.py
+│   ├── audit.py · plagiarism.py
+│   ├── ingestion/                 PDF split · crop · anonymize
+│   ├── ocr/                       Hosted + Qwen-VL adapters + router
+│   └── grader/                    Langgraph state machine + rate limiter
+├── frontend/
+│   ├── package.json · vite.config.js · tailwind.config.js
+│   └── src/
+│       ├── App.jsx · main.jsx · index.css · api.js
+│       ├── components/ui.jsx
+│       └── pages/{Rubrics,Grading,Review,Audit}.jsx
+├── scripts/
+│   ├── init_db.py
+│   ├── seed_demo.py
+│   └── run_demo.py
+├── storage/                       Local stand-in for cloud object store
+├── docker-compose.yml             Optional Postgres
+├── requirements.txt
+└── .env.example
+```
+
+---
+
+## API reference
+
+Quick tour. Full schema at `/docs` when the server is running.
+
+| Method | Path | Description |
+|---|---|---|
+| GET | `/health` | Liveness probe + active model |
+| GET | `/debug/env` | Diagnostic — what env vars actually loaded |
+| GET | `/users` | List instructor + TA accounts |
+| POST | `/exams` | Create an exam |
+| GET | `/exams` | List exams |
+| POST | `/rubrics` | Create a rubric (immutable; auto-versioned) |
+| GET | `/rubrics?exam_id={id}` | List rubrics for an exam |
+| POST | `/papers/upload` | Upload a PDF or image; runs the full pipeline |
+| GET | `/crops/{id}/image` | Fetch the anonymized crop image |
+| GET | `/review/queue` | Crops sorted by std-dev DESC, pending only |
+| POST | `/reviews` | Submit an approve / override / flag |
+| GET | `/audit` | Decision log |
+| GET | `/plagiarism` | Similarity pairs above threshold |
+| GET | `/stats` | Dashboard metrics |
+
+---
+
+## Out of scope for this build
+
+- Real authentication / SSO — there is a role toggle in the header for RBAC demonstration
+- Background workers — the pipeline runs synchronously on upload
+- Cloud object storage — the local `storage/` folder is behind a path abstraction; S3 swap is a small change
+- Failure recovery, idempotency, retries beyond the Critic loop
+
+These are flagged in the architecture as the next things to add when moving to production.

backend/audit.py

@@ -0,0 +1,41 @@
+"""Append-only audit logger.
+
+Every grading and every review decision writes a row here, stamped with the
+rubric / prompt / model versions in effect at the time. This is what gives
+the brief's "Traceability for all grading decisions" non-functional
+requirement actual teeth.
+"""
+from __future__ import annotations
+
+from typing import Any
+
+from sqlalchemy.orm import Session
+
+from .config import settings
+from .db import AuditLog
+
+
+def log_event(
+    db: Session,
+    entity_type: str,
+    entity_id: int,
+    action: str,
+    actor_id: int | None = None,
+    before: dict | None = None,
+    after: dict | None = None,
+    rubric_version: str | None = None,
+) -> AuditLog:
+    """Write one audit row. Caller is responsible for db.commit()."""
+    row = AuditLog(
+        entity_type=entity_type,
+        entity_id=entity_id,
+        action=action,
+        actor_id=actor_id,
+        before=before,
+        after=after,
+        rubric_version=rubric_version,
+        prompt_version=settings.prompt_version,
+        model_version=settings.grader_model,
+    )
+    db.add(row)
+    return row

backend/config.py

@@ -0,0 +1,89 @@
+"""Centralized configuration loaded from environment variables.
+
+Loading order (first non-empty wins):
+  1. Shell environment variable (e.g. `$env:GOOGLE_API_KEY=...`)
+  2. Values in `gradeops/.env` (loaded via python-dotenv from an ABSOLUTE
+     path resolved from this file's location — robust to whatever CWD
+     uvicorn was launched with)
+  3. Class-level defaults below
+"""
+from pathlib import Path
+
+from dotenv import load_dotenv
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+# backend/config.py → ../ → gradeops/ → .env  (absolute path, CWD-independent)
+_PROJECT_ROOT = Path(__file__).resolve().parent.parent
+_ENV_FILE = _PROJECT_ROOT / ".env"
+
+if _ENV_FILE.exists():
+    load_dotenv(_ENV_FILE, override=False)
+
+
+class Settings(BaseSettings):
+    # --- LLM provider selection ----------------------------------------
+    # 'google'    : Gemini via langchain-google-genai (FREE tier)
+    # 'anthropic' : Claude via langchain-anthropic   (paid)
+    llm_provider: str = "google"
+
+    # --- Google Gemini -------------------------------------------------
+    # 2.5-flash-lite has the highest free-tier quota of any vision-capable
+    # Gemini (15 RPM / 1000 RPD) — picked for reliability over peak quality.
+    google_api_key: str = ""
+    grader_model_google: str = "gemini-2.5-flash-lite"
+
+    # --- Anthropic Claude (paid; used only if LLM_PROVIDER=anthropic) --
+    anthropic_api_key: str = ""
+    grader_model_anthropic: str = "claude-sonnet-4-20250514"
+
+    # --- Database ------------------------------------------------------
+    database_url: str = "sqlite:///./gradeops.db"
+
+    # --- OCR routing ---------------------------------------------------
+    ocr_backend: str = "hosted"
+
+    # --- Storage -------------------------------------------------------
+    storage_root: str = "./storage"
+
+    # --- Grader behavior -----------------------------------------------
+    grader_num_passes: int = 1            # 1 keeps free-tier-friendly; 5 matches the multi-pass design
+    grader_critic_retry: int = 0          # set to 1 to enable critic→scorer retry
+
+    # --- Rate-limit throttling -----------------------------------------
+    # Seconds between successive LLM calls. Gemini free tier = 15 RPM,
+    # so the safe floor is 4s. We default to 4.5s with a small jitter
+    # cushion so even rapid back-to-back uploads stay under quota.
+    llm_min_gap_seconds: float = 4.5
+
+    # --- Plagiarism ----------------------------------------------------
+    plagiarism_threshold: float = 0.82
+    embedding_model: str = "sentence-transformers/all-MiniLM-L6-v2"
+
+    # --- Versioning ----------------------------------------------------
+    prompt_version: str = "v1.0"
+    schema_version: str = "v1.0"
+
+    model_config = SettingsConfigDict(
+        env_file=str(_ENV_FILE) if _ENV_FILE.exists() else None,
+        env_file_encoding="utf-8-sig",
+        extra="ignore",
+        case_sensitive=False,
+    )
+
+    @property
+    def storage_path(self) -> Path:
+        p = Path(self.storage_root)
+        (p / "pdfs").mkdir(parents=True, exist_ok=True)
+        (p / "pages").mkdir(parents=True, exist_ok=True)
+        (p / "crops").mkdir(parents=True, exist_ok=True)
+        return p
+
+    @property
+    def grader_model(self) -> str:
+        if (self.llm_provider or "google").lower() == "anthropic":
+            return self.grader_model_anthropic
+        return self.grader_model_google
+
+
+settings = Settings()

backend/db.py

@@ -0,0 +1,180 @@
+"""SQLAlchemy ORM models matching the architecture diagram.
+
+Tables:
+  users              instructor / TA accounts (simple RBAC)
+  exams              one row per exam instance
+  rubrics            versioned per exam (immutable; updates create new rows)
+  papers             one row per uploaded student PDF
+  crops              one row per cropped answer region
+  gradings           one row per grading pass (5 per crop)
+  grading_aggregates median / max / std-dev per crop
+  reviews            TA decisions (approve / override / flag)
+  plagiarism_flags   pairs of crops above similarity threshold
+  audit_log          immutable decision trail with model + prompt + rubric versions
+"""
+from __future__ import annotations
+
+from datetime import datetime
+from sqlalchemy import (
+    create_engine, Column, Integer, String, Float, DateTime,
+    ForeignKey, JSON, Text, Boolean, UniqueConstraint
+)
+from sqlalchemy.orm import declarative_base, relationship, sessionmaker, Session
+
+from .config import settings
+
+
+# Engine + session ------------------------------------------------------------
+connect_args = {"check_same_thread": False} if settings.database_url.startswith("sqlite") else {}
+engine = create_engine(settings.database_url, connect_args=connect_args, future=True)
+SessionLocal = sessionmaker(bind=engine, autoflush=False, autocommit=False, future=True)
+Base = declarative_base()
+
+
+def get_db() -> Session:
+    """FastAPI dependency that yields a database session and closes it on exit."""
+    db = SessionLocal()
+    try:
+        yield db
+    finally:
+        db.close()
+
+
+def init_db() -> None:
+    """Create all tables. Idempotent — safe to call on every boot."""
+    Base.metadata.create_all(bind=engine)
+
+
+# Tables ---------------------------------------------------------------------
+class User(Base):
+    __tablename__ = "users"
+    id = Column(Integer, primary_key=True)
+    email = Column(String, unique=True, nullable=False)
+    name = Column(String, nullable=False)
+    role = Column(String, nullable=False)  # 'instructor' | 'ta'
+    created_at = Column(DateTime, default=datetime.utcnow)
+
+
+class Exam(Base):
+    __tablename__ = "exams"
+    id = Column(Integer, primary_key=True)
+    title = Column(String, nullable=False)
+    created_by = Column(Integer, ForeignKey("users.id"), nullable=True)
+    created_at = Column(DateTime, default=datetime.utcnow)
+
+    rubrics = relationship("Rubric", back_populates="exam", cascade="all, delete-orphan")
+    papers = relationship("Paper", back_populates="exam", cascade="all, delete-orphan")
+
+
+class Rubric(Base):
+    __tablename__ = "rubrics"
+    id = Column(Integer, primary_key=True)
+    exam_id = Column(Integer, ForeignKey("exams.id"), nullable=False)
+    version = Column(String, nullable=False)        # e.g. 'v1', 'v2'
+    title = Column(String, nullable=False)
+    question_text = Column(Text, nullable=False)
+    max_marks = Column(Float, nullable=False)
+    course_instructions = Column(Text, nullable=False)
+    criteria = Column(JSON, nullable=False)         # list of dicts; see schemas.py
+    created_at = Column(DateTime, default=datetime.utcnow)
+
+    exam = relationship("Exam", back_populates="rubrics")
+
+
+class Paper(Base):
+    __tablename__ = "papers"
+    id = Column(Integer, primary_key=True)
+    exam_id = Column(Integer, ForeignKey("exams.id"), nullable=False)
+    student_anon_id = Column(String, nullable=False)  # e.g. 'STU-0001'; never the real ID
+    source_pdf_path = Column(String, nullable=False)
+    uploaded_at = Column(DateTime, default=datetime.utcnow)
+
+    exam = relationship("Exam", back_populates="papers")
+    crops = relationship("Crop", back_populates="paper", cascade="all, delete-orphan")
+
+
+class Crop(Base):
+    __tablename__ = "crops"
+    id = Column(Integer, primary_key=True)
+    paper_id = Column(Integer, ForeignKey("papers.id"), nullable=False)
+    question_id = Column(String, nullable=False)        # e.g. 'Q1', 'Q2a'
+    rubric_id = Column(Integer, ForeignKey("rubrics.id"), nullable=False)
+    image_path = Column(String, nullable=False)         # raw crop
+    anonymized_path = Column(String, nullable=False)    # post-anonymization
+    bbox = Column(JSON, nullable=True)                  # {x,y,w,h} on source page
+    created_at = Column(DateTime, default=datetime.utcnow)
+
+    paper = relationship("Paper", back_populates="crops")
+    gradings = relationship("Grading", back_populates="crop", cascade="all, delete-orphan")
+
+
+class Grading(Base):
+    """One row per LLM grading pass. NUM_PASSES rows expected per crop."""
+    __tablename__ = "gradings"
+    id = Column(Integer, primary_key=True)
+    crop_id = Column(Integer, ForeignKey("crops.id"), nullable=False)
+    rubric_id = Column(Integer, ForeignKey("rubrics.id"), nullable=False)
+    pass_num = Column(Integer, nullable=False)
+    score = Column(Float, nullable=False)
+    max_score = Column(Float, nullable=False)
+    per_criterion = Column(JSON, nullable=False)        # list[{name, awarded, max, reasoning}]
+    justification = Column(Text, nullable=False)
+    transcript = Column(Text, nullable=False)
+    flags = Column(JSON, nullable=False, default=list)
+    critic_passed = Column(Boolean, nullable=False, default=True)
+    critic_feedback = Column(Text, nullable=True)
+    model_version = Column(String, nullable=False)
+    prompt_version = Column(String, nullable=False)
+    created_at = Column(DateTime, default=datetime.utcnow)
+
+    crop = relationship("Crop", back_populates="gradings")
+
+
+class GradingAggregate(Base):
+    """Aggregated scores across passes; one row per crop."""
+    __tablename__ = "grading_aggregates"
+    crop_id = Column(Integer, ForeignKey("crops.id"), primary_key=True)
+    median = Column(Float, nullable=False)
+    max_score = Column(Float, nullable=False)
+    min_score = Column(Float, nullable=False)
+    std_dev = Column(Float, nullable=False)
+    n_passes = Column(Integer, nullable=False)
+    computed_at = Column(DateTime, default=datetime.utcnow)
+
+
+class Review(Base):
+    __tablename__ = "reviews"
+    id = Column(Integer, primary_key=True)
+    crop_id = Column(Integer, ForeignKey("crops.id"), nullable=False)
+    reviewer_id = Column(Integer, ForeignKey("users.id"), nullable=True)
+    action = Column(String, nullable=False)             # approve | override | flag
+    ai_score = Column(Float, nullable=False)
+    final_score = Column(Float, nullable=False)
+    notes = Column(Text, nullable=True)
+    created_at = Column(DateTime, default=datetime.utcnow)
+
+
+class PlagiarismFlag(Base):
+    __tablename__ = "plagiarism_flags"
+    id = Column(Integer, primary_key=True)
+    crop_a_id = Column(Integer, ForeignKey("crops.id"), nullable=False)
+    crop_b_id = Column(Integer, ForeignKey("crops.id"), nullable=False)
+    similarity = Column(Float, nullable=False)
+    flagged_at = Column(DateTime, default=datetime.utcnow)
+    __table_args__ = (UniqueConstraint("crop_a_id", "crop_b_id", name="uniq_pair"),)
+
+
+class AuditLog(Base):
+    """Immutable trail of every state change. Append-only."""
+    __tablename__ = "audit_log"
+    id = Column(Integer, primary_key=True)
+    entity_type = Column(String, nullable=False)        # 'grading', 'review', etc
+    entity_id = Column(Integer, nullable=False)
+    action = Column(String, nullable=False)
+    actor_id = Column(Integer, ForeignKey("users.id"), nullable=True)
+    before = Column(JSON, nullable=True)
+    after = Column(JSON, nullable=True)
+    rubric_version = Column(String, nullable=True)
+    prompt_version = Column(String, nullable=True)
+    model_version = Column(String, nullable=True)
+    created_at = Column(DateTime, default=datetime.utcnow)

backend/grader/__init__.py

@@ -0,0 +1,2 @@
+from .graph import grade_one_pass, grade_multi_pass  # noqa: F401
+from .aggregate import aggregate_scores  # noqa: F401

backend/grader/aggregate.py

@@ -0,0 +1,32 @@
+"""Aggregate scores across multiple grading passes.
+
+We deliberately keep median, max, AND std-dev:
+  - median is the "fair" provisional score (less sensitive to outliers)
+  - max is the conservative-in-student's-favor choice (Paper 2's primary)
+  - std-dev is the routing signal for the review queue (highest variance first)
+
+Paper 2 found no reliable threshold for fully-automated low-confidence
+skipping. So std-dev is used here as a SORTING signal, not a SKIP signal —
+every grade still goes to a human, but high-std-dev ones go to the front
+of the queue.
+"""
+from __future__ import annotations
+
+import statistics
+
+
+def aggregate_scores(passes: list[dict]) -> dict:
+    """Given N pass dicts (each with 'score'), produce summary stats."""
+    scores = [float(p.get("score", 0.0)) for p in passes if "score" in p]
+    if not scores:
+        return {
+            "median": 0.0, "max_score": 0.0, "min_score": 0.0,
+            "std_dev": 0.0, "n_passes": 0,
+        }
+    return {
+        "median": float(statistics.median(scores)),
+        "max_score": float(max(scores)),
+        "min_score": float(min(scores)),
+        "std_dev": float(statistics.pstdev(scores)) if len(scores) > 1 else 0.0,
+        "n_passes": len(scores),
+    }

backend/grader/graph.py

@@ -0,0 +1,99 @@
+"""Langgraph wiring for the agentic grader.
+
+Graph:
+    extractor -> scorer -> justifier -> critic --pass--> END
+                   ^                       |
+                   +----- retry-with-feedback (optional)
+
+Multi-pass:
+    Runs the graph NUM_PASSES times PER CROP, sequentially. Sequential
+    (not threadpooled) so the global rate limiter in rate_limit.py can
+    space all calls to stay under Gemini's free-tier RPM cap. For paid
+    tiers, set llm_min_gap_seconds=0 in .env to remove the throttle.
+"""
+from __future__ import annotations
+
+import base64
+from pathlib import Path
+
+from langgraph.graph import StateGraph, START, END
+
+from ..config import settings
+from .state import GradingState
+from .nodes import (
+    extractor_node, scorer_node, justifier_node, critic_node, critic_router,
+)
+
+
+def build_grading_graph():
+    g = StateGraph(GradingState)
+    g.add_node("extractor", extractor_node)
+    g.add_node("scorer", scorer_node)
+    g.add_node("justifier", justifier_node)
+    g.add_node("critic", critic_node)
+    g.add_edge(START, "extractor")
+    g.add_edge("extractor", "scorer")
+    g.add_edge("scorer", "justifier")
+    g.add_edge("justifier", "critic")
+    g.add_conditional_edges("critic", critic_router, {"scorer": "scorer", END: END})
+    return g.compile()
+
+
+GRAPH = build_grading_graph()
+
+
+def _read_image_b64(image_path: str) -> tuple[str, str]:
+    p = Path(image_path)
+    data = p.read_bytes()
+    suffix = p.suffix.lower().lstrip(".")
+    media_type = "image/jpeg" if suffix in ("jpg", "jpeg") else f"image/{suffix or 'jpeg'}"
+    return base64.b64encode(data).decode("ascii"), media_type
+
+
+def grade_one_pass(image_path: str, question: str, max_marks: float,
+                   criteria: list[dict]) -> dict:
+    img_b64, media_type = _read_image_b64(image_path)
+    initial: GradingState = {
+        "image_b64": img_b64,
+        "media_type": media_type,
+        "question": question,
+        "max_marks": max_marks,
+        "criteria": criteria,
+        "retry_count": 0,
+        "errors": [],
+    }
+    try:
+        final = GRAPH.invoke(initial)
+    except Exception as e:
+        return {
+            "score": 0.0,
+            "max_score": max_marks,
+            "per_criterion": [],
+            "transcript": "",
+            "justification": f"[grading failed: {e}]",
+            "flags": ["api_error"],
+            "critic_passed": False,
+            "critic_feedback": str(e),
+        }
+    return {
+        "score": float(final.get("score", 0.0)),
+        "max_score": float(final.get("max_score", max_marks)),
+        "per_criterion": final.get("per_criterion", []),
+        "transcript": final.get("transcript", ""),
+        "justification": final.get("justification", ""),
+        "flags": final.get("flags", []),
+        "critic_passed": bool(final.get("critic_passed", True)),
+        "critic_feedback": final.get("critic_feedback", ""),
+    }
+
+
+def grade_multi_pass(image_path: str, question: str, max_marks: float,
+                     criteria: list[dict], num_passes: int | None = None) -> list[dict]:
+    """Run NUM_PASSES grading invocations sequentially.
+
+    Sequential is intentional: the rate-limit module enforces a global
+    minimum gap between calls, so parallelism doesn't help and only
+    increases the risk of bursting past the per-minute quota.
+    """
+    n = num_passes or settings.grader_num_passes
+    return [grade_one_pass(image_path, question, max_marks, criteria) for _ in range(n)]

backend/grader/llm.py

@@ -0,0 +1,88 @@
+"""Provider-abstracted LLM factory.
+
+Returns a langchain ChatModel for whichever provider is configured. Both
+the agentic grader nodes and the OCR transcriber import from here, so
+flipping `LLM_PROVIDER` in .env swaps the entire LLM backend in one place.
+
+Supported providers:
+  - 'google'    → Gemini via langchain-google-genai (FREE tier; recommended)
+  - 'anthropic' → Claude via langchain-anthropic   (paid)
+
+Key resolution is belt-and-braces:
+  - First consults `settings.<provider>_api_key` (loaded by pydantic-settings
+    from .env)
+  - Falls back directly to os.environ, so a manually-set shell variable
+    works even if pydantic-settings missed the file
+"""
+from __future__ import annotations
+
+import os
+
+from langchain_core.language_models import BaseChatModel
+
+from ..config import settings
+
+
+_llm: BaseChatModel | None = None
+
+
+def _resolve_key(field_value: str, env_var: str) -> str:
+    """Settings field first, then os.environ. Returns '' if neither has it."""
+    if field_value:
+        return field_value
+    return os.environ.get(env_var, "") or ""
+
+
+def get_llm() -> BaseChatModel:
+    """Construct (and cache) the chat model for the configured provider."""
+    global _llm
+    if _llm is not None:
+        return _llm
+
+    provider = (settings.llm_provider or "google").lower()
+
+    if provider == "google":
+        from langchain_google_genai import ChatGoogleGenerativeAI
+        key = _resolve_key(settings.google_api_key, "GOOGLE_API_KEY")
+        if not key:
+            raise RuntimeError(
+                "LLM_PROVIDER=google but GOOGLE_API_KEY is empty.\n"
+                "Get a free key at https://aistudio.google.com/app/apikey "
+                "and set GOOGLE_API_KEY in your .env file (or shell env var).\n"
+                "Hit GET /debug/env to see what the backend is loading."
+            )
+        _llm = ChatGoogleGenerativeAI(
+            model=settings.grader_model_google,
+            google_api_key=key,
+            max_output_tokens=2048,
+            timeout=120,
+            # Free tier is 15 RPM — we use 5 parallel passes per crop.
+            max_retries=3,
+        )
+        return _llm
+
+    if provider == "anthropic":
+        from langchain_anthropic import ChatAnthropic
+        key = _resolve_key(settings.anthropic_api_key, "ANTHROPIC_API_KEY")
+        if not key:
+            raise RuntimeError(
+                "LLM_PROVIDER=anthropic but ANTHROPIC_API_KEY is empty. "
+                "Set it in .env or switch LLM_PROVIDER=google for the free tier."
+            )
+        _llm = ChatAnthropic(
+            model=settings.grader_model_anthropic,
+            max_tokens=2000,
+            api_key=key,
+            timeout=120,
+        )
+        return _llm
+
+    raise RuntimeError(
+        f"Unknown LLM_PROVIDER: {provider!r}. Use 'google' or 'anthropic'."
+    )
+
+
+def reset_llm() -> None:
+    """Clear the cached LLM instance (used by tests when settings change)."""
+    global _llm
+    _llm = None

backend/grader/nodes.py

@@ -0,0 +1,166 @@
+"""The four agentic nodes wired together by graph.py.
+
+Architecture: Extractor sees the image, Scorer sees only the extracted claims.
+This separation is the structural defense against the LLM "fixing" or
+hallucinating intermediate steps that aren't on the page.
+
+LLM calls go through `backend.grader.llm.get_llm()`, which returns
+Gemini or Claude depending on settings.llm_provider. The node code does
+not know or care which provider is in use.
+"""
+from __future__ import annotations
+
+import json
+import re
+from typing import Any
+
+from langchain_core.messages import HumanMessage, SystemMessage
+
+from ..config import settings
+from . import prompts
+from .llm import get_llm
+from .rate_limit import wait_turn
+from .state import GradingState
+
+
+# LLM is obtained from .llm.get_llm() (provider-agnostic factory).
+
+
+# ---------------------------------------------------------------------------
+# JSON helpers — every node returns strict JSON, so a robust parser earns
+# its keep when the model occasionally wraps in fences.
+# ---------------------------------------------------------------------------
+_FENCE_RE = re.compile(r"^```(?:json)?\s*|\s*```\s*$", re.IGNORECASE)
+
+
+def parse_json(raw: str) -> dict | None:
+    if not raw:
+        return None
+    cleaned = _FENCE_RE.sub("", raw.strip()).strip()
+    # If the model added prose around the JSON, try to grab the outermost {...}
+    try:
+        return json.loads(cleaned)
+    except json.JSONDecodeError:
+        start = cleaned.find("{")
+        end = cleaned.rfind("}")
+        if start != -1 and end != -1 and end > start:
+            try:
+                return json.loads(cleaned[start:end + 1])
+            except json.JSONDecodeError:
+                return None
+        return None
+
+
+def _invoke_text(system: str, user_content: list[dict] | str) -> str:
+    """Call the LLM with a text-only or multimodal user message."""
+    wait_turn()
+    llm = get_llm()
+    if isinstance(user_content, str):
+        msgs = [SystemMessage(content=system), HumanMessage(content=user_content)]
+    else:
+        msgs = [SystemMessage(content=system), HumanMessage(content=user_content)]
+    response = llm.invoke(msgs)
+    return response.content if isinstance(response.content, str) else str(response.content)
+
+
+# ===========================================================================
+# Node 1: Extractor — sees the IMAGE, produces transcript + claims
+# ===========================================================================
+def extractor_node(state: GradingState) -> dict:
+    user = prompts.EXTRACTOR_USER.format(question=state["question"])
+    content = [
+        {
+            "type": "image_url",
+            "image_url": {"url": f"data:{state.get('media_type', 'image/jpeg')};base64,{state['image_b64']}"},
+        },
+        {"type": "text", "text": user},
+    ]
+    raw = _invoke_text(prompts.EXTRACTOR_SYSTEM, content)
+    parsed = parse_json(raw) or {}
+    return {
+        "transcript": parsed.get("transcript", ""),
+        "claims": parsed.get("claims", []) or [],
+        "global_notes": parsed.get("global_notes", ""),
+    }
+
+
+# ===========================================================================
+# Node 2: Scorer — sees ONLY the extracted claims, not the image
+# ===========================================================================
+def scorer_node(state: GradingState) -> dict:
+    user = prompts.SCORER_USER.format(
+        question=state["question"],
+        max_marks=state["max_marks"],
+        criteria_block=prompts.format_criteria(state["criteria"]),
+        claims_block=prompts.format_claims(state.get("claims", [])),
+        critic_feedback=state.get("critic_feedback") or "(none — this is the first attempt)",
+    )
+    raw = _invoke_text(prompts.SCORER_SYSTEM, user)
+    parsed = parse_json(raw) or {}
+    per_criterion = parsed.get("per_criterion", []) or []
+    # Defensive: clamp awarded values inside [0, max]
+    for pc in per_criterion:
+        try:
+            pc["awarded"] = max(0.0, min(float(pc.get("awarded", 0)), float(pc.get("max", 0))))
+            pc["max"] = float(pc.get("max", 0))
+        except (TypeError, ValueError):
+            pc["awarded"] = 0.0
+    total = sum(pc.get("awarded", 0) for pc in per_criterion)
+    return {
+        "per_criterion": per_criterion,
+        "score": total,
+        "max_score": float(parsed.get("max_score") or state["max_marks"]),
+    }
+
+
+# ===========================================================================
+# Node 3: Justifier — writes the natural-language explanation for TAs
+# ===========================================================================
+def justifier_node(state: GradingState) -> dict:
+    user = prompts.JUSTIFIER_USER.format(
+        question=state["question"],
+        claims_block=prompts.format_claims(state.get("claims", [])),
+        scoring_block=prompts.format_scoring(state.get("per_criterion", [])),
+    )
+    raw = _invoke_text(prompts.JUSTIFIER_SYSTEM, user)
+    parsed = parse_json(raw) or {}
+    return {
+        "justification": parsed.get("justification", "(no justification generated)"),
+        "flags": parsed.get("flags", []) or [],
+    }
+
+
+# ===========================================================================
+# Node 4: Critic — audits whether awarded points are claim-supported
+# ===========================================================================
+def critic_node(state: GradingState) -> dict:
+    user = prompts.CRITIC_USER.format(
+        question=state["question"],
+        claims_block=prompts.format_claims(state.get("claims", [])),
+        scoring_block=prompts.format_scoring(state.get("per_criterion", [])),
+        justification=state.get("justification", ""),
+    )
+    raw = _invoke_text(prompts.CRITIC_SYSTEM, user)
+    parsed = parse_json(raw) or {}
+    passed = bool(parsed.get("passed", True))
+    feedback = parsed.get("feedback", "") if not passed else ""
+    return {
+        "critic_passed": passed,
+        "critic_feedback": feedback,
+        "retry_count": state.get("retry_count", 0) + (0 if passed else 1),
+    }
+
+
+# ===========================================================================
+# Conditional router — decides whether to retry the Scorer
+# ===========================================================================
+def critic_router(state: GradingState) -> str:
+    """Return the name of the next node to run, or '__end__' to finish."""
+    from langgraph.graph import END
+
+    if state.get("critic_passed", True):
+        return END
+    if state.get("retry_count", 0) > settings.grader_critic_retry:
+        # Bail out after configured retries so we never loop forever
+        return END
+    return "scorer"

backend/grader/prompts.py

@@ -0,0 +1,168 @@
+"""All prompts used by the agentic grader.
+
+Per Vanhoyweghen et al. (2026), the prompts are THE most iterated artifact in
+the pipeline. They are kept here, separate from logic, so a non-engineer can
+tune them. Every change should bump PROMPT_VERSION in config so audit trails
+stay honest.
+"""
+
+# ---- Course-level anti-hallucination guard (used by every node) ------------
+COURSE_GUARD = """Base all scoring strictly on evidence visible in the student's handwritten work. If evidence is missing, assign zero — do not guess, infer, or hallucinate.
+Award credit for intermediate steps only if they are explicitly written by the student. Do not infer non-trivial reasoning from a correct final answer except for trivial algebraic simplifications.
+Be aware of nonsensical segments; apply partial credit only to valid, supported steps. Do not award credit for reasoning that would not imply the subsequent result.
+If the student's solution does not match the question being asked, assign a score of 0."""
+
+
+# ---- Node 1: Extractor -----------------------------------------------------
+# Forces the model to enumerate what it *sees* before any scoring decision.
+# This is the structural defense against over-optimism (Paper 2's main failure mode).
+EXTRACTOR_SYSTEM = """You are the EXTRACTOR node of a handwriting-grading pipeline. Your only job is to look at the image and produce a faithful, literal transcription of what the student wrote, broken into atomic steps.
+
+{course_guard}
+
+You do not score. You do not judge. You only describe.
+You output strict JSON only — no markdown, no commentary outside the JSON.""".format(course_guard=COURSE_GUARD)
+
+
+EXTRACTOR_USER = """Question on the exam: {question}
+
+The image below is one student's handwritten answer to the above question.
+
+Your job:
+1. Read the handwriting literally. Do not correct mistakes.
+2. Break what the student wrote into a list of atomic claim-steps, in order.
+3. Note anything illegible, crossed out, or written outside the answer area.
+
+Return EXACTLY this JSON schema and nothing else:
+{{
+  "transcript": "<full literal transcription, line by line>",
+  "claims": [
+    {{"step": 1, "content": "<what the student wrote at this step, verbatim>", "concern": "<empty string, or one of: illegible, crossed_out, off_topic, partial>"}}
+  ],
+  "global_notes": "<any observations about layout, attempts, or non-mathematical content>"
+}}"""
+
+
+# ---- Node 2: Scorer --------------------------------------------------------
+# Takes ONLY the extracted claims (text), not the image. This is deliberate:
+# the scorer is forced to score what was extracted, not what it imagines.
+SCORER_SYSTEM = """You are the SCORER node of a handwriting-grading pipeline. You receive a list of claims that the student wrote (already extracted by another node). You map each claim to the grading criteria and assign points.
+
+{course_guard}
+
+Important: you score ONLY what is in the claims list. If a criterion's required content is not present in any claim, that criterion gets ZERO points. Do not award sympathy points. Do not invent intermediate steps.
+
+You output strict JSON only — no markdown, no commentary outside the JSON.""".format(course_guard=COURSE_GUARD)
+
+
+SCORER_USER = """Question: {question}
+Maximum marks: {max_marks}
+
+GRADING CRITERIA:
+{criteria_block}
+
+PREVIOUS CRITIC FEEDBACK (apply this if non-empty):
+{critic_feedback}
+
+STUDENT'S CLAIMS (extracted from their handwriting):
+{claims_block}
+
+For each criterion, decide how many points are supported by the claims. Be strict.
+
+Return EXACTLY this JSON schema:
+{{
+  "per_criterion": [
+    {{"name": "<criterion name>", "awarded": <number, 0..max>, "max": <max for this criterion>, "reasoning": "<one short sentence citing claim numbers, e.g. 'claims 2 and 3 show F(x) correctly'>"}}
+  ],
+  "score": <sum of all awarded>,
+  "max_score": <sum of all max>
+}}"""
+
+
+# ---- Node 3: Justifier -----------------------------------------------------
+# Writes a TA-facing natural-language explanation. This is what shows up in the
+# review dashboard. It must be useful to a busy TA — concise, evidence-cited.
+JUSTIFIER_SYSTEM = """You are the JUSTIFIER node. Given the student's claims and the criterion-by-criterion scoring, write a short, TA-facing explanation of the grade. Cite specific claim numbers where you can. Do not introduce new judgments.
+
+You output strict JSON only.""".format()
+
+
+JUSTIFIER_USER = """Question: {question}
+
+CLAIMS:
+{claims_block}
+
+PER-CRITERION SCORES:
+{scoring_block}
+
+Write a 2-3 sentence justification a teaching assistant can read in 5 seconds. Cite claim numbers. Be neutral.
+
+Return EXACTLY:
+{{
+  "justification": "<2-3 sentences>",
+  "flags": ["<zero or more of: hallucination_risk, illegible, off_topic, ambiguous_evidence, partial_solution_only, blank>"]
+}}"""
+
+
+# ---- Node 4: Critic --------------------------------------------------------
+# Reads the (claims, scores, justification) tuple and decides whether to retry.
+# The Critic checks: does the scoring actually follow from the claims? This is
+# the structural guard against the model "fixing" the student's answer.
+CRITIC_SYSTEM = """You are the CRITIC node. Your job is to audit the scoring for one specific failure mode: did the SCORER award points for criteria that are NOT actually supported by the EXTRACTED CLAIMS?
+
+You do NOT re-grade. You only check internal consistency: every awarded point must be traceable to a specific claim. If you find awarded points with no supporting claim, you fail the check and request a retry with specific feedback.
+
+You output strict JSON only.""".format()
+
+
+CRITIC_USER = """Question: {question}
+
+CLAIMS:
+{claims_block}
+
+PER-CRITERION SCORES (from the SCORER):
+{scoring_block}
+
+JUSTIFICATION (from the JUSTIFIER):
+{justification}
+
+Check each criterion. For each one with awarded > 0, is there a claim that actually supports it? Or did the scorer reward something not present in the claims?
+
+Return EXACTLY:
+{{
+  "passed": <true if all awarded points are supported by claims, false otherwise>,
+  "feedback": "<empty string if passed; otherwise concrete instructions to the scorer about which criteria are over-credited and why>"
+}}"""
+
+
+def format_criteria(criteria: list[dict]) -> str:
+    """Render a criteria list into the indented block used by the prompts."""
+    lines = []
+    for i, c in enumerate(criteria, 1):
+        lines.append(f"Criterion {i}: {c['name']} ({c['points']} pts)")
+        lines.append(f"  Conditions: {c.get('conditions') or '(none)'}")
+        if c.get("accept_alternatives"):
+            lines.append(f"  Accept also: {c['accept_alternatives']}")
+        if c.get("do_not_deduct_for"):
+            lines.append(f"  Do not deduct for: {c['do_not_deduct_for']}")
+        lines.append("")
+    return "\n".join(lines).rstrip()
+
+
+def format_claims(claims: list[dict]) -> str:
+    if not claims:
+        return "(no claims extracted)"
+    out = []
+    for c in claims:
+        line = f"Claim {c['step']}: {c['content']}"
+        if c.get("concern"):
+            line += f"   [concern: {c['concern']}]"
+        out.append(line)
+    return "\n".join(out)
+
+
+def format_scoring(per_criterion: list[dict]) -> str:
+    return "\n".join(
+        f"- {pc['name']}: {pc['awarded']}/{pc['max']} — {pc['reasoning']}"
+        for pc in per_criterion
+    )

backend/grader/rate_limit.py

@@ -0,0 +1,35 @@
+"""Process-wide rate limiter for all LLM calls.
+
+Every call to the Gemini/Claude API — from the agentic grader nodes AND
+from the OCR transcriber — passes through `wait_turn()`. We enforce a
+minimum gap between calls (default 4.5s, configurable via .env), which
+keeps us comfortably under the Gemini free-tier 15 RPM cap even when
+several uploads land back-to-back.
+
+This is deliberately a hard, global throttle rather than per-thread:
+running 5 parallel grading passes would otherwise blow the per-minute
+budget within a second.
+"""
+from __future__ import annotations
+
+import threading
+import time
+
+from ..config import settings
+
+
+_lock = threading.Lock()
+_last_call_ts: float = 0.0
+
+
+def wait_turn() -> None:
+    """Block until the configured minimum gap has elapsed since the last call."""
+    global _last_call_ts
+    gap = float(settings.llm_min_gap_seconds or 0.0)
+    if gap <= 0:
+        return
+    with _lock:
+        elapsed = time.monotonic() - _last_call_ts
+        if elapsed < gap:
+            time.sleep(gap - elapsed)
+        _last_call_ts = time.monotonic()

backend/grader/state.py

@@ -0,0 +1,35 @@
+"""Shared state that flows through the Langgraph nodes."""
+from __future__ import annotations
+
+from typing import TypedDict, Optional
+
+
+class GradingState(TypedDict, total=False):
+    # Inputs (set at graph entry)
+    image_b64: str
+    media_type: str
+    question: str
+    max_marks: float
+    criteria: list[dict]
+
+    # Set by Extractor
+    transcript: str
+    claims: list[dict]
+    global_notes: str
+
+    # Set by Scorer (may be overwritten on retry)
+    per_criterion: list[dict]
+    score: float
+    max_score: float
+
+    # Set by Justifier
+    justification: str
+    flags: list[str]
+
+    # Set by Critic
+    critic_passed: bool
+    critic_feedback: str
+
+    # Bookkeeping
+    retry_count: int
+    errors: list[str]

backend/ingestion/__init__.py

@@ -0,0 +1,3 @@
+from .pdf_split import split_pdf_to_pages  # noqa: F401
+from .crop import detect_answer_regions, crop_region  # noqa: F401
+from .anonymize import anonymize_crop  # noqa: F401

backend/ingestion/anonymize.py

@@ -0,0 +1,43 @@
+"""Anonymize a crop by masking regions that may contain student identifiers.
+
+Per Paper 2's privacy design, identifier regions are erased from the crop
+BEFORE the image is sent to any external API. Two modes:
+
+  - 'top_strip' (default): paints over the top 8% of the image, where
+    name/ID bubbles typically appear on the GRADEOPS template.
+  - 'none': pass-through (use when you know the crop is already free of
+    identifiers — e.g. the crop was already taken from below the ID area).
+
+In production the anonymizer should read bbox coordinates from the rubric
+metadata so it knows exactly which sub-regions contain identifiers.
+"""
+from __future__ import annotations
+
+import uuid
+from pathlib import Path
+
+from PIL import Image, ImageDraw
+
+
+def anonymize_crop(crop_path: str, output_dir: str, mode: str = "top_strip") -> str:
+    """Anonymize a crop and write the result. Returns the new path."""
+    output_dir = Path(output_dir)
+    output_dir.mkdir(parents=True, exist_ok=True)
+
+    img = Image.open(crop_path).convert("RGB")
+    if mode == "none":
+        out = output_dir / f"anon_{uuid.uuid4().hex[:10]}.png"
+        img.save(str(out), format="PNG")
+        return str(out)
+
+    w, h = img.size
+    strip_h = int(h * 0.08)
+    draw = ImageDraw.Draw(img)
+    # Paint white over the top strip to remove any ID/name region
+    draw.rectangle([0, 0, w, strip_h], fill="white")
+    # Add a thin grey line as a visual marker that anonymization happened
+    draw.line([0, strip_h, w, strip_h], fill=(200, 200, 200), width=2)
+
+    out = output_dir / f"anon_{uuid.uuid4().hex[:10]}.png"
+    img.save(str(out), format="PNG")
+    return str(out)

backend/ingestion/crop.py

@@ -0,0 +1,120 @@
+"""Detect and crop answer regions from a page image.
+
+Two modes:
+  - Template-marker mode: looks for fiducial markers (filled black squares)
+    at the corners of the answer sheet, then crops the rectangle they bound.
+    This is the production path, matching the Vanhoyweghen et al. (2026)
+    sheet layout (Figure 7 in that paper).
+  - Fallback mode: if no markers are found, treat the whole page as one
+    answer region. Useful for ad-hoc demos and for scans of arbitrary
+    exam papers that don't follow the GRADEOPS template.
+
+For a fully production setup, the question-to-crop binding (Q1 vs Q2a) is
+determined by detecting labeled regions inside the marker rectangle. Here
+we expose a simple `detect_answer_regions` that returns one box per page
+(the fallback), but the structure supports multi-region pages.
+"""
+from __future__ import annotations
+
+import uuid
+from pathlib import Path
+
+import cv2
+import numpy as np
+from PIL import Image
+
+
+def _find_corner_markers(gray: np.ndarray) -> list[tuple[int, int]] | None:
+    """Locate the four corner fiducial markers (filled black squares).
+
+    Returns four (x, y) centroids or None if fewer than 4 are found.
+    """
+    # Threshold to isolate dark regions
+    _, bw = cv2.threshold(gray, 60, 255, cv2.THRESH_BINARY_INV)
+    contours, _ = cv2.findContours(bw, cv2.RETR_EXTERNAL, cv2.CHAIN_APPROX_SIMPLE)
+
+    h, w = gray.shape
+    img_area = h * w
+    candidates: list[tuple[int, int, int]] = []  # (x, y, area)
+
+    for c in contours:
+        x, y, cw, ch = cv2.boundingRect(c)
+        area = cw * ch
+        # Marker heuristics: ~square, small fraction of page, dark fill
+        if area < img_area * 0.0001 or area > img_area * 0.01:
+            continue
+        ratio = cw / max(ch, 1)
+        if not 0.7 < ratio < 1.4:
+            continue
+        # Mostly-filled black?
+        roi = bw[y:y + ch, x:x + cw]
+        fill = roi.mean() / 255.0
+        if fill < 0.6:
+            continue
+        candidates.append((x + cw // 2, y + ch // 2, area))
+
+    if len(candidates) < 4:
+        return None
+
+    # Pick the candidates closest to the four corners of the page.
+    corners = [(0, 0), (w, 0), (0, h), (w, h)]
+    chosen: list[tuple[int, int]] = []
+    used = set()
+    for cx, cy in corners:
+        best = None
+        best_d = float("inf")
+        for i, (x, y, _) in enumerate(candidates):
+            if i in used:
+                continue
+            d = (x - cx) ** 2 + (y - cy) ** 2
+            if d < best_d:
+                best_d = d
+                best = (i, x, y)
+        if best is None:
+            return None
+        used.add(best[0])
+        chosen.append((best[1], best[2]))
+    return chosen  # [TL, TR, BL, BR]
+
+
+def detect_answer_regions(page_image_path: str) -> list[dict]:
+    """Return a list of {bbox, question_id} for each detected answer region.
+
+    Falls back to a single full-page region if markers are absent.
+    """
+    img = cv2.imread(page_image_path, cv2.IMREAD_GRAYSCALE)
+    if img is None:
+        raise ValueError(f"Could not read image: {page_image_path}")
+    h, w = img.shape
+
+    markers = _find_corner_markers(img)
+    if markers is not None:
+        xs = [m[0] for m in markers]
+        ys = [m[1] for m in markers]
+        x0, y0, x1, y1 = min(xs), min(ys), max(xs), max(ys)
+        # Pad inward 1% so the markers themselves aren't included
+        pad = int(min(w, h) * 0.01)
+        return [{
+            "bbox": {"x": x0 + pad, "y": y0 + pad,
+                     "w": (x1 - x0) - 2 * pad, "h": (y1 - y0) - 2 * pad},
+            "question_id": "Q1",
+        }]
+
+    # Fallback: whole page is one answer region
+    return [{
+        "bbox": {"x": 0, "y": 0, "w": w, "h": h},
+        "question_id": "Q1",
+    }]
+
+
+def crop_region(page_image_path: str, bbox: dict, output_dir: str) -> str:
+    """Crop the given bbox from the page image and save as PNG."""
+    output_dir = Path(output_dir)
+    output_dir.mkdir(parents=True, exist_ok=True)
+
+    img = Image.open(page_image_path)
+    x, y, w, h = bbox["x"], bbox["y"], bbox["w"], bbox["h"]
+    crop = img.crop((x, y, x + w, y + h))
+    out = output_dir / f"crop_{uuid.uuid4().hex[:10]}.png"
+    crop.save(str(out), format="PNG")
+    return str(out)

backend/ingestion/pdf_split.py

@@ -0,0 +1,39 @@
+"""Split a multi-page PDF into per-page PNG images.
+
+PyMuPDF handles all major PDF dialects including scanned exam papers.
+Pages are rasterized at 200 DPI by default — high enough for handwriting
+OCR, low enough to keep crops under a few hundred KB each.
+"""
+from __future__ import annotations
+
+import uuid
+from pathlib import Path
+
+import fitz  # PyMuPDF
+
+
+def split_pdf_to_pages(pdf_path: str, output_dir: str, dpi: int = 200) -> list[str]:
+    """Rasterize each page of a PDF and write to output_dir.
+
+    Returns a list of page image paths in page order.
+    """
+    pdf_path = Path(pdf_path)
+    output_dir = Path(output_dir)
+    output_dir.mkdir(parents=True, exist_ok=True)
+
+    doc = fitz.open(pdf_path)
+    paths: list[str] = []
+    zoom = dpi / 72.0  # PyMuPDF default is 72 DPI
+    matrix = fitz.Matrix(zoom, zoom)
+    prefix = uuid.uuid4().hex[:8]
+
+    try:
+        for page_idx in range(doc.page_count):
+            page = doc.load_page(page_idx)
+            pix = page.get_pixmap(matrix=matrix, alpha=False)
+            out = output_dir / f"{pdf_path.stem}_{prefix}_p{page_idx + 1:03d}.png"
+            pix.save(str(out))
+            paths.append(str(out))
+    finally:
+        doc.close()
+    return paths

backend/main.py

@@ -0,0 +1,490 @@
+"""FastAPI application: the API surface for the React frontend.
+
+Routes:
+  /users        bootstrap instructor + TA users for RBAC
+  /exams        CRUD exams
+  /rubrics      CRUD rubrics (immutable; updates create new versions)
+  /papers       upload PDFs, kick off the full pipeline
+  /crops        list crops + image bytes
+  /review       review queue (sorted by std-dev DESC) + decision endpoint
+  /audit        immutable audit log
+  /plagiarism   pair list above threshold
+  /stats        override-rate dashboard metrics
+  /debug/env    diagnostic — what env vars actually loaded
+  /health       liveness probe
+
+Pipeline (kicked off on POST /papers/upload):
+  PDF split → answer-region crop → anonymize →
+    OCR transcribe → agentic grader 5x in parallel →
+    aggregate → plagiarism worker over this exam
+"""
+from __future__ import annotations
+
+import os
+import shutil
+import uuid
+from pathlib import Path
+
+from fastapi import FastAPI, Depends, File, UploadFile, HTTPException, Form
+from fastapi.middleware.cors import CORSMiddleware
+from fastapi.responses import FileResponse
+from sqlalchemy.orm import Session
+from sqlalchemy import func
+
+from .config import settings, _ENV_FILE
+from .db import (
+    get_db, init_db, User, Exam, Rubric, Paper, Crop,
+    Grading, GradingAggregate, Review, PlagiarismFlag, AuditLog,
+)
+from . import schemas
+from .audit import log_event
+from .ingestion import split_pdf_to_pages, detect_answer_regions, crop_region, anonymize_crop
+from .ocr import transcribe as ocr_transcribe
+from .grader import grade_multi_pass, aggregate_scores
+from .plagiarism import find_similar_pairs
+
+
+app = FastAPI(title="GRADEOPS", version="0.1.0")
+
+# Open CORS for the React dev server (Vite defaults to 5173).
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=["*"],
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+
+@app.on_event("startup")
+def _startup():
+    init_db()
+    # Seed two default users so RBAC has something to point at.
+    from .db import SessionLocal
+    db = SessionLocal()
+    try:
+        if db.query(User).count() == 0:
+            db.add_all([
+                User(email="instructor@gradeops.local", name="Instructor", role="instructor"),
+                User(email="ta@gradeops.local", name="TA", role="ta"),
+            ])
+            db.commit()
+    finally:
+        db.close()
+
+
+# ---------------------------------------------------------------------------
+# Health + diagnostics
+# ---------------------------------------------------------------------------
+@app.get("/health")
+def health():
+    return {
+        "status": "ok",
+        "provider": settings.llm_provider,
+        "model": settings.grader_model,
+        "ocr_backend": settings.ocr_backend,
+    }
+
+
+@app.get("/debug/env")
+def debug_env():
+    """Diagnostic — shows exactly what the backend loaded.
+    Remove or restrict by role in production."""
+    def safe(val: str) -> dict:
+        return {"len": len(val or ""), "prefix": ((val or "")[:6] + "...") if val else "(empty)"}
+
+    return {
+        "cwd": os.getcwd(),
+        "project_root": str(_ENV_FILE.parent),
+        "env_file_path": str(_ENV_FILE),
+        "env_file_exists": _ENV_FILE.exists(),
+        "settings_llm_provider": settings.llm_provider,
+        "settings_google_api_key": safe(settings.google_api_key),
+        "settings_anthropic_api_key": safe(settings.anthropic_api_key),
+        "os_environ_GOOGLE_API_KEY": safe(os.environ.get("GOOGLE_API_KEY", "")),
+        "os_environ_ANTHROPIC_API_KEY": safe(os.environ.get("ANTHROPIC_API_KEY", "")),
+    }
+
+
+# ---------------------------------------------------------------------------
+# Users
+# ---------------------------------------------------------------------------
+@app.get("/users")
+def list_users(db: Session = Depends(get_db)):
+    return [{"id": u.id, "email": u.email, "name": u.name, "role": u.role}
+            for u in db.query(User).all()]
+
+
+# ---------------------------------------------------------------------------
+# Exams
+# ---------------------------------------------------------------------------
+@app.post("/exams", response_model=schemas.ExamOut)
+def create_exam(payload: schemas.ExamCreate, db: Session = Depends(get_db)):
+    e = Exam(title=payload.title)
+    db.add(e)
+    db.commit()
+    db.refresh(e)
+    return e
+
+
+@app.get("/exams", response_model=list[schemas.ExamOut])
+def list_exams(db: Session = Depends(get_db)):
+    return db.query(Exam).order_by(Exam.created_at.desc()).all()
+
+
+# ---------------------------------------------------------------------------
+# Rubrics (immutable, versioned per exam)
+# ---------------------------------------------------------------------------
+@app.post("/rubrics", response_model=schemas.RubricOut)
+def create_rubric(payload: schemas.RubricCreate, db: Session = Depends(get_db)):
+    exam = db.get(Exam, payload.exam_id)
+    if exam is None:
+        raise HTTPException(404, "exam not found")
+
+    existing = db.query(Rubric).filter(Rubric.exam_id == exam.id).count()
+    version = f"v{existing + 1}"
+
+    r = Rubric(
+        exam_id=exam.id,
+        version=version,
+        title=payload.title,
+        question_text=payload.question_text,
+        max_marks=payload.max_marks,
+        course_instructions=payload.course_instructions,
+        criteria=[c.model_dump() for c in payload.criteria],
+    )
+    db.add(r)
+    db.commit()
+    db.refresh(r)
+    log_event(db, "rubric", r.id, "create",
+              after={"version": version, "title": r.title},
+              rubric_version=version)
+    db.commit()
+    return _rubric_to_out(r)
+
+
+@app.get("/rubrics", response_model=list[schemas.RubricOut])
+def list_rubrics(exam_id: int | None = None, db: Session = Depends(get_db)):
+    q = db.query(Rubric)
+    if exam_id is not None:
+        q = q.filter(Rubric.exam_id == exam_id)
+    return [_rubric_to_out(r) for r in q.order_by(Rubric.created_at.desc()).all()]
+
+
+@app.get("/rubrics/{rubric_id}", response_model=schemas.RubricOut)
+def get_rubric(rubric_id: int, db: Session = Depends(get_db)):
+    r = db.get(Rubric, rubric_id)
+    if r is None:
+        raise HTTPException(404, "rubric not found")
+    return _rubric_to_out(r)
+
+
+def _rubric_to_out(r: Rubric) -> schemas.RubricOut:
+    return schemas.RubricOut(
+        id=r.id, exam_id=r.exam_id, version=r.version, title=r.title,
+        question_text=r.question_text, max_marks=r.max_marks,
+        course_instructions=r.course_instructions,
+        criteria=[schemas.Criterion(**c) for c in (r.criteria or [])],
+        created_at=r.created_at,
+    )
+
+
+# ---------------------------------------------------------------------------
+# Papers — upload + run pipeline
+# ---------------------------------------------------------------------------
+@app.post("/papers/upload")
+def upload_papers(
+    exam_id: int = Form(...),
+    rubric_id: int = Form(...),
+    file: UploadFile = File(...),
+    student_anon_id: str | None = Form(default=None),
+    db: Session = Depends(get_db),
+):
+    """Upload one PDF (or one image acting as a single-page PDF).
+
+    Runs the full pipeline synchronously and returns the resulting crop ids.
+    In production this should move to a background task; for the demo,
+    synchronous keeps the trace easy to follow.
+    """
+    exam = db.get(Exam, exam_id)
+    rubric = db.get(Rubric, rubric_id)
+    if exam is None or rubric is None:
+        raise HTTPException(404, "exam or rubric not found")
+
+    storage = settings.storage_path
+    anon_id = student_anon_id or f"STU-{uuid.uuid4().hex[:6].upper()}"
+
+    # 1. Save uploaded file
+    suffix = Path(file.filename or "upload.pdf").suffix.lower() or ".pdf"
+    upload_path = storage / "pdfs" / f"{anon_id}_{uuid.uuid4().hex[:8]}{suffix}"
+    with upload_path.open("wb") as f:
+        shutil.copyfileobj(file.file, f)
+
+    paper = Paper(exam_id=exam.id, student_anon_id=anon_id, source_pdf_path=str(upload_path))
+    db.add(paper)
+    db.commit()
+    db.refresh(paper)
+
+    # 2. Split into pages
+    if suffix == ".pdf":
+        page_paths = split_pdf_to_pages(str(upload_path), str(storage / "pages"))
+    else:
+        page_paths = [str(upload_path)]
+
+    crop_records: list[Crop] = []
+
+    for page_path in page_paths:
+        # 3. Detect answer regions (with whole-page fallback)
+        regions = detect_answer_regions(page_path)
+        for region in regions:
+            # 4. Crop + 5. Anonymize
+            raw_crop = crop_region(page_path, region["bbox"], str(storage / "crops"))
+            anon = anonymize_crop(raw_crop, str(storage / "crops"))
+
+            crop = Crop(
+                paper_id=paper.id,
+                question_id=region["question_id"],
+                rubric_id=rubric.id,
+                image_path=raw_crop,
+                anonymized_path=anon,
+                bbox=region["bbox"],
+            )
+            db.add(crop)
+            db.commit()
+            db.refresh(crop)
+
+            # 6. OCR transcribe (canonical transcript for plagiarism + search)
+            try:
+                transcript = ocr_transcribe(anon)
+            except Exception as e:
+                transcript = f"[OCR error: {e}]"
+
+            # 7. Run the agentic grader NUM_PASSES times in parallel
+            passes = grade_multi_pass(
+                anon,
+                question=rubric.question_text,
+                max_marks=rubric.max_marks,
+                criteria=rubric.criteria,
+            )
+
+            # 8. Persist gradings + aggregate
+            for i, p in enumerate(passes, 1):
+                g = Grading(
+                    crop_id=crop.id,
+                    rubric_id=rubric.id,
+                    pass_num=i,
+                    score=p["score"],
+                    max_score=p["max_score"],
+                    per_criterion=p["per_criterion"],
+                    justification=p["justification"],
+                    transcript=transcript,
+                    flags=p["flags"],
+                    critic_passed=p["critic_passed"],
+                    critic_feedback=p["critic_feedback"],
+                    model_version=settings.grader_model,
+                    prompt_version=settings.prompt_version,
+                )
+                db.add(g)
+
+            agg = aggregate_scores(passes)
+            db.add(GradingAggregate(
+                crop_id=crop.id,
+                median=agg["median"],
+                max_score=agg["max_score"],
+                min_score=agg["min_score"],
+                std_dev=agg["std_dev"],
+                n_passes=agg["n_passes"],
+            ))
+            log_event(db, "grading", crop.id, "create",
+                      after={"median": agg["median"], "std_dev": agg["std_dev"]},
+                      rubric_version=rubric.version)
+            db.commit()
+            crop_records.append(crop)
+
+    # 9. Plagiarism worker across all crops in this exam
+    try:
+        _refresh_plagiarism(db, exam_id=exam.id)
+    except Exception as e:
+        print(f"[plagiarism] failed: {e}")
+
+    return {
+        "paper_id": paper.id,
+        "student_anon_id": anon_id,
+        "crop_ids": [c.id for c in crop_records],
+    }
+
+
+def _refresh_plagiarism(db: Session, exam_id: int) -> None:
+    """Recompute similarity pairs across all crops in this exam."""
+    rows = (
+        db.query(Crop.id, Grading.transcript)
+        .join(Grading, Grading.crop_id == Crop.id)
+        .join(Paper, Paper.id == Crop.paper_id)
+        .filter(Paper.exam_id == exam_id, Grading.pass_num == 1)
+        .all()
+    )
+    transcripts = [(cid, t) for cid, t in rows if t]
+    if len(transcripts) < 2:
+        return
+
+    pairs = find_similar_pairs(transcripts)
+    for a, b, s in pairs:
+        existing = db.query(PlagiarismFlag).filter_by(crop_a_id=a, crop_b_id=b).first()
+        if existing:
+            existing.similarity = s
+        else:
+            db.add(PlagiarismFlag(crop_a_id=a, crop_b_id=b, similarity=s))
+    db.commit()
+
+
+# ---------------------------------------------------------------------------
+# Crops + images
+# ---------------------------------------------------------------------------
+@app.get("/crops/{crop_id}/image")
+def get_crop_image(crop_id: int, db: Session = Depends(get_db)):
+    crop = db.get(Crop, crop_id)
+    if crop is None:
+        raise HTTPException(404, "crop not found")
+    path = crop.anonymized_path
+    if not Path(path).exists():
+        raise HTTPException(404, "image file missing")
+    return FileResponse(path)
+
+
+# ---------------------------------------------------------------------------
+# Review queue
+# ---------------------------------------------------------------------------
+@app.get("/review/queue", response_model=list[schemas.ReviewQueueItem])
+def review_queue(
+    exam_id: int | None = None,
+    only_pending: bool = True,
+    db: Session = Depends(get_db),
+):
+    """Return crops sorted by std-dev DESC (highest uncertainty first)."""
+    q = (
+        db.query(Crop, GradingAggregate, Paper, Rubric)
+        .join(GradingAggregate, GradingAggregate.crop_id == Crop.id)
+        .join(Paper, Paper.id == Crop.paper_id)
+        .join(Rubric, Rubric.id == Crop.rubric_id)
+    )
+    if exam_id is not None:
+        q = q.filter(Paper.exam_id == exam_id)
+
+    items: list[schemas.ReviewQueueItem] = []
+    for crop, agg, paper, rubric in q.order_by(GradingAggregate.std_dev.desc()).all():
+        latest_review = (
+            db.query(Review)
+            .filter(Review.crop_id == crop.id)
+            .order_by(Review.created_at.desc())
+            .first()
+        )
+        if only_pending and latest_review is not None:
+            continue
+
+        gradings = (
+            db.query(Grading)
+            .filter(Grading.crop_id == crop.id)
+            .order_by(Grading.pass_num.asc())
+            .all()
+        )
+
+        flagged = (
+            db.query(PlagiarismFlag)
+            .filter((PlagiarismFlag.crop_a_id == crop.id) | (PlagiarismFlag.crop_b_id == crop.id))
+            .first()
+            is not None
+        )
+
+        items.append(schemas.ReviewQueueItem(
+            crop_id=crop.id,
+            paper_id=paper.id,
+            student_anon_id=paper.student_anon_id,
+            question_id=crop.question_id,
+            rubric_id=rubric.id,
+            rubric_title=rubric.title,
+            image_path=f"/crops/{crop.id}/image",
+            aggregate=schemas.AggregateOut(
+                crop_id=crop.id,
+                median=agg.median,
+                max_score=agg.max_score,
+                min_score=agg.min_score,
+                std_dev=agg.std_dev,
+                n_passes=agg.n_passes,
+            ),
+            gradings=[schemas.GradingOut.model_validate(g) for g in gradings],
+            plagiarism_flagged=flagged,
+            reviewed=latest_review is not None,
+            final_score=latest_review.final_score if latest_review else None,
+        ))
+    return items
+
+
+@app.post("/reviews", response_model=schemas.ReviewOut)
+def submit_review(payload: schemas.ReviewCreate, db: Session = Depends(get_db)):
+    crop = db.get(Crop, payload.crop_id)
+    if crop is None:
+        raise HTTPException(404, "crop not found")
+
+    agg = db.get(GradingAggregate, payload.crop_id)
+    ai_score = agg.median if agg else 0.0
+    rubric = db.get(Rubric, crop.rubric_id)
+
+    r = Review(
+        crop_id=payload.crop_id,
+        reviewer_id=payload.reviewer_id,
+        action=payload.action,
+        ai_score=ai_score,
+        final_score=payload.final_score,
+        notes=payload.notes,
+    )
+    db.add(r)
+    db.commit()
+    db.refresh(r)
+
+    log_event(
+        db, "review", r.id, payload.action,
+        actor_id=payload.reviewer_id,
+        before={"ai_score": ai_score},
+        after={"final_score": payload.final_score, "notes": payload.notes},
+        rubric_version=rubric.version if rubric else None,
+    )
+    db.commit()
+    return r
+
+
+# ---------------------------------------------------------------------------
+# Audit + plagiarism views
+# ---------------------------------------------------------------------------
+@app.get("/audit", response_model=list[schemas.AuditEntry])
+def list_audit(limit: int = 200, db: Session = Depends(get_db)):
+    return db.query(AuditLog).order_by(AuditLog.created_at.desc()).limit(limit).all()
+
+
+@app.get("/plagiarism", response_model=list[schemas.PlagiarismPair])
+def list_plagiarism(db: Session = Depends(get_db)):
+    return db.query(PlagiarismFlag).order_by(PlagiarismFlag.similarity.desc()).all()
+
+
+# ---------------------------------------------------------------------------
+# Stats — surfaces the metrics dashboard
+# ---------------------------------------------------------------------------
+@app.get("/stats")
+def get_stats(db: Session = Depends(get_db)):
+    total_crops = db.query(Crop).count()
+    total_reviewed = db.query(Review).count()
+    overrides = db.query(Review).filter(Review.action == "override").count()
+    flags = db.query(Review).filter(Review.action == "flag").count()
+    mean_std = db.query(func.avg(GradingAggregate.std_dev)).scalar() or 0.0
+
+    override_rows = db.query(Review).filter(Review.action == "override").all()
+    deltas = [abs(r.final_score - r.ai_score) for r in override_rows]
+    mean_delta = sum(deltas) / len(deltas) if deltas else 0.0
+
+    return {
+        "total_crops": total_crops,
+        "total_reviewed": total_reviewed,
+        "override_rate": overrides / total_reviewed if total_reviewed else 0.0,
+        "flag_rate": flags / total_reviewed if total_reviewed else 0.0,
+        "mean_std_dev": float(mean_std),
+        "mean_override_delta": float(mean_delta),
+        "plagiarism_pairs": db.query(PlagiarismFlag).count(),
+    }

backend/ocr/__init__.py

@@ -0,0 +1 @@
+from .router import transcribe  # noqa: F401

backend/ocr/hosted_adapter.py

@@ -0,0 +1,45 @@
+"""Hosted vision-API OCR adapter — passes through the shared LLM factory.
+
+Uses whichever LLM is configured in settings.llm_provider (Gemini by
+default — free tier — or Claude). Runs on any laptop with no GPU.
+Throttled through the shared rate limiter so OCR calls cannot blow past
+the per-minute quota when followed by grading calls.
+"""
+from __future__ import annotations
+
+import base64
+from pathlib import Path
+
+from langchain_core.messages import HumanMessage
+
+from ..grader.llm import get_llm
+from ..grader.rate_limit import wait_turn
+
+
+TRANSCRIBE_PROMPT = (
+    "You are an OCR system specialized in handwritten student exam answers — "
+    "math equations, derivations, prose, diagrams.\n\n"
+    "Transcribe the handwritten content in the image LITERALLY. Do not correct "
+    "mistakes. Do not interpret intent. Preserve line breaks. Use LaTeX for "
+    "math expressions. Mark illegible segments as [illegible].\n\n"
+    "Output the transcript only — no preamble, no commentary, no markdown fences."
+)
+
+
+def transcribe(image_path: str) -> str:
+    """Transcribe handwritten content via the configured chat model."""
+    wait_turn()
+    img_bytes = Path(image_path).read_bytes()
+    img_b64 = base64.b64encode(img_bytes).decode("ascii")
+    suffix = Path(image_path).suffix.lower().lstrip(".")
+    media_type = "image/jpeg" if suffix in ("jpg", "jpeg") else f"image/{suffix or 'jpeg'}"
+    data_url = f"data:{media_type};base64,{img_b64}"
+
+    llm = get_llm()
+    msg = HumanMessage(content=[
+        {"type": "image_url", "image_url": {"url": data_url}},
+        {"type": "text", "text": TRANSCRIBE_PROMPT},
+    ])
+    response = llm.invoke([msg])
+    content = response.content
+    return content if isinstance(content, str) else str(content)

backend/ocr/qwen_vl_adapter.py

@@ -0,0 +1,75 @@
+"""Qwen2-VL adapter via HuggingFace transformers.
+
+This is the production-target adapter the brief asks for. It is intentionally
+behind a lazy import so the demo runs without GPU dependencies installed.
+
+To enable:
+  1. Uncomment transformers / torch / accelerate in requirements.txt
+  2. Install on a GPU host
+  3. Set OCR_BACKEND=qwen_vl in .env
+
+On a CPU-only machine the model will load extremely slowly. For Nougat
+(a math-specialised alternative), swap Qwen2-VL-7B for facebook/nougat-base
+and update the processor calls accordingly.
+"""
+from __future__ import annotations
+
+from pathlib import Path
+
+
+_model = None
+_processor = None
+
+
+def _load_model():
+    """Lazy load Qwen2-VL. Raises an informative error if HF deps aren't present."""
+    global _model, _processor
+    if _model is not None:
+        return _model, _processor
+
+    try:
+        import torch  # noqa: F401
+        from transformers import Qwen2VLForConditionalGeneration, AutoProcessor
+    except ImportError as e:
+        raise RuntimeError(
+            "Qwen-VL adapter requires `transformers` and `torch`. "
+            "Either install them (see requirements.txt comments) or set "
+            "OCR_BACKEND=hosted in your .env to use the hosted Claude vision adapter."
+        ) from e
+
+    model_id = "Qwen/Qwen2-VL-7B-Instruct"
+    _processor = AutoProcessor.from_pretrained(model_id)
+    _model = Qwen2VLForConditionalGeneration.from_pretrained(
+        model_id, torch_dtype="auto", device_map="auto"
+    )
+    return _model, _processor
+
+
+TRANSCRIBE_PROMPT = (
+    "You are an OCR system specialised in handwritten student exam answers, "
+    "including math, derivations and free text. Transcribe the handwritten "
+    "content in the image LITERALLY. Use LaTeX for math. Preserve line breaks. "
+    "Mark illegible segments as [illegible]. Output the transcript only."
+)
+
+
+def transcribe(image_path: str) -> str:
+    from PIL import Image
+
+    model, processor = _load_model()
+    image = Image.open(image_path).convert("RGB")
+
+    messages = [{
+        "role": "user",
+        "content": [
+            {"type": "image", "image": image},
+            {"type": "text", "text": TRANSCRIBE_PROMPT},
+        ],
+    }]
+    text_prompt = processor.apply_chat_template(messages, tokenize=False, add_generation_prompt=True)
+    inputs = processor(text=[text_prompt], images=[image], return_tensors="pt").to(model.device)
+
+    out_ids = model.generate(**inputs, max_new_tokens=1500)
+    out_trimmed = [o[len(i):] for i, o in zip(inputs.input_ids, out_ids)]
+    text = processor.batch_decode(out_trimmed, skip_special_tokens=True)[0]
+    return text.strip()

backend/ocr/router.py

@@ -0,0 +1,21 @@
+"""OCR router. Picks an adapter based on settings.ocr_backend.
+
+This is the abstraction layer mentioned in the architecture diagram: any
+new OCR model (Nougat, TrOCR, a fine-tuned model) plugs in by adding a new
+adapter and a new branch here. The grader and the rest of the pipeline
+don't change.
+"""
+from __future__ import annotations
+
+from ..config import settings
+
+
+def transcribe(image_path: str) -> str:
+    """Dispatch to the configured OCR adapter."""
+    backend = (settings.ocr_backend or "hosted").lower()
+    if backend == "qwen_vl":
+        from . import qwen_vl_adapter
+        return qwen_vl_adapter.transcribe(image_path)
+    # default
+    from . import hosted_adapter
+    return hosted_adapter.transcribe(image_path)

backend/plagiarism.py

@@ -0,0 +1,62 @@
+"""Plagiarism flagging via sentence-embedding similarity.
+
+The brief calls for flagging "highly similar logic structures across
+papers." We do this on the OCR transcripts (not the raw images) because:
+  - handwriting varies even when reasoning is copied, so image similarity
+    is the wrong signal
+  - transcripts capture the LOGIC the student used
+  - embedding similarity catches paraphrases that string matching misses
+
+This is a background worker. It is intentionally simple: O(n^2) cosine
+similarity, with a threshold check. For real exam scale (thousands of
+papers per exam) you would FAISS-index the embeddings.
+"""
+from __future__ import annotations
+
+from sentence_transformers import SentenceTransformer
+from sklearn.metrics.pairwise import cosine_similarity
+import numpy as np
+
+from .config import settings
+
+
+_model: SentenceTransformer | None = None
+
+
+def _get_model() -> SentenceTransformer:
+    global _model
+    if _model is None:
+        _model = SentenceTransformer(settings.embedding_model)
+    return _model
+
+
+def find_similar_pairs(
+    transcripts: list[tuple[int, str]],
+    threshold: float | None = None,
+) -> list[tuple[int, int, float]]:
+    """Return all (crop_a_id, crop_b_id, similarity) tuples above the threshold.
+
+    transcripts: list of (crop_id, transcript_text) tuples.
+    """
+    if len(transcripts) < 2:
+        return []
+
+    threshold = threshold if threshold is not None else settings.plagiarism_threshold
+    ids = [t[0] for t in transcripts]
+    texts = [t[1] or "" for t in transcripts]
+
+    model = _get_model()
+    embeddings = model.encode(texts, convert_to_numpy=True, show_progress_bar=False)
+
+    sim = cosine_similarity(embeddings)
+    pairs: list[tuple[int, int, float]] = []
+    n = len(ids)
+    for i in range(n):
+        for j in range(i + 1, n):
+            s = float(sim[i, j])
+            if s >= threshold:
+                # Always store with a < b for the uniqueness constraint
+                a, b = sorted((ids[i], ids[j]))
+                pairs.append((a, b, s))
+    pairs.sort(key=lambda p: p[2], reverse=True)
+    return pairs

backend/schemas.py

@@ -0,0 +1,164 @@
+"""Pydantic schemas — the contract between frontend, API, and grader.
+
+The Criterion / Rubric schemas implement the design principles from
+Vanhoyweghen et al. (2026): fine-grained criteria with explicit alternatives
+and explicit do-not-deduct conditions, so the LLM has no room to invent
+its own interpretation.
+"""
+from __future__ import annotations
+
+from typing import Any
+from datetime import datetime
+from pydantic import BaseModel, Field, ConfigDict
+
+
+# --- Rubric ----------------------------------------------------------------
+class Criterion(BaseModel):
+    name: str
+    points: float = Field(..., ge=0)
+    conditions: str = Field(..., description="What must be present in the answer to earn these points.")
+    accept_alternatives: str = Field("", description="Equivalent forms to also accept.")
+    do_not_deduct_for: str = Field("", description="Surface issues to ignore.")
+
+
+class RubricCreate(BaseModel):
+    exam_id: int
+    title: str
+    question_text: str
+    max_marks: float
+    course_instructions: str
+    criteria: list[Criterion]
+
+
+class RubricOut(BaseModel):
+    id: int
+    exam_id: int
+    version: str
+    title: str
+    question_text: str
+    max_marks: float
+    course_instructions: str
+    criteria: list[Criterion]
+    created_at: datetime
+    model_config = ConfigDict(from_attributes=True)
+
+
+# --- Exam ------------------------------------------------------------------
+class ExamCreate(BaseModel):
+    title: str
+
+
+class ExamOut(BaseModel):
+    id: int
+    title: str
+    created_at: datetime
+    model_config = ConfigDict(from_attributes=True)
+
+
+# --- Paper / Crop ----------------------------------------------------------
+class CropOut(BaseModel):
+    id: int
+    paper_id: int
+    question_id: str
+    rubric_id: int
+    image_path: str
+    anonymized_path: str
+    created_at: datetime
+    model_config = ConfigDict(from_attributes=True)
+
+
+# --- Grading ---------------------------------------------------------------
+class PerCriterionScore(BaseModel):
+    name: str
+    awarded: float
+    max: float
+    reasoning: str
+
+
+class GradingOut(BaseModel):
+    id: int
+    crop_id: int
+    pass_num: int
+    score: float
+    max_score: float
+    per_criterion: list[PerCriterionScore]
+    justification: str
+    transcript: str
+    flags: list[str]
+    critic_passed: bool
+    critic_feedback: str | None
+    model_version: str
+    prompt_version: str
+    created_at: datetime
+    model_config = ConfigDict(from_attributes=True)
+
+
+class AggregateOut(BaseModel):
+    crop_id: int
+    median: float
+    max_score: float
+    min_score: float
+    std_dev: float
+    n_passes: int
+    model_config = ConfigDict(from_attributes=True)
+
+
+# --- Review queue item -----------------------------------------------------
+class ReviewQueueItem(BaseModel):
+    """One row in the TA review dashboard."""
+    crop_id: int
+    paper_id: int
+    student_anon_id: str
+    question_id: str
+    rubric_id: int
+    rubric_title: str
+    image_path: str
+    aggregate: AggregateOut
+    gradings: list[GradingOut]
+    plagiarism_flagged: bool = False
+    reviewed: bool = False
+    final_score: float | None = None
+
+
+# --- Review action ---------------------------------------------------------
+class ReviewCreate(BaseModel):
+    crop_id: int
+    action: str  # 'approve' | 'override' | 'flag'
+    final_score: float
+    notes: str = ""
+    reviewer_id: int | None = None
+
+
+class ReviewOut(BaseModel):
+    id: int
+    crop_id: int
+    action: str
+    ai_score: float
+    final_score: float
+    notes: str | None
+    created_at: datetime
+    model_config = ConfigDict(from_attributes=True)
+
+
+# --- Plagiarism ------------------------------------------------------------
+class PlagiarismPair(BaseModel):
+    crop_a_id: int
+    crop_b_id: int
+    similarity: float
+    flagged_at: datetime
+    model_config = ConfigDict(from_attributes=True)
+
+
+# --- Audit log -------------------------------------------------------------
+class AuditEntry(BaseModel):
+    id: int
+    entity_type: str
+    entity_id: int
+    action: str
+    before: dict | None = None
+    after: dict | None = None
+    rubric_version: str | None = None
+    prompt_version: str | None = None
+    model_version: str | None = None
+    created_at: datetime
+    model_config = ConfigDict(from_attributes=True)

debug_llm.py

@@ -0,0 +1,95 @@
+"""Standalone diagnostic for the GRADEOPS LLM chain.
+
+Walks every link from OS env → .env file → pydantic settings →
+llm.get_llm() → an actual test API call. Prints exactly which step fails.
+
+Run from the gradeops/ folder:
+    python debug_llm.py
+"""
+import os
+import sys
+from pathlib import Path
+
+print("=" * 60)
+print("GRADEOPS LLM DIAGNOSTIC")
+print("=" * 60)
+
+# ---------- STEP 1: OS environment ----------
+print("\n[1] os.environ check")
+print("-" * 60)
+key_in_env = "GOOGLE_API_KEY" in os.environ
+print(f"  GOOGLE_API_KEY in os.environ : {key_in_env}")
+if key_in_env:
+    k = os.environ["GOOGLE_API_KEY"]
+    print(f"  length                       : {len(k)}")
+    print(f"  prefix                       : {k[:6]}")
+
+# ---------- STEP 2: .env file ----------
+print("\n[2] .env file check")
+print("-" * 60)
+env_file = Path(__file__).resolve().parent / ".env"
+print(f"  Looking at  : {env_file}")
+print(f"  Exists      : {env_file.exists()}")
+if env_file.exists():
+    try:
+        content = env_file.read_text(encoding="utf-8-sig")
+        for ln in content.splitlines():
+            ln = ln.strip()
+            if not ln or ln.startswith("#"):
+                continue
+            if "=" in ln:
+                k, _, v = ln.partition("=")
+                k = k.strip()
+                v = v.strip().strip('"').strip("'")
+                if "API_KEY" in k or k.upper() == "LLM_PROVIDER":
+                    shown = (v[:6] + "...") if v else "(empty)"
+                    print(f"    {k} = {shown}  (len {len(v)})")
+    except Exception as e:
+        print(f"  READ FAILED: {e}")
+
+# ---------- STEP 3: backend.config.settings ----------
+print("\n[3] backend.config.settings")
+print("-" * 60)
+try:
+    sys.path.insert(0, str(Path(__file__).resolve().parent))
+    from backend.config import settings
+    print(f"  settings.llm_provider              : {settings.llm_provider}")
+    gk = settings.google_api_key or ""
+    print(f"  settings.google_api_key length     : {len(gk)}")
+    print(f"  settings.google_api_key prefix     : {(gk[:6] + '...') if gk else '(empty)'}")
+    print(f"  settings.grader_model_google       : {settings.grader_model_google}")
+except Exception as e:
+    print(f"  IMPORT FAILED: {e}")
+    sys.exit(1)
+
+# ---------- STEP 4: llm.get_llm() ----------
+print("\n[4] backend.grader.llm.get_llm()")
+print("-" * 60)
+try:
+    from backend.grader.llm import get_llm
+    llm = get_llm()
+    print(f"  LLM loaded : {type(llm).__name__}")
+    print(f"  Model      : {getattr(llm, 'model', '?')}")
+except Exception as e:
+    print(f"  FAILED: {e}")
+    print("\n  → fix this before going further.")
+    sys.exit(2)
+
+# ---------- STEP 5: actual API call ----------
+print("\n[5] live API call (1 token, costs ~nothing)")
+print("-" * 60)
+try:
+    from langchain_core.messages import HumanMessage
+    resp = llm.invoke([HumanMessage(content="Reply with exactly the single word OK.")])
+    text = resp.content if hasattr(resp, "content") else str(resp)
+    print(f"  Response: {text!r}")
+    print("\n  ✓ EVERYTHING WORKS. The pipeline should grade correctly.")
+    print("  If the Review page still shows the old error, those crops are")
+    print("  pre-fix DB rows — upload a new paper to verify.")
+except Exception as e:
+    print(f"  FAILED: {type(e).__name__}: {e}")
+    print("\n  This is the actual API error. Common causes:")
+    print("    - Invalid key  → regenerate at https://aistudio.google.com/app/apikey")
+    print("    - Model name wrong → try gemini-1.5-flash or gemini-2.5-flash")
+    print("    - Region restriction on the key")
+    sys.exit(3)

docker-compose.yml

@@ -0,0 +1,23 @@
+version: "3.9"
+
+# Optional: Postgres for the brief's tech-stack alignment.
+# The app works with SQLite by default (DATABASE_URL=sqlite:///./gradeops.db).
+# To use Postgres:
+#   docker compose up -d db
+#   set DATABASE_URL=postgresql+psycopg2://gradeops:gradeops@localhost:5432/gradeops in .env
+#   python scripts/init_db.py
+
+services:
+  db:
+    image: postgres:16-alpine
+    environment:
+      POSTGRES_USER: gradeops
+      POSTGRES_PASSWORD: gradeops
+      POSTGRES_DB: gradeops
+    ports:
+      - "5432:5432"
+    volumes:
+      - gradeops_pgdata:/var/lib/postgresql/data
+
+volumes:
+  gradeops_pgdata:

frontend/index.html

@@ -0,0 +1,18 @@
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>GradeOps</title>
+    <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=Inter:wght@400;500;600;700&display=swap"
+      rel="stylesheet"
+    />
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.jsx"></script>
+  </body>
+</html>

frontend/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "gradeops-frontend",
+  "private": true,
+  "version": "0.1.0",
+  "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "build": "vite build",
+    "preview": "vite preview"
+  },
+  "dependencies": {
+    "axios": "^1.7.7",
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1",
+    "react-router-dom": "^6.26.2"
+  },
+  "devDependencies": {
+    "@vitejs/plugin-react": "^4.3.2",
+    "autoprefixer": "^10.4.20",
+    "postcss": "^8.4.47",
+    "tailwindcss": "^3.4.13",
+    "vite": "^5.4.8"
+  }
+}

frontend/postcss.config.js

@@ -0,0 +1,6 @@
+export default {
+  plugins: {
+    tailwindcss: {},
+    autoprefixer: {},
+  },
+}

frontend/src/App.jsx

@@ -0,0 +1,118 @@
+import React, { createContext, useEffect, useState } from 'react'
+import { Routes, Route, NavLink, Navigate } from 'react-router-dom'
+import { api } from './api'
+
+import Rubrics from './pages/Rubrics.jsx'
+import Grading from './pages/Grading.jsx'
+import Review from './pages/Review.jsx'
+import Audit from './pages/Audit.jsx'
+
+export const RoleContext = createContext({ role: 'instructor', user: null, users: [] })
+
+const NAV = [
+  { to: '/rubrics', label: 'Rubrics' },
+  { to: '/grading', label: 'Grading' },
+  { to: '/review',  label: 'Review'  },
+  { to: '/audit',   label: 'Audit'   },
+]
+
+export default function App() {
+  const [users, setUsers] = useState([])
+  const [user, setUser] = useState(null)
+  const [health, setHealth] = useState(null)
+
+  useEffect(() => {
+    api.users().then(us => { setUsers(us); setUser(us[0] || null) }).catch(() => {})
+    api.health().then(setHealth).catch(() => setHealth({ status: 'error' }))
+  }, [])
+
+  return (
+    <RoleContext.Provider value={{ role: user?.role || 'instructor', user, users }}>
+      <div className="min-h-full flex flex-col bg-background">
+        <Header user={user} users={users} setUser={setUser} health={health} />
+
+        <main className="flex-1 max-w-[1400px] w-full mx-auto px-8 py-8">
+          <Routes>
+            <Route path="/" element={<Navigate to="/rubrics" replace />} />
+            <Route path="/rubrics" element={<Rubrics />} />
+            <Route path="/grading" element={<Grading />} />
+            <Route path="/review" element={<Review />} />
+            <Route path="/audit" element={<Audit />} />
+          </Routes>
+        </main>
+
+        <footer className="border-t border-border bg-surface">
+          <div className="max-w-[1400px] mx-auto px-8 py-3 flex justify-between text-label-sm text-ink-subtle">
+            <span>GradeOps</span>
+            <span>v0.1.0</span>
+          </div>
+        </footer>
+      </div>
+    </RoleContext.Provider>
+  )
+}
+
+function Header({ user, users, setUser, health }) {
+  return (
+    <header className="bg-surface border-b border-border sticky top-0 z-30">
+      <div className="max-w-[1400px] mx-auto px-8 h-14 flex items-center justify-between gap-6">
+        <div className="flex items-center gap-8">
+          <Wordmark />
+          <nav className="flex items-center gap-1">
+            {NAV.map(item => (
+              <NavLink
+                key={item.to}
+                to={item.to}
+                className={({ isActive }) =>
+                  `relative h-9 px-3 inline-flex items-center text-label-md rounded transition-colors ${
+                    isActive
+                      ? 'text-brand bg-brand-subtle'
+                      : 'text-ink-muted hover:text-ink hover:bg-surface-muted'
+                  }`
+                }
+              >
+                {item.label}
+              </NavLink>
+            ))}
+          </nav>
+        </div>
+
+        <div className="flex items-center gap-4">
+         {health && (
+  <div className="hidden md:flex items-center gap-1.5 text-label-sm text-ink-subtle">
+    <span className={`h-1.5 w-1.5 rounded-full ${health.status === 'ok' ? 'bg-success' : 'bg-danger'}`} />
+    <span>{health.status === 'ok' ? 'Connected' : 'Disconnected'}</span>
+  </div>
+)}
+          {users.length > 0 && (
+            <select
+              value={user?.id || ''}
+              onChange={(e) => setUser(users.find(u => String(u.id) === e.target.value))}
+              className="h-8 px-2.5 pr-7 text-label-md text-ink bg-surface border border-border rounded
+                         focus:outline-none focus:ring-2 focus:ring-brand/30 focus:border-brand"
+            >
+              {users.map(u => (
+                <option key={u.id} value={u.id}>
+                  {u.role === 'instructor' ? 'Instructor' : 'TA'} · {u.name}
+                </option>
+              ))}
+            </select>
+          )}
+        </div>
+      </div>
+    </header>
+  )
+}
+
+function Wordmark() {
+  return (
+    <div className="flex items-center gap-2.5">
+      <div className="h-7 w-7 rounded bg-brand flex items-center justify-center">
+        <svg width="14" height="14" viewBox="0 0 14 14" fill="none">
+          <path d="M3 7L6 10L11 4" stroke="white" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round"/>
+        </svg>
+      </div>
+      <span className="text-headline-sm tracking-tight text-ink">GradeOps</span>
+    </div>
+  )
+}

frontend/src/api.js

@@ -0,0 +1,43 @@
+import axios from 'axios'
+
+const client = axios.create({
+  baseURL: '/api',
+  timeout: 600_000, // 10 min — grading is slow on first run
+})
+
+export const api = {
+  health: () => client.get('/health').then(r => r.data),
+  users:  () => client.get('/users').then(r => r.data),
+
+  // Exams
+  createExam: (payload) => client.post('/exams', payload).then(r => r.data),
+  listExams:  () => client.get('/exams').then(r => r.data),
+
+  // Rubrics
+  createRubric: (payload) => client.post('/rubrics', payload).then(r => r.data),
+  listRubrics:  (examId) => client.get('/rubrics', { params: examId ? { exam_id: examId } : {} }).then(r => r.data),
+
+  // Papers / upload
+  uploadPaper: (examId, rubricId, file, anonId) => {
+    const fd = new FormData()
+    fd.append('exam_id', examId)
+    fd.append('rubric_id', rubricId)
+    if (anonId) fd.append('student_anon_id', anonId)
+    fd.append('file', file)
+    return client.post('/papers/upload', fd, {
+      headers: { 'Content-Type': 'multipart/form-data' },
+    }).then(r => r.data)
+  },
+
+  // Review queue
+  reviewQueue: (examId) => client.get('/review/queue', { params: examId ? { exam_id: examId } : {} }).then(r => r.data),
+  submitReview: (payload) => client.post('/reviews', payload).then(r => r.data),
+
+  // Audit + stats
+  audit: () => client.get('/audit').then(r => r.data),
+  plagiarism: () => client.get('/plagiarism').then(r => r.data),
+  stats: () => client.get('/stats').then(r => r.data),
+
+  // Crop image URL
+  cropImageUrl: (cropId) => `/api/crops/${cropId}/image`,
+}

frontend/src/components/ui.jsx

@@ -0,0 +1,203 @@
+import React, { forwardRef } from 'react'
+
+// ===========================================================================
+// Button
+// ===========================================================================
+export const Button = forwardRef(function Button(
+  { variant = 'secondary', size = 'md', className = '', children, disabled, ...rest }, ref
+) {
+  const base =
+    'inline-flex items-center justify-center gap-1.5 font-medium rounded transition-colors duration-150 ease-standard ' +
+    'focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-brand/30 ' +
+    'disabled:opacity-40 disabled:cursor-not-allowed select-none whitespace-nowrap'
+  const variants = {
+    primary:   'bg-brand text-brand-fg hover:bg-brand-hover',
+    secondary: 'bg-surface text-ink border border-border hover:bg-surface-subtle',
+    ghost:     'text-ink-muted hover:bg-surface-muted hover:text-ink',
+    danger:    'bg-surface text-danger border border-border hover:bg-danger-subtle hover:border-danger/30',
+    success:   'bg-success text-white hover:bg-success-strong',
+    link:      'text-brand hover:text-brand-hover underline-offset-2 hover:underline',
+  }
+  const sizes = {
+    sm: 'h-7 px-2.5 text-label-sm',
+    md: 'h-9 px-3.5 text-label-md',
+    lg: 'h-11 px-5 text-label-md',
+    icon: 'h-9 w-9 text-label-md',
+  }
+  return (
+    <button
+      ref={ref}
+      disabled={disabled}
+      className={`${base} ${variants[variant]} ${sizes[size]} ${className}`}
+      {...rest}
+    >
+      {children}
+    </button>
+  )
+})
+
+// ===========================================================================
+// Card / Surface
+// ===========================================================================
+export function Card({ className = '', children, ...rest }) {
+  return (
+    <div
+      className={`bg-surface border border-border rounded-lg shadow-card ${className}`}
+      {...rest}
+    >
+      {children}
+    </div>
+  )
+}
+
+export function CardHeader({ title, description, action, className = '' }) {
+  return (
+    <div className={`flex items-start justify-between gap-4 px-5 py-4 border-b border-border ${className}`}>
+      <div>
+        <h3 className="text-headline-sm text-ink">{title}</h3>
+        {description && <p className="mt-0.5 text-body-sm text-ink-muted">{description}</p>}
+      </div>
+      {action}
+    </div>
+  )
+}
+
+export function CardBody({ className = '', children }) {
+  return <div className={`px-5 py-4 ${className}`}>{children}</div>
+}
+
+// ===========================================================================
+// Input + TextArea
+// ===========================================================================
+export const Input = forwardRef(function Input({ className = '', invalid, ...rest }, ref) {
+  return (
+    <input
+      ref={ref}
+      className={`block w-full h-9 px-3 text-body-sm text-ink bg-surface border rounded transition-colors duration-150 placeholder:text-ink-faint
+        ${invalid ? 'border-danger focus-visible:ring-danger/20 focus-visible:border-danger' : 'border-border focus-visible:ring-brand/30 focus-visible:border-brand'}
+        focus-visible:outline-none focus-visible:ring-2 ${className}`}
+      {...rest}
+    />
+  )
+})
+
+export const TextArea = forwardRef(function TextArea({ className = '', rows = 3, invalid, ...rest }, ref) {
+  return (
+    <textarea
+      ref={ref}
+      rows={rows}
+      className={`block w-full px-3 py-2 text-body-sm text-ink bg-surface border rounded transition-colors duration-150 resize-y placeholder:text-ink-faint
+        ${invalid ? 'border-danger focus-visible:ring-danger/20 focus-visible:border-danger' : 'border-border focus-visible:ring-brand/30 focus-visible:border-brand'}
+        focus-visible:outline-none focus-visible:ring-2 ${className}`}
+      {...rest}
+    />
+  )
+})
+
+export function Select({ className = '', children, ...rest }) {
+  return (
+    <select
+      className={`block w-full h-9 px-3 text-body-sm text-ink bg-surface border border-border rounded transition-colors duration-150
+        focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-brand/30 focus-visible:border-brand ${className}`}
+      {...rest}
+    >
+      {children}
+    </select>
+  )
+}
+
+// ===========================================================================
+// Field — label + control + hint pattern
+// ===========================================================================
+export function Field({ label, hint, error, required, children, className = '' }) {
+  return (
+    <label className={`block ${className}`}>
+      {label && (
+        <div className="mb-1.5 flex items-baseline gap-1">
+          <span className="text-label-sm uppercase tracking-wide text-ink-muted">{label}</span>
+          {required && <span className="text-danger text-label-sm">*</span>}
+        </div>
+      )}
+      {children}
+      {error
+        ? <p className="mt-1 text-label-sm text-danger">{error}</p>
+        : hint && <p className="mt-1 text-label-sm text-ink-subtle">{hint}</p>}
+    </label>
+  )
+}
+
+// ===========================================================================
+// Badge / Pill
+// ===========================================================================
+export function Badge({ variant = 'neutral', children, className = '' }) {
+  const variants = {
+    neutral: 'bg-surface-muted text-ink-muted border-border',
+    brand:   'bg-brand-subtle text-brand border-brand/15',
+    success: 'bg-success-subtle text-success-strong border-success/15',
+    warning: 'bg-warning-subtle text-warning-strong border-warning/15',
+    danger:  'bg-danger-subtle text-danger-strong border-danger/15',
+    info:    'bg-info-subtle text-info-strong border-info/15',
+  }
+  return (
+    <span className={`inline-flex items-center gap-1 px-2 h-5 rounded-full border text-label-sm ${variants[variant]} ${className}`}>
+      {children}
+    </span>
+  )
+}
+
+// ===========================================================================
+// Stat — used in the audit metrics row
+// ===========================================================================
+export function Stat({ label, value, hint, accent }) {
+  return (
+    <Card>
+      <div className="px-5 py-4">
+        <div className="text-label-sm uppercase tracking-wide text-ink-muted">{label}</div>
+        <div className={`mt-1 text-headline-md ${accent || 'text-ink'}`}>{value}</div>
+        {hint && <div className="mt-0.5 text-label-sm text-ink-subtle">{hint}</div>}
+      </div>
+    </Card>
+  )
+}
+
+// ===========================================================================
+// Empty state
+// ===========================================================================
+export function EmptyState({ title, description, action, icon }) {
+  return (
+    <Card>
+      <div className="px-10 py-16 text-center">
+        {icon && <div className="mx-auto mb-3 h-10 w-10 text-ink-faint">{icon}</div>}
+        <p className="text-body-md text-ink font-medium">{title}</p>
+        {description && <p className="mt-1 text-body-sm text-ink-muted max-w-md mx-auto">{description}</p>}
+        {action && <div className="mt-5">{action}</div>}
+      </div>
+    </Card>
+  )
+}
+
+// ===========================================================================
+// PageHeader
+// ===========================================================================
+export function PageHeader({ title, description, actions }) {
+  return (
+    <div className="flex items-start justify-between gap-4 mb-6">
+      <div>
+        <h1 className="text-headline-lg text-ink">{title}</h1>
+        {description && <p className="mt-1 text-body-md text-ink-muted">{description}</p>}
+      </div>
+      {actions && <div className="flex items-center gap-2 shrink-0">{actions}</div>}
+    </div>
+  )
+}
+
+// ===========================================================================
+// Keyboard hint chip
+// ===========================================================================
+export function Kbd({ children }) {
+  return (
+    <kbd className="inline-flex items-center justify-center min-w-[20px] h-5 px-1.5 rounded border border-border-strong bg-surface-muted text-label-sm text-ink-muted font-medium">
+      {children}
+    </kbd>
+  )
+}

frontend/src/index.css

@@ -0,0 +1,28 @@
+@tailwind base;
+@tailwind components;
+@tailwind utilities;
+
+@layer base {
+  html, body, #root { height: 100%; }
+  html { -webkit-font-smoothing: antialiased; -moz-osx-font-smoothing: grayscale; }
+  body {
+    font-family: 'Inter', ui-sans-serif, system-ui, sans-serif;
+    background-color: #F9FAFB;
+    color: #111827;
+    font-feature-settings: 'cv11', 'ss01', 'ss03';
+  }
+  /* Make all native focus rings consistent with the design system */
+  *:focus { outline: none; }
+  ::selection { background: rgba(79, 70, 229, 0.18); color: #111827; }
+
+  /* Number inputs without spinner clutter */
+  input[type='number']::-webkit-inner-spin-button,
+  input[type='number']::-webkit-outer-spin-button { -webkit-appearance: none; margin: 0; }
+  input[type='number'] { -moz-appearance: textfield; }
+}
+
+@layer components {
+  .focus-ring {
+    @apply focus-visible:ring-2 focus-visible:ring-brand/30 focus-visible:border-brand;
+  }
+}

frontend/src/main.jsx

@@ -0,0 +1,13 @@
+import React from 'react'
+import ReactDOM from 'react-dom/client'
+import { BrowserRouter } from 'react-router-dom'
+import App from './App.jsx'
+import './index.css'
+
+ReactDOM.createRoot(document.getElementById('root')).render(
+  <React.StrictMode>
+    <BrowserRouter>
+      <App />
+    </BrowserRouter>
+  </React.StrictMode>
+)

frontend/src/pages/Audit.jsx

@@ -0,0 +1,149 @@
+import React, { useEffect, useState } from 'react'
+import { api } from '../api'
+import {
+  Button, Card, CardHeader, Badge, Stat, EmptyState, PageHeader,
+} from '../components/ui.jsx'
+
+export default function Audit() {
+  const [stats, setStats] = useState(null)
+  const [entries, setEntries] = useState([])
+  const [plag, setPlag] = useState([])
+  const [loading, setLoading] = useState(true)
+
+  const load = async () => {
+    setLoading(true)
+    try {
+      const [s, e, p] = await Promise.all([api.stats(), api.audit(), api.plagiarism()])
+      setStats(s); setEntries(e); setPlag(p)
+    } finally {
+      setLoading(false)
+    }
+  }
+  useEffect(() => { load() }, [])
+
+  const pct = (n) => `${Math.round((n || 0) * 100)}%`
+
+  return (
+    <div>
+      <PageHeader
+        title="Audit & analytics"
+        description="Immutable record of every grading and review decision. Each row is stamped with the rubric, prompt, and model versions in effect at the time."
+        actions={<Button onClick={load}>Refresh</Button>}
+      />
+
+      {stats && (
+        <div className="grid grid-cols-2 md:grid-cols-3 lg:grid-cols-6 gap-3 mb-6">
+          <Stat label="Total answers" value={stats.total_crops} />
+          <Stat label="Reviewed" value={stats.total_reviewed} />
+          <Stat
+            label="Override rate" value={pct(stats.override_rate)}
+            accent={(stats.override_rate || 0) > 0.2 ? 'text-warning-strong' : 'text-ink'}
+          />
+          <Stat label="Flag rate" value={pct(stats.flag_rate)} />
+          <Stat
+            label="Mean σ" value={(stats.mean_std_dev || 0).toFixed(2)}
+            accent={(stats.mean_std_dev || 0) > 1 ? 'text-warning-strong' : 'text-success-strong'}
+          />
+          <Stat
+            label="Similarity pairs" value={stats.plagiarism_pairs}
+            accent={stats.plagiarism_pairs > 0 ? 'text-danger-strong' : 'text-ink'}
+          />
+        </div>
+      )}
+
+      <div className="grid grid-cols-1 lg:grid-cols-2 gap-4">
+        <Card>
+          <CardHeader title="Decision log" description="Newest first" />
+          <div className="max-h-[64vh] overflow-auto">
+            {loading ? (
+              <p className="px-5 py-6 text-body-sm text-ink-muted">Loading…</p>
+            ) : entries.length === 0 ? (
+              <p className="px-5 py-6 text-body-sm text-ink-muted text-center">No audit entries yet.</p>
+            ) : (
+              <table className="w-full text-body-sm">
+                <thead className="sticky top-0 bg-surface-subtle">
+                  <tr className="text-left text-label-sm uppercase tracking-wide text-ink-subtle border-b border-border">
+                    <th className="px-5 py-2 font-medium">When</th>
+                    <th className="px-2 py-2 font-medium">Entity</th>
+                    <th className="px-2 py-2 font-medium">Action</th>
+                    <th className="px-2 py-2 font-medium">Versions</th>
+                    <th className="px-5 py-2 font-medium">Detail</th>
+                  </tr>
+                </thead>
+                <tbody>
+                  {entries.map(e => (
+                    <tr key={e.id} className="border-b border-border last:border-0 hover:bg-surface-subtle">
+                      <td className="px-5 py-2.5 text-ink-muted whitespace-nowrap">
+                        {new Date(e.created_at).toLocaleTimeString()}
+                      </td>
+                      <td className="px-2 py-2.5 text-ink">{e.entity_type}#{e.entity_id}</td>
+                      <td className="px-2 py-2.5">
+                        <Badge variant={actionVariant(e.action)}>{e.action}</Badge>
+                      </td>
+                      <td className="px-2 py-2.5 text-label-sm text-ink-subtle">
+                        r:{e.rubric_version || '—'} · p:{e.prompt_version || '—'}
+                      </td>
+                      <td className="px-5 py-2.5 text-ink-muted truncate max-w-[200px]" title={JSON.stringify(e.after)}>
+                        {summarizeDelta(e)}
+                      </td>
+                    </tr>
+                  ))}
+                </tbody>
+              </table>
+            )}
+          </div>
+        </Card>
+
+        <Card>
+          <CardHeader
+            title="Similarity flags"
+            description="Pairs of answers with highly similar reasoning"
+          />
+          <div className="max-h-[64vh] overflow-auto">
+            {loading ? (
+              <p className="px-5 py-6 text-body-sm text-ink-muted">Loading…</p>
+            ) : plag.length === 0 ? (
+              <p className="px-5 py-6 text-body-sm text-ink-muted text-center">No similarity pairs above the configured threshold.</p>
+            ) : (
+              <table className="w-full text-body-sm">
+                <thead className="sticky top-0 bg-surface-subtle">
+                  <tr className="text-left text-label-sm uppercase tracking-wide text-ink-subtle border-b border-border">
+                    <th className="px-5 py-2 font-medium">Answer A</th>
+                    <th className="px-2 py-2 font-medium">Answer B</th>
+                    <th className="px-5 py-2 font-medium text-right">Similarity</th>
+                  </tr>
+                </thead>
+                <tbody>
+                  {plag.map(p => (
+                    <tr key={`${p.crop_a_id}-${p.crop_b_id}`} className="border-b border-border last:border-0">
+                      <td className="px-5 py-2.5 text-ink">#{p.crop_a_id}</td>
+                      <td className="px-2 py-2.5 text-ink">#{p.crop_b_id}</td>
+                      <td className="px-5 py-2.5 text-right">
+                        <span className="text-danger-strong font-medium">{(p.similarity * 100).toFixed(1)}%</span>
+                      </td>
+                    </tr>
+                  ))}
+                </tbody>
+              </table>
+            )}
+          </div>
+        </Card>
+      </div>
+    </div>
+  )
+}
+
+function actionVariant(action) {
+  if (action === 'approve')  return 'success'
+  if (action === 'override') return 'warning'
+  if (action === 'flag')     return 'danger'
+  return 'neutral'
+}
+
+function summarizeDelta(e) {
+  const a = e.after || {}
+  if (a.final_score !== undefined) return `→ ${a.final_score}`
+  if (a.median !== undefined) return `median ${a.median} · σ ${(a.std_dev || 0).toFixed(2)}`
+  if (a.title) return a.title
+  return '—'
+}

frontend/src/pages/Grading.jsx

@@ -0,0 +1,169 @@
+import React, { useEffect, useState } from 'react'
+import { api } from '../api'
+import {
+  Button, Card, CardHeader, CardBody, Select, Field, Badge,
+  EmptyState, PageHeader,
+} from '../components/ui.jsx'
+
+export default function Grading() {
+  const [exams, setExams] = useState([])
+  const [examId, setExamId] = useState(null)
+  const [rubrics, setRubrics] = useState([])
+  const [rubricId, setRubricId] = useState(null)
+  const [files, setFiles] = useState([])
+  const [batch, setBatch] = useState([])
+  const [running, setRunning] = useState(false)
+
+  const refresh = async () => {
+    const es = await api.listExams()
+    setExams(es)
+    const eid = examId ?? es[0]?.id ?? null
+    setExamId(eid)
+    if (eid) {
+      const rs = await api.listRubrics(eid)
+      setRubrics(rs)
+      if (!rubricId && rs[0]) setRubricId(rs[0].id)
+    }
+  }
+  useEffect(() => { refresh() }, []) // eslint-disable-line
+  useEffect(() => { if (examId) api.listRubrics(examId).then(setRubrics) }, [examId])
+
+  const onPickFiles = (e) => setFiles(Array.from(e.target.files || []))
+
+  const runBatch = async () => {
+    if (!examId || !rubricId || !files.length) return
+    setRunning(true)
+    const fresh = files.map((f, i) => ({
+      id: `${Date.now()}_${i}`,
+      name: f.name,
+      status: 'queued',
+    }))
+    setBatch(fresh)
+    for (let i = 0; i < files.length; i++) {
+      const f = files[i]
+      setBatch(b => b.map((x, idx) => idx === i ? { ...x, status: 'grading' } : x))
+      try {
+        const res = await api.uploadPaper(examId, rubricId, f)
+        setBatch(b => b.map((x, idx) => idx === i ? {
+          ...x, status: 'done',
+          paperId: res.paper_id, anonId: res.student_anon_id,
+          cropIds: res.crop_ids,
+        } : x))
+      } catch (err) {
+        setBatch(b => b.map((x, idx) => idx === i ? {
+          ...x, status: 'failed',
+          error: err?.response?.data?.detail || err.message,
+        } : x))
+      }
+    }
+    setRunning(false)
+    setFiles([])
+  }
+
+  const rubric = rubrics.find(r => r.id === rubricId)
+  const anyDone = batch.some(b => b.status === 'done')
+
+  return (
+    <div>
+      <PageHeader
+        title="Grading"
+        description="Upload scanned answer sheets. The system extracts each answer region, transcribes the handwriting, and grades against the selected rubric."
+      />
+
+      {exams.length === 0 ? (
+        <EmptyState
+          title="Create an exam and a rubric first"
+          description="Go to the Rubrics tab, create an exam, and add at least one rubric. Then come back here to upload answer sheets."
+        />
+      ) : (
+        <>
+          <Card className="mb-4">
+            <CardBody>
+              <div className="grid grid-cols-1 lg:grid-cols-3 gap-4">
+                <Field label="Exam">
+                  <Select value={examId || ''} onChange={e => setExamId(Number(e.target.value))}>
+                    {exams.map(e => <option key={e.id} value={e.id}>{e.title}</option>)}
+                  </Select>
+                </Field>
+                <Field label="Rubric">
+                  <Select value={rubricId || ''} onChange={e => setRubricId(Number(e.target.value))}>
+                    {rubrics.length === 0 && <option value="">No rubrics in this exam</option>}
+                    {rubrics.map(r => <option key={r.id} value={r.id}>{r.title} ({r.version})</option>)}
+                  </Select>
+                </Field>
+                <Field label="Answer sheets" hint="PDF or image. One student per file.">
+                  <label className="cursor-pointer">
+                    <input type="file" accept="application/pdf,image/*" multiple
+                           onChange={onPickFiles} className="sr-only" />
+                    <span className="block w-full h-9 px-3 rounded border border-dashed border-border bg-surface-subtle text-body-sm text-ink-muted flex items-center hover:border-brand hover:bg-brand-subtle hover:text-brand transition-colors">
+                      {files.length > 0
+                        ? `${files.length} file${files.length === 1 ? '' : 's'} selected`
+                        : 'Click to choose files'}
+                    </span>
+                  </label>
+                </Field>
+              </div>
+
+              {rubric && (
+                <div className="mt-4 rounded border border-border bg-surface-subtle px-4 py-3">
+                  <div className="flex items-center gap-2 mb-1">
+                    <Badge variant="brand">{rubric.version}</Badge>
+                    <span className="text-label-md text-ink font-medium">{rubric.title}</span>
+                    <span className="text-label-sm text-ink-muted">· {rubric.max_marks} pts · {rubric.criteria.length} criteria</span>
+                  </div>
+                  <p className="text-body-sm text-ink-muted whitespace-pre-line line-clamp-2">{rubric.question_text}</p>
+                </div>
+              )}
+
+              <div className="mt-4 flex items-center justify-between">
+                <span className="text-label-md text-ink-muted">
+                  {files.length} file{files.length === 1 ? '' : 's'} queued
+                </span>
+                <Button
+                  variant="primary" onClick={runBatch}
+                  disabled={!rubricId || !files.length || running}
+                >
+                  {running ? 'Grading…' : `Run grading on ${files.length || 0}`}
+                </Button>
+              </div>
+            </CardBody>
+          </Card>
+
+          {batch.length > 0 && (
+            <Card>
+              <CardHeader title="Batch progress" />
+              <div className="divide-y divide-border">
+                {batch.map(item => <BatchRow key={item.id} item={item} />)}
+              </div>
+            </Card>
+          )}
+
+          {anyDone && (
+            <p className="mt-6 text-body-sm text-ink-muted">
+              Done. Open the <span className="text-brand font-medium">Review</span> tab to see grades and approve, override, or flag each answer.
+            </p>
+          )}
+        </>
+      )}
+    </div>
+  )
+}
+
+function BatchRow({ item }) {
+  return (
+    <div className="flex items-center gap-3 px-5 py-3">
+      <span className="flex-1 text-body-sm text-ink truncate">{item.name}</span>
+      {item.status === 'queued'  && <Badge>queued</Badge>}
+      {item.status === 'grading' && <Badge variant="info">Grading…</Badge>}
+      {item.status === 'done'    && (
+        <>
+          <Badge variant="success">✓ {item.cropIds?.length || 0} answer{item.cropIds?.length === 1 ? '' : 's'}</Badge>
+          <span className="text-label-sm text-ink-subtle">{item.anonId}</span>
+        </>
+      )}
+      {item.status === 'failed'  && (
+        <Badge variant="danger" title={item.error}>Failed</Badge>
+      )}
+    </div>
+  )
+}

frontend/src/pages/Review.jsx

@@ -0,0 +1,302 @@
+import React, { useCallback, useContext, useEffect, useRef, useState } from 'react'
+import { api } from '../api'
+import {
+  Button, Card, CardHeader, CardBody, Input, Field, Badge,
+  EmptyState, PageHeader, Kbd,
+} from '../components/ui.jsx'
+import { RoleContext } from '../App.jsx'
+
+export default function Review() {
+  const { user } = useContext(RoleContext)
+  const [queue, setQueue] = useState([])
+  const [idx, setIdx] = useState(0)
+  const [loading, setLoading] = useState(true)
+  const [override, setOverride] = useState({ open: false, score: '', notes: '' })
+  const overrideInputRef = useRef(null)
+
+  const load = async () => {
+    setLoading(true)
+    try {
+      const items = await api.reviewQueue()
+      setQueue(items)
+      setIdx(0)
+    } finally {
+      setLoading(false)
+    }
+  }
+  useEffect(() => { load() }, [])
+
+  const current = queue[idx]
+
+  const submit = useCallback(async (action, finalScore, notes) => {
+    if (!current) return
+    await api.submitReview({
+      crop_id: current.crop_id,
+      action,
+      final_score: finalScore,
+      notes: notes || '',
+      reviewer_id: user?.id,
+    })
+    setQueue(q => q.filter((_, i) => i !== idx))
+    setIdx(i => Math.max(0, Math.min(i, queue.length - 2)))
+    setOverride({ open: false, score: '', notes: '' })
+  }, [current, idx, queue.length, user])
+
+  const onApprove = () => current && submit('approve', current.aggregate.median, '')
+  const onFlag    = () => current && submit('flag', current.aggregate.median, 'Flagged by reviewer')
+  const openOverride = () => {
+    if (!current) return
+    setOverride({ open: true, score: String(current.aggregate.median), notes: '' })
+    setTimeout(() => overrideInputRef.current?.focus(), 30)
+  }
+  const submitOverride = () => {
+    const s = Number(override.score)
+    if (isNaN(s)) return
+    submit('override', s, override.notes)
+  }
+
+  // Keyboard shortcuts
+  useEffect(() => {
+    const handler = (e) => {
+      if (override.open) {
+        if (e.key === 'Escape') { setOverride({ open: false, score: '', notes: '' }); e.preventDefault() }
+        if (e.key === 'Enter' && (e.ctrlKey || e.metaKey)) { submitOverride(); e.preventDefault() }
+        return
+      }
+      if (['INPUT', 'TEXTAREA', 'SELECT'].includes(document.activeElement?.tagName)) return
+      switch (e.key.toLowerCase()) {
+        case 'enter': onApprove(); e.preventDefault(); break
+        case 'o': openOverride(); e.preventDefault(); break
+        case 'f': onFlag(); e.preventDefault(); break
+        case 'j': case 'arrowright':
+          setIdx(i => Math.min(i + 1, queue.length - 1)); e.preventDefault(); break
+        case 'k': case 'arrowleft':
+          setIdx(i => Math.max(i - 1, 0)); e.preventDefault(); break
+      }
+    }
+    window.addEventListener('keydown', handler)
+    return () => window.removeEventListener('keydown', handler)
+  }, [override.open, queue.length, current, idx]) // eslint-disable-line
+
+  if (loading) {
+    return (
+      <div>
+        <PageHeader title="Review queue" description="Loading…" />
+      </div>
+    )
+  }
+
+  if (queue.length === 0) {
+    return (
+      <div>
+        <PageHeader
+          title="Review queue"
+          description="Answers awaiting human approval, sorted by AI uncertainty (highest variance first)."
+          actions={<Button onClick={load}>Refresh</Button>}
+        />
+        <EmptyState
+          title="Queue is clear"
+          description="Either nothing has been graded yet, or every graded answer has been reviewed. Upload more answer sheets in the Grading tab."
+          action={<Button onClick={load}>Refresh queue</Button>}
+        />
+      </div>
+    )
+  }
+
+  return (
+    <div>
+      <PageHeader
+        title="Review queue"
+        description={`${queue.length} pending · sorted by AI uncertainty (highest variance first)`}
+        actions={
+          <>
+            <div className="hidden md:flex items-center gap-3 text-label-sm text-ink-muted mr-2">
+              <span className="flex items-center gap-1"><Kbd>↵</Kbd> approve</span>
+              <span className="flex items-center gap-1"><Kbd>O</Kbd> override</span>
+              <span className="flex items-center gap-1"><Kbd>F</Kbd> flag</span>
+              <span className="flex items-center gap-1"><Kbd>J</Kbd>/<Kbd>K</Kbd> next/prev</span>
+            </div>
+            <Button onClick={load} variant="ghost">↻</Button>
+          </>
+        }
+      />
+
+      <div className="flex items-center justify-between mb-3">
+        <span className="text-label-md text-ink-muted">Item {idx + 1} of {queue.length}</span>
+        <div className="flex gap-1">
+          <Button variant="ghost" size="sm" onClick={() => setIdx(i => Math.max(0, i - 1))} disabled={idx === 0}>← Prev</Button>
+          <Button variant="ghost" size="sm" onClick={() => setIdx(i => Math.min(queue.length - 1, i + 1))} disabled={idx === queue.length - 1}>Next →</Button>
+        </div>
+      </div>
+
+      <div className="grid grid-cols-1 lg:grid-cols-2 gap-4">
+        {/* LEFT: image + metadata */}
+        <Card>
+          <CardHeader
+            title={current.student_anon_id}
+            description={`${current.question_id} · ${current.rubric_title}`}
+            action={
+              <div className="flex items-center gap-2">
+                {current.plagiarism_flagged && <Badge variant="danger">Similarity</Badge>}
+                <span className="text-label-sm text-ink-subtle">#{current.crop_id}</span>
+              </div>
+            }
+          />
+          <div className="bg-surface-subtle p-3 border-t border-border">
+            <img
+              src={api.cropImageUrl(current.crop_id)}
+              alt="student answer"
+              className="w-full h-auto max-h-[64vh] object-contain bg-white rounded border border-border"
+            />
+          </div>
+        </Card>
+
+        {/* RIGHT: AI grade panels */}
+        <div className="space-y-4">
+          {/* Aggregate */}
+          <Card>
+            <CardHeader title={`AI grade · ${current.aggregate.n_passes} pass${current.aggregate.n_passes === 1 ? '' : 'es'}`} />
+            <CardBody>
+              <div className="grid grid-cols-4 gap-2">
+                <ScoreBlock label="Median" value={current.aggregate.median} accent="text-brand" />
+                <ScoreBlock label="Max" value={current.aggregate.max_score} />
+                <ScoreBlock label="Min" value={current.aggregate.min_score} />
+                <ScoreBlock
+                  label="σ"
+                  value={current.aggregate.std_dev.toFixed(2)}
+                  accent={current.aggregate.std_dev > 1 ? 'text-warning-strong' : 'text-success-strong'}
+                />
+              </div>
+              {current.gradings.length > 1 && (
+                <div className="mt-3 flex gap-1.5">
+                  {current.gradings.map(g => (
+                    <div
+                      key={g.id}
+                      title={`Pass ${g.pass_num}: ${g.score}/${g.max_score}${g.critic_passed ? '' : ' (critic failed)'}`}
+                      className="flex-1 h-7 rounded border border-border bg-surface-subtle flex items-center justify-center text-label-md text-ink"
+                    >
+                      {g.score}{!g.critic_passed && <span className="ml-1 text-warning">!</span>}
+                    </div>
+                  ))}
+                </div>
+              )}
+            </CardBody>
+          </Card>
+
+          {/* Per-criterion */}
+          <Card>
+            <CardHeader title="Per-criterion" description="From the median pass" />
+            <div className="divide-y divide-border">
+              {pickMedianGrading(current).per_criterion.map((c, i) => (
+                <div key={i} className="px-5 py-3">
+                  <div className="flex items-center justify-between gap-3">
+                    <span className="text-body-sm text-ink font-medium">
+                      <span className="text-ink-subtle mr-2">#{i + 1}</span>{c.name}
+                    </span>
+                    <span className="text-body-sm text-ink font-medium">{c.awarded} / {c.max}</span>
+                  </div>
+                  <p className="text-label-sm text-ink-muted mt-0.5 pl-6">{c.reasoning}</p>
+                </div>
+              ))}
+            </div>
+          </Card>
+
+          {/* Justification */}
+          <Card>
+            <CardHeader title="Justification" />
+            <CardBody>
+              <p className="text-body-sm text-ink leading-relaxed">
+                {pickMedianGrading(current).justification}
+              </p>
+              {pickMedianGrading(current).flags?.length > 0 && (
+                <div className="mt-3 flex gap-1.5 flex-wrap">
+                  {pickMedianGrading(current).flags.map(f => (
+                    <Badge key={f} variant="warning">{f}</Badge>
+                  ))}
+                </div>
+              )}
+            </CardBody>
+          </Card>
+
+          {/* Actions */}
+          <Card className="border-brand/20 bg-brand-subtle/40">
+            <CardBody>
+              {!override.open ? (
+                <div className="flex items-center gap-2">
+                  <Button variant="primary" onClick={onApprove}>
+                    <Kbd>↵</Kbd> Approve {current.aggregate.median}
+                  </Button>
+                  <Button onClick={openOverride}>
+                    <Kbd>O</Kbd> Override
+                  </Button>
+                  <Button variant="danger" onClick={onFlag}>
+                    <Kbd>F</Kbd> Flag
+                  </Button>
+                </div>
+              ) : (
+                <div className="space-y-3">
+                  <div className="grid grid-cols-3 gap-3">
+                    <Field label={`New score (0 — ${current.gradings[0]?.max_score || 0})`}>
+                      <Input
+                        ref={overrideInputRef} type="number" step="0.5" min="0"
+                        max={current.gradings[0]?.max_score || 0}
+                        value={override.score}
+                        onChange={e => setOverride({ ...override, score: e.target.value })}
+                      />
+                    </Field>
+                    <div className="col-span-2">
+                      <Field label="Note (optional)">
+                        <Input
+                          value={override.notes}
+                          onChange={e => setOverride({ ...override, notes: e.target.value })}
+                          placeholder="Why you changed the score"
+                        />
+                      </Field>
+                    </div>
+                  </div>
+                  <div className="flex gap-2 justify-end">
+                    <Button onClick={() => setOverride({ open: false, score: '', notes: '' })}>
+                      <Kbd>Esc</Kbd> Cancel
+                    </Button>
+                    <Button variant="success" onClick={submitOverride}>
+                      <Kbd>⌘↵</Kbd> Save override
+                    </Button>
+                  </div>
+                </div>
+              )}
+            </CardBody>
+          </Card>
+        </div>
+      </div>
+
+      {/* Transcript drawer */}
+      <details className="mt-4 group">
+        <summary className="list-none cursor-pointer rounded-lg border border-border bg-surface px-5 py-3 text-label-md text-ink-muted hover:text-ink hover:bg-surface-subtle transition-colors">
+          <span className="inline-flex items-center gap-2">
+            <span className="text-ink-faint group-open:rotate-90 transition-transform">›</span>
+            OCR transcript
+          </span>
+        </summary>
+        <pre className="mt-2 p-4 rounded-lg border border-border bg-surface text-body-sm text-ink whitespace-pre-wrap font-sans leading-relaxed">
+{current.gradings[0]?.transcript || '(no transcript captured)'}
+        </pre>
+      </details>
+    </div>
+  )
+}
+
+function pickMedianGrading(item) {
+  const sorted = [...item.gradings].sort(
+    (a, b) => Math.abs(a.score - item.aggregate.median) - Math.abs(b.score - item.aggregate.median)
+  )
+  return sorted[0] || item.gradings[0]
+}
+
+function ScoreBlock({ label, value, accent }) {
+  return (
+    <div className="rounded border border-border bg-surface px-3 py-2.5">
+      <div className="text-label-sm uppercase tracking-wide text-ink-subtle">{label}</div>
+      <div className={`text-headline-md ${accent || 'text-ink'}`}>{value}</div>
+    </div>
+  )
+}

frontend/src/pages/Rubrics.jsx

@@ -0,0 +1,349 @@
+import React, { useEffect, useState } from 'react'
+import { api } from '../api'
+import {
+  Button, Card, CardHeader, CardBody, Input, TextArea, Select,
+  Field, Badge, EmptyState, PageHeader,
+} from '../components/ui.jsx'
+
+const DEFAULT_INSTRUCTIONS = `Base all scoring strictly on evidence visible in the student's handwritten work. If evidence is missing, assign zero — do not guess, infer, or hallucinate.
+Award credit for intermediate steps only if they are explicitly written by the student. Do not infer non-trivial reasoning from a correct final answer except for trivial algebraic simplifications.
+If the student's solution does not match the question being asked, assign a score of 0.`
+
+const SAMPLE_RUBRIC = {
+  title: 'Linear equation — sample',
+  question_text: 'Solve for x and show all steps:\n\n2x + 5 = 15',
+  max_marks: 10,
+  course_instructions: DEFAULT_INSTRUCTIONS,
+  criteria: [
+    {
+      name: 'Isolate the variable term',
+      points: 5,
+      conditions: 'Student subtracts 5 from both sides to obtain 2x = 10.',
+      accept_alternatives: 'Equivalent algebraic rearrangements that arrive at 2x = 10.',
+      do_not_deduct_for: 'Minor handwriting or notation differences.',
+    },
+    {
+      name: 'Solve for x',
+      points: 5,
+      conditions: 'Student divides both sides by 2 and obtains x = 5.',
+      accept_alternatives: 'Equivalent forms such as x=5 or x = 5.0.',
+      do_not_deduct_for: 'Minor notation differences.',
+    },
+  ],
+}
+
+export default function Rubrics() {
+  const [exams, setExams] = useState([])
+  const [examId, setExamId] = useState(null)
+  const [rubrics, setRubrics] = useState([])
+  const [editing, setEditing] = useState(null)
+  const [loading, setLoading] = useState(true)
+
+  const refresh = async (eid) => {
+    setLoading(true)
+    try {
+      const es = await api.listExams()
+      setExams(es)
+      const useExam = eid ?? examId ?? (es[0]?.id || null)
+      setExamId(useExam)
+      setRubrics(useExam ? await api.listRubrics(useExam) : [])
+    } finally {
+      setLoading(false)
+    }
+  }
+
+  useEffect(() => { refresh() }, []) // eslint-disable-line
+
+  const createExam = async () => {
+    const title = prompt('Name this exam')
+    if (!title) return
+    const e = await api.createExam({ title })
+    await refresh(e.id)
+  }
+
+  const startBlank = () => {
+    if (!examId) { alert('Create an exam first.'); return }
+    setEditing({
+      _new: true, exam_id: examId,
+      title: '', question_text: '', max_marks: 10,
+      course_instructions: DEFAULT_INSTRUCTIONS,
+      criteria: [{ name: '', points: 1, conditions: '', accept_alternatives: '', do_not_deduct_for: '' }],
+    })
+  }
+
+  const startSample = () => {
+    if (!examId) { alert('Create an exam first.'); return }
+    setEditing({ _new: true, exam_id: examId, ...SAMPLE_RUBRIC })
+  }
+
+  const save = async (r) => {
+    const { _new, ...payload } = r
+    await api.createRubric(payload)
+    setEditing(null)
+    await refresh()
+  }
+
+  if (editing) {
+    return <RubricEditor initial={editing} onSave={save} onCancel={() => setEditing(null)} />
+  }
+
+  return (
+    <div>
+      <PageHeader
+        title="Rubrics"
+        description="Define grading criteria for each question. Criteria support alternatives and explicit do-not-deduct rules."
+        actions={
+          <>
+            <ExamPicker exams={exams} value={examId} onChange={(id) => refresh(id)} />
+            <Button onClick={createExam}>New exam</Button>
+            <Button onClick={startSample}>Load sample</Button>
+            <Button variant="primary" onClick={startBlank}>New rubric</Button>
+          </>
+        }
+      />
+
+      {loading ? (
+        <Card><CardBody><p className="text-body-sm text-ink-muted">Loading…</p></CardBody></Card>
+      ) : exams.length === 0 ? (
+        <EmptyState
+          title="No exams yet"
+          description="Create an exam first, then add one or more rubrics to it. Each question on the exam needs its own rubric."
+          action={<Button variant="primary" onClick={createExam}>Create your first exam</Button>}
+        />
+      ) : rubrics.length === 0 ? (
+        <EmptyState
+          title="No rubrics for this exam"
+          description="Add a rubric to start grading. Use a blank rubric or load a sample to see the structure."
+          action={
+            <div className="flex gap-2 justify-center">
+              <Button onClick={startSample}>Load sample</Button>
+              <Button variant="primary" onClick={startBlank}>New rubric</Button>
+            </div>
+          }
+        />
+      ) : (
+        <div className="grid gap-4">
+          {rubrics.map(r => <RubricCard key={r.id} rubric={r} />)}
+        </div>
+      )}
+    </div>
+  )
+}
+
+function ExamPicker({ exams, value, onChange }) {
+  return (
+    <Select value={value || ''} onChange={e => onChange(Number(e.target.value))} className="!w-auto min-w-[200px]">
+      {exams.length === 0 && <option value="">No exams</option>}
+      {exams.map(e => <option key={e.id} value={e.id}>{e.title}</option>)}
+    </Select>
+  )
+}
+
+function RubricCard({ rubric }) {
+  return (
+    <Card>
+      <div className="px-5 py-4">
+        <div className="flex items-start justify-between gap-4">
+          <div className="min-w-0">
+            <div className="flex items-center gap-2 mb-1">
+              <h3 className="text-headline-sm text-ink truncate">{rubric.title}</h3>
+              <Badge variant="brand">{rubric.version}</Badge>
+              <Badge>{rubric.max_marks} pts</Badge>
+              <Badge>{rubric.criteria.length} criteria</Badge>
+            </div>
+            <p className="text-body-sm text-ink-muted whitespace-pre-line">{rubric.question_text}</p>
+          </div>
+          <span className="text-label-sm text-ink-faint shrink-0">#{rubric.id}</span>
+        </div>
+
+        <div className="mt-4 grid grid-cols-1 sm:grid-cols-2 lg:grid-cols-4 gap-2">
+          {rubric.criteria.map((c, i) => (
+            <div key={i} className="rounded border border-border bg-surface-subtle px-3 py-2.5">
+              <div className="flex items-center justify-between mb-0.5">
+                <span className="text-label-sm uppercase tracking-wide text-ink-subtle">#{i + 1}</span>
+                <span className="text-label-sm font-medium text-ink">{c.points} pts</span>
+              </div>
+              <p className="text-body-sm text-ink font-medium truncate">{c.name}</p>
+              <p className="text-label-sm text-ink-muted line-clamp-2 mt-0.5">{c.conditions}</p>
+            </div>
+          ))}
+        </div>
+      </div>
+    </Card>
+  )
+}
+
+// ===========================================================================
+// Editor
+// ===========================================================================
+function RubricEditor({ initial, onSave, onCancel }) {
+  const [r, setR] = useState(initial)
+  const [submitted, setSubmitted] = useState(false)
+
+  const update = (patch) => setR({ ...r, ...patch })
+  const updateCrit = (i, patch) => update({
+    criteria: r.criteria.map((c, idx) => idx === i ? { ...c, ...patch } : c),
+  })
+  const addCrit = () => update({
+    criteria: [...r.criteria, { name: '', points: 1, conditions: '', accept_alternatives: '', do_not_deduct_for: '' }],
+  })
+  const removeCrit = (i) => update({ criteria: r.criteria.filter((_, idx) => idx !== i) })
+
+  const total = r.criteria.reduce((s, c) => s + (Number(c.points) || 0), 0)
+  const mismatch = total !== Number(r.max_marks)
+  const allCritsNamed = r.criteria.every(c => c.name.trim())
+  const canSave = r.title.trim() && r.question_text.trim() && r.criteria.length > 0 && allCritsNamed
+
+  const onSaveClick = () => {
+    setSubmitted(true)
+    if (canSave) onSave(r)
+  }
+
+  return (
+    <div>
+      <PageHeader
+        title={initial._new ? 'New rubric' : 'Edit rubric'}
+        description="Fine-grained criteria with explicit conditions, alternatives, and do-not-deduct rules give the grader the least room for misinterpretation."
+        actions={
+          <>
+            <Button onClick={onCancel}>Cancel</Button>
+            <Button variant="primary" onClick={onSaveClick} disabled={!canSave}>Save rubric</Button>
+          </>
+        }
+      />
+
+      {submitted && !canSave && (
+        <div className="mb-4 px-4 py-3 rounded-lg border border-danger/30 bg-danger-subtle text-body-sm text-danger-strong">
+          Fill in the rubric title, question text, and a name for every criterion before saving.
+        </div>
+      )}
+
+      <Card className="mb-4">
+        <CardHeader title="Basics" />
+        <CardBody>
+          <div className="grid grid-cols-3 gap-4 mb-4">
+            <div className="col-span-2">
+              <Field label="Title" required>
+                <Input
+                  value={r.title}
+                  onChange={e => update({ title: e.target.value })}
+                  placeholder="Short, descriptive name"
+                  invalid={submitted && !r.title.trim()}
+                />
+              </Field>
+            </div>
+            <Field label="Max marks">
+              <Input
+                type="number" min={0}
+                value={r.max_marks}
+                onChange={e => update({ max_marks: Number(e.target.value) || 0 })}
+              />
+            </Field>
+          </div>
+
+          <Field label="Question text" required hint="Exactly as the question appears on the exam.">
+            <TextArea
+              rows={3}
+              value={r.question_text}
+              onChange={e => update({ question_text: e.target.value })}
+              invalid={submitted && !r.question_text.trim()}
+            />
+          </Field>
+        </CardBody>
+      </Card>
+
+      <Card className="mb-4">
+        <CardHeader
+          title="Grading instructions"
+          description="Course-level anti-hallucination guardrails passed to the grader on every call."
+        />
+        <CardBody>
+          <TextArea
+            rows={5}
+            value={r.course_instructions}
+            onChange={e => update({ course_instructions: e.target.value })}
+          />
+        </CardBody>
+      </Card>
+
+      <Card>
+        <CardHeader
+          title="Criteria"
+          description={`${total} / ${r.max_marks} pts allocated${mismatch ? '  •  totals do not match' : ''}`}
+          action={<Button onClick={addCrit}>Add criterion</Button>}
+        />
+        <div className="divide-y divide-border">
+          {r.criteria.map((c, i) => (
+            <CriterionRow
+              key={i}
+              index={i}
+              criterion={c}
+              showError={submitted && !c.name.trim()}
+              onChange={(patch) => updateCrit(i, patch)}
+              onRemove={() => removeCrit(i)}
+              canRemove={r.criteria.length > 1}
+            />
+          ))}
+        </div>
+      </Card>
+    </div>
+  )
+}
+
+function CriterionRow({ index, criterion, showError, onChange, onRemove, canRemove }) {
+  return (
+    <div className="px-5 py-4">
+      {/* Top row: index + name + points + remove. Uses GRID with explicit
+          column widths so the name field cannot get visually squashed. */}
+      <div className="grid items-center gap-3 mb-3"
+           style={{ gridTemplateColumns: '32px minmax(0,1fr) 96px auto' }}>
+        <span className="text-label-md font-medium text-ink-subtle">#{index + 1}</span>
+        <Input
+          value={criterion.name}
+          onChange={e => onChange({ name: e.target.value })}
+          placeholder="Criterion name"
+          invalid={showError}
+        />
+        <div className="flex items-center gap-1.5">
+          <Input
+            type="number" min={0} step="0.5"
+            value={criterion.points}
+            onChange={e => onChange({ points: Number(e.target.value) || 0 })}
+            className="text-right"
+          />
+          <span className="text-label-sm text-ink-muted">pts</span>
+        </div>
+        <Button
+          variant="ghost" size="icon" onClick={onRemove} disabled={!canRemove}
+          aria-label="Remove criterion"
+        >
+          <span aria-hidden="true">×</span>
+        </Button>
+      </div>
+
+      <div className="grid grid-cols-1 lg:grid-cols-3 gap-3 pl-11">
+        <Field label="Conditions">
+          <TextArea rows={3}
+            value={criterion.conditions}
+            onChange={e => onChange({ conditions: e.target.value })}
+            placeholder="What must the student show to earn these points?"
+          />
+        </Field>
+        <Field label="Accept also">
+          <TextArea rows={3}
+            value={criterion.accept_alternatives}
+            onChange={e => onChange({ accept_alternatives: e.target.value })}
+            placeholder="Equivalent forms or alternative paths"
+          />
+        </Field>
+        <Field label="Do not deduct for">
+          <TextArea rows={3}
+            value={criterion.do_not_deduct_for}
+            onChange={e => onChange({ do_not_deduct_for: e.target.value })}
+            placeholder="Surface issues to ignore"
+          />
+        </Field>
+      </div>
+    </div>
+  )
+}

frontend/tailwind.config.js

@@ -0,0 +1,82 @@
+/** @type {import('tailwindcss').Config} */
+export default {
+  content: ['./index.html', './src/**/*.{js,jsx}'],
+  theme: {
+    extend: {
+      fontFamily: {
+        sans: ['Inter', 'ui-sans-serif', 'system-ui', 'sans-serif'],
+      },
+      colors: {
+        // Surface scale (Material 3 tonal palette adapted to the spec)
+        background: '#F9FAFB',
+        surface: {
+          DEFAULT: '#FFFFFF',
+          subtle: '#F9FAFB',
+          muted: '#F3F4F6',
+          inset: '#F1F3FF',
+        },
+        // Strokes
+        border: {
+          DEFAULT: '#E5E7EB',
+          strong: '#D1D5DB',
+          subtle: '#F3F4F6',
+        },
+        // Text
+        ink: {
+          DEFAULT: '#111827',
+          muted: '#4B5563',
+          subtle: '#6B7280',
+          faint: '#9CA3AF',
+        },
+        // Brand (indigo)
+        brand: {
+          DEFAULT: '#4F46E5',
+          hover: '#4338CA',
+          fg: '#FFFFFF',
+          subtle: '#EEF2FF',
+          ring: 'rgba(79, 70, 229, 0.12)',
+        },
+        // Status
+        success: { DEFAULT: '#059669', subtle: '#ECFDF5', strong: '#047857' },
+        warning: { DEFAULT: '#D97706', subtle: '#FFFBEB', strong: '#B45309' },
+        danger:  { DEFAULT: '#DC2626', subtle: '#FEF2F2', strong: '#B91C1C' },
+        info:    { DEFAULT: '#2563EB', subtle: '#EFF6FF', strong: '#1D4ED8' },
+      },
+      fontSize: {
+        // Spec-defined scale
+        'display-lg': ['48px', { lineHeight: '56px', letterSpacing: '-0.02em', fontWeight: '700' }],
+        'headline-lg':['32px', { lineHeight: '40px', letterSpacing: '-0.02em', fontWeight: '600' }],
+        'headline-md':['24px', { lineHeight: '32px', letterSpacing: '-0.01em', fontWeight: '600' }],
+        'headline-sm':['20px', { lineHeight: '28px', fontWeight: '600' }],
+        'body-lg':    ['18px', { lineHeight: '28px', fontWeight: '400' }],
+        'body-md':    ['16px', { lineHeight: '24px', fontWeight: '400' }],
+        'body-sm':    ['14px', { lineHeight: '20px', fontWeight: '400' }],
+        'label-md':   ['14px', { lineHeight: '20px', fontWeight: '500' }],
+        'label-sm':   ['12px', { lineHeight: '16px', letterSpacing: '0.01em', fontWeight: '500' }],
+      },
+      borderRadius: {
+        sm: '0.125rem',
+        DEFAULT: '0.25rem',
+        md: '0.375rem',
+        lg: '0.5rem',
+        xl: '0.75rem',
+        '2xl': '1rem',
+      },
+      boxShadow: {
+        // Soft, low-opacity, large-blur — never aggressive
+        card: '0 1px 2px 0 rgba(17, 24, 39, 0.04)',
+        elevated: '0 4px 12px -2px rgba(17, 24, 39, 0.08), 0 1px 2px rgba(17, 24, 39, 0.04)',
+        popover: '0 8px 24px -6px rgba(17, 24, 39, 0.12), 0 2px 4px rgba(17, 24, 39, 0.04)',
+        'focus-ring': '0 0 0 3px rgba(79, 70, 229, 0.18)',
+      },
+      transitionTimingFunction: {
+        'standard': 'cubic-bezier(0.2, 0, 0, 1)',
+      },
+      spacing: {
+        '13': '3.25rem',
+        '15': '3.75rem',
+      },
+    },
+  },
+  plugins: [],
+}

frontend/vite.config.js

@@ -0,0 +1,17 @@
+import { defineConfig } from 'vite'
+import react from '@vitejs/plugin-react'
+
+// Proxy /api/* to the FastAPI backend at 8000 so we don't fight CORS in dev.
+export default defineConfig({
+  plugins: [react()],
+  server: {
+    port: 5173,
+    proxy: {
+      '/api': {
+        target: 'http://localhost:8000',
+        changeOrigin: true,
+        rewrite: (path) => path.replace(/^\/api/, ''),
+      },
+    },
+  },
+})

requirements.txt

@@ -0,0 +1,36 @@
+# --- Web layer ---
+fastapi>=0.110
+uvicorn[standard]>=0.27
+python-multipart>=0.0.6
+python-dotenv>=1.0
+
+# --- Data layer ---
+sqlalchemy>=2.0
+# Use psycopg2-binary for Postgres. SQLite works out of the box for dev.
+psycopg2-binary>=2.9
+pydantic>=2.5
+pydantic-settings>=2.1
+
+# --- Ingestion / image ---
+pymupdf>=1.23
+pillow>=10.0
+numpy>=1.24
+opencv-python-headless>=4.9
+
+# --- LLM stack (agentic) ---
+anthropic>=0.40
+langchain>=0.3
+langchain-anthropic>=0.2
+langchain-google-genai>=2.0
+google-generativeai>=0.8
+langgraph>=0.2
+
+# --- Plagiarism / embeddings ---
+sentence-transformers>=2.5
+scikit-learn>=1.4
+
+# --- Optional: Qwen-VL via HuggingFace (requires GPU) ---
+# Uncomment to enable the qwen_vl adapter. Demo runs without these.
+# transformers>=4.45
+# torch>=2.2
+# accelerate>=0.30

scripts/init_db.py

@@ -0,0 +1,29 @@
+"""Initialize the database. Idempotent. Run once after install."""
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent.parent))
+
+from backend.db import init_db, SessionLocal, User
+
+
+def main():
+    init_db()
+    db = SessionLocal()
+    try:
+        if db.query(User).count() == 0:
+            db.add_all([
+                User(email="instructor@gradeops.local", name="Instructor", role="instructor"),
+                User(email="ta@gradeops.local", name="TA", role="ta"),
+            ])
+            db.commit()
+            print("seeded default users (instructor + ta)")
+        else:
+            print(f"db already has {db.query(User).count()} user(s); skipping seed")
+    finally:
+        db.close()
+    print("db ready")
+
+
+if __name__ == "__main__":
+    main()

scripts/run_demo.py

@@ -0,0 +1,126 @@
+"""Command-line walkthrough of the full grading pipeline.
+
+Usage:
+    python scripts/run_demo.py path/to/answer.jpg
+    python scripts/run_demo.py path/to/exam.pdf
+
+Prints a step-by-step trace of every phase: ingest → OCR → agentic grade
+→ aggregate. The trace is useful for showing the system working without
+the UI in the loop.
+"""
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent.parent))
+
+from backend.config import settings
+from backend.ingestion import (
+    split_pdf_to_pages, detect_answer_regions, crop_region, anonymize_crop,
+)
+from backend.ocr import transcribe as ocr_transcribe
+from backend.grader import grade_multi_pass, aggregate_scores
+
+
+SAMPLE_RUBRIC = {
+    "question_text": "Solve for x and show all steps:\n2x + 5 = 15",
+    "max_marks": 10,
+    "criteria": [
+        {"name": "Isolate the variable term", "points": 5,
+         "conditions": "Student writes 2x = 10.",
+         "accept_alternatives": "Equivalent rearrangements arriving at 2x = 10.",
+         "do_not_deduct_for": "Minor notation differences."},
+        {"name": "Solve for x", "points": 5,
+         "conditions": "Student writes x = 5.",
+         "accept_alternatives": "Equivalent forms.",
+         "do_not_deduct_for": "Minor notation differences."},
+    ],
+}
+
+
+def banner(text: str) -> None:
+    line = "─" * 70
+    print(f"\n{line}\n {text}\n{line}")
+
+
+def run(image_or_pdf: Path) -> None:
+    storage = settings.storage_path
+    banner(f"GradeOps demo · model={settings.grader_model} · OCR={settings.ocr_backend}")
+    print(f"input: {image_or_pdf}")
+
+    banner("Step 1 · Ingest")
+    if image_or_pdf.suffix.lower() == ".pdf":
+        pages = split_pdf_to_pages(str(image_or_pdf), str(storage / "pages"))
+        print(f"  split into {len(pages)} page(s)")
+    else:
+        pages = [str(image_or_pdf)]
+        print("  single image — no PDF split needed")
+
+    all_crops = []
+    for p in pages:
+        regions = detect_answer_regions(p)
+        print(f"  {Path(p).name}: detected {len(regions)} answer region(s)")
+        for r in regions:
+            raw = crop_region(p, r["bbox"], str(storage / "crops"))
+            anon = anonymize_crop(raw, str(storage / "crops"))
+            all_crops.append(anon)
+            print(f"    cropped → {Path(anon).name}")
+
+    banner("Step 2 · OCR")
+    for c in all_crops:
+        try:
+            t = ocr_transcribe(c)
+        except Exception as e:
+            t = f"[OCR failed: {e}]"
+        print(f"  {Path(c).name}:")
+        for line in t.splitlines()[:8]:
+            print(f"    | {line}")
+        if len(t.splitlines()) > 8:
+            print(f"    | ... [{len(t.splitlines()) - 8} more lines]")
+
+    banner(f"Step 3 · Agentic grading · {settings.grader_num_passes} pass(es)")
+    for c in all_crops:
+        print(f"\n  crop: {Path(c).name}")
+        passes = grade_multi_pass(
+            c,
+            question=SAMPLE_RUBRIC["question_text"],
+            max_marks=SAMPLE_RUBRIC["max_marks"],
+            criteria=SAMPLE_RUBRIC["criteria"],
+        )
+        for i, p in enumerate(passes, 1):
+            print(f"    pass {i}: {p['score']:.1f}/{p['max_score']:.0f}")
+        agg = aggregate_scores(passes)
+        print(f"    → median {agg['median']} · max {agg['max_score']} · min {agg['min_score']} · σ {agg['std_dev']:.2f}")
+        med = min(passes, key=lambda p: abs(p["score"] - agg["median"]))
+        print(f"    justification: {med['justification']}")
+
+    banner("done")
+
+
+def main():
+    if len(sys.argv) > 1:
+        target = Path(sys.argv[1]).expanduser().resolve()
+        if not target.exists():
+            print(f"file not found: {target}")
+            sys.exit(2)
+    else:
+        samples_dir = Path(__file__).resolve().parent.parent / "data" / "samples"
+        candidates = (
+            sorted(samples_dir.glob("*.png")) + sorted(samples_dir.glob("*.jpg")) +
+            sorted(samples_dir.glob("*.jpeg")) + sorted(samples_dir.glob("*.pdf"))
+        )
+        if not candidates:
+            print("Usage: python scripts/run_demo.py path/to/answer.{jpg,pdf}")
+            sys.exit(1)
+        target = candidates[0]
+
+    if not settings.google_api_key and not settings.anthropic_api_key:
+        print("ERROR: No API key configured. Set GOOGLE_API_KEY (or ANTHROPIC_API_KEY) in .env.")
+        sys.exit(3)
+
+    run(target)
+
+
+if __name__ == "__main__":
+    main()

scripts/seed_demo.py

@@ -0,0 +1,62 @@
+"""Seed a sample exam and rubric so a fresh install has something to show.
+
+Run once after init_db.py. Idempotent — skips if any exam exists.
+"""
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent.parent))
+
+from backend.db import SessionLocal, Exam, Rubric
+
+
+SAMPLE_RUBRIC_CRITERIA = [
+    {
+        "name": "Isolate the variable term",
+        "points": 5,
+        "conditions": "Student subtracts 5 from both sides to obtain 2x = 10.",
+        "accept_alternatives": "Equivalent algebraic rearrangements that arrive at 2x = 10.",
+        "do_not_deduct_for": "Minor handwriting or notation differences.",
+    },
+    {
+        "name": "Solve for x",
+        "points": 5,
+        "conditions": "Student divides both sides by 2 and obtains x = 5.",
+        "accept_alternatives": "Equivalent forms such as x=5 or x = 5.0.",
+        "do_not_deduct_for": "Minor notation differences.",
+    },
+]
+
+DEFAULT_INSTRUCTIONS = """Base all scoring strictly on evidence visible in the student's handwritten work. If evidence is missing, assign zero — do not guess, infer, or hallucinate.
+Award credit for intermediate steps only if explicitly written by the student. Do not infer non-trivial reasoning from a correct final answer except for trivial algebraic simplifications.
+If the student's solution does not match the question being asked, assign a score of 0."""
+
+
+def main():
+    db = SessionLocal()
+    try:
+        if db.query(Exam).count() > 0:
+            print("an exam already exists; skipping seed")
+            return
+
+        exam = Exam(title="Sample exam")
+        db.add(exam); db.commit(); db.refresh(exam)
+
+        rubric = Rubric(
+            exam_id=exam.id,
+            version="v1",
+            title="Linear equation — sample",
+            question_text="Solve for x and show all steps:\n\n2x + 5 = 15",
+            max_marks=10,
+            course_instructions=DEFAULT_INSTRUCTIONS,
+            criteria=SAMPLE_RUBRIC_CRITERIA,
+        )
+        db.add(rubric); db.commit(); db.refresh(rubric)
+        print(f"seeded exam #{exam.id} '{exam.title}'")
+        print(f"seeded rubric #{rubric.id} '{rubric.title}' ({rubric.version})")
+    finally:
+        db.close()
+
+
+if __name__ == "__main__":
+    main()