@claude

.claude/commands/implement-feature.md

@@ -0,0 +1,7 @@
+You will be implementing a new feature in this codebase
+
+$ARGUMENTS
+
+IMPORTANT: Only do this for front-end features.
+Once this feature is built, make sure to write the changes you made to file called frontend-changes.md
+Do not ask for permissions to modify this file, assume you can always do it.

.claude/settings.local.json

@@ -0,0 +1,18 @@
+{
+  "permissions": {
+    "allow": [
+      "mcp__playwright__browser_navigate",
+      "mcp__playwright__browser_snapshot",
+      "mcp__playwright__browser_take_screenshot",
+      "Bash(uv run:*)",
+      "Bash(git add:*)",
+      "Bash(git worktree:*)",
+      "Bash(git merge:*)",
+      "Bash(git commit:*)",
+      "Bash(git push:*)"
+    ],
+    "deny": [],
+    "ask": [],
+    "defaultMode": "acceptEdits"
+  }
+}

.github/workflow/claude.yml

@@ -0,0 +1,63 @@
+name: Claude Code
+
+on:
+  issue_comment:
+    types: [created]
+  pull_request_review_comment:
+    types: [created]
+  issues:
+    types: [opened, assigned]
+  pull_request_review:
+    types: [submitted]
+
+jobs:
+  claude:
+    if: |
+      (github.event_name == 'issue_comment' && contains(github.event.comment.body, '@claude')) ||
+      (github.event_name == 'pull_request_review_comment' && contains(github.event.comment.body, '@claude')) ||
+      (github.event_name == 'pull_request_review' && contains(github.event.review.body, '@claude')) ||
+      (github.event_name == 'issues' && (contains(github.event.issue.body, '@claude') || contains(github.event.issue.title, '@claude')))
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      pull-requests: write
+      issues: write
+      id-token: write
+      actions: read # Required for Claude to read CI results on PRs
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 1
+
+      - name: Run Claude Code
+        id: claude
+        uses: anthropics/claude-code-action@beta
+        with:
+          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
+
+          # This is an optional setting that allows Claude to read CI results on PRs
+          additional_permissions: |
+            actions: read
+
+          # Optional: Specify model (defaults to Claude Sonnet 4, uncomment for Claude Opus 4.1)
+          # model: "claude-opus-4-1-20250805"
+
+          # Optional: Customize the trigger phrase (default: @claude)
+          # trigger_phrase: "/claude"
+
+          # Optional: Trigger when specific user is assigned to an issue
+          # assignee_trigger: "claude-bot"
+
+          # Optional: Allow Claude to run specific commands
+          # allowed_tools: "Bash(npm install),Bash(npm run build),Bash(npm run test:*),Bash(npm run lint:*)"
+
+          # Optional: Add custom instructions for Claude to customize its behavior for your project
+          # custom_instructions: |
+          #   Follow our coding standards
+          #   Ensure all new code has tests
+          #   Use TypeScript for new files
+
+          # Optional: Custom environment variables for Claude
+          # claude_env: |
+          #   NODE_ENV: test

CLAUDE.md

