# CLAUDE.md - YouTube Summarizer Backend

This file provides guidance to Claude Code when working with the YouTube Summarizer backend services.

## Backend Architecture Overview

The backend is built with FastAPI and follows a clean architecture pattern with clear separation of concerns:

```
backend/
├── api/                    # API endpoints and request/response models
├── services/              # Business logic and external integrations
├── models/                # Data models and database schemas
├── core/                  # Core utilities, exceptions, and configurations
└── tests/                 # Unit and integration tests
```

## Key Services and Components

### Authentication System (Story 3.1 - COMPLETE ✅)

**Architecture**: Production-ready JWT-based authentication with Database Registry singleton pattern

**AuthService** (`services/auth_service.py`)
- JWT token generation and validation (access + refresh tokens)
- Password hashing with bcrypt and strength validation
- User registration with email verification workflow
- Password reset with secure token generation
- Session management and token refresh logic

**Database Registry Pattern** (`core/database_registry.py`)
- **CRITICAL FIX**: Resolves SQLAlchemy "Multiple classes found for path" errors
- Singleton pattern ensuring single Base instance across application
- Automatic model registration preventing table redefinition conflicts
- Thread-safe model management with registry cleanup for testing
- Production-ready architecture preventing relationship resolver issues

**Authentication Models** (`models/user.py`)
- User, RefreshToken, APIKey, EmailVerificationToken, PasswordResetToken
- Fully qualified relationship paths preventing SQLAlchemy conflicts
- String UUID fields for SQLite compatibility
- Proper model inheritance using Database Registry Base

**Authentication API** (`api/auth.py`)
- Complete endpoint coverage: register, login, logout, refresh, verify email, reset password
- Comprehensive input validation and error handling
- Protected route dependencies and middleware
- Async/await patterns throughout

### Dual Transcript Services ✅ **NEW**

**DualTranscriptService** (`services/dual_transcript_service.py`)
- Orchestrates between YouTube captions and Whisper AI transcription
- Supports three extraction modes: `youtube`, `whisper`, `both`
- Parallel processing for comparison mode with real-time progress updates
- Advanced quality comparison with punctuation/capitalization analysis
- Processing time estimation and intelligent recommendation engine
- Seamless integration with existing TranscriptService

**FasterWhisperTranscriptService** (`services/faster_whisper_transcript_service.py`) ✅ **UPGRADED**
- **20-32x Speed Improvement**: Powered by faster-whisper (CTranslate2 optimization engine)
- **Large-v3-Turbo Model**: Best accuracy/speed balance with advanced AI capabilities
- **Intelligent Optimizations**: Voice Activity Detection (VAD), int8 quantization, GPU acceleration
- **Native MP3 Support**: No audio conversion needed, direct processing
- **Advanced Configuration**: Fully configurable via VideoDownloadConfig with environment variables
- **Production Features**: Async processing, intelligent chunking, comprehensive metadata
- **Performance Metrics**: Real-time speed ratios, processing time tracking, quality scoring

### Core Pipeline Services

**IntelligentVideoDownloader** (`services/intelligent_video_downloader.py`) ✅ **NEW**
- **9-Tier Transcript Extraction Fallback Chain**:
  1. YouTube Transcript API - Primary method using official API
  2. Auto-generated Captions - YouTube's automatic captions fallback
  3. Whisper AI Transcription - OpenAI Whisper for high-quality audio transcription
  4. PyTubeFix Downloader - Alternative YouTube library
  5. YT-DLP Downloader - Robust video/audio extraction tool
  6. Playwright Browser - Browser automation for JavaScript-rendered content
  7. External Tools - 4K Video Downloader CLI integration
  8. Web Services - Third-party transcript API services
  9. Transcript-Only - Metadata without full transcript as final fallback
- **Audio Retention System** for re-transcription capability
- **Intelligent method selection** based on success rates
- **Comprehensive error handling** with detailed logging
- **Performance telemetry** and health monitoring

**SummaryPipeline** (`services/summary_pipeline.py`)
- Main orchestration service for end-to-end video processing
- 7-stage async pipeline: URL validation → metadata extraction → transcript → analysis → summarization → quality validation → completion
- Integrates with IntelligentVideoDownloader for robust transcript extraction
- Intelligent content analysis and configuration optimization
- Real-time progress tracking via WebSocket
- Automatic retry logic with exponential backoff
- Quality scoring and validation system

