# Project export: CurricuLearn

This document was generated by HackStack to give an AI agent context about a hackathon project. Sections are labeled with their provenance; content marked as truncated was cut to keep this document small.

## Project metadata

- Hackathon: UC Berkeley AI Hackathon 2026
- Tagline: CurricuLearn automatically rewrites lessons to maximize predicted learning outcomes by simulating cognitive responses and iteratively optimizing content.
- Devpost: https://devpost.com/software/curriculearn-24yxz9
- GitHub: https://github.com/jshaha/Curriculearn-
- Video: https://www.youtube.com/embed/Toeh2SYBiAI?enablejsapi=1&hl=en_US&rel=0&start=&version=3&wmode=transparent
- Team: 4 GitHub contributor(s) — jshaha (13 commits), Claude Sonnet 4.5 (7 commits), arham-siddiqui (7 commits), Hillary Kchao (3 commits)

## Devpost submission (written by the team)

### Inspiration

The New York Times published an article this past May with the headline claiming "U.S. Test Scores Are in a 'Generation-Long' Decline". These statistics are backed by teacher sentiment: nearly half of all teachers say that student engagement has declined compared with 2019 (Discovery Education, 2024). Teachers have no way to see inside a student's mind before a lesson fails them. Now, they can! CurricuLearn attacks this gap directly by asking a new question: what if we could simulate how curriculum feels to a student’s brain before it ever reaches the classroom? We applied TribeV2, Meta’s cutting-edge brain encoding model, in a novel educational context: the model predicts cognitive responses to uploaded lesson material and identifies weak points in the curriculum. Then, based on desired patterns of neural activity for the best learning experience possible, it iteratively optimizes the lesson for engagement, clarity, and overall learning.

### What it does

CurricuLearn is a curriculum optimization platform grounded in the science of learning. Teachers can upload educational resources (e.g. lesson plans, slideshows, worksheets, transcripts), and the system simulates how students would cognitively respond to it by scoring the lesson across five metrics: learning score, cognitive load, engagement, concept flow, and retention. Rather than simply providing feedback, CurricuLearn automatically rewrites weak sections: splitting dense content, inserting examples and knowledge checks, and generating better speaker notes. It then re-simulates the revised lesson and compares scores against the original to ensure a stronger solution.

### How we built it

We built CurricuLearn as a multi-agent curriculum optimization pipeline. First, we structured lesson content into individual sections so that each part of the lesson could be analyzed independently. From there, our system passes the lesson through a brain-simulation layer, translates the resulting representations into educational metrics, diagnoses weak points in the lesson, and automatically generates improved versions of the curriculum. Our original goal was to use TribeV2’s brain simulation capabilities to predict how students might cognitively respond to lesson material. However, because running full brain-response simulation was too computationally expensive for the hackathon environment, we built a lightweight proxy model that preserves the same core idea. Instead of producing full voxel-level brain activity, our prototype converts lesson segments into semantic embedding trajectories, treating each embedding as a simplified representation of a student’s cognitive state over time. We then built a metric translation layer employing Claude agents, which will map these representations into five interpretable learning metrics: learning score, cognitive load, engagement, concept flow, and retention. These scores allow the system to identify issues like overloaded sections, abrupt transitions, weak reinforcement, or material that introduces concepts too quickly. Finally, we designed an optimization loop to automatically improve the lesson. Using these diagnoses, Claude agents can split dense sections, insert transitions, add review questions, generate examples, and restructure content. After each rewrite, the lesson can be re-evaluated and scored again, allowing CurricuLearn to search for a version of the curriculum that is predicted to be more engaging, understandable, and effective. Although our hackathon prototype uses a lightweight approximation instead of the full TribeV2 model, we built the architecture around the same interface: lesson content goes in, simulated cognitive responses come out, and those responses drive automatic curriculum improvement. This lets us demonstrate the full CurricuLearn workflow now while leaving a clear path to swap in TribeV2’s brain simulation system as the backend when more compute is available.

### Challenges we ran into

Compute constraints: TribeV2's full simulation required more disk/compute than our laptops could support. We pivoted to the lightweight embedding-based proxy described above, preserving the same architecture and interface. Balancing depth with usability: Our users are teachers, not engineers, so the dashboard needed to explain a technical process without overwhelming them. We iterated on the UI multiple times to keep it informative but clean. The particle visualization: Building a Next.js animation to represent the background cognitive simulation was technically tricky to get smooth, but it made the optimization process feel tangible rather than like a black box.

### Accomplishments we're proud of

