Modern Dev Agent is a teaching-first MVP for programming assignments. It ingests markdown assignment material, turns it into structured task data, supports layered student tutoring, runs a pre-submit checklist, and gives teachers a risk-oriented dashboard powered by demo sessions and behavior events.

• Student assignment overview pages with task, deliverable, rubric, and risk summaries.
• Tutor sessions that escalate hints from direction to files, testing, and bounded implementation guidance.
• RAG-backed tutor context using a generated assignment/domain vector knowledge index.
• Deterministic tutor tool calls for knowledge search, student progress lookup, and submission readiness checks.
• Pre-submit checklist that checks writeup, README, testing notes, and reflection coverage.
• Teacher dashboard, assignment insight page, student portrait page, and intervention queue.
• Scripts for markdown ingestion and demo student or event seeding.

cp .env.example .env
pnpm install
pnpm ingest
pnpm rag:index
docker compose up llm-gateway --build
pnpm dev

Open http://localhost:3000 and use the student or teacher entry points.

The Next.js app runs locally on the host. Only the FastAPI LLM gateway is containerized so model-side dependencies stay isolated.

• Copy .env.example to .env and fill in OPENAI_API_KEY before starting the gateway.
• LLM_GATEWAY_URL should stay http://127.0.0.1:8000 when Next.js runs locally.
• LLM_GATEWAY_MODEL controls the model name sent by /api/tutor.
• LLM_EMBEDDING_MODEL controls the embedding model requested when building/querying the RAG index.
• RAG_TOP_K and RAG_MIN_SCORE tune vector retrieval breadth and score cutoff.
• OPENAI_BASE_URL, OPENAI_MODEL, and OPENAI_EMBEDDING_MODEL point the FastAPI gateway at an OpenAI-compatible provider; chat uses /chat/completions and embeddings use /embeddings.
• OPENCODE_VERSION controls the opencode-style User-Agent used by the gateway's upstream model requests.
• INTERNAL_API_TOKEN and LLM_GATEWAY_TOKEN must match.

• pnpm dev starts the Next.js app.
• pnpm build builds the production app.
• pnpm test runs the unit test suite.
• pnpm sync:content rebuilds the normalized app-facing markdown from the official assignments/week1-4 materials.
• pnpm ingest syncs the official week 1-4 assignments into content/source/Assignments and regenerates the imported database.
• pnpm rag:index builds content/imported/vector-knowledge.json from imported assignments.
• pnpm rag:rebuild runs ingest and then rebuilds the vector knowledge index.
• pnpm seed:students refreshes demo students, sessions, and derived insights.
• pnpm seed:events refreshes the simulated event log.

• src/app contains the pages and route handlers.
• src/lib/agents contains the assignment parser, tutor, checklist, and teacher insight logic.
• src/lib/analytics contains risk scoring and aggregation helpers.
• src/lib/content holds the migration logic that normalizes the official course assignments for the app.
• src/lib/rag holds vector index building, local fallback embeddings, and retrieval helpers.
• content/source holds the generated markdown assignments used by the ingest pipeline.
• assignments stores the official raw course materials; weeks 1-4 are the current migration source.
• content/imported stores the generated local data snapshot.

• The runtime persistence layer is a local JSON store so the MVP can run without database setup friction.
• prisma/schema.prisma is included as a forward-compatible schema blueprint for migrating the MVP to SQLite via Prisma later.