**AnthropicSummarizer** (`services/anthropic_summarizer.py`)
- AI service integration using Claude 3.5 Haiku for cost efficiency
- Structured JSON output with fallback text parsing
- Token counting and cost estimation
- Intelligent chunking for long transcripts (up to 200k context)
- Comprehensive error handling and retry logic

**CacheManager** (`services/cache_manager.py`)
- Multi-level caching for pipeline results, transcripts, and metadata
- TTL-based expiration with automatic cleanup
- Redis-ready architecture for production scaling
- Configurable cache keys with collision prevention

**WebSocketManager** (`core/websocket_manager.py`)
- Singleton pattern for WebSocket connection management
- Job-specific connection tracking and broadcasting
- Real-time progress updates and completion notifications
- Heartbeat mechanism and stale connection cleanup

**NotificationService** (`services/notification_service.py`)
- Multi-type notifications (completion, error, progress, system)
- Notification history and statistics tracking
- Email/webhook integration ready architecture
- Configurable filtering and management

### API Layer

**Pipeline API** (`api/pipeline.py`)
- Complete pipeline management endpoints
- Process video with configuration options
- Status monitoring and job history
- Pipeline cancellation and cleanup
- Health checks and system statistics

**Summarization API** (`api/summarization.py`)
- Direct AI summarization endpoints
- Sync and async processing options
- Cost estimation and validation
- Background job management

**Dual Transcript API** (`api/transcripts.py`) ✅ **NEW**
- `POST /api/transcripts/dual/extract` - Start dual transcript extraction
- `GET /api/transcripts/dual/jobs/{job_id}` - Monitor extraction progress
- `POST /api/transcripts/dual/estimate` - Get processing time estimates  
- `GET /api/transcripts/dual/compare/{video_id}` - Force comparison analysis
- Background job processing with real-time progress updates
- YouTube captions, Whisper AI, or both sources simultaneously

## Development Patterns

### Service Dependency Injection

```python
def get_summary_pipeline(
    video_service: VideoService = Depends(get_video_service),
    transcript_service: TranscriptService = Depends(get_transcript_service),
    ai_service: AnthropicSummarizer = Depends(get_ai_service),
    cache_manager: CacheManager = Depends(get_cache_manager),
    notification_service: NotificationService = Depends(get_notification_service)
) -> SummaryPipeline:
    return SummaryPipeline(...)
```

### Database Registry Pattern (CRITICAL ARCHITECTURE)

**Problem Solved**: SQLAlchemy "Multiple classes found for path" relationship resolver errors

```python
# Always use the registry for model creation
from backend.core.database_registry import registry
from backend.models.base import Model

# Models inherit from Model (which uses registry.Base)
class User(Model):
    __tablename__ = "users"
    # Use fully qualified relationship paths to prevent conflicts
    summaries = relationship("backend.models.summary.Summary", back_populates="user")

# Registry ensures single Base instance and safe model registration
registry.create_all_tables(engine)  # For table creation
registry.register_model(ModelClass)  # Automatic via BaseModel mixin
```

**Key Benefits**:
- Prevents SQLAlchemy table redefinition conflicts
- Thread-safe singleton pattern
- Automatic model registration and deduplication
- Production-ready architecture
- Clean testing with registry reset capabilities

### Authentication Pattern

```python
# Protected endpoint with user dependency
@router.post("/api/protected")
async def protected_endpoint(
    current_user: User = Depends(get_current_user),
    db: Session = Depends(get_db)
):
    return {"user_id": current_user.id}

# JWT token validation and refresh
from backend.services.auth_service import AuthService
auth_service = AuthService()
user = await auth_service.authenticate_user(email, password)
tokens = auth_service.create_access_token(user)
```

### Async Pipeline Pattern

```python
async def process_video(self, video_url: str, config: PipelineConfig = None) -> str:
    job_id = str(uuid.uuid4())
    result = PipelineResult(job_id=job_id, video_url=video_url, ...)
    self.active_jobs[job_id] = result
    
    # Start background processing
    asyncio.create_task(self._execute_pipeline(job_id, config))
    return job_id
```

### Error Handling Pattern