We built more than a lesson generator: CurricuLearn evaluates why a lesson would or wouldn't work cognitively, then closes the loop by rewriting and re-scoring it. We preserved the intent of brain-based optimization despite real compute limits, made a technically dense system feel approachable for non-technical users, and finalized a full end-to-end flow: upload → simulate → score → rewrite → re-score. Ethical considerations Because CurricuLearn touches simulated neural data and automated assessment of teachers' work, we treated a few principles as non-negotiable: No conflating simulated and real data: Every score in the UI is explicitly tagged as coming from our proxy model, never presented as an actual student's biometric reading. As we integrate TribeV2's real backend, this distinction will remain visible to users. Minimal, non-identifying data: The pipeline only ever produces coarse, named metrics (e.g., "cognitive load: 0.7"). In the case that we do obtain real student neural data to improve our model, we will not have raw signals tied to an individual student. Human-in-the-loop, not human-replaced: Claude simply suggests and rewrites. It doesn't make unilateral decisions about a teacher's curriculum or a student's ability, since teachers see why a change was made and retain full control to accept or reject it. Awareness of compute cost: Re-simulating a lesson on every optimization pass isn't free. We kept our proxy lightweight specifically to avoid the environmental cost of brute-force re-running large models on every iteration, and see real efficiency tradeoffs as part of the eventual TribeV2 integration, not an afterthought. Open questions we haven't solved yet: consent and data governance for real student neural data, and bias testing for the LLM's rewriting decisions, are both necessary before any real deployment, and we see them as our next milestone.

### What we learned

We learned how to design an AI system around a real optimization loop rather than a single generation step. Hitting TribeV2's compute wall taught us to build around a stable interface so a backend swap doesn't require a redesign. We also learned to translate raw model outputs into metrics non-technical users can actually act on, and how to keep iterating on a UI for an audience.

### What's next

Integrate TribeV2's full brain simulation once compute allows, replacing our proxy with richer neural representations. Support more material types: lecture transcripts, videos, diagrams. Generate and compare multiple candidate rewrites per lesson, not just one. Incorporate real student feedback and outcome data to validate and improve scoring accuracy over time. Build out the consent and data-governance framework needed before any real neural data is used.

## README (from the GitHub repository)

# Curriculearn

**AI-powered curriculum optimization using science-backed, simulated cognitive response.**

CurricuLearn takes a lesson — a PDF, a PowerPoint, a Word doc, or plain text — and answers a question teachers normally can't answer until they're already standing in front of a class: *where, exactly, does this lesson lose a student's mind?*

It does this by converting each lesson segment into a semantic "brain state," scoring that state against five learning metrics, automatically diagnosing the weak points, rewriting them, and re-scoring — in a loop — until the lesson's predicted learning score stops improving.

---

## Table of contents

