Quoc/convert-to-general-documents2

.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,33 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(git add:*)",
+      "Bash(git commit:*)",
+      "mcp__playwright__browser_navigate",
+      "Bash(uv run:*)",
+      "mcp__playwright__browser_click",
+      "mcp__playwright__browser_wait_for",
+      "Bash(mkdir:*)",
+      "Bash(uv add:*)",
+      "Bash(uv sync:*)",
+      "Bash(./check-quality.ps1)",
+      "Bash(powershell:*)",
+      "Bash(uv sync:*)",
+      "Bash(git merge:*)"
+    ],
+    "deny": []
+  },
+  "hooks": {
+    "PostToolUse": [
+      {
+        "matcher": "Read|Grep",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "echo done"
+          }
+        ]
+      }
+    ]
+  }
+}

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

@@ -0,0 +1,78 @@
+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@beta
+        with:
+          claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
+
+          # Optional: Specify model (defaults to Claude Sonnet 4, uncomment for Claude Opus 4.1)
+          # model: "claude-opus-4-1-20250805"
+
+          # Direct prompt for automated review (no @claude mention needed)
+          direct_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
+
+            Be constructive and helpful in your feedback.
+
+          # Optional: Use sticky comments to make Claude reuse the same comment on subsequent pushes to the same PR
+          # use_sticky_comment: true
+
+          # Optional: Customize review based on file types
+          # direct_prompt: |
+          #   Review this PR focusing on:
+          #   - For TypeScript files: Type safety and proper interface usage
+          #   - For API endpoints: Security, input validation, and error handling
+          #   - For React components: Performance, accessibility, and best practices
+          #   - For tests: Coverage, edge cases, and test quality
+
+          # Optional: Different prompts for different authors
+          # direct_prompt: |
+          #   ${{ github.event.pull_request.author_association == 'FIRST_TIME_CONTRIBUTOR' && 
+          #   'Welcome! Please review this PR from a first-time contributor. Be encouraging and provide detailed explanations for any suggestions.' ||
+          #   'Please provide a thorough code review focusing on our coding standards and best practices.' }}
+
+          # Optional: Add specific tools for running tests or linting
+          # allowed_tools: "Bash(npm run test),Bash(npm run lint),Bash(npm run typecheck)"
+
+          # Optional: Skip review for certain conditions
+          # if: |
+          #   !contains(github.event.pull_request.title, '[skip-review]') &&
+          #   !contains(github.event.pull_request.title, '[WIP]')
+

.github/workflows/claude.yml

@@ -0,0 +1,64 @@
+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@beta
+        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: 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
+

.gitignore

@@ -28,4 +28,13 @@ uploads/
 
 # OS
 .DS_Store
