Skip to content

CLAUDE.md

Latest commit

 

History

History
128 lines (96 loc) · 3.92 KB

CLAUDE.md

File metadata and controls

128 lines (96 loc) · 3.92 KB

CLAUDE.md

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

Project Overview

This is a Retrieval-Augmented Generation (RAG) system that answers questions about course materials using semantic search and AI-powered responses. The application uses:

  • ChromaDB for vector storage
  • Anthropic's Claude, OpenAI's GPT, or Google's Gemini for AI generation
  • FastAPI for the web backend
  • A React frontend (in the frontend/ directory)

Key Architecture Components

  1. Backend (backend/):

    • app.py: Main FastAPI application with endpoints
    • rag_system.py: Core orchestrator that coordinates document processing, vector storage, and AI generation
    • document_processor.py: Handles parsing and chunking of course documents
    • vector_store.py: Manages ChromaDB interactions for storing/retrieving document embeddings
    • ai_generator.py: Provider-agnostic AI generation interface supporting multiple LLM providers
    • config.py: Configuration management with environment variables
    • search_tools.py: Implements semantic search functionality using tools
    • session_manager.py: Manages conversation history
    • models.py: Data models for courses, lessons, and chunks

  2. Frontend (frontend/): React application for user interface

  3. Documents (docs/): Course materials in PDF, DOCX, or TXT format

Development Commands

Setup

# Install dependencies
uv sync

# Set up environment variables in .env:
# ANTHROPIC_API_KEY=your_key_here
# LLM_PROVIDER=anthropic  # or openai or gemini

Running the Application

# Quick start (recommended)
chmod +x run.sh
./run.sh

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

Adding Course Documents

Place PDF/DOCX/TXT files in the docs/ folder. The system will automatically load them on startup.

Code Quality & Testing

Quick Setup

# Set up development environment with quality tools
uv sync --group dev

# Install pre-commit hooks (optional but recommended)
./scripts/setup-hooks.sh

Code Formatting & Linting

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

# Check code formatting and linting
./scripts/lint.sh

# Run type checking
./scripts/typecheck.sh

# Run all quality checks (format check + linting + type checking)
./scripts/quality-check.sh

Testing

# Run tests
./scripts/test.sh

Pre-commit Hooks

The project includes pre-commit hooks that automatically run quality checks before each commit. This ensures consistent code quality and catches issues early.

Quality Tools Used

  • Black for code formatting (line length: 88)
  • isort for import organization
  • flake8 for linting
  • mypy for type checking
  • pytest for testing
  • pre-commit for automated quality checks

Key URLs

Multi-Provider LLM Support

The system supports three LLM providers:

  • Anthropic Claude (default)
  • OpenAI GPT
  • Google Gemini

Switch between them by setting the LLM_PROVIDER environment variable in .env.

Team Memory

  • Always use uv for Python env management, installs, and execution — never use pip directly.

    • Install/resolve deps: uv sync
    • Run server (manual): cd backend && uv run uvicorn app:app --reload --port 8000
    • Run tests: uv run pytest -q
    • Add deps: uv add <pkg> (or edit pyproject.toml then uv sync)
    • Do not run pip install or python -m pip in this project.

  • The run script already uses uv:

    • ./run.sh starts the API via uv run uvicorn …

  • If a virtualenv appears broken, prefer rm -rf .venv && uv sync over pip.

  • make sure to use uv to manage all dependencies

  • use uv to run python files