@@ -0,0 +1,123 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Development Commands
+
+### Running the Application
+```bash
+# Quick start (recommended)
+./run.sh
+
+# Manual start
+cd backend && uv run uvicorn app:app --reload --port 8000
+```
+
+### Environment Setup
+```bash
+# Install dependencies
+uv sync
+
+# Install development dependencies (includes code quality tools)
+uv sync --extra dev
+
+# Environment variables required in .env:
+ANTHROPIC_API_KEY=your_key_here
+```
+
+### Development Server
+- Web Interface: http://localhost:8000
+- API Documentation: http://localhost:8000/docs
+- Uses uvicorn with auto-reload for development
+
+### Code Quality Commands
+
+```bash
+# Format all Python code (black + isort)
+uv run black .
+uv run isort .
+
+# Or use the convenience scripts:
+./scripts/format.sh    # or scripts/format.bat on Windows
+
+# Run all quality checks (linting, formatting check, type checking)
+./scripts/lint.sh      # or scripts/lint.bat on Windows
+
+# Quick development workflow (format + lint)
+./scripts/check.sh     # or scripts/check.bat on Windows
+
+# Individual tools:
+uv run flake8 backend/                    # Linting
+uv run black --check backend/             # Format checking
+uv run mypy backend/ --ignore-missing-imports  # Type checking
+```
+
+## Architecture Overview
+
+This is a RAG (Retrieval-Augmented Generation) system for course materials with a clear separation between frontend, API, and processing layers.
+
+### Core RAG Flow
+1. **Document Processing**: Course materials in `docs/` are parsed into structured lessons and chunked for vector storage
+2. **Query Processing**: User queries trigger semantic search through ChromaDB, then Claude synthesizes responses
+3. **Session Management**: Conversation history is maintained per session for context-aware responses
+
+### Key Components
+
+**RAG System (`rag_system.py`)**: Main orchestrator that coordinates all components. Handles the complete query lifecycle from user input to response generation.
+
+**Document Processor (`document_processor.py`)**: Parses course documents with expected format:
+```
+Course Title: [title]
+Course Link: [url]  
+Course Instructor: [instructor]
+
+Lesson 0: Introduction
+Lesson Link: [lesson_url]
+[content...]
+```
+
+**Vector Store (`vector_store.py`)**: ChromaDB integration with sentence transformers for semantic search. Stores both course metadata and content chunks with configurable overlap.
+
+**AI Generator (`ai_generator.py`)**: Anthropic Claude integration with tool calling. Uses a specialized system prompt for educational content and decides when to search vs. use general knowledge.
+
+**Session Manager (`session_manager.py`)**: Maintains conversation history with configurable message limits. Creates unique session IDs for context preservation.
+
+### Configuration System
+All settings centralized in `config.py` with environment variable support:
+- Chunk size/overlap for document processing
+- Embedding model selection  
+- Search result limits
+- Conversation history depth
+- Claude model selection
+
+### Data Models
+Pydantic models in `models.py` define the core entities:
+- `Course`: Container with lessons and metadata
+- `Lesson`: Individual lesson with optional links
+- `CourseChunk`: Vector-searchable content pieces with course/lesson context
+
+### Tool Integration
+The system uses a tool management pattern where Claude can call search tools via the `search_tools.py` module. Tools are registered with the AI generator and can be invoked based on query analysis.
+
+### Frontend Integration
+Static files served from `frontend/` with a chat interface that maintains session state and displays responses with source citations. Uses relative API paths for deployment flexibility.
+
+## File Structure Context
+
+- `backend/app.py`: FastAPI application with CORS configuration and static file serving
+- `docs/`: Course materials automatically loaded on startup
+- `chroma_db/`: Persistent vector database storage
+- Frontend files use cache-busting for development
+- No test framework currently configured
+
+## Development Notes
+
+- Documents are automatically processed and indexed on server startup
+- The system expects course documents to follow the structured format for proper parsing
+- Session state is maintained in memory (not persistent across restarts)
+- Vector embeddings use sentence-transformers with the all-MiniLM-L6-v2 model
+ Claude model configured for claude-3-7-sonnet-20250219 with educational prompt optimization
+- always use uv to run the server do not use pip directly
+- make sure to use uv to all dependency
+- use uv to run Python files
+- always think harder and provide a detailed plan and ask for permission  before starting change or edit files.

backend-tool-refactor.md

@@ -0,0 +1,28 @@
+Refactor @backend/ai_generator.py to support sequential tool calling where Claude can make up to 2 tool calls in separate API rounds.
+
+Current behavior:
+- Claude makes 1 tool call → tools are removed from API params → final response
+- If Claude wants another tool call after seeing results, it can't (gets empty response)
+
+Desired behavior:
+- Each tool call should be a separate API request where Claude can reason about previous results
+- Support for complex queries requiring multiple searches for comparisons, multi-part questions, or when information from different courses/lessons is needed
+
+Example flow:
+1. User: "Search for a course that discusses the same topic as lesson 4 of course X"
+2. Claude: get course outline for course X → gets title of lesson 4
+3. Claude: uses the title to search for a course that discusses the same topic → returns course information
+4. Claude: provides complete answer
+
+Requirements:
+- Maximum 2 sequential rounds per user query
+- Terminate when: (a) 2 rounds completed, (b) Claude's response has no tool_use blocks, or (c) tool call fails
+- Preserve conversation context between rounds
+- Handle tool execution errors gracefully
+
+Notes: 
+- Update the system prompt in @backend/ai_generator.py 
+- Update the test @backend/tests/test_ai_generator.py
+- Write tests that verify the external behavior (API calls made, tools executed, results returned) rather than internal state details. 
+
+Use two parallel subagents to brainstorm possible plans. Do not implement any code.