-Thumbs.db
+Thumbs.db
+
+# Logs
+**/*.log
+
+# Work trees
+.trees/
+
+# Large documents
+*.pdf

CLAUDE.md

@@ -0,0 +1,115 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Development Environment
+- **Platform**: Windows
+- **Shell**: PowerShell
+- **Package Manager**: uv
+
+## Development Commands
+
+### Installation & Setup
+```powershell
+# Install dependencies using uv package manager
+uv sync
+
+# Create .env file with required API key
+echo "ANTHROPIC_API_KEY=your_key_here" > .env
+```
+
+### Running the Application
+```powershell
+# Manual start (preferred for development)
+cd backend; uv run uvicorn app:app --reload --port 8000
+
+# Alternative: Use run script if available
+./run.sh
+```
+
+### Code Quality Commands
+```powershell
+# Format code and fix style issues
+powershell -File ./format.ps1
+
+# Check code quality without making changes (dry-run)
+powershell -File ./quality-check.ps1
+
+# Individual commands
+uv run black backend/ main.py    # Format with black
+uv run isort backend/ main.py    # Sort imports
+uv run flake8 backend/ main.py   # Check style with flake8
+```
+
+### Development Workflow
+- **Frontend**: Static files served from `frontend/` directory (HTML/CSS/JS)
+- **Backend**: FastAPI server with auto-reload during development
+- **Database**: ChromaDB persisted locally in `backend/chroma_db/`
+- **Logging**: Full logging implementation with appropriate DEBUG and INFO levels throughout the codebase
+- **Code Quality**: Black formatter, isort import sorting, flake8 linting integrated
+
+## Architecture Overview
+
+This is a **Retrieval-Augmented Generation (RAG) system** for course materials with the following architecture:
+
+### Core Components
+- **`RAGSystem`** (`rag_system.py`): Main orchestrator that coordinates all components
+- **`VectorStore`** (`vector_store.py`): ChromaDB-based vector storage with two collections:
+  - `course_catalog`: Course metadata (titles, instructors, links)
+  - `course_content`: Chunked course content for semantic search
+- **`AIGenerator`** (`ai_generator.py`): Anthropic Claude API integration with tool support
+- **`DocumentProcessor`** (`document_processor.py`): Processes course documents into chunks
+- **`SessionManager`** (`session_manager.py`): Manages conversation history per session
+
+### Key Design Patterns
+- **Tool-based AI Search**: Uses Claude's function calling to search course content
+- **Two-tier Vector Storage**: Separate collections for metadata vs content search
+- **Session-aware Conversations**: Maintains conversation history per user session
+- **Chunked Content Processing**: Documents split into 800-character chunks with 100-char overlap
+
+### Configuration
+All settings centralized in `config.py` with defaults:
+- Chunk size: 800 characters (overlap: 100)
+- Max search results: 5
+- Embedding model: `all-MiniLM-L6-v2`
+- Claude model: `claude-sonnet-4-20250514`
+
+### API Endpoints
+- `POST /api/query`: Process user queries with RAG
+- `GET /api/courses`: Get course analytics
+- `/`: Serves frontend static files
+
+### Document Processing Flow
+1. Documents from `docs/` folder are processed on startup
+2. Each document becomes a `Course` with multiple `Lesson` objects
+3. Content is chunked into `CourseChunk` objects for vector search
+4. Both metadata and content chunks are stored separately for optimal retrieval
+
+## Dependencies
+
+The project uses **uv** as the package manager with core dependencies:
+- `chromadb==1.0.15`: Vector database
+- `anthropic==0.58.2`: Claude API integration
+- `sentence-transformers==5.0.0`: Embedding generation
+- `fastapi==0.116.1`: Web framework
+- `uvicorn==0.35.0`: ASGI server
+
+### Code Quality Dependencies
+- `black==24.10.0`: Python code formatter for consistent style
+- `isort==5.13.2`: Import statement sorting and organization
+- `flake8==7.1.1`: Code linting and style checking
+
+## File Structure Notes
+- `docs/`: Course materials (TXT files processed on startup)
+- `backend/chroma_db/`: Persisted vector database
+- `frontend/`: Static web interface files
+- `main.py`: Entry point (unused in favor of FastAPI app)
+- Always use uv to run the server and do not run pip directly
+- Always use uv to manage all dependencies
+
+## Code Generation Guidelines
+- **Logging**: All generated code must include appropriate logging statements
+  - Use `logger.debug()` for detailed debugging information
+  - Use `logger.info()` for important operational events
+  - Follow existing logging patterns in the codebase
+  - Import logger: `import logging; logger = logging.getLogger(__name__)`

README.md

@@ -6,7 +6,6 @@ A Retrieval-Augmented Generation (RAG) system designed to answer questions about
 
 This application is a full-stack web application that enables users to query course materials and receive intelligent, context-aware responses. It uses ChromaDB for vector storage, Anthropic's Claude for AI generation, and provides a web interface for interaction.
 
-
 ## Prerequisites
 
 - Python 3.13 or higher
@@ -17,18 +16,21 @@ This application is a full-stack web application that enables users to query cou
 ## Installation
 
 1. **Install uv** (if not already installed)
+
    ```bash
    curl -LsSf https://astral.sh/uv/install.sh | sh
    ```
 
 2. **Install Python dependencies**
+
    ```bash
    uv sync
    ```
 
 3. **Set up environment variables**
-   
+
    Create a `.env` file in the root directory:
+
    ```bash
    ANTHROPIC_API_KEY=your_anthropic_api_key_here
    ```
@@ -38,6 +40,7 @@ This application is a full-stack web application that enables users to query cou
 ### Quick Start
 
 Use the provided shell script:
+
 ```bash
 chmod +x run.sh
 ./run.sh
@@ -51,6 +54,14 @@ uv run uvicorn app:app --reload --port 8000
 ```
 
 The application will be available at:
+
 - Web Interface: `http://localhost:8000`
 - API Documentation: `http://localhost:8000/docs`
 
+Commands
+
+```sh
+claude mcp add playwright npx @playwright/mcp@latest
+```
+
+[Reading Notes including Prompts](https://github.com/https-deeplearning-ai/sc-claude-code-files/tree/main/reading_notes)