🎓 Adaptive Multi-Tool Learning Platform

An AI-powered tutoring backend that watches how students learn, picks the right problem to show next, and helps teachers spot who's struggling — all in real time.

---

The Three Actors

Who	What they do
🧑‍🎓 Student	Practices math problems. The system adapts to their level automatically.
👩‍🏫 Teacher	Reviews AI-generated feedback, approves intervention plans, checks class analytics.
🤖 AI Agents	A Tutor agent explains concepts to students. An Educator agent drafts lesson plans for teachers.

What's Inside Right Now

This is an MVP backend focused on one subject: Grade 6 Math — Fractions. It includes:

• 6 skills in a prerequisite chain (basic concepts → equivalent fractions → LCD → adding/subtracting)
• 12 practice problems with automatic grading
• Adaptive item selection — the system figures out what to practice next based on mastery + prerequisites
• AI-powered feedback — the Tutor agent writes encouraging, misconception-aware feedback
• Misconception detection — clusters common wrong answers so teachers can see patterns
• Full audit trail — every action is logged for accountability

---

🏗️ Project Structure

Project_with_LLM/
├── app/
│   ├── main.py          # FastAPI app wiring (thin — just registers routers)
│   ├── routes/           # API endpoints, organized by domain
│   │   ├── practice.py   #   Student practice attempts & next-item
│   │   ├── tutor.py      #   AI tutor explanations
│   │   ├── educator.py   #   AI interventions, feedback drafts, gradebook
│   │   ├── teacher.py    #   Teacher analytics (mastery, struggling students)
│   │   ├── lms.py        #   Mock LMS data import
│   │   └── health.py     #   Health checks & audit retrieval
│   ├── schemas.py        # Request/response models (what the API accepts & returns)
│   ├── domain.py         # Core data types (Student, Skill, etc.)
│   ├── models.py         # Database tables (SQLAlchemy ORM)
│   ├── learning.py       # Business logic: grading, mastery, adaptive engine
│   ├── agents.py         # AI agent definitions (Tutor + Educator)
│   ├── driver.py         # Runs the AI agents and parses their responses
│   ├── prompts.py        # The actual prompts sent to the AI
│   ├── tools.py          # Functions the AI can call (fetch materials, prerequisites)
│   ├── callbacks.py      # Policy checks, audit logging, idempotency
│   ├── auth.py           # Authentication (bearer tokens)
│   ├── lms.py            # Mock LMS adapter (simulates Google Classroom/Canvas)
│   ├── db.py             # Database setup (SQLite by default)
│   ├── settings.py       # Configuration from environment variables
│   ├── llm.py            # LLM model factory (Claude via LiteLLM)
│   └── static/           # Test console HTML
├── tests/                # Automated test suite (40+ tests)
├── pyproject.toml        # Python project config & dependencies
└── .env.example          # Example environment variables

---

🚀 Getting Started

Prerequisites

• Python 3.11+ — Download here
• An Anthropic API key — Get one here (needed only if you want to use the AI features)

Step 1: Clone & Install

# Clone the repo
git clone <your-repo-url>
cd Project_with_LLM

# Create a virtual environment
python -m venv .venv
source .venv/bin/activate    # On Windows: .venv\Scripts\activate

# Install dependencies
pip install -e ".[dev]"

Step 2: Set Up Environment

# Copy the example env file
cp .env.example .env

# If you want AI features, add your Anthropic API key:
# Open .env and add:  ANTHROPIC_API_KEY=sk-ant-...

Step 3: Run the Server

# Start the development server
uvicorn app.main:app --reload --port 8000

You should see:

INFO:     Uvicorn running on http://127.0.0.1:8000
INFO:     Started reloader process

🎉 That's it! Open your browser to http://localhost:8000 — you'll see the test console.

Step 4: Try It Out

The easiest way to explore is with the dev auth tokens. Start the server with:

ENABLE_DEV_AUTH=1 uvicorn app.main:app --reload --port 8000

Then use these pre-made tokens to call the API:

Token	Role	User
dev-teacher-t1	Teacher	t1
dev-student-s1	Student	s1
dev-admin-a1	Admin	a1