```python
try:
    result = await self.ai_service.generate_summary(request)
except AIServiceError as e:
    raise HTTPException(status_code=500, detail={
        "error": "AI service error",
        "message": e.message,
        "code": e.error_code
    })
```

## Configuration and Environment

### Required Environment Variables

```bash
# Core Services
ANTHROPIC_API_KEY=sk-ant-...           # Required for AI summarization
YOUTUBE_API_KEY=AIza...                # YouTube Data API v3 key
GOOGLE_API_KEY=AIza...                 # Google/Gemini API key

# Feature Flags
USE_MOCK_SERVICES=false                # Disable mock services
ENABLE_REAL_TRANSCRIPT_EXTRACTION=true # Enable real transcript extraction

# Video Download & Storage Configuration
VIDEO_DOWNLOAD_STORAGE_PATH=./video_storage     # Base storage directory
VIDEO_DOWNLOAD_KEEP_AUDIO_FILES=true           # Save audio for re-transcription
VIDEO_DOWNLOAD_AUDIO_CLEANUP_DAYS=30           # Audio retention period
VIDEO_DOWNLOAD_MAX_STORAGE_GB=10               # Storage limit

# Faster-Whisper Configuration (20-32x Speed Improvement)
VIDEO_DOWNLOAD_WHISPER_MODEL=large-v3-turbo    # Model: 'large-v3-turbo', 'large-v3', 'medium', 'small', 'base'
VIDEO_DOWNLOAD_WHISPER_DEVICE=auto             # Device: 'auto', 'cpu', 'cuda'
VIDEO_DOWNLOAD_WHISPER_COMPUTE_TYPE=auto       # Compute: 'auto', 'int8', 'float16', 'float32'
VIDEO_DOWNLOAD_WHISPER_BEAM_SIZE=5             # Beam search size (1-10, higher = better quality)
VIDEO_DOWNLOAD_WHISPER_VAD_FILTER=true         # Voice Activity Detection (efficiency)
VIDEO_DOWNLOAD_WHISPER_WORD_TIMESTAMPS=true    # Word-level timestamps
VIDEO_DOWNLOAD_WHISPER_TEMPERATURE=0.0         # Sampling temperature (0 = deterministic)
VIDEO_DOWNLOAD_WHISPER_BEST_OF=5               # Number of candidates when sampling

# Dependencies: faster-whisper automatically handles dependencies
# pip install faster-whisper torch pydub yt-dlp pytubefix
# GPU acceleration: CUDA automatically detected and used when available

# Optional Configuration
DATABASE_URL=sqlite:///./data/app.db   # Database connection
REDIS_URL=redis://localhost:6379/0    # Cache backend (optional)
LOG_LEVEL=INFO                         # Logging level
CORS_ORIGINS=http://localhost:3000     # Frontend origins
```

### Service Configuration

Services are configured through dependency injection with sensible defaults:

```python
# Cost-optimized AI model
ai_service = AnthropicSummarizer(
    api_key=api_key, 
    model="claude-3-5-haiku-20241022"  # Cost-effective choice
)

# Cache with TTL
cache_manager = CacheManager(default_ttl=3600)  # 1 hour default

# Pipeline with retry logic
config = PipelineConfig(
    summary_length="standard",
    quality_threshold=0.7,
    max_retries=2,
    enable_notifications=True
)
```

## Testing Strategy

### Unit Tests
- **Location**: `tests/unit/`
- **Coverage**: 17+ tests for pipeline orchestration
- **Mocking**: All external services mocked
- **Patterns**: Async test patterns with proper fixtures

### Integration Tests
- **Location**: `tests/integration/`
- **Coverage**: 20+ API endpoint scenarios
- **Testing**: Full FastAPI integration with TestClient
- **Validation**: Request/response validation and error handling

### Running Tests

```bash
# From backend directory
PYTHONPATH=/path/to/youtube-summarizer python3 -m pytest tests/unit/ -v
PYTHONPATH=/path/to/youtube-summarizer python3 -m pytest tests/integration/ -v

# With coverage
python3 -m pytest tests/ --cov=backend --cov-report=html
```

## Common Development Tasks

### Adding New API Endpoints

1. Create endpoint in appropriate `api/` module
2. Add business logic to `services/` layer
3. Update `main.py` to include router
4. Add unit and integration tests
5. Update API documentation