- [What it does](#what-it-does)
- [Architecture](#architecture)
- [Repository structure](#repository-structure)
- [Getting started](#getting-started)
- [Walkthrough: four ways to use this repo](#walkthrough-four-ways-to-use-this-repo)
- [The metrics, explained](#the-metrics-explained)
- [The agent pipeline, in detail](#the-agent-pipeline-in-detail)
- [Deterministic vs. Claude-powered agents](#deterministic-vs-claude-powered-agents)
- [Testing](#testing)
- [Deployment](#deployment)
- [Known gaps and rough edges](#known-gaps-and-rough-edges)
- [License](#license)

---

## What it does

```
Lesson file  →  Brain Simulation  →  Learning Metrics  →  Diagnosis  →  AI Rewrite  →  Re-simulate  →  Improved Lesson
```

Instead of generating lesson content from scratch, CurricuLearn takes a lesson you already have and **optimizes it against a model of how a student's mind would move through it** — flagging cognitive overload, abrupt topic jumps, missing reinforcement, and low engagement stretches, then rewriting those specific spots and checking whether the rewrite actually helped before keeping it.

## Architecture

```
                         ┌──────────────────────────────┐
                         │   Lesson file (.pdf/.pptx/    │
                         │   .docx/.txt/raw text)        │
                         └───────────────┬──────────────┘
                                         ↓
                         Agent 1 — Curriculum Parser
                         extracts + segments lesson text
                                         ↓
                         Agent 2 — Brain Simulator
                         384-dim semantic embedding per segment
                                         ↓
                         Agent 3 — Metric Translator
                         engagement / cognitive load / concept flow /
                         retention / learning score + flagged segments
                                         ↓
                         Agent 4 — Educational Diagnostician
                         turns metrics into prioritized diagnoses
                                         ↓
                         Agent 5 — Curriculum Editor
                         generates a rewritten lesson candidate
                                         ↓
                         Agent 6 — Optimizer
                  ┌──────── re-simulate candidate, keep if score improves ────────┐
                  │                                                              │
                  └───────────────────────  loop until convergence  ─────────────┘
                                         ↓
                         Agent 7 — Visualization Generator (optional)
                         generates supporting diagrams for weak segments
                                         ↓
                         Optimized lesson + before/after metrics + edit history
```

The REST API (`backend/api_server.py`) wraps this whole pipeline; the Next.js frontend (`frontend-next/`) calls that API and renders the result as a 3D brain visualization with per-section breakdowns of learning, cognitive load, engagement, concept flow, and retention.

## Repository structure

```
Curriculearn-/
├── src/                                 # "Brain simulation" half of the pipeline
│   ├── agents/
│   │   ├── curriculum_parser.py         # Agent 1
│   │   ├── brain_simulator.py           # Agent 2
│   │   └── metric_translator.py         # Agent 3
│   └── adapters/
│       └── brain_simulator_adapter.py   # Bridges src/ agents into backend/ schema
│
├── backend/                             # API + optimization loop
│   ├── api_server.py                    # Flask REST API (the main entry point)
│   ├── start_server.py-equivalent paths handled by /start_server.py at repo root
│   └── neurocompiler/                   # Installable package (pyproject.toml)
│       ├── agents/
│       │   ├── diagnostician.py         # Agent 4 (deterministic)
│       │   ├── curriculum_editor.py     # Agent 5 (deterministic)
│       │   ├── optimizer.py             # Agent 6
│       │   ├── visualization_generator.py  # Agent 7
│       │   └── claude/                  # Claude-powered Agent 4 & 5 variants
│       ├── adapters/                    # Simulator interface + MockSimulator
│       ├── schemas.py                   # Pydantic data contracts (StructuredLesson, MetricReport, etc.)
│       ├── scoring.py                   # Learning score weighting
│       ├── cli.py                       # Local demo CLI (mock-simulator backed)
│       ├── data/                        # Sample lessons + sample metric reports
│       └── tests/                       # pytest suite for the backend package
│
├── frontend-next/                       # Active frontend (Next.js + Three.js)
│   ├── app/                             # class list → /class/[id] brain view
│   ├── three/                           # 3D brain scene, point cloud, region data
│   ├── content/sections.ts              # Maps brain sections → the 5 metrics
│   └── STRUCTURE.md                     # Frontend's own structure notes
│
├── frontend-new/                        # Earlier, simpler prototype UI (not deployed)
│
├── examples/                            # Standalone runnable demos
│   ├── basic_pipeline.py
│   ├── full_pipeline_demo.py
│   ├── photosynthesis_demo.py
│   └── test_parser.py
│
├── test_files/                          # Sample lessons with intentionally seeded issues
│   ├── photosynthesis_lesson.html
│   ├── bayes_theorem_lesson.html
│   └── sample_lesson.txt
│
├── docs/
│   ├── PRODUCT_SPEC.md                  # Original product vision
│   ├── AGENT_INTERFACE_SPEC.md          # Inter-agent data contract
│   ├── FRONTEND_DESIGN.md / FRONTEND_IMPLEMENTATION.md
│   ├── VISUALIZATION_AGENT.md
│   └── PARTNER_INTEGRATION_TODO.md
│
├── archived_old_code/                   # Legacy prototype frontend + early scripts (reference only)
│
├── run_full_optimization.py             # Root-level script: real end-to-end pipeline run
├── start_server.py                      # Convenience launcher for the API server
├── Introduction to Photosynthesis - Lesson Plan.pdf   # Sample input file
├── optimization_result.json             # A committed sample output from a real run
├── requirements.txt                     # Python dependencies
├── pyproject.toml                       # Packaging config for backend/curriculearn
└── render.yaml                          # Render.com deployment config (backend + frontend)
```

## Getting started

### Prerequisites

- Python 3.10+
- Node.js 20+ (only needed if you're running `frontend-next`)
- ~80MB free for the sentence-transformer model (downloaded automatically on first run)

### Install backend dependencies

```bash
pip install -r requirements.txt
```

This installs Flask, the sentence-transformers/torch stack (Agent 2), document parsers (Agent 1), and the Anthropic SDK (for the optional Claude-powered Agents 4/5).

To also install the `neurocompiler` backend package itself (needed for the test suite and CLI):

```bash
pip install -e ".[dev]"
```

### Environment variables

Create a `.env` file in the repo root if you want the optional integrations. Everything below is optional — the core pipeline (Agents 1–3 and 6, with deterministic Agents 4–5) runs with no API keys at all.

| V

[README truncated for size]

## Detected evidence (automated analysis)

Indexed codebase: 252 recognized source files, 1396 KB.
- Anthropic (technology) — detected in the code
- CSS (language) — detected in the code
- Flask (technology) — detected in the code
- HTML (language) — detected in the code
- JavaScript (language) — detected in the code
- Next.js (technology) — detected in the code
- Python (language) — detected in the code
- PyTorch (technology) — detected in the code
- React (technology) — detected in the code
- Supabase (technology) — detected in the code
- Tailwind CSS (technology) — detected in the code
- TypeScript (language) — detected in the code
- AI coding agent: Claude Code — evidence: config files committed to the repository; commit authorship or trailers
- AI coding agent: Codex — evidence: config files committed to the repository

## Codebase structure (from repository index)

### Files (120 of 285)

```
.DS_Store
.gitignore
.mcp.json
AGENT1_COMPLETE.md
archived_old_code/AGENT_OUTPUTS.md
archived_old_code/agent_pipeline_walkthrough.py
archived_old_code/COGNITIVE_LOAD_BUG_REPORT.md
archived_old_code/frontend/.DS_Store
archived_old_code/frontend/app/class/[id]/lesson/[lessonId]/page.tsx
archived_old_code/frontend/app/class/[id]/page.tsx
archived_old_code/frontend/app/globals.css
archived_old_code/frontend/app/layout.tsx
archived_old_code/frontend/app/page.tsx
archived_old_code/frontend/components.json
archived_old_code/frontend/components/agent-suggestions.tsx
archived_old_code/frontend/components/app-header.tsx
archived_old_code/frontend/components/brain-activation.tsx
archived_old_code/frontend/components/brain-map-3d.tsx
archived_old_code/frontend/components/brain/BrainCanvas.tsx
archived_old_code/frontend/components/brain/BrainHighlightOverlay.tsx
archived_old_code/frontend/components/brain/brainPhysics.ts
archived_old_code/frontend/components/brain/BrainPoints.tsx
archived_old_code/frontend/components/brain/brainSampling.ts
archived_old_code/frontend/components/brain/brainShared.ts
archived_old_code/frontend/components/brain/brainSpots.ts
archived_old_code/frontend/components/brain/brainTuning.ts
archived_old_code/frontend/components/brain/types.ts
archived_old_code/frontend/components/class-brain-overview.tsx
archived_old_code/frontend/components/class-detail.tsx
archived_old_code/frontend/components/class-form-dialog.tsx
archived_old_code/frontend/components/ClassBrainHero.tsx
archived_old_code/frontend/components/dashboard.tsx
archived_old_code/frontend/components/lesson-detail-page.tsx
archived_old_code/frontend/components/lesson-form-dialog.tsx
archived_old_code/frontend/components/lesson-resources.tsx
archived_old_code/frontend/components/lesson-status-badge.tsx
archived_old_code/frontend/components/planner-provider.tsx
archived_old_code/frontend/components/timeline-lesson-card.tsx
archived_old_code/frontend/components/ui/badge.tsx
archived_old_code/frontend/components/ui/button.tsx
archived_old_code/frontend/components/ui/card.tsx
archived_old_code/frontend/components/ui/dialog.tsx
archived_old_code/frontend/components/ui/dropdown-menu.tsx
archived_old_code/frontend/components/ui/input.tsx
archived_old_code/frontend/components/ui/label.tsx
archived_old_code/frontend/components/ui/select.tsx
archived_old_code/frontend/components/ui/separator.tsx
archived_old_code/frontend/components/ui/sonner.tsx
archived_old_code/frontend/components/ui/tabs.tsx
archived_old_code/frontend/components/ui/textarea.tsx
archived_old_code/frontend/components/week-calendar.tsx
archived_old_code/frontend/index.html
archived_old_code/frontend/lib/api-client.ts
archived_old_code/frontend/lib/planner-data.ts
archived_old_code/frontend/lib/utils.ts
archived_old_code/frontend/next-env.d.ts
archived_old_code/frontend/next.config.mjs
archived_old_code/frontend/package.json
archived_old_code/frontend/pnpm-workspace.yaml
archived_old_code/frontend/postcss.config.mjs
archived_old_code/frontend/public/assets/brain/cortex.glb
archived_old_code/frontend/public/assets/brain/lh_pial.obj
archived_old_code/frontend/public/assets/brain/rh_pial.obj
archived_old_code/frontend/README.md
archived_old_code/frontend/styles/main.css
archived_old_code/frontend/tsconfig.json
archived_old_code/frontend/utils/animations.js
archived_old_code/frontend/utils/app-mock.js
archived_old_code/frontend/utils/app.js
archived_old_code/frontend/utils/neural-bg.js
archived_old_code/simple_walkthrough.py
archived_old_code/test_all_metrics.py
archived_old_code/test_lesson.txt
archived_old_code/test_sentence_transformer.py
backend/api_server.py
backend/clean_lesson_content.py
backend/json_to_html.py
backend/json_to_slides.py
backend/neurocompiler/__init__.py
backend/neurocompiler/adapters/__init__.py
backend/neurocompiler/adapters/external_simulator.py
backend/neurocompiler/adapters/json_metric_simulator.py
backend/neurocompiler/adapters/mock_simulator.py
backend/neurocompiler/adapters/simulator.py
backend/neurocompiler/agents/__init__.py
backend/neurocompiler/agents/claude/__init__.py
backend/neurocompiler/agents/claude/base.py
backend/neurocompiler/agents/claude/config.py
backend/neurocompiler/agents/claude/curriculum_editor.py
backend/neurocompiler/agents/claude/diagnostician.py
backend/neurocompiler/agents/claude/prompts/__init__.py
backend/neurocompiler/agents/claude/prompts/diagnostician_prompt.py
backend/neurocompiler/agents/claude/prompts/editor_prompt.py
backend/neurocompiler/agents/claude/tools/__init__.py
backend/neurocompiler/agents/claude/tools/diagnostician_tools.py
backend/neurocompiler/agents/claude/tools/editor_tools.py
backend/neurocompiler/agents/curriculum_editor.py
backend/neurocompiler/agents/diagnostician.py
backend/neurocompiler/agents/optimizer.py
backend/neurocompiler/agents/visualization_generator.py
backend/neurocompiler/cli.py
backend/neurocompiler/data/optimized_lesson.json
backend/neurocompiler/data/partner_metric_report_sample.json
backend/neurocompiler/data/sample_lesson.json
backend/neurocompiler/data/sample_metric_report.json
backend/neurocompiler/schemas.py
backend/neurocompiler/scoring.py
backend/neurocompiler/tests/test_cli.py
backend/neurocompiler/tests/test_diagnostician.py
backend/neurocompiler/tests/test_editor.py
backend/neurocompiler/tests/test_imports.py
backend/neurocompiler/tests/test_json_metric_simulator.py
backend/neurocompiler/tests/test_optimizer.py
backend/neurocompiler/tests/test_packaging.py
backend/neurocompiler/tests/test_schemas.py
backend/pdf_export/__init__.py
backend/pdf_export/lesson_to_markdown.py
backend/pdf_export/README.md
BRAIN_INTEGRATION_PLAN.md
claude_optimization_result.json
[165 more files omitted for size]
```

### Dependencies

- archived_old_code/frontend/package.json: @base-ui/react@^1.5.0, @react-three/fiber@^9.6.1, @tailwindcss/postcss@^4.2.0, @types/node@^24, @types/react@^19.2.17, @types/react-dom@^19.2.3, @types/three@^0.170.0, @vercel/analytics@1.6.1, class-variance-authority@^0.7.1, clsx@^2.1.1, lucide-react@^1.16.0, next@^15.5.19, next-themes@^0.4.6, postcss@^8.5, react@^19.2.7, react-dom@^19.2.7, shadcn@^4.8.0, sonner@^2.0.7, tailwind-merge@^3.3.1, tailwindcss@^4.2.0, three@^0.170.0, tw-animate-css@^1.4.0, typescript@5.7.3
- frontend-new/package.json: @types/node@^22, @types/react@^19, @types/react-dom@^19, next@15.1.6, postcss@^8, react@^19, react-dom@^19, tailwindcss@^3.4.1, typescript@^5
- frontend-next/package.json: @react-three/drei@^10.7.7, @react-three/fiber@^9.6.1, @supabase/supabase-js@^2.110.0, @tailwindcss/postcss@^4, @types/node@^20, @types/react@^19, @types/react-dom@^19, eslint@^9, eslint-config-next@16.2.9, framer-motion@^12.40.0, next@16.2.9, react@19.2.4, react-dom@19.2.4, react-markdown@^10.1.0, tailwindcss@^4, three@^0.184.0, typescript@^5, zustand@^5.0.14
- pyproject.toml: pydantic@>=2.0, pytest@>=8.0
- requirements.txt: anthropic@>=0.40.0, flask@>=3.0.0, flask-cors@>=4.0.0, gunicorn@>=21.0.0, numpy@>=1.24.0, pydantic@>=2.0.0, pypdf@>=3.0.0, python-docx@>=1.0.0, python-dotenv@>=1.0.0, python-pptx@>=0.6.21, requests@>=2.31.0, scipy@>=1.10.0, sentence-transformers@>=2.7.0, torch@>=2.0.0

### Recent commits (newest first)

- Strip trailing slash from API base URL to fix //api double-slash upload failure
- fixed supabase race
- Add gunicorn threads so health checks don't time out during inference
- Improve CORS config and wake backend on frontend load
- Wake up backend on page load to handle Render free tier spin-down
- fix agents use
- Merge remote-tracking branch 'origin/main'
- Migrate to Supabase (Postgres + anonymous auth) for multi-user support
- Fix build and harden Render deployment config
- updated README v3
- updated README v2
- updated README
- Add content-aware Claude agents and persistent storage
- Configure Render services for free tier deployment
- Setup Render deployment and add Claude agents
- Add complete accordion layout and document upload flow
- Reorganize file structure - archive unused portfolio files
- Merge branch 'main' of github.com:jshaha/Curriculearn-
- Integrate brain visualization with class-based navigation
- new frontend

## Key source files (fetched from GitHub, selected and truncated for size)

### CONNECT_FRONTEND.md

```markdown
# Connect Frontend to Backend

## What Changed

The other Claude session built the complete backend with all 6 agents working. Now we need to connect your frontend to it.

## Setup (2 minutes)

### Step 1: Update Frontend to Use API

```bash
cd frontend
# Replace the mock app.js with connected version
cp utils/app-connected.js utils/app.js
```

### Step 2: Start the API Server

```bash
# From project root
python backend/api_server.py
```

You should see:
```
NeuroCompiler API Server
Real Brain Simulation + Curriculum Optimization
Starting server on http://localhost:5000
```

### Step 3: Open Frontend

```bash
cd frontend
open index.html
```

## How It Works Now

### Full Flow:
1. **Upload PDF** → API parses it
2. **Select objectives** → Stored for optimization
3. **Analyze** → Real brain simulation runs (sentence transformers)
4. **View metrics** → Real cognitive load, engagement, etc.
5. **Generate optimized** → Runs full optimization loop (Agents 4-6)
6. **Download result** → Get improved lesson as JSON

### API Endpoints Used:

| Endpoint | Purpose |
|----------|---------|
| `POST /api/upload` | Upload lesson file |
| `POST /api/analyze/<id>` | Run brain simulation |
| `POST /api/optimize/<id>` | Run optimization loop |
| `GET /api/result/<id>` | Get optimization results |
| `GET /api/download/<id>` | Download optimized lesson |

## Test It

1. Open frontend: `http://localhost:8000` (or just open index.html)
2. Upload your `Introduction to Photosynthesis.pdf`
3. Select objectives (e.g., "Maximize Learning" + "Reduce Cognitive Overload")
4. Watch it analyze (takes ~5-10 seconds for brain simulation)
5. See real metrics appear
6. Click "Generate Optimized Lesson" (takes ~20-30 seconds)
7. View before/after comparison with real scores!

## What's Real vs Mock

### Real (Using API):
✅ File upload and parsing
✅ Brain simulation (sentence transformers)
✅ Metric calculation (cognitive load, engagement, etc.)
✅ Issue detection
✅ Optimization loop
✅ Score improvements

### Still Mock (Just UI):
❌ Slide preview images (shows placeholder content)
❌ Timeline chart (shows dummy data)
❌ Some UI animations

## Troubleshooting

**"Upload failed"**
- Make sure API server is running: `python backend/api_server.py`
- Check it's on port 5000: `http://localhost:5000/health`

**"CORS error"**
- API has CORS enabled, should work
- If still issues, serve frontend via http-server instead of file://

**"Analysis takes forever"**
- First run downloads sentence transformer model (~80MB)
- Subsequent runs are much faster (~5-10 seconds)

**"Optimization failed"**
- Check API server console for errors
- Make sure all dependencies installed: `pip install -r requirements.txt`

## Development

### Frontend Changes
Edit `frontend/utils/app-connected.js` to modify API integration

### Backend Changes
Edit `backend/api_server.py` to add/modify endpoints

### Test Locally
```bash
# Terminal 1: Start API
python backend/api_server.py

# Terminal 2: Serve frontend (optional)
cd fron
[truncated — 469 more characters]
```

### AGENT1_COMPLETE.md

```markdown
# Agent 1: Curriculum Parser - COMPLETE ✅

## What It Does

The Curriculum Parser extracts and structures lesson content from various document formats into a format ready for brain simulation.

## Supported Formats

✅ **PDF Files** (.pdf)
- Lesson plans
- Worksheets
- Reading passages
- Extracts text page by page
- Segments by paragraphs

✅ **PowerPoint** (.pptx)
- Presentations
- Lecture slides
- Extracts text from each slide
- Preserves slide structure

✅ **Word Documents** (.docx)
- Documents
- Lesson plans
- Extracts paragraphs
- Identifies headings vs content

✅ **Plain Text** (.txt)
- Transcripts
- Passages
- Notes
- Segments by paragraphs or sentences

✅ **Raw Text**
- Pasted content
- Transcripts
- Custom segmentation options

## Usage

### Parse a File

```python
from agents import CurriculumParser

parser = CurriculumParser()

# Parse any supported file
lesson = parser.parse("lesson.pdf")      # PDF
# OR
lesson = parser.parse("slides.pptx")     # PowerPoint
# OR
lesson = parser.parse("notes.txt")       # Text file
# OR
lesson = parser.parse("document.docx")   # Word doc

# What you get back:
{
    'sections': [
        "Lesson segment 1 text...",
        "Lesson segment 2 text...",
        ...
    ],
    'metadata': {
        'filename': 'lesson.pdf',
        'format': '.pdf',
        'num_sections': 15
    },
    'source_type': 'pdf'
}
```

### Parse Raw Text

```python
# For transcripts or pasted content
lesson = parser.parse_text(
    text="Your lesson content here...",
    segment_by='paragraph'  # or 'sentence', 'line'
)
```

### Preview Parsed Content

```python
# See what was extracted
print(parser.get_preview(lesson, max_sections=5))
```

## Features

### Intelligent Segmentation
- Automatically splits content into meaningful segments
- Filters out noise (page numbers, headers, footers)
- Preserves structure (slides, paragraphs, sections)

### Clean Output
- Removes extra whitespace
- Filters very short segments
- Standardizes text format

### Metadata Tracking
- Keeps track of source file
- Maintains page/slide numbers
- Identifies section types (headings vs paragraphs)

## Full Pipeline Integration

```python
from agents import CurriculumParser, BrainSimulator, MetricTranslator

# Complete pipeline
parser = CurriculumParser()
brain_sim = BrainSimulator()
metric_translator = MetricTranslator()

# 1. Parse lesson file
lesson_content = parser.parse("photosynthesis_lesson.pptx")

# 2. Generate brain states
brain_states = brain_sim.simulate(lesson_content)

# 3. Compute educational metrics
metrics = metric_translator.translate(brain_states)

print(f"Learning Score: {metrics['learning_score']:.1f}/100")
```

## Example Output

### Input File
`photosynthesis.txt` (19 paragraphs)

### Parsed Output
```python
{
    'sections': [
        "Today we will explore one of nature's most important processes...",
        "What is Photosynthesis?",
        "Photosynthesis is the process by which plants convert light...",
        "The Basic Equat
[truncated — 1361 more characters]
```

### pyproject.toml

```
[build-system]
requires = ["setuptools>=68", "wheel"]
build-backend = "setuptools.build_meta"

[project]
name = "curriculearn-neurocompiler"
version = "0.1.0"
description = "Model-agnostic curriculum optimization agents for Curriculearn."
readme = "README.MD"
requires-python = ">=3.10"
dependencies = ["pydantic>=2.0"]

[project.optional-dependencies]
dev = ["pytest>=8.0"]

[tool.setuptools.packages.find]
where = ["backend"]

[tool.pytest.ini_options]
testpaths = ["backend/neurocompiler/tests"]
pythonpath = ["backend"]

```

### requirements.txt

```
# Install CPU-only torch wheels (smaller; fits Render's free tier disk/RAM).
# PyPI's default Linux torch wheel bundles CUDA libs (~2GB) which is unnecessary here.
--extra-index-url https://download.pytorch.org/whl/cpu

# Web server
flask>=3.0.0
flask-cors>=4.0.0
gunicorn>=21.0.0
requests>=2.31.0

# Data models
pydantic>=2.0.0

# ML/AI dependencies
sentence-transformers>=2.7.0
numpy>=1.24.0
scipy>=1.10.0
torch>=2.0.0

# Agent 1: Document parsing
pypdf>=3.0.0
python-pptx>=0.6.21
python-docx>=1.0.0

# Claude-powered agents (Agent 4 & 5)
anthropic>=0.40.0
python-dotenv>=1.0.0

```

### frontend-new/package.json

```
{
  "name": "teacher-classes",
  "version": "0.1.0",
  "private": true,
  "scripts": {
    "dev": "next dev",
    "build": "next build",
    "start": "next start",
    "lint": "next lint"
  },
  "dependencies": {
    "next": "15.1.6",
    "react": "^19",
    "react-dom": "^19"
  },
  "devDependencies": {
    "@types/node": "^22",
    "@types/react": "^19",
    "@types/react-dom": "^19",
    "postcss": "^8",
    "tailwindcss": "^3.4.1",
    "typescript": "^5"
  }
}

```

### frontend-next/package.json

```
{
  "name": "frontend-next",
  "version": "0.1.0",
  "private": true,
  "scripts": {
    "dev": "next dev",
    "build": "next build",
    "start": "next start",
    "lint": "eslint"
  },
  "dependencies": {
    "@react-three/drei": "^10.7.7",
    "@react-three/fiber": "^9.6.1",
    "@supabase/supabase-js": "^2.110.0",
    "framer-motion": "^12.40.0",
    "next": "16.2.9",
    "react": "19.2.4",
    "react-dom": "19.2.4",
    "react-markdown": "^10.1.0",
    "three": "^0.184.0",
    "zustand": "^5.0.14"
  },
  "devDependencies": {
    "@tailwindcss/postcss": "^4",
    "@types/node": "^20",
    "@types/react": "^19",
    "@types/react-dom": "^19",
    "eslint": "^9",
    "eslint-config-next": "16.2.9",
    "tailwindcss": "^4",
    "typescript": "^5"
  }
}

```

### archived_old_code/frontend/package.json

```
{
  "name": "my-project",
  "version": "0.1.0",
  "private": true,
  "scripts": {
    "dev": "next dev",
    "build": "next build",
    "start": "next start",
    "lint": "eslint ."
  },
  "dependencies": {
    "@base-ui/react": "^1.5.0",
    "@react-three/fiber": "^9.6.1",
    "@vercel/analytics": "1.6.1",
    "class-variance-authority": "^0.7.1",
    "clsx": "^2.1.1",
    "lucide-react": "^1.16.0",
    "next": "^15.5.19",
    "next-themes": "^0.4.6",
    "react": "^19.2.7",
    "react-dom": "^19.2.7",
    "shadcn": "^4.8.0",
    "sonner": "^2.0.7",
    "tailwind-merge": "^3.3.1",
    "three": "^0.170.0",
    "tw-animate-css": "^1.4.0"
  },
  "devDependencies": {
    "@tailwindcss/postcss": "^4.2.0",
    "@types/node": "^24",
    "@types/react": "^19.2.17",
    "@types/react-dom": "^19.2.3",
    "@types/three": "^0.170.0",
    "postcss": "^8.5",
    "tailwindcss": "^4.2.0",
    "typescript": "5.7.3"
  }
}

```

### frontend-new/app/page.tsx

```typescript
import { redirect } from "next/navigation"

export default function Home() {
  redirect("/teacher-class")
}

```

### frontend-new/app/layout.tsx

```typescript
import type { Metadata } from "next"
import "./globals.css"

export const metadata: Metadata = {
  title: "Teacher Classes",
  description: "Minimalist class management",
}

export default function RootLayout({
  children,
}: {
  children: React.ReactNode
}) {
  return (
    <html lang="en">
      <body>{children}</body>
    </html>
  )
}

```

### frontend-next/app/layout.tsx

```typescript
import type { Metadata } from "next";
import type { ReactNode } from "react";

import { AuthGate } from "@/components/AuthGate";
import { PageTransitionOverlay } from "@/components/PageTransitionOverlay";
import { TransitionProvider } from "@/components/TransitionProvider";
import { siteContent } from "@/content/siteContent";

import "./globals.css";

export const metadata: Metadata = {
  title: siteContent.siteConfig.seo.title,
  description: siteContent.siteConfig.seo.description,
  keywords: siteContent.siteConfig.seo.keywords,
  applicationName: siteContent.siteConfig.name
};

export default function RootLayout({ children }: Readonly<{ children: ReactNode }>) {
  return (
    <html lang="en">
      <body>
        <TransitionProvider>
          <PageTransitionOverlay />
          <AuthGate>{children}</AuthGate>
        </TransitionProvider>
      </body>
    </html>
  );
}

```

[239 more indexed source files omitted to keep this export small. The full file list is in the Codebase structure section above.]