Example: Import mock course data (as a teacher)

curl -X POST http://localhost:8000/lms/mock_import \
  -H "Authorization: Bearer dev-teacher-t1" \
  -H "Content-Type: application/json" \
  -d '{"course_id": "math6-fractions"}'

Example: Submit a practice attempt (as a student)

curl -X POST http://localhost:8000/practice/attempts \
  -H "Authorization: Bearer dev-student-s1" \
  -H "Content-Type: application/json" \
  -d '{
    "student_id": "s1",
    "class_id": "math6-fractions",
    "skill_id": "fractions.add_unlike_denominators",
    "item_id": "pi-fractions-unlike-1",
    "submitted_answer": "7/12"
  }'

You can also browse the auto-generated API docs at http://localhost:8000/docs.

---

🧪 Running Tests

The project includes 40+ automated tests. No API key needed — the AI is mocked in tests.

python -m pytest tests/ -v

---

📚 API Endpoints at a Glance

For Students

Method	Endpoint	What it does
POST	/practice/attempts	Submit an answer to a practice problem
POST	/practice/next_item	Get the next best problem to practice

For Teachers

Method	Endpoint	What it does
POST	/tutor/explain	Ask the AI to explain a concept
POST	/educator/draft_intervention	Generate an AI intervention plan
POST	/educator/feedback_draft	Generate AI feedback for a student
POST	/educator/feedback_draft/{id}/approve	Approve an AI-written feedback
POST	/educator/gradebook_write	Write a grade to the LMS
GET	/classes/{id}/mastery	See mastery scores for a class
GET	/classes/{id}/skills/{id}/struggling_students	Find students below threshold
GET	/classes/{id}/skills/{id}/misconceptions	See common wrong answers

System

Method	Endpoint	What it does
POST	/lms/mock_import	Seed the database with sample data
GET	/healthz	Liveness check
GET	/readyz	Database readiness check
GET	/audit/{correlation_id}	View audit trail

---

⚙️ Configuration

All settings are controlled via environment variables:

Variable	Default	Description
DATABASE_URL	sqlite:///./adaptive_platform.db	Database connection string
ANTHROPIC_API_KEY	(none)	Required for AI features
CLAUDE_MODEL	anthropic/claude-sonnet-4-5	Which Claude model to use
ENABLE_DEV_AUTH	false	Enable pre-made dev tokens
APP_ENV	development	Set to production to disable auto table creation
LANGFUSE_PUBLIC_KEY	(none)	Optional: enable Langfuse tracing
LANGFUSE_SECRET_KEY	(none)	Optional: enable Langfuse tracing

---

🧠 How the Adaptive Engine Works

The magic happens in app/learning.py. Here's the simplified logic:

1. Mastery Tracking — Each student has a mastery score (0.0 to 1.0) per skill. Correct answers add +0.15, wrong answers subtract -0.05.

2. Prerequisite Graph — Skills form a chain. You can't practice "adding unlike denominators" until you've mastered "equivalent fractions" and "LCD".

   basic_concept ── equivalent ── lcd ── add_unlike ── subtract_unlike
                  └── add_like
   

3. Next Item Selection — When a student asks "what should I practice?":

   • Find all skills they haven't mastered yet
   • Check which ones have all prerequisites met → pick the lowest mastery one
   • If no skill is "ready", fall back to the unmet prerequisite with the lowest mastery

4. Misconception Detection — Groups wrong answers by frequency so teachers can see: "12 students answered 2/7 instead of 7/12 — they're adding numerators and denominators separately."

---

🛡️ Security Model

• Bearer token auth — every request requires an Authorization: Bearer <token> header
• Role-based access control — students can only submit their own attempts; teachers can draft interventions; only teachers can approve feedback or write grades
• Multi-tenant isolation — all data is scoped by tenant; a teacher from School A cannot see School B's data
• Audit trail — every operation is logged with correlation IDs for traceability

---

🤝 Contributing

1. Create a feature branch: git checkout -b feature/my-feature
2. Make your changes
3. Run tests: python -m pytest tests/ -v
4. Commit and push
5. Open a pull request

---

📄 License

This project is for educational and demonstration purposes.