### Adding New Services

1. Create service class in `services/`
2. Implement proper async patterns
3. Add error handling with custom exceptions
4. Create dependency injection function
5. Add comprehensive unit tests

### Debugging Pipeline Issues

```python
# Enable detailed logging
import logging
logging.getLogger("backend").setLevel(logging.DEBUG)

# Check pipeline status
pipeline = get_summary_pipeline()
result = await pipeline.get_pipeline_result(job_id)
print(f"Status: {result.status}, Error: {result.error}")

# Monitor active jobs
active_jobs = pipeline.get_active_jobs()
print(f"Active jobs: {len(active_jobs)}")
```

## Performance Optimization

### Faster-Whisper Performance (✅ MAJOR UPGRADE)
- **20-32x Speed Improvement**: CTranslate2 optimization engine provides massive speed gains
- **Large-v3-Turbo Model**: Combines best accuracy with 5-8x additional speed over large-v3
- **Intelligent Processing**: Voice Activity Detection reduces processing time by filtering silence
- **CPU Optimization**: int8 quantization provides excellent performance even without GPU
- **GPU Acceleration**: Automatic CUDA detection and utilization when available
- **Native MP3**: Direct processing without audio conversion overhead
- **Real-time Performance**: Typical 2-3x faster than realtime processing speeds

**Benchmark Results** (3.6 minute video):
- **Processing Time**: 94 seconds (vs ~30+ minutes with OpenAI Whisper)
- **Quality Score**: 1.000 (perfect transcription accuracy)
- **Confidence Score**: 0.962 (very high confidence)
- **Speed Ratio**: 2.3x faster than realtime

### Async Patterns
- All I/O operations use async/await
- Background tasks for long-running operations
- Connection pooling for external services
- Proper exception handling to prevent blocking

### Caching Strategy
- Pipeline results cached for 1 hour
- Transcript and metadata cached separately
- Cache invalidation on video updates
- Redis-ready for distributed caching

### Cost Optimization
- Claude 3.5 Haiku for 80% cost savings vs GPT-4
- Intelligent chunking prevents token waste
- Cost estimation and limits
- Quality scoring to avoid unnecessary retries

## Security Considerations

### API Security
- Environment variable for API keys
- Input validation on all endpoints
- Rate limiting (implement with Redis)
- CORS configuration for frontend origins

### Error Sanitization
```python
# Never expose internal errors to clients
except Exception as e:
    logger.error(f"Internal error: {e}")
    raise HTTPException(status_code=500, detail="Internal server error")
```

### Content Validation
```python
# Validate transcript length
if len(request.transcript.strip()) < 50:
    raise HTTPException(status_code=400, detail="Transcript too short")
```

## Monitoring and Observability

### Health Checks
- `/api/health` - Service health status
- `/api/stats` - Pipeline processing statistics
- WebSocket connection monitoring
- Background job tracking

### Logging
- Structured logging with JSON format
- Error tracking with context
- Performance metrics logging
- Request/response logging (without sensitive data)

### Metrics
```python
# Built-in metrics
stats = {
    "active_jobs": len(pipeline.get_active_jobs()),
    "cache_stats": await cache_manager.get_cache_stats(),
    "notification_stats": notification_service.get_notification_stats(),
    "websocket_connections": websocket_manager.get_stats()
}
```

## Deployment Considerations

### Production Configuration
- Use Redis for caching and session storage
- Configure proper logging (structured JSON)
- Set up health checks and monitoring
- Use environment-specific configuration
- Enable HTTPS and security headers

### Scaling Patterns
- Stateless design enables horizontal scaling
- Background job processing via task queue
- Database connection pooling
- Load balancer health checks

### Database Migrations & Epic 4 Features

**Current Status:** ✅ Epic 4 migration complete (add_epic_4_features)

**Database Schema:** 21 tables including Epic 4 features:
- **Multi-Agent Tables:** `agent_summaries`, `prompt_templates`
- **Enhanced Export Tables:** `export_metadata`, `summary_sections`
- **RAG Chat Tables:** `chat_sessions`, `chat_messages`, `video_chunks`
- **Analytics Tables:** `playlist_analysis`, `rag_analytics`, `prompt_experiments`

