Skip to content

CLAUDE.md

Latest commit

 

History

History
136 lines (105 loc) · 4.65 KB

CLAUDE.md

File metadata and controls

136 lines (105 loc) · 4.65 KB

CLAUDE.md

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

Development Commands

Running the Application

# Quick start (preferred)
./run.sh

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

Dependencies

# Install all dependencies
uv sync

# Run any Python command in the environment
uv run <command>

Code Quality

# Format code with Black and isort
./scripts/format.sh

# Run linting checks (flake8, mypy)
./scripts/lint.sh

# Run complete quality pipeline (format + lint + tests)
./scripts/quality.sh

# Individual tools
uv run black .          # Format with Black
uv run isort .          # Sort imports
uv run flake8 backend/  # Lint with flake8
uv run mypy backend/    # Type checking with mypy

Environment Setup

# Copy and configure environment variables
cp .env.example .env
# Edit .env to add your ANTHROPIC_API_KEY

Architecture Overview

This is a RAG (Retrieval-Augmented Generation) chatbot system for querying course materials. The architecture follows a layered design with clear separation of concerns:

Core Components

RAG System (rag_system.py) - Main orchestrator that coordinates all components:

  • Manages document processing, vector storage, AI generation, and sessions
  • Handles the complete query processing pipeline
  • Coordinates tool-based searches through the AI model

Document Processing Pipeline:

  • document_processor.py - Parses structured course documents with metadata extraction
  • Expected format: Course Title/Link/Instructor, then Lesson markers with content
  • Implements intelligent sentence-based chunking with configurable overlap
  • Creates CourseChunk objects with contextual metadata

Vector Storage (vector_store.py) - ChromaDB integration:

  • Stores course metadata and content chunks as embeddings
  • Uses sentence-transformers for semantic similarity search
  • Maintains course/lesson hierarchy in metadata

AI Generation (ai_generator.py) - Claude API integration:

  • Uses tool-based approach where Claude decides when to search
  • System prompt optimized for educational content
  • Supports conversation history and contextual responses

Search Tools (search_tools.py) - Tool interface for AI:

  • CourseSearchTool - Semantic search capability exposed to Claude
  • ToolManager - Handles tool registration and source tracking
  • Enables intelligent, conditional searching based on query type

Session Management (session_manager.py) - Conversation persistence:

  • Tracks conversation history per session
  • Configurable history length (default: 2 exchanges)

Data Models (models.py)

  • Course - Course metadata with lessons list
  • Lesson - Individual lesson with number, title, optional link
  • CourseChunk - Text chunks with course/lesson context for vector storage

Configuration (config.py)

Key settings in dataclass format:

  • Chunking: 800 char size, 100 char overlap
  • Model: Claude Sonnet 4, all-MiniLM-L6-v2 embeddings
  • Database: ChromaDB stored in ./chroma_db
  • Max results: 5, conversation history: 2 exchanges

Query Processing Flow

  1. Frontend sends POST to /api/query with query and session_id
  2. FastAPI routes to RAG system
  3. RAG System builds prompt and retrieves conversation history
  4. AI Generator calls Claude with available search tools
  5. Claude decides whether to use search tool based on query type
  6. If search needed: Vector search retrieves relevant course chunks
  7. AI synthesizes response using search results and context
  8. Sources tracked through tool manager for citations
  9. Response returned with answer and source list

Frontend Architecture

Simple HTML/CSS/JavaScript chat interface:

  • Real-time chat with loading states
  • Source citations display in collapsible sections
  • Session persistence across page reloads
  • Suggested questions for user guidance

Key Implementation Details

Document Format: Course files must follow specific structure:

Course Title: [title]
Course Link: [url]
Course Instructor: [name]

Lesson 0: [title]
Lesson Link: [url]
[content...]

Conditional Search: Not every query triggers database search - Claude intelligently determines when course-specific information is needed vs general knowledge.

Context Preservation: Chunks include enhanced context like "Course [title] Lesson [#] content: [chunk]" for better semantic matching.

Error Handling: Each layer includes graceful fallbacks and UTF-8 encoding handling.

Development Mode: FastAPI serves frontend statically with no-cache headers for development.

  • always use uv to run the server do not use pip directly