Skip to content

CLAUDE.md

Latest commit

 

History

History
64 lines (45 loc) · 2.92 KB

CLAUDE.md

File metadata and controls

64 lines (45 loc) · 2.92 KB
Raw

Columbia Course Assistant

Project Overview

Multi-agent course planning assistant for Columbia University students. Built at the Claude Builder Hackathon (April 12, 2026).

Read docs/plan.md for the full implementation plan, directory structure, shared contracts, agent architecture, and work split across team members. Read docs/prd.md for product requirements and feature priorities.

Tech Stack

  • Backend: Python 3.14, FastAPI, anthropic SDK (raw tool use, not Agent SDK)
  • Frontend: Next.js 16, TypeScript, Tailwind CSS, react-markdown
  • External Search: Linkup API (linkup-sdk Python package)
  • LLM: Claude Sonnet (claude-sonnet-4-6) for agents, Claude Haiku (claude-haiku-4-5-20251001) for fast tasks
  • Data: JSON course catalog (data/2026-Spring.json, data/2026-Fall.json), loaded into memory at startup

Architecture

The backend has 3 agents orchestrated by a coordinator. Each agent is an async function that calls anthropic.AsyncAnthropic().messages.create() with a specific system prompt and tools, then runs a tool-use loop (agents/base.py:run_agent_loop).

  • Coordinator (agents/coordinator.py): classifies user intent (simple_query, research_query, recommendation), routes to agent pipeline
  • Catalog Agent (agents/catalog.py): searches the local course catalog via search_courses tool
  • Web Research Agent (agents/web_research.py): enriches courses with external data via Linkup API (linkup_search tool with structured schemas for course reviews, professor reviews, industry demand, custom insights)
  • Advisor Agent (agents/advisor.py): ranks courses against student preferences, returns fit scores (0.0-1.0)

Pipeline flow for recommendations: Coordinator -> Catalog Agent -> Web Research Agent -> Advisor Agent. Simple queries skip directly to the Catalog Agent.

Frontend communicates with backend via SSE (Server-Sent Events) on POST /api/chat. The useChat hook handles streaming of agent status updates and text deltas.

API Endpoints

  • GET /api/health: Health check
  • GET /api/courses: Returns full course catalog as JSON
  • POST /api/chat: SSE stream (accepts ChatRequest with messages and student profile)

Coding Conventions

  • All shared data models live in backend/models.py (Pydantic). If you need a new model, add it there.
  • Tool definitions (JSON schemas + executor functions) live in backend/tools/.
  • Use async/await everywhere in the backend. No sync blocking calls.
  • Use config.py for all env vars and constants. Do not hardcode API keys or model names.
  • Frontend types in frontend/src/lib/types.ts must mirror the Pydantic models in backend/models.py. Keep them in sync.

Running the Project

# Backend
cd backend
cp .env.example .env  # fill in API keys
source ../.venv/bin/activate
uvicorn main:app --reload

# Frontend
cd frontend
npm install
npm run dev

Team

  • Andrew Suh
  • Kaspar Soukup
  • Steven Mei
  • Leo Lin