This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

A Retrieval-Augmented Generation (RAG) system for answering questions about course materials. The system uses:

• ChromaDB for vector storage with dual collections (course catalog + content chunks)
• Anthropic's Claude API for AI generation with tool-based search
• FastAPI backend serving both API endpoints and static frontend
• Sentence Transformers (all-MiniLM-L6-v2) for embeddings

# Quick start
chmod +x run.sh
./run.sh

# Manual start
cd backend
uv run uvicorn app:app --reload --port 8000

The app runs on http://localhost:8000 with API docs at http://localhost:8000/docs.

IMPORTANT: This project uses uv as the package manager. Always use uv commands instead of pip.

# Install dependencies
uv sync

# Add a new dependency
uv add package-name

# Run Python scripts
uv run python script.py

# Run any Python command
uv run <command>

Create a .env file in the root directory:

ANTHROPIC_API_KEY=your_key_here

1. Document Processing (document_processor.py)

   • Parses structured course documents from docs/ folder
   • Expected format: Course metadata (first 3 lines), then Lesson markers
   • Chunks content using sentence-based splitting with configurable overlap
   • Creates Course and CourseChunk objects

2. Dual Vector Store (vector_store.py)

   • course_catalog collection: Stores course metadata (title, instructor, lessons JSON) for fuzzy name matching
   • course_content collection: Stores chunked lesson content with course_title + lesson_number metadata
   • Search flow: Query → resolve course name via semantic search → filter content search

3. Tool-Based RAG (rag_system.py, search_tools.py, ai_generator.py)

   • Claude uses search_course_content tool to query vector store
   • Tool supports: query (required), course_name (optional fuzzy match), lesson_number (optional filter)
   • Single tool call per query enforced via system prompt
   • Sources tracked via ToolManager.get_last_sources()

4. Session Management (session_manager.py)

   • Maintains conversation history per session (max 2 exchanges by default)
   • History injected into Claude's system prompt for context

Chunk Context Enhancement: First chunk of each lesson gets "Lesson N content: {chunk}" prefix; other chunks get "Course {title} Lesson N content: {chunk}" to improve retrieval relevance.

Course Name Resolution: User queries with partial/fuzzy course names (e.g., "MCP") are resolved via semantic search on course_catalog before filtering content search.

Startup Document Loading: On FastAPI startup, docs/ folder is automatically scanned and new courses are added (existing courses skipped based on title matching).

Key settings:

• CHUNK_SIZE: 800 characters
• CHUNK_OVERLAP: 100 characters
• MAX_RESULTS: 5 search results
• MAX_HISTORY: 2 conversation exchanges
• ANTHROPIC_MODEL: claude-sonnet-4-20250514

Place .txt/.pdf/.docx files in docs/ with this structure:

Course Title: [Title]
Course Link: [URL]
Course Instructor: [Name]

Lesson 0: [Lesson Title]
Lesson Link: [URL]
[Lesson content...]

Lesson 1: [Next Lesson]
Lesson Link: [URL]
[Content...]

• POST /api/query: Query course materials

  • Request: {"query": str, "session_id": str (optional)}
  • Response: {"answer": str, "sources": List[str], "session_id": str}

• GET /api/courses: Get course statistics

  • Response: {"total_courses": int, "course_titles": List[str]}

To clear and rebuild the vector database:

# In rag_system.py
rag_system.add_course_folder(folder_path, clear_existing=True)

Edit document_processor.py:

• chunk_text(): Sentence-based chunking logic
• Adjust CHUNK_SIZE and CHUNK_OVERLAP in config.py

• Tool definition: search_tools.py → CourseSearchTool.get_tool_definition()
• System prompt instructions: ai_generator.py → AIGenerator.SYSTEM_PROMPT
• Max results: config.py → MAX_RESULTS

Edit system prompt in ai_generator.py (lines 8-30). Current constraints:

• One search per query maximum
• No meta-commentary about search process
• Brief, concise, educational responses
• Temperature: 0, Max tokens: 800

• ChromaDB: ./backend/chroma_db/ (persistent storage)
• Course documents: ./docs/

• Course Title as ID: Course titles serve as unique identifiers throughout the system (course_catalog IDs, metadata keys)
• Deduplication: add_course_folder() checks existing course titles to avoid re-processing
• Static File Serving: Frontend served via DevStaticFiles with no-cache headers for development
• Middleware: CORS and TrustedHostMiddleware configured for proxy compatibility (allow all origins)