Add claude GitHub actions 1757506113900

.claude/commands/implement-feture.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.

.github/workflows/claude-code-review.yml

@@ -0,0 +1,54 @@
+name: Claude Code Review
+
+on:
+  pull_request:
+    types: [opened, synchronize]
+    # Optional: Only run on specific file changes
+    # paths:
+    #   - "src/**/*.ts"
+    #   - "src/**/*.tsx"
+    #   - "src/**/*.js"
+    #   - "src/**/*.jsx"
+
+jobs:
+  claude-review:
+    # Optional: Filter by PR author
+    # if: |
+    #   github.event.pull_request.user.login == 'external-contributor' ||
+    #   github.event.pull_request.user.login == 'new-developer' ||
+    #   github.event.pull_request.author_association == 'FIRST_TIME_CONTRIBUTOR'
+
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      pull-requests: read
+      issues: read
+      id-token: write
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 1
+
+      - name: Run Claude Code Review
+        id: claude-review
+        uses: anthropics/claude-code-action@v1
+        with:
+          claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
+          prompt: |
+            Please review this pull request and provide feedback on:
+            - Code quality and best practices
+            - Potential bugs or issues
+            - Performance considerations
+            - Security concerns
+            - Test coverage
+            
+            Use the repository's CLAUDE.md for guidance on style and conventions. Be constructive and helpful in your feedback.
+
+            Use `gh pr comment` with your Bash tool to leave your review as a comment on the PR.
+          
+          # See https://github.com/anthropics/claude-code-action/blob/main/docs/usage.md
+          # or https://docs.anthropic.com/en/docs/claude-code/sdk#command-line for available options
+          claude_args: '--allowed-tools "Bash(gh issue view:*),Bash(gh search:*),Bash(gh issue list:*),Bash(gh pr comment:*),Bash(gh pr diff:*),Bash(gh pr view:*),Bash(gh pr list:*)"'
+

.github/workflows/claude.yml

@@ -0,0 +1,50 @@
+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: read
+      pull-requests: read
+      issues: read
+      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@v1
+        with:
+          claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
+
+          # This is an optional setting that allows Claude to read CI results on PRs
+          additional_permissions: |
+            actions: read
+
+          # Optional: Give a custom prompt to Claude. If this is not specified, Claude will perform the instructions specified in the comment that tagged it.
+          # prompt: 'Update the pull request description to include a summary of changes.'
+
+          # Optional: Add claude_args to customize behavior and configuration
+          # See https://github.com/anthropics/claude-code-action/blob/main/docs/usage.md
+          # or https://docs.anthropic.com/en/docs/claude-code/sdk#command-line for available options
+          # claude_args: '--model claude-opus-4-1-20250805 --allowed-tools Bash(gh pr:*)'
+

.python-version

@@ -1 +1 @@
-3.13
+3.12.0

CLAUDE.md