**Migration Commands:**
```bash
# Check migration status
python3 ../../scripts/utilities/migration_manager.py status

# Apply migrations (from backend directory)
PYTHONPATH=/Users/enias/projects/my-ai-projects/apps/youtube-summarizer \
  ../venv/bin/python3 -m alembic upgrade head

# Create new migration
python3 -m alembic revision --autogenerate -m "Add new feature"
```

**Python 3.11 Requirement:** Epic 4 requires Python 3.11+ for:
- `chromadb`: Vector database for RAG functionality
- `sentence-transformers`: Embedding generation for semantic search
- `aiohttp`: Async HTTP client for DeepSeek API integration

**Environment Setup:**
```bash
# Remove old environment if needed
rm -rf venv

# Create Python 3.11 virtual environment
/opt/homebrew/bin/python3.11 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

# Install Epic 4 dependencies
pip install chromadb sentence-transformers aiohttp

# Verify installation
python --version  # Should show Python 3.11.x
```

## Troubleshooting

### Common Issues

**"Pydantic validation error: Extra inputs are not permitted"**
- Issue: Environment variables not defined in Settings model
- Solution: Add `extra = "ignore"` to Config class in `core/config.py`

**"Table already exists" during migration**
- Issue: Database already has tables that migration tries to create
- Solution: Use `alembic stamp existing_revision` then `alembic upgrade head`

**"Multiple head revisions present"**
- Issue: Multiple migration branches need merging
- Solution: Use `alembic merge head1 head2 -m "Merge branches"`

**"Python 3.9 compatibility issues with Epic 4"**
- Issue: ChromaDB and modern AI libraries require Python 3.11+
- Solution: Recreate virtual environment with Python 3.11 (see Environment Setup above)

**"Anthropic API key not configured"**
- Solution: Set `ANTHROPIC_API_KEY` environment variable

**"Mock data returned instead of real transcripts"**
- Check: `USE_MOCK_SERVICES=false` in .env
- Solution: Set `ENABLE_REAL_TRANSCRIPT_EXTRACTION=true`

**"404 Not Found for /api/transcripts/extract"**
- Check: Import statements in main.py
- Solution: Use `from backend.api.transcripts import router` (not transcripts_stub)

**"Radio button selection not working"**
- Issue: Circular state updates in React
- Solution: Use ref tracking in useTranscriptSelector hook

**"VAD filter removes all audio / 0 segments generated"**
- Issue: Voice Activity Detection too aggressive for music/instrumental content
- Solution: Set `VIDEO_DOWNLOAD_WHISPER_VAD_FILTER=false` for music videos
- Alternative: Use `whisper_vad_filter=False` in service configuration

**"Faster-whisper model download fails"**
- Issue: Network issues downloading large-v3-turbo model from HuggingFace
- Solution: Model will automatically fallback to standard large-v3
- Check: Ensure internet connection for initial model download

**"CPU transcription too slow"**
- Issue: CPU-only processing on large models
- Solution: Use smaller model (`base` or `small`) or enable GPU acceleration
- Config: `VIDEO_DOWNLOAD_WHISPER_MODEL=base` for faster CPU processing

**Pipeline jobs stuck in "processing" state**
- Check: `pipeline.get_active_jobs()` for zombie jobs
- Solution: Restart service or call cleanup endpoint

**WebSocket connections not receiving updates**
- Check: WebSocket connection in browser dev tools
- Solution: Verify WebSocket manager singleton initialization

**High AI costs**
- Check: Summary length configuration and transcript sizes
- Solution: Implement cost limits and brief summary defaults

**Transcript extraction failures**
- Check: IntelligentVideoDownloader fallback chain logs
- Solution: Review which tier failed and check API keys/dependencies

### Debug Commands

```python
# Pipeline debugging
from backend.services.summary_pipeline import SummaryPipeline
pipeline = SummaryPipeline(...)
result = await pipeline.get_pipeline_result("job_id")

# Cache debugging
from backend.services.cache_manager import CacheManager
cache = CacheManager()
stats = await cache.get_cache_stats()

# WebSocket debugging
from backend.core.websocket_manager import websocket_manager
connections = websocket_manager.get_stats()
```

This backend is designed for production use with comprehensive error handling, monitoring, and scalability patterns. All services follow async patterns and clean architecture principles.