ExamCram

ExamCram is a local AI-driven exam study system for material-grounded teaching, review, and problem solving.

It is designed around three levels of workflow:

• Home: configure OpenRouter, choose a default model, and manage workspaces.
• Workspace: upload course materials, update the knowledge base, inspect extracted knowledge points, and create focused teaching conversations.
• Conversation: learn through professor cards, answer checkpoint questions, ask the TA for help, and track progress.

Current Capabilities

• Workspace-based material libraries with manual document refresh
• Automatic knowledge point extraction and lightweight course admin info extraction
• Teaching conversations scoped by module, knowledge point, or material
• Knowledge-point teaching cards with checkpoint questions and grading
• TA side panel with contextual answers
• Review overview and problem-solving workspace tools
• OpenRouter model detection with graceful fallback
• Light and dark theme support

Tech Stack

• FastAPI
• Jinja2
• Tailwind CSS
• SQLModel + SQLite
• ChromaDB
• PyMuPDF
• OpenRouter

Project Structure

app/
  llm/          OpenRouter client and prompt loading
  models/       SQLModel tables
  routers/      FastAPI routes
  services/     Workspace, teaching, TA, review, and problem services
  templates/    Jinja templates for home, workspace, and conversation pages
static/
  css/          App-level visual system
prompts/        System prompts for professor, TA, and problem solver flows
data/           Local runtime data, generated files, vector store, and uploads

Quick Start

1. Install dependencies

uv sync

If you do not use uv, a standard virtual environment also works:

python -m venv .venv
source .venv/bin/activate
pip install -e .

2. Start the app

uv run uvicorn app.main:app --reload

Or use the one-command local dev script:

./scripts/dev.sh

Then open:

• http://127.0.0.1:8000

3. Configure OpenRouter

From the home page:

• add your OpenRouter API key
• choose a default model from the dropdown
• optionally add a global prompt supplement

OpenRouter uses the standard API base internally, so the app does not require a custom base URL in normal use.

Recommended Workflow

1. Create a workspace for one course.
2. Upload slides, syllabus, subtitles, and exam materials.
3. Click 更新文档 to refresh the knowledge base.
4. Inspect extracted knowledge points and course admin info.
5. Create a teaching conversation for a specific module or topic.
6. Study through cards, answer checkpoint questions, and ask the TA when needed.
7. Use 复习总览 and 题目攻关 as the course progresses.

Development

Run in development

uv run uvicorn app.main:app --reload

Basic checks

python -m compileall app

Evaluation notes

• See docs/agent_evaluation_rubric.md for the current agent evaluation rubric and model allocation guidance.
• See docs/ee6222_agent_benchmark.md for the first concrete benchmark suite built from the uploaded EE6222 course materials.

Data notes

• Local runtime data is stored in data/
• Uploaded materials, generated text, and vector data are intentionally excluded from git

GitHub Workflow

• Use the issue templates for bugs and feature ideas
• Open pull requests with the provided PR template
• Keep commits focused and descriptive

See CONTRIBUTING.md for the preferred contribution flow.

Status

This repository currently contains a local-first working prototype and ongoing product iteration.

Some deeper production concerns are still intentionally lightweight at this stage, including:

• schema migration tooling
• stronger OCR fallback flows
• richer knowledge graph rendering
• more robust streaming from upstream LLM providers

License

No license has been added yet.