@@ -0,0 +1,175 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+This is a **Course Materials RAG System** - a full-stack Retrieval-Augmented Generation application that allows users to query course materials and receive AI-powered responses with proper source attribution.
+
+## Architecture
+
+The system uses a **modular, three-tier architecture**:
+
+### Backend (`/backend/`)
+- **FastAPI** web framework with CORS and proxy middleware
+- **RAG System Core**: Main orchestrator (`rag_system.py`)
+- **Vector Storage**: ChromaDB with SentenceTransformers embeddings (`vector_store.py`)
+- **AI Generation**: Anthropic Claude integration with tool calling (`ai_generator.py`)
+- **Document Processing**: Handles PDF/DOCX/TXT files (`document_processor.py`)
+- **Tool-Based Search**: Semantic search with course/lesson filtering (`search_tools.py`)
+- **Session Management**: Conversation history tracking (`session_manager.py`)
+
+### Frontend (`/frontend/`)
+- **Vanilla JavaScript** SPA with marked.js for markdown rendering
+- **Real-time chat interface** with loading states and source attribution
+- **Course statistics sidebar** with collapsible sections
+- **Suggested questions** for user guidance
+
+### Data Models (`/backend/models.py`)
+- **Course**: Title, description, lessons, instructor, URL
+- **Lesson**: Number, title, content, URL
+- **CourseChunk**: Processed text chunks for vector storage
+
+## Development Commands
+
+### Quick Start
+```bash
+chmod +x run.sh
+./run.sh
+```
+
+### Manual Development
+```bash
+# Install dependencies (first time)
+uv sync
+
+# Start backend server
+cd backend && uv run uvicorn app:app --reload --port 8000
+
+# Run tests
+cd backend && uv run pytest tests/ -v
+
+# Application runs at:
+# - Web Interface: http://localhost:8000
+# - API Docs: http://localhost:8000/docs
+```
+
+### Code Quality Commands
+
+```bash
+# Format code with Black and Ruff
+uv run black backend/ main.py
+uv run ruff format backend/ main.py
+uv run ruff check --fix backend/ main.py
+
+# Run type checking
+uv run mypy backend/ main.py
+
+# Run linting checks only
+uv run ruff check backend/ main.py
+
+# Complete quality check (format + lint + test)
+./scripts/quality-check.sh
+
+# Individual scripts
+./scripts/format.sh    # Format code only
+./scripts/lint.sh      # Lint and type check only
+```
+
+### Environment Setup
+Create `.env` file in root:
+```
+ANTHROPIC_API_KEY=your_key_here
+```
+
+## Key Technical Patterns
+
+### RAG Query Flow
+1. User query → FastAPI endpoint (`/api/query`)
+2. RAG system creates AI prompt with tool definitions
+3. Claude uses `search_course_content` tool with semantic matching
+4. Vector store searches ChromaDB with course/lesson filtering
+5. Search results formatted with source attribution
+6. Claude synthesizes response using retrieved content
+7. Response returned with clickable source links
+
+### Tool-Based Search Architecture
+- **CourseSearchTool**: Handles semantic search with course name fuzzy matching
+- **ToolManager**: Registers and executes tools for AI agent
+- **Source Tracking**: Last search sources stored for UI display
+- **Flexible Filtering**: Supports course title and lesson number filters
+
+### Vector Storage Strategy
+- **SentenceTransformers**: `all-MiniLM-L6-v2` for embeddings
+- **ChromaDB Collections**: Separate storage for course metadata vs content chunks
+- **Smart Deduplication**: Avoids re-processing existing courses
+- **Metadata Enrichment**: Course titles, lesson numbers, URLs stored as metadata
+
+### Session Management
+- **Conversation History**: Tracks user-assistant exchanges per session
+- **Context Limits**: Configurable max history (default: 2 messages)
+- **Session Creation**: Auto-generated UUIDs for frontend sessions
+
+## Configuration (`/backend/config.py`)
+
+Key settings:
+- **ANTHROPIC_MODEL**: `claude-sonnet-4-20250514`
+- **EMBEDDING_MODEL**: `all-MiniLM-L6-v2`
+- **CHUNK_SIZE**: 800 characters
+- **CHUNK_OVERLAP**: 100 characters
+- **MAX_RESULTS**: 5 search results
+- **MAX_HISTORY**: 2 conversation turns
+
+## Document Processing
+
+Supports: **PDF, DOCX, TXT** files
+- Course documents placed in `/docs/` folder
+- Auto-loaded on server startup
+- Structured parsing extracts course metadata and lessons
+- Text chunking with overlap for semantic search
+- Duplicate detection prevents re-processing
+
+## API Endpoints
+
+- **POST** `/api/query` - Process user questions
+- **GET** `/api/courses` - Get course statistics
+- **Static files** served at `/` (frontend)
+
+## Testing and Development
+
+### Testing
+
+The project includes comprehensive test coverage:
+
+- **Unit Tests**: Individual component testing (CourseSearchTool, VectorStore, AIGenerator)  
+- **Integration Tests**: RAG system end-to-end testing
+- **API Tests**: FastAPI endpoint testing
+
+```bash
+# Run all tests
+cd backend && uv run pytest tests/ -v
+
+# Run specific test file  
+cd backend && uv run pytest tests/test_course_search_tool.py -v
+
+# Run with coverage (requires pytest-cov: uv add pytest-cov)
+cd backend && uv run pytest tests/ --cov=. --cov-report=html
+```
+
+### Development Guidelines
+
+Since this is a RAG system with AI components:
+- Test with sample course documents in `/docs/`
+- Verify ChromaDB storage at `./backend/chroma_db/`
+- Monitor API logs for tool usage and search results
+- Test different question types (general vs course-specific)
+- Validate source attribution and clickable links
+- **Always use `uv` for dependency management and running commands**
+
+#### Code Quality Standards
+- **Black**: Automatic code formatting (line length: 88)
+- **Ruff**: Fast linting and import organization
+- **MyPy**: Static type checking with strict settings
+- **Run quality checks before committing**: Use `./scripts/quality-check.sh`
+- **Consistent formatting**: All code is formatted with Black and Ruff
+- **Type hints required**: MyPy enforces type annotations

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.