implement core api

.env

@@ -1,26 +0,0 @@
-# OpenAI
-OPENAI_API_KEY=""
-
-# Azure OpenAI
-AZURE_API_KEY=""
-AZURE_API_BASE=""
-AZURE_API_VERSION=""
-OPENROUTER_API_KEY = "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"
-# Google Vertex AI
-VERTEXAI_PROJECT=""
-VERTEXAI_LOCATION=""
-GOOGLE_APPLICATION_CREDENTIALS=""
-GITHUB_API_KEY = "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"
-GITHUB_TOKEN = "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"
-OPENAI_API_KEY = "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"
-# Google Gemini
-GEMINI_API_KEY="AIzaSyBUCGQ_hDLAHQN-T1ycWBJV8SGfwusfEjg"
-
-...
-
-# Kokoro TTS Settings
-KOKORO_MODEL_PATH="models/kokoro-v0_19.onnx"
-KOKORO_VOICES_PATH="models/voices.bin"
-KOKORO_DEFAULT_VOICE="af"
-KOKORO_DEFAULT_SPEED="1.0"
-KOKORO_DEFAULT_LANG="en-us"

.env.example

@@ -1,26 +1,77 @@
-# OpenAI
-OPENAI_API_KEY=""
-
-# Azure OpenAI
-AZURE_API_KEY=""
-AZURE_API_BASE=""
-AZURE_API_VERSION=""
-OPENROUTER_API_KEY = ""
-# Google Vertex AI
-VERTEXAI_PROJECT=""
-VERTEXAI_LOCATION=""
-GOOGLE_APPLICATION_CREDENTIALS=""
-GITHUB_API_KEY = ""
-GITHUB_TOKEN = ""
-OPENAI_API_KEY = ""
-# Google Gemini
-GEMINI_API_KEY=""
-
-...
-
-# Kokoro TTS Settings
-KOKORO_MODEL_PATH="models/kokoro-v0_19.onnx"
-KOKORO_VOICES_PATH="models/voices.bin"
-KOKORO_DEFAULT_VOICE="af"
-KOKORO_DEFAULT_SPEED="1.0"
-KOKORO_DEFAULT_LANG="en-us"
+# FastAPI Video Backend Environment Configuration
+# Copy this file to .env and update the values
+
+# Application Settings
+APP_NAME="FastAPI Video Backend"
+APP_VERSION="0.1.0"
+DEBUG=true
+ENVIRONMENT=development
+
+# Server Settings
+HOST=0.0.0.0
+PORT=8000
+RELOAD=true
+
+# API Settings
+API_V1_PREFIX="/api/v1"
+DOCS_URL="/docs"
+REDOC_URL="/redoc"
+OPENAPI_URL="/openapi.json"
+
+# CORS Settings
+ALLOWED_ORIGINS="http://localhost:3000,http://localhost:8080,http://127.0.0.1:3000"
+ALLOWED_METHODS="GET,POST,PUT,DELETE,OPTIONS"
+ALLOWED_HEADERS="*"
+
+# Redis Settings
+REDIS_URL="redis://localhost:6379/0"
+REDIS_HOST=localhost
+REDIS_PORT=6379
+REDIS_DB=0
+REDIS_PASSWORD=
+REDIS_MAX_CONNECTIONS=20
+REDIS_SOCKET_TIMEOUT=5
+REDIS_SOCKET_CONNECT_TIMEOUT=5
+
+# Clerk Authentication Settings (REQUIRED)
+CLERK_SECRET_KEY=your_clerk_secret_key_here
+CLERK_PUBLISHABLE_KEY=your_clerk_publishable_key_here
+CLERK_WEBHOOK_SECRET=your_clerk_webhook_secret_here
+CLERK_JWT_VERIFICATION=true
+
+# Job Queue Settings
+JOB_QUEUE_NAME=video_generation_queue
+JOB_QUEUE_MAX_SIZE=1000
+JOB_DEFAULT_TIMEOUT=3600
+JOB_RETRY_ATTEMPTS=3
+
+# File Storage Settings
+UPLOAD_DIR=./uploads
+MAX_FILE_SIZE=104857600
+ALLOWED_FILE_TYPES="image/jpeg,image/png,image/gif,video/mp4,text/plain"
+
+# Rate Limiting Settings
+RATE_LIMIT_REQUESTS=100
+RATE_LIMIT_WINDOW=60
+RATE_LIMIT_PER_USER=50
+
+# Logging Settings
+LOG_LEVEL=INFO
+LOG_FORMAT=json
+LOG_FILE=
+LOG_ROTATION="1 day"
+LOG_RETENTION="30 days"
+
+# Security Settings (REQUIRED)
+SECRET_KEY=your_super_secret_key_here_change_in_production
+ACCESS_TOKEN_EXPIRE_MINUTES=30
+REFRESH_TOKEN_EXPIRE_DAYS=7
+
+# Video Generation Settings
+VIDEO_OUTPUT_DIR=./videos
+VIDEO_QUALITY_DEFAULT=medium
+VIDEO_MAX_DURATION=600
+
+# Health Check Settings
+HEALTH_CHECK_INTERVAL=30
+HEALTH_CHECK_TIMEOUT=5

.gitignore

@@ -9,6 +9,8 @@ __pycache__/
 # Distribution / packaging
 .Python
 env/
+.env
+.*env
 build/
 develop-eggs/
 dist/

.kiro/specs/fastapi-backend/design.md

@@ -0,0 +1,1055 @@
+# Design Document
+
+## Overview
+
+This document outlines the design for a simplified FastAPI backend that serves as the primary interface for the multi-agent video generation system. The backend uses Pydantic for all data modeling and validation, Clerk for authentication, and Redis for both caching and job queuing. The design emphasizes simplicity and rapid development while maintaining clean architecture principles.
+
+The system provides REST API endpoints for video generation requests and job management, with Redis handling both the job queue and caching layer. Authentication is managed entirely through Clerk, eliminating the need for custom user management.
+
+## Architecture
+
+### High-Level Architecture
+
+```mermaid
+graph TB
+    subgraph "Client Layer"
+        WEB[Web Frontend]
+        MOBILE[Mobile App]
+        API_CLIENT[API Clients]
+    end
+    
+    subgraph "API Gateway Layer"
+        NGINX[Nginx Reverse Proxy]
+        RATE_LIMIT[Rate Limiting]
+        AUTH_MW[Authentication Middleware]
+    end
+    
+    subgraph "FastAPI Application"
+        API_ROUTER[API Routers]
+        WEBSOCKET[WebSocket Handlers]
+        MIDDLEWARE[Custom Middleware]
+        DEPS[Dependencies]
+    end
+    
+    subgraph "Business Logic Layer"
+        VIDEO_SERVICE[Video Generation Service]
+        JOB_SERVICE[Job Management Service]
+        FILE_SERVICE[File Management Service]
+        NOTIFICATION_SERVICE[Notification Service]
+    end
+    
+    subgraph "Data Layer"
+        REDIS[(Redis)]
+        FILE_STORAGE[Local File Storage]
+    end
+    
+    subgraph "External Services"
+        CLERK[Clerk Authentication]
+    end
+    
+    subgraph "External Systems"
+        VIDEO_PIPELINE[Multi-Agent Video Pipeline]
+        MONITORING[Monitoring & Logging]
+    end
+    
+    WEB --> NGINX
+    MOBILE --> NGINX
+    API_CLIENT --> NGINX
+    
+    NGINX --> RATE_LIMIT
+    RATE_LIMIT --> AUTH_MW
+    AUTH_MW --> API_ROUTER
+    AUTH_MW --> WEBSOCKET
+    
+    API_ROUTER --> MIDDLEWARE
+    WEBSOCKET --> MIDDLEWARE
+    MIDDLEWARE --> DEPS
+    
+    DEPS --> VIDEO_SERVICE
+    DEPS --> JOB_SERVICE
+    DEPS --> FILE_SERVICE
+    DEPS --> NOTIFICATION_SERVICE
+    
+    VIDEO_SERVICE --> REDIS
+    JOB_SERVICE --> REDIS
+    FILE_SERVICE --> FILE_STORAGE
+    NOTIFICATION_SERVICE --> REDIS
+    
+    AUTH_MW --> CLERK
+    
+    QUEUE --> VIDEO_PIPELINE
+    VIDEO_PIPELINE --> MONITORING
+```
+
+### Project Structure
+
+Simplified structure focusing on Pydantic models and Redis:
+
+```
+src/
+├── app/
+│   ├── main.py                    # FastAPI application entry point
+│   ├── api/                       # API layer
+│   │   ├── dependencies.py        # Shared dependencies (Clerk auth, Redis)
+│   │   └── v1/                    # API version 1
+│   │       ├── __init__.py
+│   │       ├── videos.py          # Video generation endpoints
+│   │       ├── jobs.py            # Job management endpoints
+│   │       └── system.py          # System health endpoints
+│   ├── core/                      # Core utilities and configurations
+│   │   ├── config.py              # Application settings
+│   │   ├── redis.py               # Redis connection and utilities
+│   │   ├── auth.py                # Clerk authentication utilities
+│   │   ├── logger.py              # Logging configuration
+│   │   └── exceptions.py          # Custom exceptions
+│   ├── services/                  # Business logic layer
+│   │   ├── video_service.py       # Video generation business logic
+│   │   ├── job_service.py         # Job management logic
+│   │   └── queue_service.py       # Redis queue management
+│   ├── models/                    # Pydantic models only
+│   │   ├── __init__.py
+│   │   ├── job.py                 # Job data models
+│   │   ├── video.py               # Video metadata models
+│   │   ├── user.py                # User data models (from Clerk)
+│   │   └── system.py              # System status models
+│   ├── middleware/                # Custom middleware
+│   │   ├── __init__.py
+│   │   ├── cors.py                # CORS middleware
+│   │   ├── clerk_auth.py          # Clerk authentication middleware
+│   │   └── error_handling.py      # Global error handling
+│   └── utils/                     # Utility functions
+│       ├── __init__.py
+│       ├── file_utils.py          # File handling utilities
+│       └── helpers.py             # General helper functions
+├── tests/                         # Test suite
+│   ├── conftest.py                # Test configuration
+│   ├── test_api/                  # API endpoint tests
+│   └── test_services/             # Service layer tests
+└── scripts/                       # Utility scripts
+    └── setup_redis.py             # Redis setup script
+```
+
+## Components and Interfaces
+
+### API Layer Components
+
+#### 1. Video Generation Router (`api/v1/videos.py`)
+
+**Endpoints:**
+- `POST /api/v1/videos/generate` - Submit video generation request
+- `POST /api/v1/videos/batch` - Submit batch video generation requests
+- `GET /api/v1/videos/jobs/{job_id}/status` - Get job status
+- `GET /api/v1/videos/jobs/{job_id}/download` - Download completed video
+- `GET /api/v1/videos/jobs/{job_id}/metadata` - Get job metadata
+
+**Key Features:**
+- Request validation using Pydantic schemas
+- Async request handling
+- Integration with job service
+- File streaming for downloads
+- Comprehensive error handling
+
+#### 2. Job Management Router (`api/v1/jobs.py`)
+
+**Endpoints:**
+- `GET /api/v1/jobs` - List jobs with pagination and filtering
+- `POST /api/v1/jobs/{job_id}/cancel` - Cancel job
+- `DELETE /api/v1/jobs/{job_id}` - Delete job (soft delete)
+- `GET /api/v1/jobs/{job_id}/logs` - Get job processing logs
+
+**Key Features:**
+- Pagination support using `fastcrud` patterns
+- Advanced filtering and sorting
+- Job lifecycle management
+- Audit trail maintenance
+
+#### 3. User Management Router (`api/v1/users.py`)
+
+**Endpoints:**
+- `POST /api/v1/users/register` - User registration
+- `POST /api/v1/users/login` - User authentication
+- `GET /api/v1/users/profile` - Get user profile
+- `PUT /api/v1/users/profile` - Update user profile
+- `POST /api/v1/users/verify-email` - Email verification
+- `POST /api/v1/users/reset-password` - Password reset
+
+**Key Features:**
+- JWT-based authentication
+- Email verification workflow
+- Password reset functionality
+- Profile management
+
+#### 4. Subscription Management Router (`api/v1/subscriptions.py`)
+
+**Endpoints:**
+- `GET /api/v1/subscriptions/plans` - List available subscription plans
+- `POST /api/v1/subscriptions/subscribe` - Create new subscription
+- `GET /api/v1/subscriptions/current` - Get current user subscription
+- `PUT /api/v1/subscriptions/upgrade` - Upgrade subscription plan
+- `POST /api/v1/subscriptions/cancel` - Cancel subscription
+- `GET /api/v1/subscriptions/usage` - Get usage statistics
+
+**Key Features:**
+- Subscription plan management
+- Credit tracking and usage monitoring
+- Billing integration
+- Usage analytics
+
+#### 5. WebSocket Handler (`api/v1/websockets.py`)
+
+**Endpoints:**
+- `WS /ws/jobs/{job_id}` - Real-time job status updates
+- `WS /ws/system/health` - System health monitoring
+
+**Key Features:**
+- Connection management
+- Real-time status broadcasting
+- Graceful disconnection handling
+- Authentication for WebSocket connections
+
+### Service Layer Components
+
+#### 1. Video Generation Service (`services/video_service.py`)
+
+**Responsibilities:**
+- Interface with multi-agent video generation pipeline
+- Job queue management
+- Configuration validation
+- Progress tracking
+
+**Key Methods:**
+```python
+async def create_video_job(request: VideoGenerationRequest) -> JobResponse
+async def create_batch_jobs(requests: List[VideoGenerationRequest]) -> BatchJobResponse
+async def get_job_status(job_id: str) -> JobStatus
+async def cancel_job(job_id: str) -> bool
+```
+
+#### 2. Job Management Service (`services/job_service.py`)
+
+**Responsibilities:**
+- Job lifecycle management
+- Status updates and notifications
+- Resource allocation
+- Performance monitoring
+
+**Key Methods:**
+```python
+async def update_job_status(job_id: str, status: JobStatus, metadata: dict)
+async def get_jobs_paginated(filters: JobFilters, pagination: PaginationParams) -> PaginatedResponse
+async def cleanup_completed_jobs(retention_days: int)
+```
+
+#### 3. File Management Service (`services/file_service.py`)
+
+**Responsibilities:**
+- AWS S3 file upload/download handling
+- Storage management with versioning
+- Security scanning and validation
+- Metadata extraction and storage
+
+**Key Methods:**
+```python
+async def upload_to_s3(file: UploadFile, user_id: str, file_type: str) -> S3FileMetadata
+async def download_from_s3(s3_key: str, bucket: str) -> StreamingResponse
+async def generate_presigned_url(s3_key: str, expiration: int = 3600) -> str
+async def validate_file(file: UploadFile) -> ValidationResult
+async def cleanup_expired_files()
+async def create_video_thumbnail(video_s3_key: str) -> str
+```
+
+#### 4. Subscription Service (`services/subscription_service.py`)
+
+**Responsibilities:**
+- Subscription lifecycle management
+- Credit tracking and usage monitoring
+- Billing integration
+- Plan upgrade/downgrade logic
+
+**Key Methods:**
+```python
+async def create_subscription(user_id: str, plan_id: int, payment_method: str) -> Subscription
+async def check_user_credits(user_id: str) -> int
+async def consume_credits(user_id: str, credits: int) -> bool
+async def upgrade_subscription(user_id: str, new_plan_id: int) -> Subscription
+async def cancel_subscription(user_id: str) -> bool
+async def process_billing_cycle()
+```
+
+#### 5. AWS Integration Service (`services/aws_service.py`)
+
+**Responsibilities:**
+- AWS service integration and management
+- DynamoDB operations for high-frequency data
+- SQS queue management
+- CloudWatch metrics and logging
+
+**Key Methods:**
+```python
+async def put_job_status_dynamodb(job_id: str, status: dict)
+async def get_job_status_history(job_id: str) -> List[dict]
+async def send_sqs_message(queue_url: str, message: dict)
+async def put_cloudwatch_metric(metric_name: str, value: float, dimensions: dict)
+async def log_user_activity(user_id: str, activity: dict)
+```
+
+### Data Layer Components
+
+#### Pydantic Data Models
+
+**Job Model (`models/job.py`):**
+```python
+from pydantic import BaseModel, Field
+from datetime import datetime
+from enum import Enum
+from typing import Optional, Dict, Any
+import uuid
+
+class JobStatus(str, Enum):
+    QUEUED = "queued"
+    PROCESSING = "processing"
+    COMPLETED = "completed"
+    FAILED = "failed"
+    CANCELLED = "cancelled"
+
+class JobCreate(BaseModel):
+    topic: str = Field(..., min_length=1, max_length=500)
+    context: str = Field(..., min_length=1, max_length=2000)
+    model: Optional[str] = None
+    quality: str = Field(default="medium")
+    use_rag: bool = Field(default=False)
+    configuration: Optional[Dict[str, Any]] = None
+
+class Job(BaseModel):
+    id: str = Field(default_factory=lambda: str(uuid.uuid4()))
+    user_id: str  # Clerk user ID
+    status: JobStatus = JobStatus.QUEUED
+    job_type: str = "video_generation"
+    configuration: Dict[str, Any]
+    progress: float = Field(default=0.0, ge=0.0, le=100.0)
+    error_message: Optional[str] = None
+    created_at: datetime = Field(default_factory=datetime.utcnow)
+    updated_at: datetime = Field(default_factory=datetime.utcnow)
+    completed_at: Optional[datetime] = None
+
+class JobResponse(BaseModel):
+    job_id: str
+    status: JobStatus
+    progress: float
+    created_at: datetime
+    estimated_completion: Optional[datetime] = None
+```
+
+**Video Model (`models/video.py`):**
+```python
+from pydantic import BaseModel, Field
+from datetime import datetime
+from typing import Optional
+import uuid
+
+class VideoMetadata(BaseModel):
+    id: str = Field(default_factory=lambda: str(uuid.uuid4()))
+    job_id: str
+    filename: str
+    file_path: str
+    file_size: int = Field(gt=0)
+    duration: Optional[float] = Field(None, gt=0)
+    resolution: Optional[str] = None
+    format: str
+    created_at: datetime = Field(default_factory=datetime.utcnow)
+
+class VideoResponse(BaseModel):
+    video_id: str
+    job_id: str
+    filename: str
+    file_size: int
+    duration: Optional[float]
+    download_url: str
+    created_at: datetime
+```
+
+#### Pydantic Schemas
+
+**Request Schemas (`schemas/job.py`):**
+```python
+class VideoGenerationRequest(BaseModel):
+    topic: str = Field(..., min_length=1, max_length=500)
+    context: str = Field(..., min_length=1, max_length=2000)
+    model: Optional[str] = Field(None, description="AI model to use")
+    quality: VideoQuality = Field(VideoQuality.MEDIUM)
+    use_rag: bool = Field(False)
+    custom_config: Optional[Dict[str, Any]] = Field(None)
+    
+    model_config = ConfigDict(
+        json_schema_extra={
+            "example": {
+                "topic": "Pythagorean Theorem",
+                "context": "Explain the mathematical proof with visual demonstration",
+                "model": "gemini/gemini-2.5-flash-preview-04-17",
+                "quality": "medium",
+                "use_rag": True
+            }
+        }
+    )
+```
+
+**Response Schemas:**
+```python
+class JobResponse(BaseModel):
+    job_id: str
+    status: JobStatus
+    created_at: datetime
+    estimated_completion: Optional[datetime] = None
+    
+class JobStatusResponse(BaseModel):
+    job_id: str
+    status: JobStatus
+    progress: float
+    current_stage: Optional[str] = None
+    error_message: Optional[str] = None
+    created_at: datetime
+    updated_at: datetime
+    completed_at: Optional[datetime] = None
+```
+
+## Data Models
+
+### Core Entities
+
+#### Job Entity
+- **Primary Key:** UUID string
+- **Status:** Enum (queued, processing, completed, failed, cancelled)
+- **Configuration:** JSON field for flexible job parameters
+- **Progress Tracking:** Float percentage and current stage
+- **Audit Fields:** Created, updated, completed timestamps
+- **Soft Delete:** Support for data retention policies
+
+#### User Entity
+- **Authentication:** JWT-based authentication
+- **Authorization:** Role-based access control
+- **Rate Limiting:** Per-user request limits
+- **Audit Trail:** Request logging and monitoring
+
+#### Video Entity
+- **Metadata:** File size, duration, resolution, format
+- **Storage:** File path and storage location
+- **Relationships:** Linked to originating job
+- **Lifecycle:** Automatic cleanup policies
+
+### Redis Data Structure Design
+
+#### Redis Keys and Data Types
+
+**Job Storage (Hash):**
+```
+jobs:{job_id} -> Hash
+{
+  "id": "uuid",
+  "user_id": "clerk_user_id", 
+  "status": "queued|processing|completed|failed|cancelled",
+  "job_type": "video_generation",
+  "configuration": "json_string",
+  "progress": "0.0-100.0",
+  "error_message": "optional_error",
+  "created_at": "iso_datetime",
+  "updated_at": "iso_datetime",
+  "completed_at": "optional_iso_datetime"
+}
+```
+
+**Job Queue (List):**
+```
+job_queue -> List
+["job_id_1", "job_id_2", "job_id_3", ...]
+```
+
+**User Jobs Index (Set):**
+```
+user_jobs:{user_id} -> Set
+{"job_id_1", "job_id_2", "job_id_3", ...}
+```
+
+**Video Metadata (Hash):**
+```
+videos:{video_id} -> Hash
+{
+  "id": "uuid",
+  "job_id": "job_uuid",
+  "filename": "video.mp4",
+  "file_path": "/path/to/video.mp4",
+  "file_size": "bytes",
+  "duration": "seconds",
+  "resolution": "1920x1080",
+  "format": "mp4",
+  "created_at": "iso_datetime"
+}
+```
+
+**Job Status Cache (String with TTL):**
+```
+job_status:{job_id} -> String (TTL: 300 seconds)
+"processing" | "completed" | "failed"
+```
+
+**System Health (Hash):**
+```
+system:health -> Hash
+{
+  "redis": "healthy",
+  "queue_length": "5",
+  "active_jobs": "3",
+  "last_check": "iso_datetime"
+}
+```
+
+## Error Handling
+
+### Exception Hierarchy
+
+```python
+class APIException(Exception):
+    """Base API exception"""
+    def __init__(self, message: str, status_code: int = 500, error_code: str = None):
+        self.message = message
+        self.status_code = status_code
+        self.error_code = error_code
+
+class ValidationException(APIException):
+    """Request validation errors"""
+    def __init__(self, message: str, field_errors: List[dict] = None):
+        super().__init__(message, 422, "VALIDATION_ERROR")
+        self.field_errors = field_errors or []
+
+class NotFoundException(APIException):
+    """Resource not found"""
+    def __init__(self, resource: str):
+        super().__init__(f"{resource} not found", 404, "NOT_FOUND")
+
+class ConflictException(APIException):
+    """Resource conflict"""
+    def __init__(self, message: str):
+        super().__init__(message, 409, "CONFLICT")
+
+class RateLimitException(APIException):
+    """Rate limit exceeded"""
+    def __init__(self, retry_after: int = None):
+        super().__init__("Rate limit exceeded", 429, "RATE_LIMIT_EXCEEDED")
+        self.retry_after = retry_after
+```
+
+### Global Error Handler
+
+```python
+@app.exception_handler(APIException)
+async def api_exception_handler(request: Request, exc: APIException):
+    return JSONResponse(
+        status_code=exc.status_code,
+        content={
+            "error": {
+                "message": exc.message,
+                "error_code": exc.error_code,
+                "timestamp": datetime.utcnow().isoformat(),
+                "path": str(request.url.path)
+            }
+        }
+    )
+
+@app.exception_handler(ValidationError)
+async def validation_exception_handler(request: Request, exc: ValidationError):
+    return JSONResponse(
+        status_code=422,
+        content={
+            "error": {
+                "message": "Validation failed",
+                "error_code": "VALIDATION_ERROR",
+                "details": exc.errors(),
+                "timestamp": datetime.utcnow().isoformat(),
+                "path": str(request.url.path)
+            }
+        }
+    )
+```
+
+### Error Response Format
+
+All error responses follow a consistent structure:
+
+```json
+{
+  "error": {
+    "message": "Human-readable error message",
+    "error_code": "MACHINE_READABLE_CODE",
+    "details": {},
+    "timestamp": "2024-01-15T10:30:00Z",
+    "path": "/api/v1/videos/generate"
+  }
+}
+```
+
+## Testing Strategy
+
+### Testing Pyramid
+
+#### Unit Tests (70%)
+- **Service Layer:** Business logic validation
+- **CRUD Operations:** Database interaction testing
+- **Utility Functions:** Helper function validation
+- **Schema Validation:** Pydantic model testing
+
+#### Integration Tests (20%)
+- **API Endpoints:** Full request/response cycle
+- **Database Integration:** Real database operations
+- **External Service Integration:** Mock external dependencies
+- **WebSocket Connections:** Real-time communication testing
+
+#### End-to-End Tests (10%)
+- **Complete Workflows:** Full video generation pipeline
+- **User Journeys:** Multi-step user interactions
+- **Performance Testing:** Load and stress testing
+- **Security Testing:** Authentication and authorization
+
+### Test Configuration
+
+```python
+# conftest.py
+@pytest.fixture
+async def test_db():
+    """Create test database session"""
+    engine = create_async_engine(TEST_DATABASE_URL)
+    async with engine.begin() as conn:
+        await conn.run_sync(Base.metadata.create_all)
+    
+    async_session = async_sessionmaker(engine, expire_on_commit=False)
+    async with async_session() as session:
+        yield session
+    
+    async with engine.begin() as conn:
+        await conn.run_sync(Base.metadata.drop_all)
+
+@pytest.fixture
+def test_client():
+    """Create test client"""
+    return TestClient(app)
+
+@pytest.fixture
+async def authenticated_user(test_db):
+    """Create authenticated test user"""
+    user = await crud_users.create(
+        db=test_db,
+        object=UserCreate(
+            username="testuser",
+            email="[email protected]",
+            password="testpass123"
+        )
+    )
+    return user
+```
+
+### Test Examples
+
+```python
+# Test API endpoint
+async def test_create_video_job(test_client, authenticated_user):
+    request_data = {
+        "topic": "Test Topic",
+        "context": "Test context for video generation",
+        "quality": "medium"
+    }
+    
+    response = test_client.post(
+        "/api/v1/videos/generate",
+        json=request_data,
+        headers={"Authorization": f"Bearer {authenticated_user.token}"}
+    )
+    
+    assert response.status_code == 201
+    data = response.json()
+    assert "job_id" in data
+    assert data["status"] == "queued"
+
+# Test service layer
+async def test_video_service_create_job(test_db):
+    service = VideoService(test_db)
+    request = VideoGenerationRequest(
+        topic="Test Topic",
+        context="Test context"
+    )
+    
+    job = await service.create_video_job(request, user_id=1)
+    
+    assert job.status == JobStatus.QUEUED
+    assert job.configuration["topic"] == "Test Topic"
+```
+
+## Security Considerations
+
+### Authentication & Authorization
+
+#### JWT Token-Based Authentication
+- **Access Tokens:** Short-lived (15 minutes) for API access
+- **Refresh Tokens:** Long-lived (7 days) for token renewal
+- **Token Blacklisting:** Support for immediate token revocation
+- **Secure Storage:** HttpOnly cookies for web clients
+
+#### Role-Based Access Control (RBAC)
+- **User Roles:** admin, user, readonly
+- **Permission System:** Granular permissions for different operations
+- **Resource Ownership:** Users can only access their own resources
+- **Admin Override:** Administrators can access all resources
+
+### Input Validation & Sanitization
+
+#### Request Validation
+- **Pydantic Models:** Automatic type validation and conversion
+- **Field Constraints:** Length limits, format validation, range checks
+- **Custom Validators:** Business rule validation
+- **Sanitization:** XSS prevention and input cleaning
+
+#### File Upload Security
+- **File Type Validation:** Whitelist of allowed file types
+- **Size Limits:** Maximum file size enforcement
+- **Virus Scanning:** Integration with antivirus services
+- **Secure Storage:** Isolated file storage with access controls
+
+### Rate Limiting & DDoS Protection
+
+#### Multi-Level Rate Limiting
+- **Global Limits:** Overall API request limits
+- **Per-User Limits:** Individual user quotas
+- **Per-Endpoint Limits:** Specific endpoint restrictions
+- **Sliding Window:** Advanced rate limiting algorithms
+
+#### Implementation Strategy
+```python
+from slowapi import Limiter, _rate_limit_exceeded_handler
+from slowapi.util import get_remote_address
+
+limiter = Limiter(key_func=get_remote_address)
+
+@app.route("/api/v1/videos/generate")
+@limiter.limit("10/minute")
+async def generate_video(request: Request):
+    # Endpoint implementation
+    pass
+```
+
+### Data Protection
+
+#### Encryption
+- **Data at Rest:** Database encryption for sensitive fields
+- **Data in Transit:** TLS 1.3 for all communications
+- **File Encryption:** Encrypted file storage
+- **Key Management:** Secure key rotation policies
+
+#### Privacy Compliance
+- **Data Minimization:** Collect only necessary data
+- **Retention Policies:** Automatic data cleanup
+- **User Rights:** Data export and deletion capabilities
+- **Audit Logging:** Comprehensive access logging
+
+## Performance Optimization
+
+### Caching Strategy
+
+#### Multi-Level Caching
+- **Application Cache:** In-memory caching with Redis
+- **Database Query Cache:** SQLAlchemy query result caching
+- **HTTP Response Cache:** CDN and browser caching
+- **File System Cache:** Temporary file caching
+
+#### Cache Implementation
+```python
+from fastapi_cache.decorator import cache
+
+@router.get("/api/v1/jobs/{job_id}/status")
+@cache(expire=30)  # Cache for 30 seconds
+async def get_job_status(job_id: str):
+    return await job_service.get_status(job_id)
+```
+
+### Database Optimization
+
+#### Query Optimization
+- **Eager Loading:** Reduce N+1 query problems
+- **Indexing Strategy:** Optimized database indexes
+- **Connection Pooling:** Efficient database connections
+- **Query Monitoring:** Performance tracking and optimization
+
+#### Pagination & Filtering
+```python
+async def get_jobs_paginated(
+    page: int = 1,
+    items_per_page: int = 10,
+    filters: JobFilters = None
+) -> PaginatedResponse:
+    offset = (page - 1) * items_per_page
+    
+    query = select(Job).where(Job.is_deleted == False)
+    if filters:
+        query = apply_filters(query, filters)
+    
+    total = await db.scalar(select(func.count()).select_from(query.subquery()))
+    jobs = await db.execute(query.offset(offset).limit(items_per_page))
+    
+    return PaginatedResponse(
+        data=jobs.scalars().all(),
+        total_count=total,
+        page=page,
+        items_per_page=items_per_page
+    )
+```
+
+### Asynchronous Processing
+
+#### Background Tasks
+- **Celery Integration:** Distributed task processing
+- **Job Queues:** Redis-based task queuing
+- **Progress Tracking:** Real-time progress updates
+- **Error Recovery:** Automatic retry mechanisms
+
+#### WebSocket Optimization
+- **Connection Pooling:** Efficient WebSocket management
+- **Message Broadcasting:** Efficient multi-client updates
+- **Heartbeat Monitoring:** Connection health checks
+- **Graceful Degradation:** Fallback to polling if needed
+
+## Monitoring & Observability
+
+### Logging Strategy
+
+#### Structured Logging
+```python
+import structlog
+
+logger = structlog.get_logger()
+
+async def create_video_job(request: VideoGenerationRequest, user_id: int):
+    logger.info(
+        "Creating video job",
+        user_id=user_id,
+        topic=request.topic,
+        quality=request.quality
+    )
+    
+    try:
+        job = await video_service.create_job(request, user_id)
+        logger.info("Video job created successfully", job_id=job.id)
+        return job
+    except Exception as e:
+        logger.error(
+            "Failed to create video job",
+            user_id=user_id,
+            error=str(e),
+            exc_info=True
+        )
+        raise
+```
+
+### Metrics Collection
+
+#### Application Metrics
+- **Request Metrics:** Response times, status codes, throughput
+- **Business Metrics:** Job completion rates, user activity
+- **System Metrics:** CPU, memory, disk usage
+- **Custom Metrics:** Domain-specific measurements
+
+#### Health Checks
+```python
+@router.get("/health")
+async def health_check():
+    checks = {
+        "database": await check_database_health(),
+        "redis": await check_redis_health(),
+        "queue": await check_queue_health(),
+        "storage": await check_storage_health()
+    }
+    
+    overall_health = all(checks.values())
+    status_code = 200 if overall_health else 503
+    
+    return JSONResponse(
+        status_code=status_code,
+        content={
+            "status": "healthy" if overall_health else "unhealthy",
+            "checks": checks,
+            "timestamp": datetime.utcnow().isoformat()
+        }
+    )
+```
+
+### Distributed Tracing
+
+#### OpenTelemetry Integration
+- **Request Tracing:** End-to-end request tracking
+- **Service Dependencies:** Inter-service communication mapping
+- **Performance Analysis:** Bottleneck identification
+- **Error Correlation:** Error tracking across services
+
+## Deployment Architecture
+
+### Container Strategy
+
+#### Docker Configuration
+```dockerfile
+FROM python:3.11-slim
+
+WORKDIR /app
+
+# Install system dependencies
+RUN apt-get update && apt-get install -y \
+    gcc \
+    && rm -rf /var/lib/apt/lists/*
+
+# Install Python dependencies
+COPY requirements.txt .
+RUN pip install --no-cache-dir -r requirements.txt
+
+# Copy application code
+COPY src/ ./src/
+COPY migrations/ ./migrations/
+
+# Set environment variables
+ENV PYTHONPATH=/app/src
+ENV PYTHONUNBUFFERED=1
+
+# Expose port
+EXPOSE 8000
+
+# Run application
+CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000"]
+```
+
+#### AWS Deployment Configuration
+
+**AWS Services Integration:**
+- **RDS PostgreSQL:** Primary relational database for user data, jobs, subscriptions
+- **DynamoDB:** High-frequency data like job status updates, user activity tracking
+- **S3:** Video files, thumbnails, job outputs, user uploads
+- **ElastiCache Redis:** Session storage, caching, real-time data
+- **SQS:** Job queue management and inter-service communication
+- **CloudFront:** CDN for video delivery and static assets
+- **Lambda:** Serverless functions for background processing
+- **ECS/Fargate:** Container orchestration for API services
+
+**Docker Compose for Local Development:**
+```yaml
+version: '3.8'
+
+services:
+  api:
+    build: .
+    ports:
+      - "8000:8000"
+    environment:
+      - AWS_REGION=us-east-1
+      - AWS_ACCESS_KEY_ID=${AWS_ACCESS_KEY_ID}
+      - AWS_SECRET_ACCESS_KEY=${AWS_SECRET_ACCESS_KEY}
+      - DATABASE_URL=${RDS_DATABASE_URL}
+      - REDIS_URL=${ELASTICACHE_URL}
+      - S3_BUCKET=${S3_BUCKET_NAME}
+      - SQS_QUEUE_URL=${SQS_QUEUE_URL}
+      - DYNAMODB_TABLE_PREFIX=${DYNAMODB_PREFIX}
+    volumes:
+      - ./logs:/app/logs
+      - ~/.aws:/root/.aws:ro
+
+  localstack:
+    image: localstack/localstack:latest
+    ports:
+      - "4566:4566"
+    environment:
+      - SERVICES=s3,sqs,dynamodb,elasticache
+      - DEBUG=1
+      - DATA_DIR=/tmp/localstack/data
+    volumes:
+      - localstack_data:/tmp/localstack
+
+  postgres:
+    image: postgres:15
+    environment:
+      - POSTGRES_DB=videoapi_local
+      - POSTGRES_USER=user
+      - POSTGRES_PASSWORD=pass
+    volumes:
+      - postgres_data:/var/lib/postgresql/data
+    ports:
+      - "5432:5432"
+
+volumes:
+  postgres_data:
+  localstack_data:
+```
+
+**AWS CDK/Terraform Infrastructure:**
+```typescript
+// AWS CDK example structure
+export class VideoAPIStack extends Stack {
+  constructor(scope: Construct, id: string, props?: StackProps) {
+    super(scope, id, props);
+
+    // RDS PostgreSQL
+    const database = new rds.DatabaseInstance(this, 'VideoAPIDB', {
+      engine: rds.DatabaseInstanceEngine.postgres({
+        version: rds.PostgresEngineVersion.VER_15
+      }),
+      instanceType: ec2.InstanceType.of(ec2.InstanceClass.T3, ec2.InstanceSize.MICRO),
+      multiAz: true,
+      backupRetention: Duration.days(7)
+    });
+
+    // S3 Buckets
+    const videoBucket = new s3.Bucket(this, 'VideoBucket', {
+      versioned: true,
+      lifecycleRules: [{
+        id: 'DeleteOldVersions',
+        expiration: Duration.days(90)
+      }]
+    });
+
+    // DynamoDB Tables
+    const jobStatusTable = new dynamodb.Table(this, 'JobStatusTable', {
+      partitionKey: { name: 'job_id', type: dynamodb.AttributeType.STRING },
+      sortKey: { name: 'timestamp', type: dynamodb.AttributeType.NUMBER },
+      timeToLiveAttribute: 'ttl'
+    });
+
+    // ECS Fargate Service
+    const cluster = new ecs.Cluster(this, 'VideoAPICluster');
+    const taskDefinition = new ecs.FargateTaskDefinition(this, 'VideoAPITask');
+    
+    const container = taskDefinition.addContainer('api', {
+      image: ecs.ContainerImage.fromRegistry('your-api-image'),
+      environment: {
+        DATABASE_URL: database.instanceEndpoint.socketAddress,
+        S3_BUCKET: videoBucket.bucketName
+      }
+    });
+
+    new ecs.FargateService(this, 'VideoAPIService', {
+      cluster,
+      taskDefinition,
+      desiredCount: 2
+    });
+  }
+}
+```
+
+### Production Considerations
+
+#### Scalability
+- **Horizontal Scaling:** Multiple API instances behind load balancer
+- **Database Scaling:** Read replicas and connection pooling
+- **Cache Scaling:** Redis clustering for high availability
+- **File Storage:** Distributed storage solutions
+
+#### Security Hardening
+- **SSL/TLS:** End-to-end encryption
+- **Firewall Rules:** Network access restrictions
+- **Secret Management:** Secure credential storage
+- **Regular Updates:** Security patch management
+
+#### Monitoring & Alerting
+- **Application Monitoring:** APM tools integration
+- **Infrastructure Monitoring:** System metrics collection
+- **Log Aggregation:** Centralized logging solution
+- **Alert Management:** Proactive issue notification

.kiro/specs/fastapi-backend/requirements.md

@@ -0,0 +1,126 @@
+# Requirements Document
+
+## Introduction
+
+This document outlines the requirements for implementing a simple FastAPI backend for the multi-agent video generation system. The backend will use Pydantic for all data modeling and validation, Clerk for authentication, and Redis for caching and job queuing. The system will provide RESTful API endpoints to manage video generation requests, monitor processing status, and integrate with the existing multi-agent pipeline through Redis queues.
+
+## Requirements
+
+### Requirement 1
+
+**User Story:** As a client application, I want to submit video generation requests through a REST API, so that I can programmatically create educational videos from textual descriptions.
+
+#### Acceptance Criteria
+
+1. WHEN a POST request is made to `/api/v1/videos/generate` with topic and context data THEN the system SHALL accept the request and return a unique job ID
+2. WHEN the request includes optional parameters like model selection, quality settings, or RAG configuration THEN the system SHALL validate and apply these parameters
+3. WHEN the request payload is invalid or missing required fields THEN the system SHALL return a 422 validation error with detailed field-level error messages
+4. WHEN the system receives a valid request THEN it SHALL queue the job for processing and return a 201 status code with job metadata
+
+### Requirement 2
+
+**User Story:** As a client application, I want to monitor the status of video generation jobs, so that I can track progress and know when videos are ready for download.
+
+#### Acceptance Criteria
+
+1. WHEN a GET request is made to `/api/v1/videos/jobs/{job_id}/status` THEN the system SHALL return the current job status (queued, processing, completed, failed)
+2. WHEN a job is in progress THEN the system SHALL return progress information including current stage and percentage completion
+3. WHEN a job has failed THEN the system SHALL return error details and failure reason
+4. WHEN a job is completed THEN the system SHALL return metadata about the generated video including file size and duration
+5. WHEN an invalid job ID is provided THEN the system SHALL return a 404 error
+
+### Requirement 3
+
+**User Story:** As a client application, I want to retrieve completed videos and their metadata, so that I can download and use the generated content.
+
+#### Acceptance Criteria
+
+1. WHEN a GET request is made to `/api/v1/videos/jobs/{job_id}/download` for a completed job THEN the system SHALL return the video file as a streaming response
+2. WHEN a GET request is made to `/api/v1/videos/jobs/{job_id}/metadata` THEN the system SHALL return comprehensive job metadata including processing logs and performance metrics
+3. WHEN a job is not yet completed THEN the download endpoint SHALL return a 409 conflict error
+4. WHEN the video file is not found THEN the system SHALL return a 404 error
+5. WHEN downloading large files THEN the system SHALL support HTTP range requests for partial content delivery
+
+### Requirement 4
+
+**User Story:** As a system administrator, I want to manage and monitor the video generation pipeline, so that I can ensure optimal system performance and troubleshoot issues.
+
+#### Acceptance Criteria
+
+1. WHEN a GET request is made to `/api/v1/system/health` THEN the system SHALL return health status of all components including database, queue, and agent services
+2. WHEN a GET request is made to `/api/v1/system/metrics` THEN the system SHALL return performance metrics including queue length, processing times, and resource utilization
+3. WHEN a POST request is made to `/api/v1/system/jobs/{job_id}/cancel` THEN the system SHALL attempt to cancel the job and return cancellation status
+4. WHEN a GET request is made to `/api/v1/system/jobs` with pagination parameters THEN the system SHALL return a paginated list of all jobs with filtering options
+5. WHEN system resources are critically low THEN the health endpoint SHALL return a 503 service unavailable status
+
+### Requirement 5
+
+**User Story:** As a client application, I want to upload custom content and configurations, so that I can customize the video generation process with specific materials or settings.
+
+#### Acceptance Criteria
+
+1. WHEN a POST request is made to `/api/v1/uploads/content` with multipart form data THEN the system SHALL accept and store uploaded files securely
+2. WHEN uploading files THEN the system SHALL validate file types, sizes, and scan for malicious content
+3. WHEN a POST request is made to `/api/v1/configurations` with custom settings THEN the system SHALL validate and store the configuration for later use
+4. WHEN uploaded content exceeds size limits THEN the system SHALL return a 413 payload too large error
+5. WHEN invalid file types are uploaded THEN the system SHALL return a 415 unsupported media type error
+
+### Requirement 6
+
+**User Story:** As a client application, I want to authenticate requests using Clerk authentication, so that the system remains secure and user access is properly managed.
+
+#### Acceptance Criteria
+
+1. WHEN a request is made without a valid Clerk session token THEN the system SHALL return a 401 unauthorized error
+2. WHEN a request is made with an invalid or expired Clerk token THEN the system SHALL return a 401 unauthorized error
+3. WHEN a valid Clerk token is provided THEN the system SHALL extract user information and process the request
+4. WHEN user information is needed THEN the system SHALL retrieve it from Clerk's user management system
+5. WHEN rate limits are exceeded THEN the system SHALL return a 429 too many requests error
+
+### Requirement 7
+
+**User Story:** As a developer integrating with the API, I want comprehensive API documentation and client generation capabilities, so that I can efficiently build applications that consume the video generation service.
+
+#### Acceptance Criteria
+
+1. WHEN accessing `/docs` THEN the system SHALL provide interactive Swagger UI documentation with all endpoints and schemas
+2. WHEN accessing `/redoc` THEN the system SHALL provide ReDoc documentation interface
+3. WHEN accessing `/openapi.json` THEN the system SHALL return the complete OpenAPI specification
+4. WHEN generating client code THEN the OpenAPI specification SHALL include proper operation IDs and detailed schemas
+5. WHEN API changes are made THEN the documentation SHALL automatically update to reflect the current API state
+
+### Requirement 8
+
+**User Story:** As a system operator, I want the API to handle errors gracefully and provide detailed logging, so that I can maintain system reliability and troubleshoot issues effectively.
+
+#### Acceptance Criteria
+
+1. WHEN any error occurs THEN the system SHALL return appropriate HTTP status codes with consistent error response format
+2. WHEN internal errors occur THEN the system SHALL log detailed error information without exposing sensitive data to clients
+3. WHEN validation errors occur THEN the system SHALL return specific field-level error messages
+4. WHEN the system is under high load THEN it SHALL implement proper backpressure and queue management
+5. WHEN critical errors occur THEN the system SHALL trigger appropriate alerting mechanisms
+
+### Requirement 9
+
+**User Story:** As a client application, I want to receive real-time updates about job progress, so that I can provide live feedback to users about video generation status.
+
+#### Acceptance Criteria
+
+1. WHEN a WebSocket connection is established to `/ws/jobs/{job_id}` THEN the system SHALL provide real-time status updates
+2. WHEN job status changes THEN connected WebSocket clients SHALL receive immediate notifications
+3. WHEN processing stages complete THEN clients SHALL receive detailed progress information
+4. WHEN WebSocket connections are lost THEN the system SHALL handle reconnection gracefully
+5. WHEN multiple clients connect to the same job THEN all SHALL receive synchronized updates
+
+### Requirement 10
+
+**User Story:** As a system integrator, I want the API to support batch operations and bulk processing, so that I can efficiently handle multiple video generation requests simultaneously.
+
+#### Acceptance Criteria
+
+1. WHEN a POST request is made to `/api/v1/videos/batch` with multiple video requests THEN the system SHALL create multiple jobs and return batch job metadata
+2. WHEN batch processing is requested THEN the system SHALL optimize resource allocation across multiple jobs
+3. WHEN batch jobs are queried THEN the system SHALL return aggregated status information for all jobs in the batch
+4. WHEN individual jobs in a batch fail THEN other jobs SHALL continue processing independently
+5. WHEN batch size exceeds system limits THEN the system SHALL return appropriate error messages with suggested batch sizes

.kiro/specs/fastapi-backend/tasks.md

@@ -0,0 +1,305 @@
+# Implementation Plan
+
+- [ ] 1. Set up project structure and basic configuration
+
+  - Create FastAPI project directory structure following the simplified design specification
+  - Set up pyproject.toml with required dependencies (FastAPI, Pydantic, Redis, Clerk SDK)
+  - Create main.py with basic FastAPI application initialization
+  - Configure environment-based settings using Pydantic BaseSettings
+  - Set up basic logging configuration
+  - _Requirements: 1.1, 6.4, 7.5_
+
+- [x] 2. Implement Redis infrastructure and connection
+
+  - [x] 2.1 Set up Redis connection and utilities
+
+    - Create redis.py with Redis connection management
+    - Implement Redis dependency injection for FastAPI endpoints
+    - Configure Redis connection pooling and error handling
+    - Add Redis health check utilities
+    - _Requirements: 1.1, 2.1, 4.1_
+
+  - [x] 2.2 Create Redis data access patterns
+
+    - Implement Redis hash operations for job storage
+    - Create Redis list operations for job queue management
+    - Add Redis set operations for user job indexing
+    - Implement Redis key expiration and cleanup utilities
+    - _Requirements: 1.1, 2.1, 8.2_
+
+- [x] 3. Implement Clerk authentication integration
+
+  - [x] 3.1 Set up Clerk authentication middleware
+
+    - Create Clerk SDK integration and configuration
+    - Implement Clerk token validation middleware
+    - Build authentication dependency for protected endpoints
+    - Add user information extraction from Clerk tokens
+    - _Requirements: 6.1, 6.2, 6.3_
+
+  - [x] 3.2 Create user management utilities
+
+    - Implement user data extraction from Clerk
+    - Create user session management utilities
+    - Add user permission checking functions
+    - _Requirements: 6.1, 6.2, 8.1_
+
+- [ ] 4. Create Pydantic data models
+
+  - [x] 4.1 Define core Pydantic models
+
+    - Create Job model with validation rules and status enum
+    - Implement VideoMetadata model for video information
+    - Define User model for Clerk user data
+    - Create SystemHealth model for monitoring
+    - Add common response models and error schemas
+    - _Requirements: 1.1, 1.3, 2.1, 7.3, 8.3_
+
+  - [x] 4.2 Implement request/response schemas
+
+    - Create VideoGenerationRequest schema with field validation
+    - Define JobResponse and JobStatusResponse schemas
+    - Implement pagination and filtering schemas
+    - Add error response schemas with consistent structure
+    - Create API documentation examples for all schemas
+    - _Requirements: 1.1, 1.3, 2.1, 7.3, 8.3_
+
+- [x] 5. Build core API endpoints
+
+  - [x] 5.1 Implement video generation endpoints
+
+    - Create POST /api/v1/videos/generate endpoint with Pydantic validation
+    - Implement GET /api/v1/videos/jobs/{job_id}/status endpoint with Redis data
+    - Build GET /api/v1/videos/jobs/{job_id}/download endpoint for file serving
+    - Add GET /api/v1/videos/jobs/{job_id}/metadata endpoint
+    - _Requirements: 1.1, 1.2, 1.3, 2.1, 2.2, 2.3, 2.4, 3.1, 3.2_
+
+  - [x] 5.2 Implement job management endpoints
+
+    - Create GET /api/v1/jobs endpoint with pagination and filtering
+    - Implement POST /api/v1/jobs/{job_id}/cancel endpoint
+    - Build DELETE /api/v1/jobs/{job_id} endpoint with Redis cleanup
+    - Add GET /api/v1/jobs/{job_id}/logs endpoint
+    - _Requirements: 2.1, 2.2, 4.3, 10.3_
+
+  - [x] 5.3 Create system monitoring endpoints
+
+    - Implement GET /api/v1/system/health endpoint with Redis and queue checks
+    - Create GET /api/v1/system/metrics endpoint for basic system stats
+    - Add GET /api/v1/system/queue-status endpoint for queue monitoring
+    - _Requirements: 4.1, 4.2, 4.5_
+
+- [x] 6. Implement business logic services
+
+  - [x] 6.1 Create video generation service
+
+    - Implement VideoService class with Redis job queue integration
+    - Add job creation and status management methods
+    - Create progress tracking and update mechanisms
+    - Implement job queue processing logic
+    - _Requirements: 1.1, 1.2, 2.1, 2.2, 9.2_
+
+  - [x] 6.2 Build job management service
+
+    - Implement JobService with Redis-based storage
+    - Add job lifecycle management methods
+    - Create job cancellation and cleanup functionality
+    - Implement job metrics collection
+    - _Requirements: 2.1, 2.2, 4.3, 10.1, 10.2, 10.4_
+
+  - [x] 6.3 Create queue management service
+
+    - Implement QueueService for Redis queue operations
+
+    - Add job queuing and dequeuing methods
+    - Create queue monitoring and health check functions
+    - Implement queue cleanup and maintenance utilities
+    - _Requirements: 1.1, 2.1, 4.2_
+
+- [x] 7. Add file handling and storage
+
+  - [x] 7.1 Implement local file management
+
+    - Create file upload handling with validation
+    - Implement secure file storage with proper permissions
+    - Add file metadata extraction and storage in Redis
+    - Create file cleanup and maintenance utilities
+    - _Requirements: 3.1, 3.2, 3.3, 5.1, 5.2, 5.4, 5.5_
+
+  - [x] 7.2 Build file serving capabilities
+
+    - Implement file download endpoints with streaming
+    - Add file access control and security checks
+    - Create file URL generation for frontend access
+    - Implement file caching strategies
+    - _Requirements: 3.1, 3.2, 3.3_
+
+- [ ] 8. Implement error handling and middleware
+
+  - [x] 8.1 Create global exception handling
+
+    - Implement custom exception classes with proper HTTP status codes
+    - Create global exception handler middleware
+    - Add structured error response formatting
+    - Implement error logging with request correlation
+    - _Requirements: 8.1, 8.2, 8.3_
+
+  - [x] 8.2 Build request/response middleware
+
+    - Implement CORS middleware for cross-origin requests
+    - Create request logging middleware with performance metrics
+    - Add response compression middleware
+    - Implement security headers middleware
+    - _Requirements: 8.2, 8.4_
+
+- [x] 9. Add caching and performance optimization
+
+  - [x] 9.1 Implement Redis caching strategies
+
+    - Create cache decorator for frequently accessed endpoints
+    - Implement cache invalidation patterns
+
+    - Add cache warming strategies for common queries
+    - Create cache monitoring and metrics collection
+    - _Requirements: 2.1, 4.2_
+
+  - [x] 9.2 Optimize API performance
+
+    - Implement response caching for static data
+    - Add request deduplication for expensive operations
+    - Create connection pooling optimization
+    - Implement async processing where beneficial
+    - _Requirements: 2.1, 4.2, 10.3_
+
+- [ ] 10. Implement batch processing capabilities
+
+  - [ ] 10.1 Create batch job endpoints
+
+    - Implement POST /api/v1/videos/batch endpoint
+    - Add batch job validation and processing logic
+    - Create batch status tracking and reporting
+    - _Requirements: 10.1, 10.2_
+
+  - [ ] 10.2 Build batch job management
+    - Implement batch job cancellation and cleanup
+    - Add batch job progress aggregation
+    - Create batch job completion notifications
+    - _Requirements: 10.3, 10.4, 10.5_
+
+- [ ] 11. Add comprehensive testing suite
+
+  - [ ] 11.1 Create unit tests for core functionality
+
+    - Write unit tests for all service layer methods
+    - Create tests for Redis operations and data models
+    - Add tests for Clerk authentication integration
+    - Test Pydantic schema validation and serialization
+    - _Requirements: 1.1, 1.3, 2.1, 6.1, 8.3_
+
+  - [ ] 11.2 Implement integration tests for API endpoints
+
+    - Create integration tests for all video generation endpoints
+    - Test job management endpoints with Redis operations
+    - Add file upload and download functionality tests
+    - Test error handling and edge cases
+    - _Requirements: 1.1, 2.1, 3.1, 9.1_
+
+  - [ ] 11.3 Build end-to-end workflow tests
+    - Create complete video generation workflow tests
+    - Test batch processing end-to-end scenarios
+    - Add performance testing for critical endpoints
+    - Test system recovery and error scenarios
+    - _Requirements: 1.1, 8.1, 10.1_
+
+- [ ] 12. Implement rate limiting and security features
+
+  - [ ] 12.1 Add rate limiting middleware
+
+    - Implement Redis-based rate limiting per user and endpoint
+    - Create rate limit configuration and storage
+    - Add rate limit headers and error responses
+    - Implement rate limit monitoring and alerting
+    - _Requirements: 6.5, 8.4_
+
+  - [ ] 12.2 Enhance security measures
+    - Implement input sanitization and validation
+    - Add request/response logging for audit trails
+    - Create security headers middleware
+    - Implement API key validation for internal services
+    - _Requirements: 6.1, 6.3, 8.2_
+
+- [x] 13. Create API documentation and client generation
+
+
+
+
+
+  - [x] 13.1 Configure OpenAPI documentation
+
+
+
+    - Customize OpenAPI schema generation with proper operation IDs
+    - Add comprehensive endpoint descriptions and examples
+    - Configure Swagger UI and ReDoc interfaces
+    - Add authentication documentation for Clerk integration
+    - _Requirements: 7.1, 7.2, 7.3_
+
+
+
+  - [ ] 13.2 Set up client code generation
+    - Configure OpenAPI specification for client generation
+    - Create example client generation scripts
+    - Add client SDK documentation and examples
+    - Test generated clients with real API endpoints
+    - _Requirements: 7.4, 7.5_
+
+- [ ] 14. Implement deployment configuration
+
+  - [ ] 14.1 Create Docker containerization
+
+    - Write Dockerfile with multi-stage build optimization
+    - Create docker-compose.yml for local development with Redis
+    - Add production docker-compose with proper networking
+    - Configure environment variable management
+    - _Requirements: 4.1, 8.4_
+
+  - [ ] 14.2 Add monitoring and logging
+    - Implement structured logging with JSON format
+    - Add application metrics collection and export
+    - Create health check endpoints for container orchestration
+    - Configure log aggregation and monitoring dashboards
+    - _Requirements: 4.1, 4.2, 8.2_
+
+- [ ] 15. Final integration and optimization
+
+  - [ ] 15.1 Integrate with existing video generation pipeline
+
+    - Create Redis queue integration with multi-agent video generation system
+    - Implement job queue management with proper error handling
+    - Add configuration mapping between API requests and pipeline parameters
+    - Test end-to-end video generation workflow
+    - _Requirements: 1.1, 1.2, 2.1_
+
+  - [ ] 15.2 Performance optimization and cleanup
+    - Optimize Redis operations and connection management
+    - Implement proper resource cleanup and garbage collection
+    - Add graceful shutdown handling for long-running operations
+    - Create production-ready configuration templates
+    - _Requirements: 4.2, 8.4_
+
+- [ ] 16. Frontend integration preparation
+
+  - [ ] 16.1 Create frontend-specific endpoints
+
+    - Implement GET /api/v1/dashboard/stats endpoint for user dashboard
+    - Create GET /api/v1/dashboard/recent-jobs endpoint
+    - Add WebSocket endpoints for real-time job updates
+    - Implement user preference and settings endpoints
+    - _Requirements: 2.1, 9.1, 9.2_
+
+  - [ ] 16.2 Set up CORS and frontend security
+    - Configure CORS middleware for frontend domain access
+    - Add rate limiting specific to frontend endpoints
+    - Create frontend-specific authentication flows with Clerk
+    - Implement proper session management for frontend clients
+    - _Requirements: 6.1, 6.5, 8.4_

API_DOCUMENTATION.md

@@ -0,0 +1,1311 @@
+# T2M API Documentation
+
+## Overview
+
+This document provides comprehensive documentation for the T2M (Text-to-Media) API endpoints. The API is organized into several modules: Authentication, Files, Jobs, System, and Videos.
+
+## Base URL
+
+```
+https://your-api-domain.com/api/v1
+```
+
+## Authentication
+
+Most endpoints require authentication. Include the authorization token in the request headers:
+
+```
+Authorization: Bearer <your-token>
+```
+
+**Public endpoints** (no authentication required):
+
+- `GET /auth/health`
+- `GET /system/health`
+
+**Optional authentication** (enhanced data for authenticated users):
+
+- All other `/system/*` endpoints
+
+## Common Response Formats
+
+### Success Response
+
+```json
+{
+  "success": true,
+  "data": {
+    "id": "12345",
+    "status": "completed"
+  },
+  "message": "Operation completed successfully"
+}
+```
+
+### Error Response
+
+```json
+{
+  "success": false,
+  "error": {
+    "code": "AUTH_INVALID",
+    "details": "Token has expired or is malformed"
+  }
+}
+```
+
+### Pagination Format
+
+```json
+{
+  "success": true,
+  "data": {
+    "items": [...],
+    "pagination": {
+      "page": 1,
+      "items_per_page": 20,
+      "total_items": 150,
+      "total_pages": 8,
+      "has_next": true,
+      "has_previous": false,
+      "next_page": 2,
+      "previous_page": null
+    }
+  }
+}
+```
+
+## Authentication Endpoints
+
+### Health Check
+
+- **Endpoint**: `GET /auth/health`
+- **Description**: Check authentication service health
+- **Authentication**: Not required
+- **Response**: Service health status
+- **Example Response**:
+
+```json
+{
+  "status": "healthy",
+  "clerk": {
+    "status": "healthy",
+    "response_time": "45ms",
+    "last_check": "2024-01-15T10:30:00Z"
+  },
+  "message": "Authentication service health check completed"
+}
+```
+
+### Get Authentication Status
+
+- **Endpoint**: `GET /auth/status`
+- **Description**: Get current user authentication status
+- **Headers**:
+  - `Authorization: Bearer <token>` (optional)
+- **Response**: Authentication status and user info
+- **Example Response (Authenticated)**:
+
+```json
+{
+  "authenticated": true,
+  "user_id": "user_12345",
+  "email": "[email protected]",
+  "email_verified": true,
+  "request_context": {
+    "path": "/auth/status",
+    "method": "GET",
+    "client_ip": "192.168.1.100"
+  }
+}
+```
+
+- **Example Response (Not Authenticated)**:
+
+```json
+{
+  "authenticated": false,
+  "message": "No authentication provided",
+  "request_context": {
+    "path": "/auth/status",
+    "method": "GET",
+    "client_ip": "192.168.1.100"
+  }
+}
+```
+
+### Get Current User Profile
+
+- **Endpoint**: `GET /auth/me`
+- **Description**: Get authenticated user's profile information
+- **Headers**:
+  - `Authorization: Bearer <token>` (required)
+- **Response**: User profile data
+- **Example Response**:
+
+```json
+{
+  "id": "user_12345",
+  "username": "john_doe",
+  "full_name": "John Doe",
+  "email": "[email protected]",
+  "image_url": "https://example.com/avatar.jpg",
+  "email_verified": true,
+  "created_at": "2024-01-01T00:00:00Z",
+  "last_sign_in_at": "2024-01-15T10:30:00Z"
+}
+```
+
+**Note**: `created_at` and `last_sign_in_at` fields may be `null` if not available from the authentication provider.
+
+### Get User Permissions
+
+- **Endpoint**: `GET /auth/permissions`
+- **Description**: Get user's permissions and access levels
+- **Headers**:
+  - `Authorization: Bearer <token>` (required)
+- **Response**: User permissions and role information
+- **Example Response**:
+
+```json
+{
+  "user_id": "user_12345",
+  "role": "USER",
+  "permissions": [
+    "read_files",
+    "upload_files",
+    "generate_videos"
+  ],
+  "access_level": "standard"
+}
+```
+
+### Test Protected Endpoint
+
+- **Endpoint**: `GET /auth/test-protected`
+- **Description**: Test endpoint for authenticated users
+- **Headers**:
+  - `Authorization: Bearer <token>` (required)
+- **Response**: Test response with user ID
+- **Example Response**:
+
+```json
+{
+  "message": "Successfully accessed protected endpoint",
+  "user_id": "user_12345",
+  "timestamp": "2024-01-15T10:30:00Z"
+}
+```
+
+### Test Verified Endpoint
+
+- **Endpoint**: `GET /auth/test-verified`
+- **Description**: Test endpoint for verified users only
+- **Headers**:
+  - `Authorization: Bearer <token>` (required)
+- **Response**: Test response for verified users
+- **Example Response**:
+
+```json
+{
+  "message": "Successfully accessed verified user endpoint",
+  "user_id": "user_12345",
+  "email": "[email protected]",
+  "email_verified": true,
+  "timestamp": "2024-01-15T10:30:00Z"
+}
+```
+
+### Verify Token
+
+- **Endpoint**: `POST /auth/verify`
+- **Description**: Verify authentication token validity
+- **Headers**:
+  - `Authorization: Bearer <token>` (required)
+- **Response**: Token verification status
+- **Example Response**:
+
+```json
+{
+  "verified": true,
+  "user_id": "user_12345",
+  "email": "[email protected]",
+  "email_verified": true,
+  "message": "Token verified successfully"
+}
+```
+
+## File Management Endpoints
+
+### Upload Single File
+
+- **Endpoint**: `POST /files/upload`
+- **Description**: Upload a single file
+- **Headers**:
+  - `Authorization: Bearer <token>` (required)
+  - `Content-Type: multipart/form-data`
+- **Parameters**:
+  - `file` (file, required): File to upload
+  - `file_type` (string, optional): File type category
+  - `subdirectory` (string, optional): Target subdirectory
+  - `description` (string, optional): File description
+- **Response**: File upload confirmation with file ID
+
+### Batch Upload Files
+
+- **Endpoint**: `POST /files/batch-upload`
+- **Description**: Upload multiple files at once
+- **Headers**:
+  - `Authorization: Bearer <token>` (required)
+  - `Content-Type: multipart/form-data`
+- **Parameters**:
+  - `files` (file[], required): Files to upload
+  - `file_type` (string, optional): File type for all files
+  - `subdirectory` (string, optional): Subdirectory for all files
+  - `description` (string, optional): Description for all files
+- **Response**: Batch upload results
+
+### List Files
+
+- **Endpoint**: `GET /files`
+- **Description**: List user's files with pagination and filtering
+- **Headers**:
+  - `Authorization: Bearer <token>` (required)
+- **Query Parameters**:
+
+| Name             | Type    | Required | Default | Description                                         |
+| ---------------- | ------- | -------- | ------- | --------------------------------------------------- |
+| `file_type`      | string  | no       | -       | Filter by file type (document, image, video, audio) |
+| `page`           | integer | no       | 1       | Page number (≥1)                                    |
+| `items_per_page` | integer | no       | 20      | Items per page (1-100)                              |
+
+- **Response**: Paginated list of files
+- **Example Response**:
+
+```json
+{
+  "success": true,
+  "data": {
+    "items": [
+      {
+        "id": "file_123456",
+        "filename": "document.pdf",
+        "size": 2048576,
+        "file_type": "document",
+        "created_at": "2024-01-15T10:30:00Z"
+      }
+    ],
+    "pagination": {
+      "page": 1,
+      "items_per_page": 20,
+      "total_items": 150,
+      "total_pages": 8,
+      "has_next": true
+    }
+  }
+}
+```
+
+### Get File Details
+
+- **Endpoint**: `GET /files/{file_id}`
+- **Description**: Get comprehensive file information including content details and metadata
+- **Headers**:
+  - `Authorization: Bearer <token>` (required)
+- **Path Parameters**:
+  - `file_id` (string, required): Unique file identifier
+- **Response**: Complete file details
+- **Example Response**:
+
+```json
+{
+  "success": true,
+  "data": {
+    "id": "file_123456",
+    "filename": "document.pdf",
+    "size": 2048576,
+    "content_type": "application/pdf",
+    "file_type": "document",
+    "subdirectory": "uploads/2024",
+    "description": "Important document",
+    "created_at": "2024-01-15T10:30:00Z",
+    "updated_at": "2024-01-15T10:30:00Z",
+    "download_count": 5,
+    "metadata": {
+      "pages": 10,
+      "author": "John Doe",
+      "creation_date": "2024-01-15"
+    }
+  }
+}
+```
+
+### Get File Metadata
+
+- **Endpoint**: `GET /files/{file_id}/metadata`
+- **Description**: Get file metadata and technical information only
+- **Headers**:
+  - `Authorization: Bearer <token>` (required)
+- **Path Parameters**:
+  - `file_id` (string, required): Unique file identifier
+- **Response**: File metadata only
+- **Example Response**:
+
+```json
+{
+  "success": true,
+  "data": {
+    "content_type": "application/pdf",
+    "size": 2048576,
+    "checksum": "sha256:abc123...",
+    "metadata": {
+      "pages": 10,
+      "author": "John Doe",
+      "creation_date": "2024-01-15"
+    }
+  }
+}
+```
+
+### Download File
+
+- **Endpoint**: `GET /files/{file_id}/download`
+- **Description**: Download file content
+- **Headers**:
+  - `Authorization: Bearer <token>` (required)
+- **Path Parameters**:
+  - `file_id` (string, required): Unique file identifier
+- **Query Parameters**:
+  - `inline` (boolean, default: false): Serve inline instead of attachment
+- **Response**: File content
+
+### Stream File
+
+- **Endpoint**: `GET /files/{file_id}/stream`
+- **Description**: Stream file content
+- **Headers**:
+  - `Authorization: Bearer <token>` (required)
+- **Path Parameters**:
+  - `file_id` (string, required): Unique file identifier
+- **Query Parameters**:
+  - `quality` (string, default: "auto"): Stream quality
+- **Response**: Streamed file content
+
+### Get File Thumbnail
+
+- **Endpoint**: `GET /files/{file_id}/thumbnail`
+- **Description**: Get file thumbnail
+- **Headers**:
+  - `Authorization: Bearer <token>` (required)
+- **Path Parameters**:
+  - `file_id` (string, required): Unique file identifier
+- **Query Parameters**:
+  - `size` (string, default: "medium"): Thumbnail size (small|medium|large)
+- **Response**: Thumbnail image
+
+### Get File Analytics
+
+- **Endpoint**: `GET /files/{file_id}/analytics`
+- **Description**: Get file usage analytics
+- **Headers**:
+  - `Authorization: Bearer <token>` (required)
+- **Path Parameters**:
+  - `file_id` (string, required): Unique file identifier
+- **Response**: File analytics data
+
+### Delete File
+
+- **Endpoint**: `DELETE /files/{file_id}`
+- **Description**: Delete a file
+- **Headers**:
+  - `Authorization: Bearer <token>` (required)
+- **Path Parameters**:
+  - `file_id` (string, required): Unique file identifier
+- **Response**: Deletion confirmation
+
+### Get File Statistics
+
+- **Endpoint**: `GET /files/stats`
+- **Description**: Get user's file statistics
+- **Headers**:
+  - `Authorization: Bearer <token>` (required)
+- **Response**: File usage statistics
+
+### Cleanup Files
+
+- **Endpoint**: `POST /files/cleanup`
+- **Description**: Cleanup files based on criteria
+- **Headers**:
+  - `Authorization: Bearer <token>` (required)
+  - `Content-Type: application/json`
+- **Request Body**: File cleanup criteria
+- **Response**: Cleanup results
+
+### Secure File Access
+
+- **Endpoint**: `GET /files/secure/{file_id}`
+- **Description**: Access files via signed URLs
+- **Query Parameters**:
+  - `user_id` (string, required): User ID from signed URL
+  - `expires` (string, required): Expiration timestamp
+  - `signature` (string, required): URL signature
+  - `file_type` (string, optional): File type
+  - `inline` (string, default: "false"): Serve inline
+  - `size` (string, optional): Thumbnail size
+  - `quality` (string, optional): Stream quality
+- **Response**: Secure file access
+
+## Job Management Endpoints
+
+### List Jobs
+
+- **Endpoint**: `GET /jobs`
+- **Description**: List user's jobs with pagination and filtering
+- **Headers**:
+  - `Authorization: Bearer <token>` (required)
+- **Query Parameters**: Pagination and filtering parameters
+- **Response**: Paginated list of jobs
+
+### Get Job Details
+
+- **Endpoint**: `GET /jobs/{job_id}`
+- **Description**: Get comprehensive job information including status, progress, and results
+- **Headers**:
+  - `Authorization: Bearer <token>` (required)
+- **Path Parameters**:
+  - `job_id` (string, required): Unique job identifier
+- **Response**: Complete job details and status
+- **Example Response**:
+
+```json
+{
+  "success": true,
+  "data": {
+    "id": "job_789012",
+    "type": "video_generation",
+    "status": "completed",
+    "progress": 100,
+    "created_at": "2024-01-15T10:30:00Z",
+    "started_at": "2024-01-15T10:30:05Z",
+    "completed_at": "2024-01-15T10:35:30Z",
+    "duration": 325,
+    "parameters": {
+      "prompt": "A beautiful sunset over mountains",
+      "duration": 10,
+      "quality": "1080p"
+    },
+    "result": {
+      "file_id": "video_456789",
+      "file_size": 15728640,
+      "thumbnail_url": "/videos/job_789012/thumbnail"
+    },
+    "error": null
+  }
+}
+```
+
+### Get Job Logs
+
+- **Endpoint**: `GET /jobs/{job_id}/logs`
+- **Description**: Get job execution logs with filtering and pagination
+- **Headers**:
+  - `Authorization: Bearer <token>` (required)
+- **Path Parameters**:
+  - `job_id` (string, required): Unique job identifier
+- **Query Parameters**:
+
+| Name     | Type    | Required | Default | Description                                       |
+| -------- | ------- | -------- | ------- | ------------------------------------------------- |
+| `limit`  | integer | no       | 100     | Maximum log entries (1-1000)                      |
+| `offset` | integer | no       | 0       | Log entries to skip (≥0)                          |
+| `level`  | string  | no       | -       | Filter by log level (DEBUG, INFO, WARNING, ERROR) |
+
+- **Response**: Job logs with metadata
+- **Example Response**:
+
+```json
+{
+  "success": true,
+  "data": {
+    "logs": [
+      {
+        "timestamp": "2024-01-15T10:30:15Z",
+        "level": "INFO",
+        "message": "Video processing started",
+        "details": {
+          "step": "initialization",
+          "progress": 0
+        }
+      },
+      {
+        "timestamp": "2024-01-15T10:30:45Z",
+        "level": "INFO",
+        "message": "Processing frame 100/1000",
+        "details": {
+          "step": "rendering",
+          "progress": 10
+        }
+      }
+    ],
+    "total_logs": 250,
+    "has_more": true
+  }
+}
+```
+
+### Cancel Job
+
+- **Endpoint**: `POST /jobs/{job_id}/cancel`
+- **Description**: Cancel a running job
+- **Headers**:
+  - `Authorization: Bearer <token>` (required)
+- **Path Parameters**:
+  - `job_id` (string, required): Unique job identifier
+- **Response**: Cancellation confirmation
+
+### Delete Job
+
+- **Endpoint**: `DELETE /jobs/{job_id}`
+- **Description**: Delete a job and its data
+- **Headers**:
+  - `Authorization: Bearer <token>` (required)
+- **Path Parameters**:
+  - `job_id` (string, required): Unique job identifier
+- **Response**: Deletion confirmation
+
+## System Monitoring Endpoints
+
+### System Health Check
+
+- **Endpoint**: `GET /system/health`
+- **Description**: Get overall system health status
+- **Headers**:
+  - `Authorization: Bearer <token>` (optional)
+- **Response**: System health metrics
+
+### System Metrics
+
+- **Endpoint**: `GET /system/metrics`
+- **Description**: Get detailed system metrics
+- **Headers**:
+  - `Authorization: Bearer <token>` (optional)
+- **Response**: System performance metrics
+
+### Queue Status
+
+- **Endpoint**: `GET /system/queue`
+- **Description**: Get job queue status and statistics
+- **Headers**:
+  - `Authorization: Bearer <token>` (optional)
+- **Response**: Queue status and metrics
+
+### Cache Information
+
+- **Endpoint**: `GET /system/cache`
+- **Description**: Get cache status and information
+- **Headers**:
+  - `Authorization: Bearer <token>` (optional)
+- **Response**: Cache metrics and status
+
+### Cache Metrics
+
+- **Endpoint**: `GET /system/cache/metrics`
+- **Description**: Get detailed cache metrics
+- **Headers**:
+  - `Authorization: Bearer <token>` (optional)
+- **Response**: Cache performance metrics
+
+### Cache Report
+
+- **Endpoint**: `GET /system/cache/report`
+- **Description**: Get comprehensive cache report
+- **Headers**:
+  - `Authorization: Bearer <token>` (optional)
+- **Response**: Detailed cache report
+
+### Performance Summary
+
+- **Endpoint**: `GET /system/performance`
+- **Description**: Get system performance summary
+- **Headers**:
+  - `Authorization: Bearer <token>` (optional)
+- **Query Parameters**:
+  - `hours` (integer, default: 1): Time range in hours
+- **Response**: Performance summary
+
+### Connection Statistics
+
+- **Endpoint**: `GET /system/connections`
+- **Description**: Get connection statistics
+- **Headers**:
+  - `Authorization: Bearer <token>` (optional)
+- **Response**: Connection metrics
+
+### Async Statistics
+
+- **Endpoint**: `GET /system/async`
+- **Description**: Get asynchronous processing statistics
+- **Headers**:
+  - `Authorization: Bearer <token>` (optional)
+- **Response**: Async processing metrics
+
+### Deduplication Statistics
+
+- **Endpoint**: `GET /system/deduplication`
+- **Description**: Get deduplication statistics
+- **Headers**:
+  - `Authorization: Bearer <token>` (optional)
+- **Response**: Deduplication metrics
+
+### Invalidate Cache
+
+- **Endpoint**: `POST /system/cache/invalidate`
+- **Description**: Invalidate cache entries
+- **Headers**:
+  - `Authorization: Bearer <token>` (optional)
+- **Query Parameters**:
+  - `pattern` (string, optional): Cache key pattern
+  - `user_id` (string, optional): User-specific cache
+- **Response**: Cache invalidation results
+
+### Warm Cache
+
+- **Endpoint**: `POST /system/cache/warm`
+- **Description**: Pre-warm cache with frequently accessed data
+- **Headers**:
+  - `Authorization: Bearer <token>` (optional)
+- **Response**: Cache warming results
+
+### Optimize Performance
+
+- **Endpoint**: `POST /system/optimize`
+- **Description**: Trigger system performance optimization
+- **Headers**:
+  - `Authorization: Bearer <token>` (optional)
+- **Response**: Optimization results
+
+## Video Processing Endpoints
+
+### Generate Video
+
+- **Endpoint**: `POST /videos/generate`
+- **Description**: Create a new video generation job
+- **Headers**:
+  - `Authorization: Bearer <token>` (required)
+  - `Content-Type: application/json`
+- **Request Body**: Job creation parameters
+- **Response**: Job creation confirmation with job ID
+
+### Get Job Status
+
+- **Endpoint**: `GET /videos/{job_id}/status`
+- **Description**: Get video generation job status
+- **Headers**:
+  - `Authorization: Bearer <token>` (required)
+- **Path Parameters**:
+  - `job_id` (string, required): Unique job identifier
+- **Response**: Job status and progress
+
+### Download Video
+
+- **Endpoint**: `GET /videos/{job_id}/download`
+- **Description**: Download generated video
+- **Headers**:
+  - `Authorization: Bearer <token>` (required)
+- **Path Parameters**:
+  - `job_id` (string, required): Unique job identifier
+- **Query Parameters**:
+  - `inline` (boolean, default: false): Serve inline instead of attachment
+- **Response**: Video file content
+
+### Stream Video
+
+- **Endpoint**: `GET /videos/{job_id}/stream`
+- **Description**: Stream generated video
+- **Headers**:
+  - `Authorization: Bearer <token>` (required)
+- **Path Parameters**:
+  - `job_id` (string, required): Unique job identifier
+- **Query Parameters**:
+  - `quality` (string, default: "auto"): Stream quality (auto|720p|1080p)
+- **Response**: Streamed video content
+
+### Get Video Metadata
+
+- **Endpoint**: `GET /videos/{job_id}/metadata`
+- **Description**: Get comprehensive video metadata and technical information
+- **Headers**:
+  - `Authorization: Bearer <token>` (required)
+- **Path Parameters**:
+  - `job_id` (string, required): Unique job identifier
+- **Response**: Detailed video metadata
+- **Example Response**:
+
+```json
+{
+  "success": true,
+  "data": {
+    "job_id": "job_789012",
+    "video": {
+      "duration": 10.5,
+      "width": 1920,
+      "height": 1080,
+      "fps": 30,
+      "bitrate": 5000000,
+      "codec": "h264",
+      "format": "mp4",
+      "file_size": 15728640
+    },
+    "audio": {
+      "codec": "aac",
+      "bitrate": 128000,
+      "sample_rate": 44100,
+      "channels": 2
+    },
+    "generation": {
+      "prompt": "A beautiful sunset over mountains",
+      "model": "t2v-v2.1",
+      "seed": 12345,
+      "created_at": "2024-01-15T10:30:00Z"
+    }
+  }
+}
+```
+
+### Get Video Thumbnail
+
+- **Endpoint**: `GET /videos/{job_id}/thumbnail`
+- **Description**: Get video thumbnail
+- **Headers**:
+  - `Authorization: Bearer <token>` (required)
+- **Path Parameters**:
+  - `job_id` (string, required): Unique job identifier
+- **Query Parameters**:
+  - `size` (string, default: "medium"): Thumbnail size (small|medium|large)
+- **Response**: Video thumbnail image
+
+## Error Handling
+
+### Error Codes
+
+| Code                  | HTTP Status | Description                     |
+| --------------------- | ----------- | ------------------------------- |
+| `AUTH_REQUIRED`       | 401         | Authentication required         |
+| `AUTH_INVALID`        | 401         | Invalid authentication token    |
+| `AUTH_EXPIRED`        | 401         | Authentication token expired    |
+| `PERMISSION_DENIED`   | 403         | Insufficient permissions        |
+| `RESOURCE_NOT_FOUND`  | 404         | Requested resource not found    |
+| `VALIDATION_ERROR`    | 400         | Request validation failed       |
+| `RATE_LIMIT_EXCEEDED` | 429         | Rate limit exceeded             |
+| `SERVER_ERROR`        | 500         | Internal server error           |
+| `SERVICE_UNAVAILABLE` | 503         | Service temporarily unavailable |
+
+### Error Response Examples
+
+**Invalid Authentication (401)**
+
+```json
+{
+  "success": false,
+  "error": {
+    "code": "AUTH_INVALID",
+    "details": "Token has expired or is malformed"
+  }
+}
+```
+
+**Resource Not Found (404)**
+
+```json
+{
+  "success": false,
+  "error": {
+    "code": "RESOURCE_NOT_FOUND",
+    "message": "File not found",
+    "details": "File with ID 'file_123456' does not exist or you don't have access"
+  }
+}
+```
+
+**Validation Error (400)**
+
+```json
+{
+  "success": false,
+  "error": {
+    "code": "VALIDATION_ERROR",
+    "message": "Request validation failed",
+    "details": {
+      "file_type": [
+        "Invalid file type. Must be one of: document, image, video, audio"
+      ],
+      "page": ["Page must be greater than 0"]
+    }
+  }
+}
+```
+
+**Rate Limit Exceeded (429)**
+
+```json
+{
+  "success": false,
+  "error": {
+    "code": "RATE_LIMIT_EXCEEDED",
+    "message": "Rate limit exceeded",
+    "details": "You have exceeded the limit of 100 uploads per hour. Try again in 45 minutes."
+  }
+}
+```
+
+## Rate Limits
+
+- **General API**: 1000 requests per hour per user
+- **File Upload**: 100 uploads per hour per user
+- **Video Generation**: 10 jobs per hour per user
+- **System Endpoints**: 500 requests per hour per user
+
+## Code Examples
+
+### cURL Examples
+
+**Upload a file**
+
+```bash
+curl -X POST "https://api.example.com/api/v1/files/upload" \
+  -H "Authorization: Bearer your-token-here" \
+  -F "[email protected]" \
+  -F "file_type=document" \
+  -F "description=Sample document"
+```
+
+**Generate video**
+
+```bash
+curl -X POST "https://api.example.com/api/v1/videos/generate" \
+  -H "Authorization: Bearer your-token-here" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "prompt": "A beautiful sunset over mountains",
+    "duration": 10,
+    "quality": "1080p"
+  }'
+```
+
+**Get job status**
+
+```bash
+curl -X GET "https://api.example.com/api/v1/jobs/job_789012" \
+  -H "Authorization: Bearer your-token-here"
+```
+
+**Get system metrics**
+
+```bash
+curl -X GET "https://api.example.com/api/v1/system/metrics" \
+  -H "Authorization: Bearer your-token-here"
+```
+
+### Python Examples
+
+**File Management**
+
+```python
+import requests
+
+headers = {"Authorization": "Bearer your-token-here"}
+base_url = "https://api.example.com/api/v1"
+
+# Upload file
+with open("example.txt", "rb") as f:
+    files = {"file": f}
+    data = {"file_type": "document", "description": "Sample document"}
+    response = requests.post(f"{base_url}/files/upload", headers=headers, files=files, data=data)
+    file_data = response.json()
+    print(f"File uploaded: {file_data['data']['id']}")
+
+# List files
+response = requests.get(f"{base_url}/files", headers=headers, params={"page": 1, "items_per_page": 10})
+files = response.json()
+print(f"Found {files['data']['pagination']['total_items']} files")
+```
+
+**Job Management**
+
+```python
+# Get job logs
+job_id = "job_789012"
+response = requests.get(f"{base_url}/jobs/{job_id}/logs", headers=headers, params={"limit": 50, "level": "INFO"})
+logs = response.json()
+print(f"Retrieved {len(logs['data']['logs'])} log entries")
+
+# Cancel job
+response = requests.post(f"{base_url}/jobs/{job_id}/cancel", headers=headers)
+if response.json()['success']:
+    print("Job cancelled successfully")
+```
+
+**Video Processing**
+
+```python
+# Generate video
+job_data = {
+    "prompt": "A beautiful sunset over mountains",
+    "duration": 10,
+    "quality": "1080p"
+}
+response = requests.post(f"{base_url}/videos/generate", headers=headers, json=job_data)
+job = response.json()
+job_id = job['data']['job_id']
+print(f"Video generation started: {job_id}")
+
+# Check status
+response = requests.get(f"{base_url}/videos/{job_id}/status", headers=headers)
+status = response.json()
+print(f"Job status: {status['data']['status']} ({status['data']['progress']}%)")
+```
+
+**System Monitoring**
+
+```python
+# Get system metrics
+response = requests.get(f"{base_url}/system/metrics", headers=headers)
+metrics = response.json()
+print(f"CPU usage: {metrics['data']['cpu_usage']}%")
+print(f"Memory usage: {metrics['data']['memory_usage']}%")
+
+# Get queue status
+response = requests.get(f"{base_url}/system/queue", headers=headers)
+queue = response.json()
+print(f"Jobs in queue: {queue['data']['pending_jobs']}")
+```
+
+### JavaScript Examples
+
+**File Management**
+
+```javascript
+const headers = {
+  Authorization: "Bearer your-token-here",
+};
+const baseUrl = "https://api.example.com/api/v1";
+
+// Upload file
+const formData = new FormData();
+formData.append("file", fileInput.files[0]);
+formData.append("file_type", "document");
+formData.append("description", "Sample document");
+
+fetch(`${baseUrl}/files/upload`, {
+  method: "POST",
+  headers: headers,
+  body: formData,
+})
+  .then((response) => response.json())
+  .then((data) => console.log("File uploaded:", data.data.id));
+
+// List files with pagination
+fetch(`${baseUrl}/files?page=1&items_per_page=10`, {
+  headers: headers,
+})
+  .then((response) => response.json())
+  .then((data) =>
+    console.log(`Found ${data.data.pagination.total_items} files`)
+  );
+```
+
+**Job Management**
+
+```javascript
+// Get job logs
+const jobId = "job_789012";
+fetch(`${baseUrl}/jobs/${jobId}/logs?limit=50&level=INFO`, {
+  headers: headers,
+})
+  .then((response) => response.json())
+  .then((data) =>
+    console.log(`Retrieved ${data.data.logs.length} log entries`)
+  );
+
+// Cancel job
+fetch(`${baseUrl}/jobs/${jobId}/cancel`, {
+  method: "POST",
+  headers: headers,
+})
+  .then((response) => response.json())
+  .then((data) => {
+    if (data.success) console.log("Job cancelled successfully");
+  });
+```
+
+**Video Processing**
+
+```javascript
+// Generate video
+const jobData = {
+  prompt: "A beautiful sunset over mountains",
+  duration: 10,
+  quality: "1080p",
+};
+
+fetch(`${baseUrl}/videos/generate`, {
+  method: "POST",
+  headers: { ...headers, "Content-Type": "application/json" },
+  body: JSON.stringify(jobData),
+})
+  .then((response) => response.json())
+  .then((data) => {
+    const jobId = data.data.job_id;
+    console.log("Video generation started:", jobId);
+
+    // Poll for status
+    const checkStatus = () => {
+      fetch(`${baseUrl}/videos/${jobId}/status`, { headers })
+        .then((response) => response.json())
+        .then((status) => {
+          console.log(
+            `Status: ${status.data.status} (${status.data.progress}%)`
+          );
+          if (status.data.status === "processing") {
+            setTimeout(checkStatus, 5000); // Check again in 5 seconds
+          }
+        });
+    };
+    checkStatus();
+  });
+```
+
+**System Monitoring**
+
+```javascript
+// Get system metrics
+fetch(`${baseUrl}/system/metrics`, { headers })
+  .then((response) => response.json())
+  .then((data) => {
+    console.log(`CPU usage: ${data.data.cpu_usage}%`);
+    console.log(`Memory usage: ${data.data.memory_usage}%`);
+  });
+
+// Get queue status
+fetch(`${baseUrl}/system/queue`, { headers })
+  .then((response) => response.json())
+  .then((data) => console.log(`Jobs in queue: ${data.data.pending_jobs}`));
+```
+
+## Support
+
+For API support and questions, please contact:
+
+- Email: [email protected]
+- Documentation: https://docs.example.com
+- Status Page: https://status.example.com
+
+## Webhooks
+
+The T2M API supports webhook notifications for long-running operations like video generation.
+
+### Webhook Configuration
+
+Configure webhook URLs in your account settings or via the API:
+
+```bash
+curl -X POST "https://api.example.com/api/v1/webhooks" \
+  -H "Authorization: Bearer your-token-here" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "url": "https://your-app.com/webhooks/t2m",
+    "events": ["job.completed", "job.failed"],
+    "secret": "your-webhook-secret"
+  }'
+```
+
+### Webhook Events
+
+| Event           | Description                     |
+| --------------- | ------------------------------- |
+| `job.started`   | Job processing has begun        |
+| `job.progress`  | Job progress update (every 10%) |
+| `job.completed` | Job completed successfully      |
+| `job.failed`    | Job failed with error           |
+| `job.cancelled` | Job was cancelled               |
+
+### Webhook Payload Example
+
+**Job Completed**
+
+```json
+{
+  "event": "job.completed",
+  "timestamp": "2024-01-15T10:35:30Z",
+  "data": {
+    "job_id": "job_789012",
+    "type": "video_generation",
+    "status": "completed",
+    "result": {
+      "file_id": "video_456789",
+      "download_url": "https://api.example.com/api/v1/videos/job_789012/download",
+      "thumbnail_url": "https://api.example.com/api/v1/videos/job_789012/thumbnail"
+    }
+  }
+}
+```
+
+### Webhook Security
+
+Verify webhook authenticity using the signature header:
+
+```python
+import hmac
+import hashlib
+
+def verify_webhook(payload, signature, secret):
+    expected = hmac.new(
+        secret.encode('utf-8'),
+        payload.encode('utf-8'),
+        hashlib.sha256
+    ).hexdigest()
+    return hmac.compare_digest(f"sha256={expected}", signature)
+
+# In your webhook handler
+signature = request.headers.get('X-T2M-Signature')
+if verify_webhook(request.body, signature, webhook_secret):
+    # Process webhook
+    pass
+```
+
+## Advanced Features
+
+### Batch Operations
+
+**Batch File Upload**
+
+```bash
+curl -X POST "https://api.example.com/api/v1/files/batch-upload" \
+  -H "Authorization: Bearer your-token-here" \
+  -F "[email protected]" \
+  -F "[email protected]" \
+  -F "[email protected]" \
+  -F "file_type=document"
+```
+
+### Signed URLs for Secure Access
+
+Generate temporary signed URLs for file access without authentication:
+
+```python
+# Request signed URL
+response = requests.post(f"{base_url}/files/{file_id}/signed-url",
+                        headers=headers,
+                        json={"expires_in": 3600})  # 1 hour
+signed_url = response.json()['data']['url']
+
+# Use signed URL (no auth required)
+file_response = requests.get(signed_url)
+```
+
+### Streaming and Quality Options
+
+**Video Streaming with Quality Selection**
+
+```bash
+# Stream in different qualities
+curl "https://api.example.com/api/v1/videos/job_789012/stream?quality=720p" \
+  -H "Authorization: Bearer your-token-here"
+```
+
+**Thumbnail Sizes**
+
+```bash
+# Get different thumbnail sizes
+curl "https://api.example.com/api/v1/videos/job_789012/thumbnail?size=large" \
+  -H "Authorization: Bearer your-token-here"
+```
+
+## Performance Optimization
+
+### Caching
+
+The API implements intelligent caching. Use these endpoints to manage cache:
+
+```bash
+# Warm cache for better performance
+curl -X POST "https://api.example.com/api/v1/system/cache/warm" \
+  -H "Authorization: Bearer your-token-here"
+
+# Invalidate specific cache patterns
+curl -X POST "https://api.example.com/api/v1/system/cache/invalidate" \
+  -H "Authorization: Bearer your-token-here" \
+  -d "pattern=user:123:*"
+```
+
+### Request Optimization
+
+- Use pagination for large datasets
+- Implement client-side caching for frequently accessed data
+- Use appropriate quality settings for streaming
+- Batch operations when possible
+
+## Monitoring and Analytics
+
+### System Health Monitoring
+
+```bash
+# Check overall system health
+curl "https://api.example.com/api/v1/system/health"
+
+# Get detailed performance metrics
+curl "https://api.example.com/api/v1/system/performance?hours=24" \
+  -H "Authorization: Bearer your-token-here"
+```
+
+### File Analytics
+
+Track file usage and performance:
+
+```bash
+curl "https://api.example.com/api/v1/files/file_123456/analytics" \
+  -H "Authorization: Bearer your-token-here"
+```
+
+## Migration Guide
+
+### From v1.0 to v1.1
+
+**Breaking Changes:**
+
+- `GET /files/{id}/info` is now `GET /files/{id}` (consolidated endpoints)
+- Error response format now includes `details` field
+- Pagination format standardized across all endpoints
+
+**New Features:**
+
+- Webhook support for job notifications
+- Batch file operations
+- Enhanced error details
+- Signed URL support
+
+**Migration Steps:**
+
+1. Update endpoint URLs for file info
+2. Update error handling to use new format
+3. Implement webhook handlers for better UX
+4. Use batch operations for improved performance
+
+## Changelog
+
+### v1.1.0 (2024-01-15)
+
+- Added webhook support
+- Introduced batch file operations
+- Enhanced error responses with details
+- Added signed URL generation
+- Improved pagination format
+- Added system performance endpoints
+
+### v1.0.0 (2023-12-01)
+
+- Initial API release
+- Basic CRUD operations for files
+- Video generation capabilities
+- Job management system
+- System monitoring endpoints

AUTHENTICATION_GUIDE.md

@@ -0,0 +1,1120 @@
+# T2M Authentication & Session Flow Guide
+
+## Overview
+
+This guide covers the complete authentication and session management flow for the T2M (Text-to-Media) application using Clerk as the authentication provider. It includes frontend SDK setup, route protection, API token management, and secure file access patterns.
+
+## Table of Contents
+
+1. [Clerk Setup & Configuration](#clerk-setup--configuration)
+2. [Frontend SDK Integration](#frontend-sdk-integration)
+3. [Route Protection Strategy](#route-protection-strategy)
+4. [API Token Management](#api-token-management)
+5. [Secure File Access](#secure-file-access)
+6. [Session Management](#session-management)
+7. [Security Best Practices](#security-best-practices)
+8. [Implementation Examples](#implementation-examples)
+
+## Clerk Setup & Configuration
+
+### 1. Clerk Dashboard Configuration
+
+**Environment Setup:**
+- **Development**: `https://dev.t2m-app.com`
+- **Production**: `https://t2m-app.com`
+
+**Required Clerk Settings:**
+```javascript
+// Environment Variables
+NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=pk_test_...
+CLERK_SECRET_KEY=sk_test_...
+NEXT_PUBLIC_CLERK_SIGN_IN_URL=/sign-in
+NEXT_PUBLIC_CLERK_SIGN_UP_URL=/sign-up
+NEXT_PUBLIC_CLERK_AFTER_SIGN_IN_URL=/dashboard
+NEXT_PUBLIC_CLERK_AFTER_SIGN_UP_URL=/onboarding
+```
+
+**Clerk Application Settings:**
+- **Session token lifetime**: 7 days
+- **JWT template**: Custom template for API integration
+- **Allowed origins**: Your frontend domains
+- **Webhook endpoints**: For user lifecycle events
+
+### 2. JWT Template Configuration
+
+Create a custom JWT template in Clerk dashboard:
+
+```json
+{
+  "aud": "t2m-api",
+  "exp": "{{session.expire_at}}",
+  "iat": "{{session.created_at}}",
+  "iss": "https://clerk.t2m-app.com",
+  "sub": "{{user.id}}",
+  "user_id": "{{user.id}}",
+  "email": "{{user.primary_email_address.email_address}}",
+  "role": "{{user.public_metadata.role}}",
+  "permissions": "{{user.public_metadata.permissions}}",
+  "subscription_tier": "{{user.public_metadata.subscription_tier}}"
+}
+```
+
+## Frontend SDK Integration
+
+### 1. Next.js Setup (@clerk/nextjs)
+
+**Installation:**
+```bash
+npm install @clerk/nextjs
+```
+
+**App Router Configuration (app/layout.tsx):**
+```typescript
+import { ClerkProvider } from '@clerk/nextjs'
+import { Inter } from 'next/font/google'
+import './globals.css'
+
+const inter = Inter({ subsets: ['latin'] })
+
+export default function RootLayout({
+  children,
+}: {
+  children: React.ReactNode
+}) {
+  return (
+    <ClerkProvider>
+      <html lang="en">
+        <body className={inter.className}>
+          {children}
+        </body>
+      </html>
+    </ClerkProvider>
+  )
+}
+```
+
+**Middleware Setup (middleware.ts):**
+```typescript
+import { authMiddleware } from "@clerk/nextjs";
+
+export default authMiddleware({
+  // Public routes that don't require authentication
+  publicRoutes: [
+    "/",
+    "/api/auth/health",
+    "/api/system/health",
+    "/pricing",
+    "/about",
+    "/contact"
+  ],
+  
+  // Routes that should be ignored by Clerk
+  ignoredRoutes: [
+    "/api/webhooks/clerk",
+    "/api/files/secure/(.*)"  // Signed URL access
+  ],
+  
+  // API routes that require authentication
+  apiRoutes: ["/api/(.*)"],
+  
+  // Redirect after sign in
+  afterAuth(auth, req, evt) {
+    // Handle users who aren't authenticated
+    if (!auth.userId && !auth.isPublicRoute) {
+      return redirectToSignIn({ returnBackUrl: req.url });
+    }
+    
+    // Redirect authenticated users away from public-only pages
+    if (auth.userId && auth.isPublicRoute && req.nextUrl.pathname === "/") {
+      const dashboard = new URL("/dashboard", req.url);
+      return NextResponse.redirect(dashboard);
+    }
+  }
+});
+
+export const config = {
+  matcher: ["/((?!.+\\.[\\w]+$|_next).*)", "/", "/(api|trpc)(.*)"],
+};
+```
+
+### 2. React Components Setup
+
+**Authentication Components:**
+```typescript
+// components/auth/SignInButton.tsx
+import { SignInButton as ClerkSignInButton } from "@clerk/nextjs";
+
+export function SignInButton() {
+  return (
+    <ClerkSignInButton mode="modal">
+      <button className="btn-primary">
+        Sign In
+      </button>
+    </ClerkSignInButton>
+  );
+}
+
+// components/auth/UserButton.tsx
+import { UserButton as ClerkUserButton } from "@clerk/nextjs";
+
+export function UserButton() {
+  return (
+    <ClerkUserButton 
+      afterSignOutUrl="/"
+      appearance={{
+        elements: {
+          avatarBox: "w-8 h-8"
+        }
+      }}
+    />
+  );
+}
+```
+
+**Protected Page Component:**
+```typescript
+// components/auth/ProtectedRoute.tsx
+import { useAuth } from "@clerk/nextjs";
+import { useRouter } from "next/navigation";
+import { useEffect } from "react";
+import { LoadingSpinner } from "@/components/ui/LoadingSpinner";
+
+interface ProtectedRouteProps {
+  children: React.ReactNode;
+  requiredRole?: string;
+  requiredPermissions?: string[];
+}
+
+export function ProtectedRoute({ 
+  children, 
+  requiredRole,
+  requiredPermissions 
+}: ProtectedRouteProps) {
+  const { isLoaded, isSignedIn, user } = useAuth();
+  const router = useRouter();
+
+  useEffect(() => {
+    if (isLoaded && !isSignedIn) {
+      router.push("/sign-in");
+    }
+  }, [isLoaded, isSignedIn, router]);
+
+  if (!isLoaded) {
+    return <LoadingSpinner />;
+  }
+
+  if (!isSignedIn) {
+    return null;
+  }
+
+  // Check role-based access
+  if (requiredRole) {
+    const userRole = user?.publicMetadata?.role as string;
+    if (userRole !== requiredRole) {
+      return <div>Access denied. Required role: {requiredRole}</div>;
+    }
+  }
+
+  // Check permission-based access
+  if (requiredPermissions) {
+    const userPermissions = user?.publicMetadata?.permissions as string[] || [];
+    const hasPermission = requiredPermissions.every(permission => 
+      userPermissions.includes(permission)
+    );
+    
+    if (!hasPermission) {
+      return <div>Access denied. Missing required permissions.</div>;
+    }
+  }
+
+  return <>{children}</>;
+}
+```
+
+## Route Protection Strategy
+
+### 1. Public Routes (No Authentication Required)
+
+```typescript
+// Public routes configuration
+const PUBLIC_ROUTES = [
+  "/",                    // Landing page
+  "/pricing",            // Pricing information
+  "/about",              // About page
+  "/contact",            // Contact page
+  "/api/auth/health",    // Auth service health
+  "/api/system/health",  // System health check
+  "/legal/privacy",      // Privacy policy
+  "/legal/terms"         // Terms of service
+];
+```
+
+### 2. Protected Routes (Authentication Required)
+
+```typescript
+// Protected routes with different access levels
+const PROTECTED_ROUTES = {
+  // Basic authenticated routes
+  AUTHENTICATED: [
+    "/dashboard",
+    "/profile",
+    "/files",
+    "/videos",
+    "/jobs"
+  ],
+  
+  // Admin-only routes
+  ADMIN: [
+    "/admin",
+    "/admin/users",
+    "/admin/system",
+    "/admin/analytics"
+  ],
+  
+  // Premium subscription routes
+  PREMIUM: [
+    "/premium/advanced-generation",
+    "/premium/batch-processing",
+    "/premium/priority-queue"
+  ]
+};
+```
+
+### 3. API Route Protection
+
+```typescript
+// app/api/auth/route-protection.ts
+import { auth } from "@clerk/nextjs";
+import { NextRequest, NextResponse } from "next/server";
+
+export async function requireAuth(request: NextRequest) {
+  const { userId } = auth();
+  
+  if (!userId) {
+    return NextResponse.json(
+      { error: "Unauthorized" }, 
+      { status: 401 }
+    );
+  }
+  
+  return userId;
+}
+
+export async function requireRole(request: NextRequest, requiredRole: string) {
+  const { userId, sessionClaims } = auth();
+  
+  if (!userId) {
+    return NextResponse.json(
+      { error: "Unauthorized" }, 
+      { status: 401 }
+    );
+  }
+  
+  const userRole = sessionClaims?.metadata?.role as string;
+  
+  if (userRole !== requiredRole) {
+    return NextResponse.json(
+      { error: "Forbidden" }, 
+      { status: 403 }
+    );
+  }
+  
+  return userId;
+}
+
+// Usage in API routes
+// app/api/files/route.ts
+import { requireAuth } from "@/app/api/auth/route-protection";
+
+export async function GET(request: NextRequest) {
+  const userId = await requireAuth(request);
+  if (userId instanceof NextResponse) return userId; // Error response
+  
+  // Continue with authenticated logic
+  // ...
+}
+```
+
+## API Token Management
+
+### 1. Token Retrieval in Frontend
+
+```typescript
+// hooks/useApiToken.ts
+import { useAuth } from "@clerk/nextjs";
+import { useCallback } from "react";
+
+export function useApiToken() {
+  const { getToken } = useAuth();
+  
+  const getApiToken = useCallback(async () => {
+    try {
+      // Get token with custom JWT template
+      const token = await getToken({ template: "t2m-api" });
+      return token;
+    } catch (error) {
+      console.error("Failed to get API token:", error);
+      throw new Error("Authentication failed");
+    }
+  }, [getToken]);
+  
+  return { getApiToken };
+}
+
+// Usage in components
+function VideoUpload() {
+  const { getApiToken } = useApiToken();
+  
+  const uploadVideo = async (file: File) => {
+    const token = await getApiToken();
+    
+    const formData = new FormData();
+    formData.append('file', file);
+    
+    const response = await fetch('/api/files/upload', {
+      method: 'POST',
+      headers: {
+        'Authorization': `Bearer ${token}`
+      },
+      body: formData
+    });
+    
+    return response.json();
+  };
+  
+  // ...
+}
+```
+
+### 2. API Client with Automatic Token Management
+
+```typescript
+// lib/api-client.ts
+import { useAuth } from "@clerk/nextjs";
+
+class ApiClient {
+  private baseUrl: string;
+  private getToken: () => Promise<string | null>;
+  
+  constructor(baseUrl: string, getToken: () => Promise<string | null>) {
+    this.baseUrl = baseUrl;
+    this.getToken = getToken;
+  }
+  
+  private async request<T>(
+    endpoint: string, 
+    options: RequestInit = {}
+  ): Promise<T> {
+    const token = await this.getToken();
+    
+    const config: RequestInit = {
+      ...options,
+      headers: {
+        'Content-Type': 'application/json',
+        ...(token && { 'Authorization': `Bearer ${token}` }),
+        ...options.headers,
+      },
+    };
+    
+    const response = await fetch(`${this.baseUrl}${endpoint}`, config);
+    
+    if (!response.ok) {
+      const error = await response.json();
+      throw new Error(error.message || 'API request failed');
+    }
+    
+    return response.json();
+  }
+  
+  // File operations
+  async uploadFile(file: File, metadata?: any) {
+    const formData = new FormData();
+    formData.append('file', file);
+    if (metadata) {
+      Object.entries(metadata).forEach(([key, value]) => {
+        formData.append(key, value as string);
+      });
+    }
+    
+    const token = await this.getToken();
+    return fetch(`${this.baseUrl}/files/upload`, {
+      method: 'POST',
+      headers: {
+        ...(token && { 'Authorization': `Bearer ${token}` })
+      },
+      body: formData
+    }).then(res => res.json());
+  }
+  
+  async getFiles(params?: any) {
+    const query = params ? `?${new URLSearchParams(params)}` : '';
+    return this.request(`/files${query}`);
+  }
+  
+  // Video operations
+  async generateVideo(prompt: string, options?: any) {
+    return this.request('/videos/generate', {
+      method: 'POST',
+      body: JSON.stringify({ prompt, ...options })
+    });
+  }
+  
+  async getJobStatus(jobId: string) {
+    return this.request(`/jobs/${jobId}`);
+  }
+}
+
+// Hook for using API client
+export function useApiClient() {
+  const { getToken } = useAuth();
+  
+  const apiClient = new ApiClient(
+    process.env.NEXT_PUBLIC_API_URL || '/api/v1',
+    () => getToken({ template: "t2m-api" })
+  );
+  
+  return apiClient;
+}
+```
+
+### 3. Backend Token Validation
+
+```typescript
+// Backend API token validation (if using proxy)
+// app/api/auth/validate-token.ts
+import { verifyToken } from "@clerk/backend";
+
+export async function validateClerkToken(token: string) {
+  try {
+    const payload = await verifyToken(token, {
+      jwtKey: process.env.CLERK_JWT_KEY,
+      authorizedParties: [process.env.NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY]
+    });
+    
+    return {
+      userId: payload.sub,
+      email: payload.email,
+      role: payload.role,
+      permissions: payload.permissions,
+      subscriptionTier: payload.subscription_tier
+    };
+  } catch (error) {
+    throw new Error('Invalid token');
+  }
+}
+
+// Usage in API routes
+export async function POST(request: NextRequest) {
+  const authHeader = request.headers.get('authorization');
+  const token = authHeader?.replace('Bearer ', '');
+  
+  if (!token) {
+    return NextResponse.json({ error: 'No token provided' }, { status: 401 });
+  }
+  
+  try {
+    const user = await validateClerkToken(token);
+    // Continue with authenticated logic
+  } catch (error) {
+    return NextResponse.json({ error: 'Invalid token' }, { status: 401 });
+  }
+}
+```
+
+## Secure File Access
+
+### 1. Signed URL Generation
+
+```typescript
+// Backend: Generate signed URLs for secure file access
+// app/api/files/[fileId]/signed-url/route.ts
+import { auth } from "@clerk/nextjs";
+import { createHmac } from "crypto";
+
+export async function POST(
+  request: NextRequest,
+  { params }: { params: { fileId: string } }
+) {
+  const { userId } = auth();
+  if (!userId) {
+    return NextResponse.json({ error: "Unauthorized" }, { status: 401 });
+  }
+  
+  const { fileId } = params;
+  const { expiresIn = 3600 } = await request.json(); // Default 1 hour
+  
+  // Verify user owns the file
+  const file = await getFileById(fileId);
+  if (!file || file.userId !== userId) {
+    return NextResponse.json({ error: "File not found" }, { status: 404 });
+  }
+  
+  // Generate signed URL
+  const expires = Math.floor(Date.now() / 1000) + expiresIn;
+  const signature = createHmac('sha256', process.env.FILE_SIGNING_SECRET!)
+    .update(`${fileId}:${userId}:${expires}`)
+    .digest('hex');
+  
+  const signedUrl = `${process.env.NEXT_PUBLIC_API_URL}/files/secure/${fileId}?` +
+    `user_id=${userId}&expires=${expires}&signature=${signature}`;
+  
+  return NextResponse.json({
+    success: true,
+    data: {
+      url: signedUrl,
+      expires_at: new Date(expires * 1000).toISOString()
+    }
+  });
+}
+```
+
+### 2. Signed URL Validation
+
+```typescript
+// Backend: Validate signed URLs
+// app/api/files/secure/[fileId]/route.ts
+import { createHmac } from "crypto";
+import { NextRequest, NextResponse } from "next/server";
+
+export async function GET(
+  request: NextRequest,
+  { params }: { params: { fileId: string } }
+) {
+  const { fileId } = params;
+  const { searchParams } = new URL(request.url);
+  
+  const userId = searchParams.get('user_id');
+  const expires = searchParams.get('expires');
+  const signature = searchParams.get('signature');
+  
+  if (!userId || !expires || !signature) {
+    return NextResponse.json({ error: "Invalid signed URL" }, { status: 400 });
+  }
+  
+  // Check expiration
+  const expiresTimestamp = parseInt(expires);
+  if (Date.now() / 1000 > expiresTimestamp) {
+    return NextResponse.json({ error: "Signed URL expired" }, { status: 410 });
+  }
+  
+  // Verify signature
+  const expectedSignature = createHmac('sha256', process.env.FILE_SIGNING_SECRET!)
+    .update(`${fileId}:${userId}:${expires}`)
+    .digest('hex');
+  
+  if (signature !== expectedSignature) {
+    return NextResponse.json({ error: "Invalid signature" }, { status: 403 });
+  }
+  
+  // Serve file
+  const file = await getFileById(fileId);
+  if (!file || file.userId !== userId) {
+    return NextResponse.json({ error: "File not found" }, { status: 404 });
+  }
+  
+  // Return file stream
+  const fileStream = await getFileStream(file.path);
+  return new NextResponse(fileStream, {
+    headers: {
+      'Content-Type': file.contentType,
+      'Content-Disposition': `attachment; filename="${file.filename}"`,
+      'Cache-Control': 'private, max-age=3600'
+    }
+  });
+}
+```
+
+### 3. Frontend: Secure Video Player
+
+```typescript
+// components/VideoPlayer.tsx
+import { useApiClient } from "@/lib/api-client";
+import { useEffect, useState } from "react";
+
+interface VideoPlayerProps {
+  jobId: string;
+  autoplay?: boolean;
+}
+
+export function VideoPlayer({ jobId, autoplay = false }: VideoPlayerProps) {
+  const [signedUrl, setSignedUrl] = useState<string | null>(null);
+  const [loading, setLoading] = useState(true);
+  const [error, setError] = useState<string | null>(null);
+  const apiClient = useApiClient();
+  
+  useEffect(() => {
+    async function getSignedUrl() {
+      try {
+        setLoading(true);
+        
+        // Get signed URL for video
+        const response = await apiClient.request(`/videos/${jobId}/signed-url`, {
+          method: 'POST',
+          body: JSON.stringify({ expiresIn: 3600 }) // 1 hour
+        });
+        
+        setSignedUrl(response.data.url);
+      } catch (err) {
+        setError(err instanceof Error ? err.message : 'Failed to load video');
+      } finally {
+        setLoading(false);
+      }
+    }
+    
+    getSignedUrl();
+  }, [jobId, apiClient]);
+  
+  if (loading) return <div>Loading video...</div>;
+  if (error) return <div>Error: {error}</div>;
+  if (!signedUrl) return <div>Video not available</div>;
+  
+  return (
+    <video
+      src={signedUrl}
+      controls
+      autoPlay={autoplay}
+      className="w-full h-auto rounded-lg"
+      onError={() => setError('Failed to load video')}
+    >
+      Your browser does not support the video tag.
+    </video>
+  );
+}
+```
+
+## Session Management
+
+### 1. Session Configuration
+
+```typescript
+// lib/session-config.ts
+export const SESSION_CONFIG = {
+  // Session duration
+  maxAge: 7 * 24 * 60 * 60, // 7 days in seconds
+  
+  // Token refresh threshold
+  refreshThreshold: 5 * 60, // Refresh if expires in 5 minutes
+  
+  // Automatic logout on inactivity
+  inactivityTimeout: 30 * 60, // 30 minutes
+  
+  // Remember me option
+  rememberMe: {
+    enabled: true,
+    duration: 30 * 24 * 60 * 60 // 30 days
+  }
+};
+```
+
+### 2. Session Monitoring Hook
+
+```typescript
+// hooks/useSessionMonitor.ts
+import { useAuth } from "@clerk/nextjs";
+import { useEffect, useRef } from "react";
+
+export function useSessionMonitor() {
+  const { isSignedIn, signOut } = useAuth();
+  const lastActivityRef = useRef(Date.now());
+  const inactivityTimerRef = useRef<NodeJS.Timeout>();
+  
+  const resetInactivityTimer = () => {
+    lastActivityRef.current = Date.now();
+    
+    if (inactivityTimerRef.current) {
+      clearTimeout(inactivityTimerRef.current);
+    }
+    
+    inactivityTimerRef.current = setTimeout(() => {
+      if (isSignedIn) {
+        signOut();
+        alert('You have been logged out due to inactivity.');
+      }
+    }, SESSION_CONFIG.inactivityTimeout * 1000);
+  };
+  
+  useEffect(() => {
+    if (!isSignedIn) return;
+    
+    const events = ['mousedown', 'mousemove', 'keypress', 'scroll', 'touchstart'];
+    
+    events.forEach(event => {
+      document.addEventListener(event, resetInactivityTimer, true);
+    });
+    
+    resetInactivityTimer(); // Initialize timer
+    
+    return () => {
+      events.forEach(event => {
+        document.removeEventListener(event, resetInactivityTimer, true);
+      });
+      
+      if (inactivityTimerRef.current) {
+        clearTimeout(inactivityTimerRef.current);
+      }
+    };
+  }, [isSignedIn]);
+}
+```
+
+### 3. Token Refresh Management
+
+```typescript
+// hooks/useTokenRefresh.ts
+import { useAuth } from "@clerk/nextjs";
+import { useEffect, useCallback } from "react";
+
+export function useTokenRefresh() {
+  const { getToken, isSignedIn } = useAuth();
+  
+  const checkTokenExpiry = useCallback(async () => {
+    if (!isSignedIn) return;
+    
+    try {
+      const token = await getToken({ template: "t2m-api" });
+      if (!token) return;
+      
+      // Decode JWT to check expiry
+      const payload = JSON.parse(atob(token.split('.')[1]));
+      const expiryTime = payload.exp * 1000; // Convert to milliseconds
+      const currentTime = Date.now();
+      const timeUntilExpiry = expiryTime - currentTime;
+      
+      // Refresh if token expires within threshold
+      if (timeUntilExpiry < SESSION_CONFIG.refreshThreshold * 1000) {
+        await getToken({ template: "t2m-api", skipCache: true });
+      }
+    } catch (error) {
+      console.error('Token refresh failed:', error);
+    }
+  }, [getToken, isSignedIn]);
+  
+  useEffect(() => {
+    if (!isSignedIn) return;
+    
+    // Check token expiry every minute
+    const interval = setInterval(checkTokenExpiry, 60 * 1000);
+    
+    return () => clearInterval(interval);
+  }, [isSignedIn, checkTokenExpiry]);
+}
+```
+
+## Security Best Practices
+
+### 1. Token Security
+
+```typescript
+// Security guidelines for token handling
+
+// ✅ DO: Use secure token storage
+const { getToken } = useAuth();
+const token = await getToken({ template: "t2m-api" });
+
+// ❌ DON'T: Store tokens in localStorage or sessionStorage
+localStorage.setItem('token', token); // NEVER DO THIS
+
+// ✅ DO: Use tokens for API calls only
+const response = await fetch('/api/files', {
+  headers: { 'Authorization': `Bearer ${token}` }
+});
+
+// ❌ DON'T: Embed tokens in URLs or HTML
+const videoUrl = `/video?token=${token}`; // NEVER DO THIS
+```
+
+### 2. CSRF Protection
+
+```typescript
+// middleware.ts - CSRF protection
+import { NextRequest, NextResponse } from "next/server";
+
+export function middleware(request: NextRequest) {
+  // CSRF protection for state-changing operations
+  if (['POST', 'PUT', 'DELETE', 'PATCH'].includes(request.method)) {
+    const origin = request.headers.get('origin');
+    const host = request.headers.get('host');
+    
+    if (origin && !origin.includes(host!)) {
+      return NextResponse.json(
+        { error: 'CSRF protection: Invalid origin' },
+        { status: 403 }
+      );
+    }
+  }
+  
+  return NextResponse.next();
+}
+```
+
+### 3. Rate Limiting
+
+```typescript
+// lib/rate-limiter.ts
+import { Ratelimit } from "@upstash/ratelimit";
+import { Redis } from "@upstash/redis";
+
+const redis = new Redis({
+  url: process.env.UPSTASH_REDIS_REST_URL!,
+  token: process.env.UPSTASH_REDIS_REST_TOKEN!,
+});
+
+export const rateLimiter = new Ratelimit({
+  redis,
+  limiter: Ratelimit.slidingWindow(100, "1 h"), // 100 requests per hour
+  analytics: true,
+});
+
+// Usage in API routes
+export async function POST(request: NextRequest) {
+  const { userId } = auth();
+  if (!userId) {
+    return NextResponse.json({ error: "Unauthorized" }, { status: 401 });
+  }
+  
+  const { success, limit, reset, remaining } = await rateLimiter.limit(userId);
+  
+  if (!success) {
+    return NextResponse.json(
+      { error: "Rate limit exceeded" },
+      { 
+        status: 429,
+        headers: {
+          'X-RateLimit-Limit': limit.toString(),
+          'X-RateLimit-Remaining': remaining.toString(),
+          'X-RateLimit-Reset': reset.toString(),
+        }
+      }
+    );
+  }
+  
+  // Continue with request processing
+}
+```
+
+## Implementation Examples
+
+### 1. Complete Authentication Flow
+
+```typescript
+// app/dashboard/page.tsx
+import { ProtectedRoute } from "@/components/auth/ProtectedRoute";
+import { useSessionMonitor } from "@/hooks/useSessionMonitor";
+import { useTokenRefresh } from "@/hooks/useTokenRefresh";
+
+export default function DashboardPage() {
+  useSessionMonitor(); // Monitor for inactivity
+  useTokenRefresh();   // Handle token refresh
+  
+  return (
+    <ProtectedRoute>
+      <div className="dashboard">
+        <h1>Welcome to T2M Dashboard</h1>
+        {/* Dashboard content */}
+      </div>
+    </ProtectedRoute>
+  );
+}
+```
+
+### 2. File Upload with Progress
+
+```typescript
+// components/FileUpload.tsx
+import { useApiClient } from "@/lib/api-client";
+import { useState } from "react";
+
+export function FileUpload() {
+  const [uploading, setUploading] = useState(false);
+  const [progress, setProgress] = useState(0);
+  const apiClient = useApiClient();
+  
+  const handleUpload = async (file: File) => {
+    setUploading(true);
+    setProgress(0);
+    
+    try {
+      // Create XMLHttpRequest for progress tracking
+      const formData = new FormData();
+      formData.append('file', file);
+      
+      const token = await apiClient.getApiToken();
+      
+      const xhr = new XMLHttpRequest();
+      
+      xhr.upload.addEventListener('progress', (e) => {
+        if (e.lengthComputable) {
+          setProgress((e.loaded / e.total) * 100);
+        }
+      });
+      
+      xhr.addEventListener('load', () => {
+        if (xhr.status === 200) {
+          const response = JSON.parse(xhr.responseText);
+          console.log('Upload successful:', response);
+        }
+      });
+      
+      xhr.open('POST', '/api/files/upload');
+      xhr.setRequestHeader('Authorization', `Bearer ${token}`);
+      xhr.send(formData);
+      
+    } catch (error) {
+      console.error('Upload failed:', error);
+    } finally {
+      setUploading(false);
+    }
+  };
+  
+  return (
+    <div className="file-upload">
+      <input
+        type="file"
+        onChange={(e) => {
+          const file = e.target.files?.[0];
+          if (file) handleUpload(file);
+        }}
+        disabled={uploading}
+      />
+      
+      {uploading && (
+        <div className="progress-bar">
+          <div 
+            className="progress-fill" 
+            style={{ width: `${progress}%` }}
+          />
+          <span>{Math.round(progress)}%</span>
+        </div>
+      )}
+    </div>
+  );
+}
+```
+
+### 3. Video Generation with Real-time Updates
+
+```typescript
+// components/VideoGenerator.tsx
+import { useApiClient } from "@/lib/api-client";
+import { useState, useEffect } from "react";
+
+export function VideoGenerator() {
+  const [prompt, setPrompt] = useState("");
+  const [jobId, setJobId] = useState<string | null>(null);
+  const [status, setStatus] = useState<string>("idle");
+  const [progress, setProgress] = useState(0);
+  const apiClient = useApiClient();
+  
+  const generateVideo = async () => {
+    try {
+      setStatus("starting");
+      
+      const response = await apiClient.generateVideo(prompt, {
+        duration: 10,
+        quality: "1080p"
+      });
+      
+      setJobId(response.data.job_id);
+      setStatus("processing");
+    } catch (error) {
+      console.error('Video generation failed:', error);
+      setStatus("error");
+    }
+  };
+  
+  // Poll for job status
+  useEffect(() => {
+    if (!jobId || status === "completed" || status === "error") return;
+    
+    const pollStatus = async () => {
+      try {
+        const response = await apiClient.getJobStatus(jobId);
+        setStatus(response.data.status);
+        setProgress(response.data.progress || 0);
+      } catch (error) {
+        console.error('Status check failed:', error);
+      }
+    };
+    
+    const interval = setInterval(pollStatus, 2000); // Poll every 2 seconds
+    return () => clearInterval(interval);
+  }, [jobId, status, apiClient]);
+  
+  return (
+    <div className="video-generator">
+      <textarea
+        value={prompt}
+        onChange={(e) => setPrompt(e.target.value)}
+        placeholder="Describe your video..."
+        disabled={status === "processing"}
+      />
+      
+      <button 
+        onClick={generateVideo}
+        disabled={!prompt || status === "processing"}
+      >
+        {status === "processing" ? "Generating..." : "Generate Video"}
+      </button>
+      
+      {status === "processing" && (
+        <div className="status">
+          <div className="progress-bar">
+            <div style={{ width: `${progress}%` }} />
+          </div>
+          <p>Progress: {progress}%</p>
+        </div>
+      )}
+      
+      {status === "completed" && jobId && (
+        <VideoPlayer jobId={jobId} />
+      )}
+    </div>
+  );
+}
+```
+
+## Troubleshooting
+
+### Common Issues
+
+1. **Token Expiry**: Implement automatic token refresh
+2. **CORS Issues**: Configure Clerk allowed origins properly
+3. **Webhook Failures**: Verify webhook URL accessibility
+4. **Rate Limiting**: Implement proper rate limiting and user feedback
+
+### Debug Tools
+
+```typescript
+// Debug helper for authentication issues
+export function useAuthDebug() {
+  const { isLoaded, isSignedIn, user, getToken } = useAuth();
+  
+  const debugAuth = async () => {
+    console.log('Auth Debug Info:', {
+      isLoaded,
+      isSignedIn,
+      userId: user?.id,
+      email: user?.primaryEmailAddress?.emailAddress,
+      metadata: user?.publicMetadata
+    });
+    
+    if (isSignedIn) {
+      try {
+        const token = await getToken({ template: "t2m-api" });
+        console.log('Token:', token);
+        
+        if (token) {
+          const payload = JSON.parse(atob(token.split('.')[1]));
+          console.log('Token payload:', payload);
+        }
+      } catch (error) {
+        console.error('Token error:', error);
+      }
+    }
+  };
+  
+  return { debugAuth };
+}
+```
+
+This comprehensive guide covers all aspects of authentication and session management for the T2M application, ensuring secure and efficient user experience while maintaining best practices for token handling and file access.

CLERK_TOKEN_GUIDE.md

@@ -0,0 +1,122 @@
+# Getting Your Clerk Token - Step by Step Guide
+
+## 🔍 Your Clerk Configuration
+
+Based on the API response, your Clerk app (`poetic-primate-48.clerk.accounts.dev`) is configured to only support:
+- ✅ Google OAuth (`oauth_google`)
+- ✅ Ticket-based authentication (`ticket`)
+- ❌ Email/Password authentication (not enabled)
+
+## 🎯 Recommended Method: Browser Console
+
+This is the easiest and most reliable method:
+
+### Step 1: Sign in via Google OAuth
+1. Open your browser
+2. Go to: `https://poetic-primate-48.clerk.accounts.dev`
+3. Click "Sign in with Google"
+4. Complete the Google OAuth flow
+
+### Step 2: Get the Token
+1. Once signed in, open Developer Tools (Press F12)
+2. Go to the **Console** tab
+3. Paste this command and press Enter:
+   ```javascript
+   window.Clerk.session.getToken().then(token => console.log('TOKEN:', token))
+   ```
+4. Copy the token (the long string after "TOKEN:")
+
+### Step 3: Test Your API
+```bash
+python test_current_api.py http://localhost:8000/api/v1 YOUR_TOKEN_HERE
+```
+
+## 🚀 Quick Start Scripts
+
+### Option A: Use the OAuth Helper
+```bash
+python get_clerk_token_oauth.py
+```
+Choose option 2 (Manual browser method)
+
+### Option B: Use the Simple Helper
+```bash
+python get_token_simple.py
+```
+Choose option 1 (Browser Console Method)
+
+## 📋 Complete Example
+
+1. **Open browser and sign in:**
+   - Go to: https://poetic-primate-48.clerk.accounts.dev
+   - Sign in with Google
+
+2. **Get token in console:**
+   ```javascript
+   window.Clerk.session.getToken().then(token => console.log('TOKEN:', token))
+   ```
+
+3. **Copy the token** (looks like: `eyJhbGciOiJSUzI1NiIsImtpZCI6Imluc18...`)
+
+4. **Test your API:**
+   ```bash
+   python test_current_api.py http://localhost:8000/api/v1 eyJhbGciOiJSUzI1NiIsImtpZCI6Imluc18...
+   ```
+
+## 🔧 Why Email/Password Didn't Work
+
+The API response showed:
+```json
+{
+  "status": "needs_identifier",
+  "supported_first_factors": [
+    {"strategy": "ticket"},
+    {"strategy": "oauth_google"}
+  ]
+}
+```
+
+This means your Clerk app is configured to only allow:
+- Google OAuth sign-in
+- Ticket-based authentication (for programmatic access)
+
+Email/password authentication is not enabled in your Clerk dashboard.
+
+## 🎯 Next Steps
+
+Once you have your token:
+
+1. **Test basic connectivity:**
+   ```bash
+   python test_current_api.py http://localhost:8000/api/v1 YOUR_TOKEN
+   ```
+
+2. **Test video generation:**
+   ```bash
+   python test_video_generation.py --base-url http://localhost:8000/api/v1 --token YOUR_TOKEN --quick
+   ```
+
+3. **Run comprehensive tests:**
+   ```bash
+   python test_video_generation.py --base-url http://localhost:8000/api/v1 --token YOUR_TOKEN
+   ```
+
+## 💡 Pro Tips
+
+- **Tokens expire**: You may need to get a fresh token periodically
+- **Save your token**: The scripts will save it to `auth_token.txt` for reuse
+- **Use the browser method**: It's the most reliable approach
+- **Check token format**: Valid tokens start with `eyJ`
+
+## 🆘 Troubleshooting
+
+**If the browser console method doesn't work:**
+1. Make sure you're signed in to your app
+2. Check that `window.Clerk` exists by typing it in console
+3. Try refreshing the page after signing in
+4. Make sure you're on the correct domain
+
+**If you get "Clerk not found" errors:**
+1. Make sure you're on a page where Clerk is loaded
+2. Try going to the main app page after signing in
+3. Check the Network tab for any Clerk-related requests

Dockerfile

@@ -1,105 +1,28 @@
-# Optimized Dockerfile for Hugging Face Spaces
-FROM python:3.12-slim
+FROM python:3.11-slim
 
 # Set working directory
 WORKDIR /app
 
-# Set environment variables for HF Spaces
-ENV DEBIAN_FRONTEND=noninteractive \
-    PYTHONUNBUFFERED=1 \
-    PYTHONPATH=/app:/app/src \
-    GRADIO_SERVER_NAME=0.0.0.0 \
-    GRADIO_SERVER_PORT=7860 \
-    HF_HOME=/app/.cache/huggingface \
-    HF_HUB_CACHE=/app/.cache/huggingface/hub \
-    TRANSFORMERS_CACHE=/app/.cache/transformers \
-    SENTENCE_TRANSFORMERS_HOME=/app/.cache/sentence_transformers \
-    PATH="/root/.TinyTeX/bin/x86_64-linux:$PATH" \
-    GRADIO_ALLOW_FLAGGING=never \
-    GRADIO_ANALYTICS_ENABLED=False \
-    HF_HUB_DISABLE_TELEMETRY=1
-
-# Install system dependencies in single layer
-RUN apt-get update && apt-get install -y --no-install-recommends \
-    wget \
-    curl \
-    git \
-    gcc \
-    g++ \
+# Install system dependencies
+RUN apt-get update && apt-get install -y \
     build-essential \
-    pkg-config \
-    portaudio19-dev \
-    libasound2-dev \
-    libsdl-pango-dev \
-    libcairo2-dev \
-    libpango1.0-dev \
-    sox \
-    ffmpeg \
-    texlive-full \
-    dvisvgm \
-    ghostscript \
-    ca-certificates \
-    && rm -rf /var/lib/apt/lists/* /tmp/* /var/tmp/*
-
+    curl \
+    && rm -rf /var/lib/apt/lists/*
 
-# Copy requirements and install Python dependencies
+# Copy requirements first for better caching
 COPY requirements.txt .
-RUN pip install --no-cache-dir  torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cpu \
-    && pip install --no-cache-dir  -r requirements.txt --extra-index-url https://download.pytorch.org/whl/cpu \
-    && python -c "import gradio; print(f'Gradio version: {gradio.__version__}')" \
-    && find /usr/local -name "*.pyc" -delete \
-    && find /usr/local -name "__pycache__" -type d -exec rm -rf {} + 2>/dev/null || true
-
-# Ensure Hugging Face cache directories are writable
 
-# Create models directory and download models efficiently
-RUN mkdir -p models && cd models \
-    && echo "Downloading models for HF Spaces..." \
-    && wget --progress=dot:giga --timeout=30 --tries=3 \
-        -O kokoro-v0_19.onnx \
-        "https://github.com/thewh1teagle/kokoro-onnx/releases/download/model-files/kokoro-v0_19.onnx" \
-    && wget --progress=dot:giga --timeout=30 --tries=3 \
-        -O voices.bin \
-        "https://github.com/thewh1teagle/kokoro-onnx/releases/download/model-files/voices.bin" \
-    && ls -la /app/models/
+# Install Python dependencies
+RUN pip install --no-cache-dir -r requirements.txt
 
-# Copy all project files and folders
+# Copy application code
 COPY . .
 
-ENV PYTHONPATH="/app:$PYTHONPATH"
-RUN echo "export PYTHONPATH=/app:\$PYTHONPATH" >> ~/.bashrc
-
-# Run embedding creation script at build time
-RUN python create_embeddings.py
-
-# Ensure all files are writable (fix PermissionError for log file)
-RUN chmod -R a+w /app
-
-# Create output directory
-RUN mkdir -p output tmp
-# Ensure output and tmp directories are writable (fix PermissionError for session_id.txt)
-RUN chmod -R a+w /app/output /app/tmp || true
-
-RUN mkdir -p output tmp logs \
-    && mkdir -p /app/.cache/huggingface/hub \
-    && mkdir -p /app/.cache/transformers \
-    && mkdir -p /app/.cache/sentence_transformers \
-    && chmod -R 755 /app/.cache \
-    && chmod 755 /app/models \
-    && ls -la /app/models/ \
-    && echo "Cache directories created with proper permissions"
-# Add HF Spaces specific metadata
-LABEL space.title="Text 2 Mnaim" \
-      space.sdk="docker" \
-      space.author="khanhthanhdev" \
-      space.description="Text to science video using multi Agent"
-
-# Expose the port that HF Spaces expects
-EXPOSE 7860
+# Create necessary directories
+RUN mkdir -p uploads videos logs
 
-# Health check optimized for HF Spaces
-HEALTHCHECK --interval=30s --timeout=10s --start-period=40s --retries=2 \
-    CMD curl -f http://localhost:7860/ || exit 1
+# Expose port
+EXPOSE 8000
 
-# Run the Gradio app with HF Spaces optimized settings
-CMD ["python", "gradio_app.py"]
+# Command to run the application
+CMD ["python", "-m", "uvicorn", "src.app.main:app", "--host", "0.0.0.0", "--port", "8000", "--reload"]

FASTAPI_SETUP_GUIDE.md

@@ -0,0 +1,302 @@
+# FastAPI Server Setup Guide
+
+This guide will help you set up and run the FastAPI server for the T2M (Text-to-Media) video generation system.
+
+## Prerequisites
+
+- Python 3.11 or higher
+- Redis server (for caching and job queuing)
+- Git (for cloning the repository)
+
+## Quick Start
+
+### 1. Environment Setup
+
+Your `.env` file is already configured with your Clerk keys. You just need to add the webhook secret once you create the webhook endpoint.
+
+### 2. Get ngrok Auth Token (if not already set)
+
+If you don't have an ngrok auth token in your `.env` file:
+
+1. Go to [ngrok Dashboard](https://dashboard.ngrok.com/get-started/your-authtoken)
+2. Sign up/login and copy your auth token
+3. Add it to your `.env` file:
+   ```env
+   NGROK_AUTHTOKEN=your_token_here
+   ```
+
+### 3. Quick Setup with Docker (Recommended)
+
+Run the automated setup script:
+
+**On Windows:**
+
+```cmd
+setup-dev.bat
+```
+
+**On Linux/macOS:**
+
+```bash
+chmod +x setup-dev.sh
+./setup-dev.sh
+```
+
+**Or manually with Make:**
+
+```bash
+make dev-services
+```
+
+### 4. Get Your Public ngrok URL
+
+After running the setup script:
+
+1. Visit the ngrok dashboard: http://localhost:4040
+2. Copy the HTTPS URL (e.g., `https://abc123.ngrok.io`)
+3. This is your public URL for webhooks
+
+**Or get it via command:**
+
+```bash
+make get-ngrok-url
+```
+
+### 5. Configure Clerk Webhook
+
+1. Go to [Clerk Dashboard](https://dashboard.clerk.com/)
+2. Navigate to **Webhooks**
+3. Click **"Add Endpoint"**
+4. Enter your ngrok URL + webhook path:
+   ```
+   https://your-ngrok-url.ngrok.io/api/v1/auth/webhooks/clerk
+   ```
+5. Select events: `user.created`, `user.updated`, `user.deleted`, `session.created`, `session.ended`
+6. Copy the **Signing Secret** and add it to your `.env`:
+   ```env
+   CLERK_WEBHOOK_SECRET=whsec_your_webhook_signing_secret_here
+   ```
+
+### 6. Install Python Dependencies
+
+```bash
+pip install -r requirements.txt
+```
+
+### 7. Start the FastAPI Server
+
+#### Method 1: Using the Makefile (Recommended)
+
+```bash
+make serve-api
+```
+
+#### Method 2: Using uvicorn directly
+
+```bash
+python -m uvicorn src.app.main:app --reload --host 0.0.0.0 --port 8000
+```
+
+#### Method 3: Full development workflow (services + API)
+
+```bash
+make dev-start
+```
+
+## Verification
+
+Once the server is running, you can verify it's working by:
+
+### 1. Health Check
+
+```bash
+curl http://localhost:8000/health
+```
+
+Expected response:
+
+```json
+{
+  "status": "healthy",
+  "app_name": "FastAPI Video Backend",
+  "version": "0.1.0",
+  "environment": "development"
+}
+```
+
+### 2. API Documentation
+
+Visit these URLs in your browser:
+
+- **Local Swagger UI**: http://localhost:8000/docs
+- **Public Swagger UI**: https://your-ngrok-url.ngrok.io/docs
+- **ReDoc**: http://localhost:8000/redoc
+- **OpenAPI JSON**: http://localhost:8000/openapi.json
+- **ngrok Dashboard**: http://localhost:4040
+
+### 3. Test Public Endpoint
+
+```bash
+# Test local endpoint
+curl http://localhost:8000/
+
+# Test public ngrok endpoint
+curl https://your-ngrok-url.ngrok.io/health
+```
+
+## Docker Services Management
+
+### Available Commands
+
+```bash
+# Start development services (Redis + ngrok)
+make dev-services
+
+# Stop development services
+make dev-services-stop
+
+# View service logs
+make dev-services-logs
+
+# Get current ngrok public URL
+make get-ngrok-url
+
+# Full development workflow
+make dev-start
+```
+
+### Manual Docker Commands
+
+```bash
+# Start services
+docker-compose -f docker-compose.dev.yml up -d
+
+# Stop services
+docker-compose -f docker-compose.dev.yml down
+
+# View logs
+docker-compose -f docker-compose.dev.yml logs -f
+
+# Check service status
+docker-compose -f docker-compose.dev.yml ps
+```
+
+## Available API Endpoints
+
+The server provides the following main endpoint groups:
+
+- **Authentication** (`/api/v1/auth/*`) - User authentication and authorization
+- **Videos** (`/api/v1/videos/*`) - Video generation and management
+- **Jobs** (`/api/v1/jobs/*`) - Background job management
+- **Files** (`/api/v1/files/*`) - File upload and management
+- **System** (`/api/v1/system/*`) - System health and monitoring
+
+## Development Features
+
+### Auto-reload
+
+The server runs with auto-reload enabled in development mode, so changes to your code will automatically restart the server.
+
+### Debug Mode
+
+When `DEBUG=true` in your `.env` file:
+
+- Detailed error messages are shown
+- API documentation is available
+- CORS is configured for local development
+
+### Logging
+
+The application uses structured logging. Logs will show:
+
+- Request/response information
+- Performance metrics
+- Error details
+- Authentication events
+
+## Troubleshooting
+
+### Common Issues
+
+#### 1. Redis Connection Error
+
+```
+Failed to initialize Redis: [Errno 111] Connection refused
+```
+
+**Solution**: Make sure Redis server is running on the configured host and port.
+
+#### 2. Clerk Authentication Error
+
+```
+Failed to initialize Clerk: Invalid secret key
+```
+
+**Solution**: Verify your Clerk API keys in the `.env` file are correct.
+
+#### 3. Port Already in Use
+
+```
+[Errno 48] Address already in use
+```
+
+**Solution**: Either stop the process using port 8000 or change the `PORT` in your `.env` file.
+
+#### 4. Import Errors
+
+```
+ModuleNotFoundError: No module named 'src'
+```
+
+**Solution**: Make sure you're running the server from the project root directory.
+
+### Checking Server Status
+
+```bash
+# Check if server is running
+curl -f http://localhost:8000/health
+
+# Check Redis connection
+redis-cli ping
+
+# View server logs (if running in background)
+tail -f logs/app.log
+```
+
+## Production Deployment
+
+For production deployment:
+
+1. Set `ENVIRONMENT=production` in your `.env`
+2. Set `DEBUG=false`
+3. Use a strong `SECRET_KEY`
+4. Configure proper `ALLOWED_ORIGINS` for CORS
+5. Set up proper Redis configuration with authentication
+6. Use a production ASGI server like Gunicorn with Uvicorn workers
+
+```bash
+# Production server example
+gunicorn src.app.main:app -w 4 -k uvicorn.workers.UvicornWorker --bind 0.0.0.0:8000
+```
+
+## Next Steps
+
+After setting up the server:
+
+1. **Generate Client SDKs**: Use `make generate-clients` to create client libraries
+2. **Test the API**: Use `make test-clients` to run integration tests
+3. **Explore the Documentation**: Visit `/docs` to understand available endpoints
+4. **Set up Authentication**: Configure Clerk for user management
+5. **Upload Files**: Test file upload functionality through the API
+
+## Support
+
+If you encounter issues:
+
+1. Check the server logs for detailed error messages
+2. Verify all environment variables are set correctly
+3. Ensure all dependencies are installed
+4. Make sure Redis is running and accessible
+5. Check that your API keys are valid and have proper permissions
+
+For additional help, refer to the project documentation or create an issue in the repository.

Makefile

@@ -0,0 +1,278 @@
+# Video Generation API - Client Generation Makefile
+# This Makefile provides convenient commands for generating and testing client SDKs
+
+.PHONY: help install-deps generate-clients test-clients clean-clients docs serve-api
+
+# Default target
+help:
+	@echo "Video Generation API - Client Generation"
+	@echo ""
+	@echo "Available targets:"
+	@echo "  help              Show this help message"
+	@echo "  install-deps      Install required dependencies"
+	@echo "  generate-clients  Generate all client SDKs"
+	@echo "  generate-ts       Generate TypeScript client only"
+	@echo "  generate-python   Generate Python client only"
+	@echo "  generate-java     Generate Java client only"
+	@echo "  test-clients      Test generated clients"
+	@echo "  clean-clients     Clean generated clients"
+	@echo "  serve-api         Start API server for testing"
+	@echo "  docs              Generate documentation"
+	@echo ""
+	@echo "Environment variables:"
+	@echo "  API_URL           API base URL (default: http://localhost:8000)"
+	@echo "  OUTPUT_DIR        Output directory (default: generated_clients)"
+	@echo "  LANGUAGES         Space-separated list of languages"
+
+# Configuration
+API_URL ?= http://localhost:8000
+OUTPUT_DIR ?= generated_clients
+LANGUAGES ?= typescript python java csharp go php ruby
+
+# Install dependencies
+install-deps:
+	@echo "Installing dependencies..."
+	@command -v node >/dev/null 2>&1 || { echo "Node.js is required but not installed. Please install Node.js first."; exit 1; }
+	@command -v npm >/dev/null 2>&1 || { echo "npm is required but not installed. Please install npm first."; exit 1; }
+	@echo "Installing OpenAPI Generator CLI..."
+	npm install -g @openapitools/openapi-generator-cli
+	@echo "Dependencies installed successfully!"
+
+# Generate all clients
+generate-clients: check-api
+	@echo "Generating client SDKs for languages: $(LANGUAGES)"
+	python scripts/generate_clients.py \
+		--api-url $(API_URL) \
+		--output-dir $(OUTPUT_DIR) \
+		--languages $(LANGUAGES)
+
+# Generate TypeScript client
+generate-ts: check-api
+	@echo "Generating TypeScript client..."
+	python scripts/generate_clients.py \
+		--api-url $(API_URL) \
+		--output-dir $(OUTPUT_DIR) \
+		--languages typescript
+
+# Generate Python client
+generate-python: check-api
+	@echo "Generating Python client..."
+	python scripts/generate_clients.py \
+		--api-url $(API_URL) \
+		--output-dir $(OUTPUT_DIR) \
+		--languages python
+
+# Generate Java client
+generate-java: check-api
+	@echo "Generating Java client..."
+	python scripts/generate_clients.py \
+		--api-url $(API_URL) \
+		--output-dir $(OUTPUT_DIR) \
+		--languages java
+
+# Test generated clients
+test-clients:
+	@echo "Testing generated clients..."
+	python scripts/test_clients.py \
+		--api-url $(API_URL) \
+		--clients-dir $(OUTPUT_DIR) \
+		--verbose
+
+# Clean generated clients
+clean-clients:
+	@echo "Cleaning generated clients..."
+	rm -rf $(OUTPUT_DIR)
+	@echo "Generated clients cleaned!"
+
+# Check if API is running
+check-api:
+	@echo "Checking if API is running at $(API_URL)..."
+	@curl -s -f $(API_URL)/health > /dev/null || { \
+		echo "API is not running at $(API_URL)"; \
+		echo "Please start the API server first with: make serve-api"; \
+		exit 1; \
+	}
+	@echo "API is running!"
+
+# Start API server
+serve-api:
+	@echo "Starting API server..."
+	python -m uvicorn src.app.main:app --reload --host 0.0.0.0 --port 8000
+
+# Development environment setup
+dev-setup-full: install-deps
+	@echo "Setting up full development environment with Docker..."
+	@chmod +x setup-dev.sh
+	@./setup-dev.sh
+
+# Start development services (Redis + ngrok)
+dev-services:
+	@echo "Starting development services (Redis + ngrok)..."
+	docker-compose -f docker-compose.dev.yml up -d
+	@echo "Services started! Visit http://localhost:4040 for ngrok dashboard"
+
+# Stop development services
+dev-services-stop:
+	@echo "Stopping development services..."
+	docker-compose -f docker-compose.dev.yml down
+
+# View development services logs
+dev-services-logs:
+	docker-compose -f docker-compose.dev.yml logs -f
+
+# Full development workflow
+dev-start: dev-services serve-api
+
+# Get ngrok public URL
+get-ngrok-url:
+	@echo "Getting ngrok public URL..."
+	@curl -s http://localhost:4040/api/tunnels | python -c "import sys, json; data = json.load(sys.stdin); print(data['tunnels'][0]['public_url'] if data['tunnels'] else 'No tunnels found')" 2>/dev/null || echo "ngrok not running or no tunnels found"
+
+# Generate documentation
+docs:
+	@echo "Generating documentation..."
+	@mkdir -p docs/generated
+	@echo "Documentation generated in docs/ directory"
+
+# Development targets
+dev-setup: install-deps
+	@echo "Setting up development environment..."
+	@chmod +x scripts/generate_clients.sh
+	@echo "Development environment ready!"
+
+# Quick test - generate and test TypeScript client
+quick-test: generate-ts
+	@echo "Running quick test with TypeScript client..."
+	cd $(OUTPUT_DIR)/typescript && npm install --silent
+	@echo "Quick test completed!"
+
+# Full workflow - generate all clients and test
+full-workflow: generate-clients test-clients
+	@echo "Full client generation and testing workflow completed!"
+
+# Docker targets
+docker-generate:
+	@echo "Generating clients using Docker..."
+	docker run --rm \
+		-v $(PWD):/workspace \
+		-w /workspace \
+		node:18-alpine \
+		sh -c "npm install -g @openapitools/openapi-generator-cli && python scripts/generate_clients.py"
+
+# CI/CD targets
+ci-test: install-deps generate-clients test-clients
+	@echo "CI/CD pipeline completed successfully!"
+
+# Validate OpenAPI spec
+validate-spec: check-api
+	@echo "Validating OpenAPI specification..."
+	curl -s $(API_URL)/openapi.json | python -m json.tool > /dev/null
+	@echo "OpenAPI specification is valid!"
+
+# Show client statistics
+stats:
+	@echo "Client generation statistics:"
+	@if [ -d "$(OUTPUT_DIR)" ]; then \
+		echo "Generated clients:"; \
+		for dir in $(OUTPUT_DIR)/*/; do \
+			if [ -d "$$dir" ]; then \
+				lang=$$(basename "$$dir"); \
+				files=$$(find "$$dir" -type f | wc -l); \
+				size=$$(du -sh "$$dir" | cut -f1); \
+				echo "  $$lang: $$files files, $$size"; \
+			fi; \
+		done; \
+	else \
+		echo "No clients generated yet. Run 'make generate-clients' first."; \
+	fi
+
+# Package clients for distribution
+package:
+	@echo "Packaging clients for distribution..."
+	@mkdir -p dist
+	@if [ -d "$(OUTPUT_DIR)" ]; then \
+		cd $(OUTPUT_DIR) && \
+		for dir in */; do \
+			if [ -d "$$dir" ]; then \
+				lang=$$(basename "$$dir"); \
+				echo "Packaging $$lang client..."; \
+				tar -czf ../dist/video-api-client-$$lang.tar.gz "$$dir"; \
+			fi; \
+		done; \
+	fi
+	@echo "Clients packaged in dist/ directory"
+
+# Publish clients (placeholder - customize for your needs)
+publish:
+	@echo "Publishing clients..."
+	@echo "This is a placeholder. Customize for your package managers."
+	@if [ -d "$(OUTPUT_DIR)/typescript" ]; then \
+		echo "Would publish TypeScript client to npm"; \
+	fi
+	@if [ -d "$(OUTPUT_DIR)/python" ]; then \
+		echo "Would publish Python client to PyPI"; \
+	fi
+	@if [ -d "$(OUTPUT_DIR)/java" ]; then \
+		echo "Would publish Java client to Maven Central"; \
+	fi
+
+# Watch for changes and regenerate
+watch:
+	@echo "Watching for API changes and regenerating clients..."
+	@echo "This requires 'entr' to be installed: brew install entr"
+	@echo "Watching src/app/ for changes..."
+	find src/app -name "*.py" | entr -r make generate-clients
+
+# Benchmark client generation
+benchmark:
+	@echo "Benchmarking client generation..."
+	@time make generate-clients
+	@echo "Benchmark completed!"
+
+# Show OpenAPI spec
+show-spec: check-api
+	@echo "OpenAPI Specification:"
+	@curl -s $(API_URL)/openapi.json | python -m json.tool
+
+# Interactive mode
+interactive:
+	@echo "Interactive client generation mode"
+	@echo "Available languages: typescript python java csharp go php ruby"
+	@read -p "Enter languages to generate (space-separated): " langs; \
+	make generate-clients LANGUAGES="$$langs"
+
+# Health check
+health:
+	@echo "Performing health check..."
+	@make check-api
+	@command -v openapi-generator-cli >/dev/null 2>&1 || { echo "OpenAPI Generator CLI not found"; exit 1; }
+	@command -v python >/dev/null 2>&1 || { echo "Python not found"; exit 1; }
+	@echo "All dependencies are available!"
+
+# Show version information
+version:
+	@echo "Version information:"
+	@echo "Node.js: $$(node --version 2>/dev/null || echo 'Not installed')"
+	@echo "npm: $$(npm --version 2>/dev/null || echo 'Not installed')"
+	@echo "Python: $$(python --version 2>/dev/null || echo 'Not installed')"
+	@echo "OpenAPI Generator: $$(openapi-generator-cli version 2>/dev/null || echo 'Not installed')"
+
+# Example usage
+example:
+	@echo "Example usage:"
+	@echo ""
+	@echo "1. Start the API server:"
+	@echo "   make serve-api"
+	@echo ""
+	@echo "2. In another terminal, generate clients:"
+	@echo "   make generate-clients"
+	@echo ""
+	@echo "3. Test the generated clients:"
+	@echo "   make test-clients"
+	@echo ""
+	@echo "4. Generate specific language only:"
+	@echo "   make generate-ts"
+	@echo "   make generate-python"
+	@echo ""
+	@echo "5. Clean up:"
+	@echo "   make clean-clients"

README.md

@@ -1,306 +1,205 @@
----
-title: AI Animation & Voice Studio
-emoji: 🎬
-colorFrom: blue
-colorTo: purple
-sdk: docker
-app_port: 7860
-suggested_hardware: cpu-upgrade
-suggested_storage: large
-pinned: true
-license: apache-2.0
-short_description: "Create mathematical animations with AI-powered using Manim"
-tags:
-  - text-to-speech
-  - animation
-  - mathematics
-  - manim
-  - ai-voice
-  - educational
-  - visualization
-models:
-  - kokoro-onnx/kokoro-v0_19
-datasets: []
-startup_duration_timeout: 30m
-fullWidth: true
-header: default
-disable_embedding: false
-preload_from_hub: []
----
-
-# AI Animation & Voice Studio 🎬
-
-A powerful application that combines AI-powered text-to-speech with mathematical animation generation using Manim and Kokoro TTS. Create stunning educational content with synchronized voice narration and mathematical visualizations.
-
-## 🚀 Features
-
-- **Text-to-Speech**: High-quality voice synthesis using Kokoro ONNX models
-- **Mathematical Animations**: Create stunning mathematical visualizations with Manim
-- **LaTeX Support**: Full LaTeX rendering capabilities with TinyTeX
-- **Interactive Interface**: User-friendly Gradio web interface
-- **Audio Processing**: Advanced audio manipulation with FFmpeg and SoX
-
-## 🛠️ Technology Stack
-
-- **Frontend**: Gradio for interactive web interface
-- **Backend**: Python with FastAPI/Flask
-- **Animation**: Manim (Mathematical Animation Engine)
-- **TTS**: Kokoro ONNX for text-to-speech synthesis
-- **LaTeX**: TinyTeX for mathematical typesetting
-- **Audio**: FFmpeg, SoX, PortAudio for audio processing
-- **Deployment**: Docker container optimized for Hugging Face Spaces
-
-## 📦 Models
-
-This application uses the following pre-trained models:
-
-- **Kokoro TTS**: `kokoro-v0_19.onnx` - High-quality neural text-to-speech model
-- **Voice Models**: `voices.bin` - Voice embedding models for different speaker characteristics
-
-Models are automatically downloaded during the Docker build process from the official releases.
-
-## 🏃‍♂️ Quick Start
-
-### Using Hugging Face Spaces
-
-1. Visit the [Space](https://huggingface.co/spaces/your-username/ai-animation-voice-studio)
-2. Wait for the container to load (initial startup may take 3-5 minutes due to model loading)
-3. Upload your script or enter text directly
-4. Choose animation settings and voice parameters
-5. Generate your animated video with AI narration!
-
-### Local Development
+# FastAPI Video Backend
 
-```bash
-# Clone the repository
-git clone https://huggingface.co/spaces/your-username/ai-animation-voice-studio
-cd ai-animation-voice-studio
-
-# Build the Docker image
-docker build -t ai-animation-studio .
-
-# Run the container
-docker run -p 7860:7860 ai-animation-studio
-```
-
-Access the application at `http://localhost:7860`
-
-### Environment Setup
-
-Create a `.env` file with your configuration:
-
-```env
-# Application settings
-DEBUG=false
-MAX_WORKERS=4
-
-# Model settings
-MODEL_PATH=/app/models
-CACHE_DIR=/tmp/cache
-
-# Optional: API keys if needed
-# OPENAI_API_KEY=your_key_here
-```
+A FastAPI backend for the multi-agent video generation system using Pydantic for data modeling, Clerk for authentication, and Redis for caching and job queuing.
 
-## 🎯 Usage Examples
+## Features
 
-### Basic Text-to-Speech
+- **FastAPI Framework**: Modern, fast web framework for building APIs
+- **Pydantic Models**: Data validation and serialization
+- **Clerk Authentication**: Secure user authentication and management
+- **Redis Integration**: Caching and job queue management
+- **Structured Logging**: JSON-formatted logging with structlog
+- **Environment Configuration**: Flexible configuration with Pydantic Settings
+- **CORS Support**: Cross-origin resource sharing configuration
+- **Health Checks**: Built-in health monitoring endpoints
+- **Testing Suite**: Comprehensive test coverage with pytest
 
-```python
-# Example usage in your code
-from src.tts import generate_speech
+## Quick Start
 
-audio = generate_speech(
-    text="Hello, this is a test of the text-to-speech system",
-    voice="default",
-    speed=1.0
-)
-```
-
-### Mathematical Animation
-
-```python
-# Example Manim scene
-from manim import *
-
-class Example(Scene):
-    def construct(self):
-        # Your animation code here
-        pass
-```
+### Prerequisites
 
-## 📁 Project Structure
+- Python 3.11+
+- Redis server
+- Clerk account (for authentication)
+
+### Installation
+
+1. **Clone the repository**
+   ```bash
+   git clone <repository-url>
+   cd fastapi-video-backend
+   ```
+
+2. **Install dependencies**
+   ```bash
+   pip install -e .
+   ```
+
+3. **Set up development environment**
+   ```bash
+   python scripts/setup.py
+   ```
+
+4. **Configure environment variables**
+   
+   Update the `.env` file with your actual configuration:
+   ```bash
+   # Required: Get these from your Clerk dashboard
+   CLERK_SECRET_KEY=your_actual_clerk_secret_key
+   CLERK_PUBLISHABLE_KEY=your_actual_clerk_publishable_key
+   
+   # Required: Generate a secure secret key
+   SECRET_KEY=your_super_secret_key_here
+   ```
+
+5. **Start Redis server**
+   ```bash
+   redis-server
+   ```
+
+6. **Run the application**
+   ```bash
+   # Development mode
+   python -m src.app.main
+   
+   # Or using the script
+   python -m uvicorn src.app.main:app --reload
+   ```
+
+7. **Access the API**
+   - API Documentation: http://localhost:8000/docs
+   - Alternative Docs: http://localhost:8000/redoc
+   - Health Check: http://localhost:8000/health
+
+## Project Structure
 
 ```
-├── src/                    # Source code
-│   ├── tts/               # Text-to-speech modules
-│   ├── manim_scenes/      # Manim animation scenes
-│   └── utils/             # Utility functions
-├── models/                # Pre-trained models (auto-downloaded)
-├── output/                # Generated content output
-├── requirements.txt       # Python dependencies
-├── Dockerfile            # Container configuration
-├── gradio_app.py         # Main application entry point
-└── README.md             # This file
+src/
+├── app/
+│   ├── main.py                    # FastAPI application entry point
+│   ├── api/                       # API layer
+│   │   ├── dependencies.py        # Shared dependencies
+│   │   └── v1/                    # API version 1
+│   │       ├── videos.py          # Video generation endpoints
+│   │       ├── jobs.py            # Job management endpoints
+│   │       └── system.py          # System health endpoints
+│   ├── core/                      # Core utilities and configurations
+│   │   ├── config.py              # Application settings
+│   │   ├── redis.py               # Redis connection and utilities
+│   │   ├── auth.py                # Clerk authentication utilities
+│   │   ├── logger.py              # Logging configuration
+│   │   └── exceptions.py          # Custom exceptions
+│   ├── services/                  # Business logic layer
+│   │   ├── video_service.py       # Video generation business logic
+│   │   ├── job_service.py         # Job management logic
+│   │   └── queue_service.py       # Redis queue management
+│   ├── models/                    # Pydantic models
+│   │   ├── job.py                 # Job data models
+│   │   ├── video.py               # Video metadata models
+│   │   ├── user.py                # User data models
+│   │   └── system.py              # System status models
+│   ├── middleware/                # Custom middleware
+│   │   ├── cors.py                # CORS middleware
+│   │   ├── clerk_auth.py          # Clerk authentication middleware
+│   │   └── error_handling.py      # Global error handling
+│   └── utils/                     # Utility functions
+│       ├── file_utils.py          # File handling utilities
+│       └── helpers.py             # General helper functions
+├── tests/                         # Test suite
+└── scripts/                       # Utility scripts
 ```
 
-## ⚙️ Configuration
+## Configuration
 
-### Docker Environment Variables
+The application uses environment-based configuration with Pydantic Settings. All configuration options are documented in `.env.example`.
 
-- `GRADIO_SERVER_NAME`: Server host (default: 0.0.0.0)
-- `GRADIO_SERVER_PORT`: Server port (default: 7860)
-- `PYTHONPATH`: Python path configuration
-- `HF_HOME`: Hugging Face cache directory
+### Key Configuration Sections
 
-### Application Settings
-
-Modify settings in your `.env` file or through environment variables:
-
-- Model parameters
-- Audio quality settings
-- Animation render settings
-- Cache configurations
-
-## 🔧 Development
-
-### Prerequisites
+- **Application Settings**: Basic app configuration
+- **Server Settings**: Host, port, and server options
+- **Redis Settings**: Redis connection and caching configuration
+- **Clerk Settings**: Authentication configuration
+- **Security Settings**: JWT and security configuration
+- **Logging Settings**: Structured logging configuration
 
-- Docker and Docker Compose
-- Python 3.12+
-- Git
+## Development
 
-### Setting Up Development Environment
+### Running Tests
 
 ```bash
-# Install dependencies locally for development
-pip install -r requirements.txt
+# Run all tests
+pytest
 
-# Run tests (if available)
-python -m pytest tests/
+# Run with coverage
+pytest --cov=src
 
-# Format code
-black .
-isort .
-
-# Lint code
-flake8 .
+# Run specific test file
+pytest tests/test_main.py
 ```
 
-### Building and Testing
+### Code Quality
 
 ```bash
-# Build the Docker image
-docker build -t your-app-name:dev .
-
-# Test the container locally
-docker run --rm -p 7860:7860 your-app-name:dev
-
-# Check container health
-docker run --rm your-app-name:dev python -c "import src; print('Import successful')"
-```
+# Format code
+black src/ tests/
 
-## 📊 Performance & Hardware
+# Sort imports
+isort src/ tests/
 
-### Recommended Specs for Hugging Face Spaces
+# Lint code
+flake8 src/ tests/
 
-- **Hardware**: `cpu-upgrade` (recommended for faster rendering)
-- **Storage**: `small` (sufficient for models and temporary files)
-- **Startup Time**: ~3-5 minutes (due to model loading and TinyTeX setup)
-- **Memory Usage**: ~2-3GB during operation
+# Type checking
+mypy src/
+```
 
-### System Requirements
+### Development Scripts
 
-- **Memory**: Minimum 2GB RAM, Recommended 4GB+
-- **CPU**: Multi-core processor recommended for faster animation rendering
-- **Storage**: ~1.5GB for models and dependencies
-- **Network**: Stable connection for initial model downloads
+- `python scripts/setup.py` - Set up development environment
+- `python -m src.app.main` - Run development server
+- `pytest` - Run test suite
 
-### Optimization Tips
+## API Documentation
 
-- Models are cached after first download
-- Gradio interface uses efficient streaming for large outputs
-- Docker multi-stage builds minimize final image size
-- TinyTeX installation is optimized for essential packages only
+Once the application is running, you can access:
 
-## 🐛 Troubleshooting
+- **Swagger UI**: http://localhost:8000/docs
+- **ReDoc**: http://localhost:8000/redoc
+- **OpenAPI JSON**: http://localhost:8000/openapi.json
 
-### Common Issues
+## Health Monitoring
 
-**Build Failures**:
-```bash
-# Clear Docker cache if build fails
-docker system prune -a
-docker build --no-cache -t your-app-name .
-```
+The application includes built-in health check endpoints:
 
-**Model Download Issues**:
-- Check internet connection
-- Verify model URLs are accessible
-- Models will be re-downloaded if corrupted
+- `GET /health` - Basic health status
+- `GET /` - Root endpoint with basic information
 
-**Memory Issues**:
-- Reduce batch sizes in configuration
-- Monitor memory usage with `docker stats`
+## Logging
 
-**Audio Issues**:
-- Ensure audio drivers are properly installed
-- Check PortAudio configuration
+The application uses structured logging with configurable output formats:
 
-### Getting Help
+- **Development**: Colorized console output
+- **Production**: JSON-formatted logs
 
-1. Check the [Discussions](https://huggingface.co/spaces/your-username/ai-animation-voice-studio/discussions) tab
-2. Review container logs in the Space settings
-3. Enable debug mode in configuration
-4. Report issues in the Community tab
+Log levels and formats can be configured via environment variables.
 
-### Common Configuration Issues
+## Security
 
-**Space Configuration**:
-- Ensure `app_port: 7860` is set in README.md front matter
-- Check that `sdk: docker` is properly configured
-- Verify hardware suggestions match your needs
+- **Authentication**: Clerk-based JWT authentication
+- **CORS**: Configurable cross-origin resource sharing
+- **Rate Limiting**: Built-in rate limiting support
+- **Input Validation**: Pydantic-based request validation
+- **Security Headers**: Automatic security header injection
 
-**Model Loading**:
-- Models download automatically on first run
-- Check Space logs for download progress
-- Restart Space if models fail to load
-
-## 🤝 Contributing
-
-We welcome contributions! Please see our contributing guidelines:
+## Contributing
 
 1. Fork the repository
 2. Create a feature branch
 3. Make your changes
-4. Add tests if applicable
-5. Submit a pull request
-
-### Code Style
-
-- Follow PEP 8 for Python code
-- Use Black for code formatting
-- Add docstrings for functions and classes
-- Include type hints where appropriate
-
-## 📄 License
-
-This project is licensed under the Apache License 2.0 - see the [LICENSE](LICENSE) file for details.
-
-## 🙏 Acknowledgments
-
-- [Manim Community](https://www.manim.community/) for the animation engine
-- [Kokoro TTS](https://github.com/thewh1teagle/kokoro-onnx) for text-to-speech models
-- [Gradio](https://gradio.app/) for the web interface framework
-- [Hugging Face](https://huggingface.co/) for hosting and infrastructure
-
-## 📞 Contact
-
-- **Author**: Your Name
-- **Email**: [email protected]
-- **GitHub**: [@your-username](https://github.com/your-username)
-- **Hugging Face**: [@your-username](https://huggingface.co/your-username)
+4. Add tests for new functionality
+5. Ensure all tests pass
+6. Submit a pull request
 
----
+## License
 
-*Built with ❤️ for the open-source community*
+This project is licensed under the MIT License - see the LICENSE file for details.

README_API_TESTING.md

@@ -0,0 +1,258 @@
+# T2M API Testing Guide
+
+This directory contains comprehensive test scripts for the T2M API endpoints.
+
+## Files
+
+- `test_api_endpoints.py` - Main test script with full endpoint coverage
+- `run_api_tests.py` - Simple runner using configuration file
+- `test_config.json` - Configuration file for API settings
+- `requirements-test.txt` - Python dependencies for testing
+
+## Quick Start
+
+### 1. Install Dependencies
+
+```bash
+pip install -r requirements-test.txt
+```
+
+### 2. Configure API Settings
+
+Edit `test_config.json` with your API details:
+
+```json
+{
+  "api_config": {
+    "base_url": "https://your-api-domain.com/api/v1",
+    "token": "your-actual-bearer-token"
+  }
+}
+```
+
+### 3. Run Tests
+
+**Option A: Using configuration file**
+```bash
+python run_api_tests.py
+```
+
+**Option B: Direct command line**
+```bash
+python test_api_endpoints.py --base-url https://your-api-domain.com/api/v1 --token your-token
+```
+
+**Option C: Token from file**
+```bash
+echo "your-token-here" > token.txt
+python test_api_endpoints.py --base-url https://your-api-domain.com/api/v1 --token-file token.txt
+```
+
+## Test Coverage
+
+The test script covers all major API endpoints:
+
+### 🔓 Public Endpoints (No Auth Required)
+- `GET /auth/health` - Authentication service health
+- `GET /system/health` - System health check
+
+### 🔐 Authentication Endpoints
+- `GET /auth/status` - Authentication status
+- `GET /auth/profile` - User profile
+- `GET /auth/permissions` - User permissions
+- `GET /auth/test/protected` - Protected endpoint test
+- `GET /auth/test/verified` - Verified user test
+- `POST /auth/verify` - Token verification
+
+### 📁 File Management Endpoints
+- `POST /files/upload` - Single file upload
+- `GET /files` - List files with pagination
+- `GET /files/{id}` - File details
+- `GET /files/{id}/metadata` - File metadata
+- `GET /files/{id}/thumbnail` - File thumbnail
+- `GET /files/stats` - File statistics
+- `DELETE /files/{id}` - File deletion (cleanup)
+
+### ⚙️ Job Management Endpoints
+- `GET /jobs` - List jobs
+- `GET /jobs/{id}` - Job details
+- `GET /jobs/{id}/logs` - Job logs
+- `POST /jobs/{id}/cancel` - Cancel job (cleanup)
+- `DELETE /jobs/{id}` - Delete job (cleanup)
+
+### 🖥️ System Monitoring Endpoints
+- `GET /system/metrics` - System metrics
+- `GET /system/queue` - Queue status
+- `GET /system/cache` - Cache information
+- `GET /system/cache/metrics` - Cache metrics
+- `GET /system/cache/report` - Cache report
+- `GET /system/performance` - Performance summary
+- `GET /system/connections` - Connection statistics
+- `GET /system/async` - Async statistics
+- `GET /system/deduplication` - Deduplication statistics
+
+### 🎥 Video Processing Endpoints
+- `POST /videos/generate` - Generate video
+- `GET /videos/{id}/status` - Video job status
+- `GET /videos/{id}/metadata` - Video metadata
+- `GET /videos/{id}/thumbnail` - Video thumbnail
+
+## Test Results
+
+After running tests, you'll get:
+
+1. **Console output** with real-time test results
+2. **Summary statistics** showing pass/fail rates
+3. **JSON report** saved to `api_test_results.json`
+
+### Example Output
+
+```
+🚀 Starting T2M API Endpoint Tests
+Base URL: https://api.example.com/api/v1
+Token: Provided
+
+🔓 Testing Public Endpoints
+✅ PASS GET /auth/health
+    Status: 200
+✅ PASS GET /system/health
+    Status: 200
+
+🔐 Testing Authentication Endpoints
+✅ PASS GET /auth/status
+    Status: 200
+✅ PASS GET /auth/profile
+    Status: 200
+
+📊 TEST SUMMARY
+==================================================
+Total Tests: 25
+Passed: 23 ✅
+Failed: 2 ❌
+Success Rate: 92.0%
+```
+
+## Test Features
+
+### 🧹 Automatic Cleanup
+- Deletes uploaded test files
+- Cancels/deletes created jobs
+- Prevents resource accumulation
+
+### 📊 Comprehensive Reporting
+- Real-time console feedback
+- Detailed JSON results file
+- Pass/fail statistics
+- Error details for debugging
+
+### 🔧 Flexible Configuration
+- Command line arguments
+- Configuration file support
+- Token file support
+- Environment variable support
+
+### 🛡️ Error Handling
+- Network timeout handling
+- Graceful failure handling
+- Detailed error reporting
+- Resource cleanup on failure
+
+## Advanced Usage
+
+### Testing Specific Endpoints
+
+You can modify the test script to focus on specific endpoint groups:
+
+```python
+# Only test public endpoints
+tester.test_public_endpoints()
+
+# Only test file operations
+tester.test_file_endpoints()
+
+# Only test system monitoring
+tester.test_system_endpoints()
+```
+
+### Custom Test Data
+
+Modify `test_config.json` to customize test parameters:
+
+```json
+{
+  "test_data": {
+    "video_generation": {
+      "prompt": "Your custom test prompt",
+      "duration": 10,
+      "quality": "1080p"
+    }
+  }
+}
+```
+
+### Environment Variables
+
+You can also use environment variables:
+
+```bash
+export T2M_API_URL="https://your-api-domain.com/api/v1"
+export T2M_API_TOKEN="your-token-here"
+python test_api_endpoints.py --base-url $T2M_API_URL --token $T2M_API_TOKEN
+```
+
+## Troubleshooting
+
+### Common Issues
+
+**Connection Errors**
+- Verify the base URL is correct
+- Check network connectivity
+- Ensure API server is running
+
+**Authentication Errors**
+- Verify token is valid and not expired
+- Check token format (should be just the token, not "Bearer token")
+- Ensure user has required permissions
+
+**Rate Limiting**
+- Tests may hit rate limits on busy servers
+- Add delays between requests if needed
+- Run tests during off-peak hours
+
+**Resource Cleanup Failures**
+- Some resources may not be cleaned up if tests fail
+- Manually delete test files/jobs if needed
+- Check API logs for cleanup issues
+
+### Debug Mode
+
+For more detailed debugging, modify the test script to add verbose logging:
+
+```python
+import logging
+logging.basicConfig(level=logging.DEBUG)
+```
+
+## Integration with CI/CD
+
+The test script returns appropriate exit codes for CI/CD integration:
+
+```bash
+# Run tests and capture exit code
+python test_api_endpoints.py --base-url $API_URL --token $API_TOKEN
+if [ $? -eq 0 ]; then
+    echo "All tests passed"
+else
+    echo "Some tests failed"
+    exit 1
+fi
+```
+
+## Contributing
+
+To add new test cases:
+
+1. Add the endpoint to the appropriate test method
+2. Follow the existing pattern for error handling
+3. Add cleanup logic if the endpoint creates resources
+4. Update this README with the new endpoint coverage

SYSTEM_OVERVIEW.md

@@ -0,0 +1,399 @@
+# Multi-Agent Video Generation System - Architecture Overview
+
+## 🎯 System Purpose
+This is a sophisticated **multi-agent system** that automatically generates educational videos using Manim (Mathematical Animation Engine). The system transforms textual descriptions of mathematical concepts, theorems, and educational content into high-quality animated videos through coordinated AI agents.
+
+## 🏗️ System Architecture
+
+```mermaid
+flowchart TD
+    %% Input Layer
+    U["User Input<br/>(Topic & Context)"]:::input
+    GV["generate_video.py<br/>(Main Orchestrator)"]:::input
+    ES["evaluate.py<br/>(Quality Assessment)"]:::input
+
+    %% Configuration and Data
+    CONF["Configuration<br/>(.env, src/config)"]:::config
+    DATA["Data Repository<br/>(data/)"]:::data
+
+    %% Core Generation Pipeline
+    subgraph "Core Multi-Agent Pipeline"
+        CG["Code Generation Agent<br/>(src/core/code_generator.py)"]:::core
+        VP["Video Planning Agent<br/>(src/core/video_planner.py)"]:::core
+        VR["Video Rendering Agent<br/>(src/core/video_renderer.py)"]:::core
+    end
+
+    %% Retrieval & Augmentation (RAG)
+    RAG["RAG Intelligence Agent<br/>(src/rag/rag_integration.py,<br/>src/rag/vector_store.py)"]:::rag
+
+    %% Task & Prompt Generation
+    TASK["Task & Prompt Generation<br/>(task_generator/)"]:::task
+
+    %% External LLM & Model Tools
+    LLM["LLM Provider Agents<br/>(mllm_tools/)"]:::ai
+
+    %% Voiceover & Utilities
+    VOX["Utility Services<br/>(src/utils/)"]:::voice
+
+    %% Evaluation Module
+    EVAL["Quality Evaluation Agent<br/>(eval_suite/)"]:::eval
+
+    %% Connections
+    U -->|"provides data"| GV
+    GV -->|"reads configuration"| CONF
+    CONF -->|"configures processing"| CG
+    CONF -->|"fetches theorem data"| DATA
+
+    %% Core Pipeline Flow
+    GV -->|"orchestrates generation"| CG
+    CG -->|"sends code/instructions"| VP
+    VP -->|"plans scenes"| VR
+    VR -->|"integrates audio"| VOX
+    VOX -->|"produces final video"| EVAL
+
+    %% Cross Module Integrations
+    TASK -->|"supplies prompt templates"| CG
+    TASK -->|"guides scene planning"| VP
+    CG -->|"augments with retrieval"| RAG
+    VP -->|"queries documentation"| RAG
+    LLM -->|"supports AI generation"| CG
+    LLM -->|"supports task generation"| TASK
+
+    %% Evaluation Script
+    ES -->|"evaluates output"| EVAL
+
+    %% Styles
+    classDef input fill:#FFD580,stroke:#333,stroke-width:2px;
+    classDef config fill:#B3E5FC,stroke:#333,stroke-width:2px;
+    classDef data fill:#C8E6C9,stroke:#333,stroke-width:2px;
+    classDef core fill:#FFF59D,stroke:#333,stroke-width:2px;
+    classDef rag fill:#FFCC80,stroke:#333,stroke-width:2px;
+    classDef task fill:#D1C4E9,stroke:#333,stroke-width:2px;
+    classDef ai fill:#B2EBF2,stroke:#333,stroke-width:2px;
+    classDef voice fill:#FFE0B2,stroke:#333,stroke-width:2px;
+    classDef eval fill:#E1BEE7,stroke:#333,stroke-width:2px;
+```
+
+## 🤖 Core Agents & Responsibilities
+
+### 1. **🎬 Video Planning Agent** (`src/core/video_planner.py`)
+**Role**: Strategic planning and scene orchestration
+
+**Key Capabilities**:
+- Scene outline generation and decomposition
+- Storyboard creation with visual descriptions
+- Technical implementation planning
+- Concurrent scene processing with enhanced parallelization
+- Context learning from previous examples
+- RAG integration for Manim documentation retrieval
+
+**Key Methods**:
+- `generate_scene_outline()` - Creates overall video structure
+- `generate_scene_implementation_concurrently_enhanced()` - Parallel scene planning
+- `_initialize_context_examples()` - Loads learning contexts
+
+### 2. **⚡ Code Generation Agent** (`src/core/code_generator.py`)
+**Role**: Manim code synthesis and optimization
+
+**Key Capabilities**:
+- Intelligent Manim code generation from scene descriptions
+- Automatic error detection and fixing
+- Visual self-reflection for code quality
+- RAG-enhanced code generation with documentation context
+- Context learning from successful examples
+- Banned reasoning prevention
+
+**Key Methods**:
+- `generate_manim_code()` - Primary code generation
+- `fix_code_errors()` - Intelligent error correction
+- `visual_self_reflection()` - Quality validation
+
+### 3. **🎞️ Video Rendering Agent** (`src/core/video_renderer.py`)
+**Role**: Video compilation and optimization
+
+**Key Capabilities**:
+- Optimized Manim scene rendering
+- Intelligent caching system for performance
+- Parallel scene processing
+- Quality preset management (preview/low/medium/high/production)
+- GPU acceleration support
+- Video combination and assembly
+
+**Key Methods**:
+- `render_scene_optimized()` - Enhanced scene rendering
+- `combine_videos_optimized()` - Final video assembly
+- `_get_code_hash()` - Intelligent caching
+
+### 4. **🔍 RAG Intelligence Agent** (`src/rag/rag_integration.py`, `src/rag/vector_store.py`)
+**Role**: Knowledge retrieval and context augmentation
+
+**Key Capabilities**:
+- Manim documentation retrieval
+- Plugin detection and relevance scoring
+- Vector store management with ChromaDB
+- Query generation for technical contexts
+- Enhanced document embedding and retrieval
+
+**Key Methods**:
+- `detect_relevant_plugins()` - Smart plugin identification
+- `retrieve_relevant_docs()` - Context-aware documentation retrieval
+- `generate_rag_queries()` - Intelligent query formulation
+
+### 5. **📝 Task & Prompt Generation Service** (`task_generator/`)
+**Role**: Template management and prompt engineering
+
+**Key Capabilities**:
+- Dynamic prompt template generation
+- Context-aware prompt customization
+- Banned reasoning pattern management
+- Multi-modal prompt support
+
+**Key Components**:
+- `parse_prompt.py` - Template processing
+- `prompts_raw/` - Prompt template repository
+
+### 6. **🤖 LLM Provider Agents** (`mllm_tools/`)
+**Role**: AI model abstraction and management
+
+**Key Capabilities**:
+- Multi-provider LLM support (OpenAI, Gemini, Vertex AI, OpenRouter)
+- Unified interface for different AI models
+- Cost tracking and usage monitoring
+- Langfuse integration for observability
+
+**Key Components**:
+- `litellm.py` - LiteLLM wrapper for multiple providers
+- `openrouter.py` - OpenRouter integration
+- `gemini.py` - Google Gemini integration
+- `vertex_ai.py` - Google Cloud Vertex AI
+
+### 7. **✅ Quality Evaluation Agent** (`eval_suite/`)
+**Role**: Output validation and quality assurance
+
+**Key Capabilities**:
+- Multi-modal content evaluation (text, image, video)
+- Automated quality scoring
+- Error pattern detection
+- Performance metrics collection
+
+**Key Components**:
+- `text_utils.py` - Text quality evaluation
+- `image_utils.py` - Visual content assessment
+- `video_utils.py` - Video quality metrics
+
+## 🔄 Multi-Agent Workflow
+
+### **Phase 1: Initialization & Planning**
+1. **System Orchestrator** (`generate_video.py`) receives user input
+2. **Configuration Manager** loads system settings and model configurations
+3. **Session Manager** creates/loads session for continuity
+4. **Video Planning Agent** analyzes topic and creates scene breakdown
+5. **RAG Agent** detects relevant plugins and retrieves documentation
+
+### **Phase 2: Implementation Planning**
+1. **Video Planning Agent** generates detailed implementation plans for each scene
+2. **Task Generator** provides appropriate prompt templates
+3. **RAG Agent** augments plans with relevant technical documentation
+4. **Scene Analyzer** validates plan completeness
+
+### **Phase 3: Code Generation**
+1. **Code Generation Agent** transforms scene plans into Manim code
+2. **RAG Agent** provides contextual documentation for complex animations
+3. **Error Detection** validates code syntax and logic
+4. **Quality Assurance** ensures code meets standards
+
+### **Phase 4: Rendering & Assembly**
+1. **Video Rendering Agent** executes Manim code to generate scenes
+2. **Caching System** optimizes performance through intelligent storage
+3. **Parallel Processing** renders multiple scenes concurrently
+4. **Quality Control** validates rendered output
+
+### **Phase 5: Final Assembly**
+1. **Video Rendering Agent** combines individual scenes
+2. **Audio Integration** adds voiceovers and sound effects
+3. **Quality Evaluation Agent** performs final validation
+4. **Output Manager** delivers final video with metadata
+
+## 🏛️ Design Principles
+
+### **SOLID Principles Implementation**
+
+1. **Single Responsibility Principle**
+   - Each agent has a focused, well-defined purpose
+   - Clear separation of concerns across components
+
+2. **Open/Closed Principle**
+   - System extensible through composition and interfaces
+   - New agents can be added without modifying existing code
+
+3. **Liskov Substitution Principle**
+   - Agents implement common interfaces for interchangeability
+   - Protocol-based design ensures compatibility
+
+4. **Interface Segregation Principle**
+   - Clean, focused interfaces for agent communication
+   - No forced dependencies on unused functionality
+
+5. **Dependency Inversion Principle**
+   - High-level modules depend on abstractions
+   - Factory pattern for component creation
+
+### **Multi-Agent Coordination Patterns**
+
+1. **Pipeline Architecture**: Sequential processing with clear handoffs
+2. **Publish-Subscribe**: Event-driven communication between agents
+3. **Factory Pattern**: Dynamic agent creation and configuration
+4. **Strategy Pattern**: Pluggable algorithms for different tasks
+5. **Observer Pattern**: Monitoring and logging across agents
+
+## ⚡ Performance Optimizations
+
+### **Concurrency & Parallelization**
+- **Async/Await**: Non-blocking agent coordination
+- **Semaphore Control**: Intelligent resource management
+- **Thread Pools**: Parallel I/O operations
+- **Concurrent Scene Processing**: Multiple scenes rendered simultaneously
+
+### **Intelligent Caching**
+- **Code Hash-based Caching**: Avoid redundant renders
+- **Context Caching**: Reuse prompt templates and examples
+- **Vector Store Caching**: Optimized document retrieval
+
+### **Resource Management**
+- **GPU Acceleration**: Hardware-accelerated rendering
+- **Memory Optimization**: Efficient data structures
+- **Quality Presets**: Speed vs. quality tradeoffs
+
+## 🔧 Configuration Management
+
+### **Environment Configuration** (`.env`, `src/config/config.py`)
+```python
+class VideoGenerationConfig:
+    planner_model: str                    # Primary AI model
+    scene_model: Optional[str] = None     # Scene-specific model
+    helper_model: Optional[str] = None    # Helper tasks model
+    max_scene_concurrency: int = 5        # Parallel scene limit
+    use_rag: bool = False                 # RAG integration
+    enable_caching: bool = True           # Performance caching
+    use_gpu_acceleration: bool = False    # Hardware acceleration
+```
+
+### **Model Provider Configuration**
+- Support for multiple LLM providers (OpenAI, Gemini, Claude, etc.)
+- Unified interface through LiteLLM
+- Cost tracking and usage monitoring
+- Automatic failover capabilities
+
+## 📊 Data Flow Architecture
+
+### **Input Data Sources**
+- **Theorem Datasets**: JSON files with mathematical concepts (`data/thb_*/`)
+- **Context Learning**: Historical examples (`data/context_learning/`)
+- **RAG Documentation**: Manim docs and plugins (`data/rag/manim_docs/`)
+
+### **Processing Pipeline**
+```
+User Input → Topic Analysis → Scene Planning → Code Generation → Rendering → Quality Check → Final Output
+     ↓              ↓              ↓              ↓              ↓              ↓
+Configuration → RAG Context → Implementation → Error Fixing → Optimization → Validation
+```
+
+### **Output Artifacts**
+- **Scene Outlines**: Structured video plans
+- **Implementation Plans**: Technical specifications
+- **Manim Code**: Executable animation scripts
+- **Rendered Videos**: Individual scene outputs
+- **Combined Videos**: Final assembled content
+- **Metadata**: Processing logs and metrics
+
+## 🎪 Advanced Features
+
+### **Error Recovery & Self-Healing**
+- **Multi-layer Retry Logic**: Automatic error recovery at each agent level
+- **Intelligent Error Analysis**: Pattern recognition for common failures
+- **Self-Reflection**: Code quality validation through visual analysis
+- **Fallback Strategies**: Alternative approaches when primary methods fail
+
+### **Monitoring & Observability**
+- **Langfuse Integration**: Comprehensive LLM call tracking
+- **Performance Metrics**: Render times, success rates, resource usage
+- **Status Dashboard**: Real-time pipeline state visualization
+- **Cost Tracking**: Token usage and API cost monitoring
+
+### **Scalability Features**
+- **Horizontal Scaling**: Multiple concurrent topic processing
+- **Resource Pooling**: Shared computational resources
+- **Load Balancing**: Intelligent task distribution
+- **State Persistence**: Resume interrupted processing
+
+## 🚀 Usage Examples
+
+### **Single Topic Generation**
+```bash
+python generate_video.py \
+    --topic "Pythagorean Theorem" \
+    --context "Explain the mathematical proof and visual demonstration" \
+    --model "gemini/gemini-2.5-flash-preview-04-17" \
+    --use_rag \
+    --quality medium
+```
+
+### **Batch Processing**
+```bash
+python generate_video.py \
+    --theorems_path data/thb_easy/math.json \
+    --sample_size 5 \
+    --max_scene_concurrency 3 \
+    --use_context_learning \
+    --enable_caching
+```
+
+### **Status Monitoring**
+```bash
+python generate_video.py \
+    --theorems_path data/thb_easy/math.json \
+    --check_status
+```
+
+## 📈 System Metrics & KPIs
+
+### **Performance Indicators**
+- **Scene Generation Speed**: Average time per scene
+- **Rendering Efficiency**: Cache hit rates and parallel utilization
+- **Quality Scores**: Automated evaluation metrics
+- **Success Rates**: Completion percentage across pipeline stages
+
+### **Resource Utilization**
+- **LLM Token Usage**: Cost optimization and efficiency
+- **Computational Resources**: CPU/GPU utilization
+- **Storage Efficiency**: Cache effectiveness and data management
+- **Memory Footprint**: System resource consumption
+
+## 🔮 Future Enhancements
+
+### **Planned Agent Improvements**
+- **Advanced Visual Agent**: Enhanced image understanding and generation
+- **Audio Synthesis Agent**: Dynamic voiceover generation
+- **Interactive Agent**: Real-time user feedback integration
+- **Curriculum Agent**: Adaptive learning path generation
+
+### **Technical Roadmap**
+- **Distributed Processing**: Multi-node agent deployment
+- **Real-time Streaming**: Live video generation capabilities
+- **Mobile Integration**: Responsive design for mobile platforms
+- **API Gateway**: RESTful service architecture
+
+---
+
+## 📚 Related Documentation
+
+- **[API Reference](docs/api_reference.md)** - Detailed method documentation
+- **[Configuration Guide](docs/configuration.md)** - Setup and customization
+- **[Development Guide](docs/development.md)** - Contributing and extending
+- **[Troubleshooting](docs/troubleshooting.md)** - Common issues and solutions
+
+---
+
+**Last Updated**: August 25, 2025  
+**Version**: Multi-Agent Enhanced Pipeline v2.0  
+**Maintainer**: T2M Development Team

WORKING_SETUP.md

@@ -0,0 +1,131 @@
+# ✅ Working FastAPI + Docker + ngrok Setup
+
+## 🎯 Current Status: WORKING!
+
+Your development environment is successfully set up with:
+- ✅ Redis running in Docker
+- ✅ ngrok exposing your local server publicly  
+- ✅ FastAPI server running locally
+- ✅ Public HTTPS URL: `https://d4e9601ecb72.ngrok-free.app`
+
+## 🚀 Quick Start Commands
+
+### 1. Start Services (Redis + ngrok)
+```bash
+./start-services.sh
+```
+
+### 2. Start FastAPI Server
+```bash
+# Simple working version
+python simple_app.py
+
+# Or the full version (once config is fixed)
+python -m uvicorn src.app.main:app --reload --host 0.0.0.0 --port 8000
+```
+
+### 3. Get Your Public URL
+```bash
+curl -s http://localhost:4040/api/tunnels | jq -r '.tunnels[0].public_url'
+```
+
+## 🌐 Your URLs
+
+- **Local API**: http://localhost:8000
+- **Public API**: https://d4e9601ecb72.ngrok-free.app
+- **API Docs**: https://d4e9601ecb72.ngrok-free.app/docs (when using simple_app.py)
+- **ngrok Dashboard**: http://localhost:4040
+- **Redis**: localhost:6379
+
+## 🔧 Configure Clerk Webhook
+
+Now you can set up your Clerk webhook:
+
+1. Go to [Clerk Dashboard](https://dashboard.clerk.com/)
+2. Navigate to **Webhooks** → **Add Endpoint**
+3. Enter your webhook URL:
+   ```
+   https://d4e9601ecb72.ngrok-free.app/api/v1/auth/webhooks/clerk
+   ```
+4. Select events: `user.created`, `user.updated`, `user.deleted`, `session.created`, `session.ended`
+5. Copy the **Signing Secret** and add to your `.env`:
+   ```env
+   CLERK_WEBHOOK_SECRET=whsec_your_webhook_signing_secret_here
+   ```
+
+## 📝 Available Endpoints (Simple App)
+
+- `GET /` - Welcome message
+- `GET /health` - Health check
+- `GET /config` - Configuration info
+
+Test them:
+```bash
+curl https://d4e9601ecb72.ngrok-free.app/
+curl https://d4e9601ecb72.ngrok-free.app/health
+curl https://d4e9601ecb72.ngrok-free.app/config
+```
+
+## 🛠️ Service Management
+
+### Check Services
+```bash
+# Check Redis
+redis-cli ping
+
+# Check ngrok tunnels
+curl -s http://localhost:4040/api/tunnels
+
+# Check Docker containers
+docker ps
+```
+
+### Stop Services
+```bash
+# Stop all related containers
+docker stop $(docker ps -q --filter 'ancestor=redis:7-alpine' --filter 'ancestor=ngrok/ngrok:latest')
+```
+
+### Restart Services
+```bash
+./start-services.sh
+```
+
+## 🔍 Troubleshooting
+
+### If ngrok URL changes:
+The ngrok URL will change each time you restart ngrok (unless you have a paid plan). Get the new URL with:
+```bash
+curl -s http://localhost:4040/api/tunnels | jq -r '.tunnels[0].public_url'
+```
+
+### If Redis connection fails:
+```bash
+# Check if Redis is running
+docker ps | grep redis
+
+# Restart Redis if needed
+docker restart $(docker ps -q --filter 'ancestor=redis:7-alpine')
+```
+
+### If FastAPI config fails:
+Use the simple app for now:
+```bash
+python simple_app.py
+```
+
+## 🎉 Next Steps
+
+1. **Test your webhook**: Use the public URL to set up Clerk webhooks
+2. **Fix the main FastAPI app**: The config parsing issue needs to be resolved
+3. **Add authentication**: Implement Clerk authentication middleware
+4. **Add your business logic**: Build your video generation endpoints
+
+## 📋 Working Files
+
+- `start-services.sh` - Starts Redis and ngrok
+- `simple_app.py` - Working FastAPI application
+- `simple_config.py` - Working configuration
+- `.env` - Environment variables (configured)
+
+Your development environment is ready for webhook testing! 🚀

auth_token.txt

@@ -0,0 +1 @@
+eyJhbGciOiJSUzI1NiIsImNhdCI6ImNsX0I3ZDRQRDExMUFBQSIsImtpZCI6Imluc18zMXBCZktEanhrSFJDUUFUTDN6Q29pUmxad2YiLCJ0eXAiOiJKV1QifQ.eyJhenAiOiJodHRwczovL3BvZXRpYy1wcmltYXRlLTQ4LmFjY291bnRzLmRldiIsImV4cCI6MTc1NjI3NzQ3OCwiZnZhIjpbMTcsLTFdLCJpYXQiOjE3NTYyNzc0MTgsImlzcyI6Imh0dHBzOi8vcG9ldGljLXByaW1hdGUtNDguY2xlcmsuYWNjb3VudHMuZGV2IiwibmJmIjoxNzU2Mjc3NDA4LCJzaWQiOiJzZXNzXzMxckpnS3R1Z1BKU2VlNVFJRXp5NGpYcW1NbyIsInN0cyI6ImFjdGl2ZSIsInN1YiI6InVzZXJfMzFxbHNuWDZYZTh4TmRXYnNHTDVNU3hnQnhIIiwidiI6Mn0.XUCI_plOZmMBfZhMMHViCj4KXpMWobjQp-AJf7VgdeALSi6lPKdzKA6vDLyjFngnY-XrFCDP4UI7iNNqRw32_Mvr9ipxqzWKAtL6P_KP3HonOEGfrsMibFUZdUF2cv9N3aJ-sL64QteIV0-NAdlprjM_vbYiW8dlJPuNlpOoFF9fWGPr8s3uVwEK6BPSrzbBSkcIHSbAGiBpzRaFdaupOZBgC-WAxj-_cPQIA0AKr_9nrG-UFozjdfbi74AGM0MWSP7GLe_pDQ-t1FKAFXMNtS0ZB5ylwnZpnAnxPBMG4UPQzHXjo5xeibtRb0-4JSUu-_kCmvTxWuvcHqsjqFwXpg

docker-compose.simple.yml

@@ -0,0 +1,34 @@
+version: '3.8'
+
+services:
+  # Redis service for caching and job queuing
+  redis:
+    image: redis:7-alpine
+    container_name: t2m-redis
+    ports:
+      - "6379:6379"
+    volumes:
+      - redis_data:/data
+    command: redis-server --appendonly yes
+    healthcheck:
+      test: ["CMD", "redis-cli", "ping"]
+      interval: 10s
+      timeout: 3s
+      retries: 3
+    restart: unless-stopped
+
+  # ngrok service - simple HTTP tunnel
+  ngrok:
+    image: ngrok/ngrok:latest
+    container_name: t2m-ngrok
+    restart: unless-stopped
+    command: ["http", "host.docker.internal:8000"]
+    ports:
+      - "4040:4040"
+    environment:
+      - NGROK_AUTHTOKEN=${NGROK_AUTHTOKEN}
+    extra_hosts:
+      - "host.docker.internal:host-gateway"
+
+volumes:
+  redis_data:

docker-compose.test.yml

@@ -0,0 +1,68 @@
+version: '3.8'
+
+services:
+  theoremexplain:
+    build:
+      context: .
+      dockerfile: dockerfile
+    container_name: theoremexplain-agent
+    ports:
+      - "7860:7860"
+    volumes:
+      # Mount output directory to persist generated videos
+      - ./output:/app/output
+      # Mount models directory if you want to use local models
+      - ./models:/app/models
+      # Mount data directory for RAG and datasets
+      - ./data:/app/data
+    environment:
+      # Copy environment variables from host .env file
+      - OPENAI_API_KEY=${OPENAI_API_KEY}
+      - GEMINI_API_KEY=${GEMINI_API_KEY}
+      # Kokoro TTS settings
+      - KOKORO_MODEL_PATH=models/kokoro-v0_19.onnx
+      - KOKORO_VOICES_PATH=models/voices.bin
+      - KOKORO_DEFAULT_VOICE=af
+      - KOKORO_DEFAULT_SPEED=1.0
+      - KOKORO_DEFAULT_LANG=en-us
+      # Python path
+      - PYTHONPATH=/app:$PYTHONPATH
+    restart: unless-stopped
+    healthcheck:
+      test: ["uv", "run" , "manim" ,"checkhealth"]
+      interval: 30s
+      timeout: 10s
+      retries: 3
+      start_period: 60s
+
+  # Optional: Add a service for running batch generation
+  theoremexplain-batch:
+    build:
+      context: .
+      dockerfile: dockerfile
+    container_name: theoremexplain-batch
+    profiles:
+      - batch
+    volumes:
+      - ./output:/app/output
+      - ./models:/app/models
+      - ./data:/app/data
+    environment:
+      # Same environment variables as main service
+      - OPENAI_API_KEY=${OPENAI_API_KEY}
+      - GEMINI_API_KEY=${GEMINI_API_KEY}
+      - KOKORO_MODEL_PATH=models/kokoro-v0_19.onnx
+      - KOKORO_VOICES_PATH=models/voices.bin
+      - KOKORO_DEFAULT_VOICE=af
+      - KOKORO_DEFAULT_SPEED=1.0
+      - KOKORO_DEFAULT_LANG=en-us
+      - PYTHONPATH=/app:$PYTHONPATH
+    command: >
+      uv run python generate_video.py
+      --model "openai/gpt-4o-mini"
+      --helper_model "openai/gpt-4o-mini"
+      --output_dir "output/batch_generation"
+      --theorems_path "data/thb_easy/math.json"
+      --max_scene_concurrency 3
+      --max_topic_concurrency 5
+    restart: no

docker-compose.yml

@@ -1,80 +0,0 @@
-version: '3.8'
-
-services:
-  theoremexplain:
-    build:
-      context: .
-      dockerfile: dockerfile
-    container_name: theoremexplain-agent
-    ports:
-      - "7860:7860"
-    volumes:
-      # Mount output directory to persist generated videos
-      - ./output:/app/output
-      # Mount models directory if you want to use local models
-      - ./models:/app/models
-      # Mount data directory for RAG and datasets
-      - ./data:/app/data
-    environment:
-      # Copy environment variables from host .env file
-      - OPENAI_API_KEY=${OPENAI_API_KEY}
-      - AZURE_API_KEY=${AZURE_API_KEY}
-      - AZURE_API_BASE=${AZURE_API_BASE}
-      - AZURE_API_VERSION=${AZURE_API_VERSION}
-      - VERTEXAI_PROJECT=${VERTEXAI_PROJECT}
-      - VERTEXAI_LOCATION=${VERTEXAI_LOCATION}
-      - GOOGLE_APPLICATION_CREDENTIALS=${GOOGLE_APPLICATION_CREDENTIALS}
-      - GEMINI_API_KEY=${GEMINI_API_KEY}
-      # Kokoro TTS settings
-      - KOKORO_MODEL_PATH=models/kokoro-v0_19.onnx
-      - KOKORO_VOICES_PATH=models/voices.bin
-      - KOKORO_DEFAULT_VOICE=af
-      - KOKORO_DEFAULT_SPEED=1.0
-      - KOKORO_DEFAULT_LANG=en-us
-      # Python path
-      - PYTHONPATH=/app:$PYTHONPATH
-    restart: unless-stopped
-    healthcheck:
-      test: ["CMD", "conda", "run", "-n", "tea", "python", "-c", "import src; import manim; print('Health check passed')"]
-      interval: 30s
-      timeout: 10s
-      retries: 3
-      start_period: 60s
-
-  # Optional: Add a service for running batch generation
-  theoremexplain-batch:
-    build:
-      context: .
-      dockerfile: dockerfile
-    container_name: theoremexplain-batch
-    profiles:
-      - batch
-    volumes:
-      - ./output:/app/output
-      - ./models:/app/models
-      - ./data:/app/data
-    environment:
-      # Same environment variables as main service
-      - OPENAI_API_KEY=${OPENAI_API_KEY}
-      - AZURE_API_KEY=${AZURE_API_KEY}
-      - AZURE_API_BASE=${AZURE_API_BASE}
-      - AZURE_API_VERSION=${AZURE_API_VERSION}
-      - VERTEXAI_PROJECT=${VERTEXAI_PROJECT}
-      - VERTEXAI_LOCATION=${VERTEXAI_LOCATION}
-      - GOOGLE_APPLICATION_CREDENTIALS=${GOOGLE_APPLICATION_CREDENTIALS}
-      - GEMINI_API_KEY=${GEMINI_API_KEY}
-      - KOKORO_MODEL_PATH=models/kokoro-v0_19.onnx
-      - KOKORO_VOICES_PATH=models/voices.bin
-      - KOKORO_DEFAULT_VOICE=af
-      - KOKORO_DEFAULT_SPEED=1.0
-      - KOKORO_DEFAULT_LANG=en-us
-      - PYTHONPATH=/app:$PYTHONPATH
-    command: >
-      conda run --no-capture-output -n tea python generate_video.py
-      --model "openai/gpt-4o-mini"
-      --helper_model "openai/gpt-4o-mini"
-      --output_dir "output/batch_generation"
-      --theorems_path "data/thb_easy/math.json"
-      --max_scene_concurrency 3
-      --max_topic_concurrency 5
-    restart: no

docs/client-generation.md

@@ -0,0 +1,525 @@
+# Client SDK Generation Guide
+
+This guide explains how to generate and use client SDKs for the Video Generation API.
+
+## Overview
+
+The Video Generation API supports automatic client SDK generation in multiple programming languages using OpenAPI Generator. This allows developers to quickly integrate with the API using idiomatic code in their preferred language.
+
+## Supported Languages
+
+- **TypeScript/JavaScript** - Modern TypeScript client with fetch API
+- **Python** - Python client with requests library
+- **Java** - Java client with OkHttp and Gson
+- **C#** - .NET Standard 2.0 compatible client
+- **Go** - Go client with native HTTP library
+- **PHP** - PHP client with Guzzle HTTP
+- **Ruby** - Ruby client with Faraday HTTP
+
+## Prerequisites
+
+### Required Tools
+
+1. **Node.js and npm** - For OpenAPI Generator CLI
+2. **OpenAPI Generator CLI** - For generating clients
+3. **Language-specific tools** (optional, for testing):
+   - TypeScript: Node.js, npm
+   - Python: Python 3.7+, pip
+   - Java: JDK 8+, Maven
+   - C#: .NET Core SDK
+   - Go: Go 1.16+
+   - PHP: PHP 7.4+, Composer
+   - Ruby: Ruby 2.7+, Bundler
+
+### Installation
+
+Install OpenAPI Generator CLI:
+
+```bash
+npm install -g @openapitools/openapi-generator-cli
+```
+
+## Quick Start
+
+### Using the Python Script
+
+The easiest way to generate clients is using the provided Python script:
+
+```bash
+# Generate all supported clients
+python scripts/generate_clients.py
+
+# Generate specific languages
+python scripts/generate_clients.py --languages typescript python
+
+# Use custom API URL
+python scripts/generate_clients.py --api-url https://api.example.com
+
+# Custom output directory
+python scripts/generate_clients.py --output-dir my_clients
+```
+
+### Using the Shell Script
+
+Alternatively, use the shell script:
+
+```bash
+# Generate all clients
+./scripts/generate_clients.sh
+
+# Generate specific languages
+./scripts/generate_clients.sh typescript python java
+
+# Use custom API URL
+./scripts/generate_clients.sh --api-url https://api.example.com typescript
+```
+
+### Manual Generation
+
+For manual control, use OpenAPI Generator CLI directly:
+
+```bash
+# Fetch OpenAPI specification
+curl -o openapi.json http://localhost:8000/openapi.json
+
+# Generate TypeScript client
+openapi-generator-cli generate \
+  -i openapi.json \
+  -g typescript-fetch \
+  -o clients/typescript \
+  --package-name video-api-client
+
+# Generate Python client
+openapi-generator-cli generate \
+  -i openapi.json \
+  -g python \
+  -o clients/python \
+  --package-name video_api_client
+```
+
+## Generated Client Structure
+
+Each generated client includes:
+
+```
+clients/
+├── typescript/
+│   ├── src/
+│   │   ├── apis/
+│   │   ├── models/
+│   │   └── index.ts
+│   ├── package.json
+│   ├── README.md
+│   └── example.ts
+├── python/
+│   ├── video_api_client/
+│   │   ├── api/
+│   │   ├── models/
+│   │   └── __init__.py
+│   ├── setup.py
+│   ├── README.md
+│   └── example.py
+└── ...
+```
+
+## Usage Examples
+
+### TypeScript
+
+```typescript
+import { Configuration, VideosApi } from 'video-api-client';
+
+const config = new Configuration({
+  basePath: 'https://api.example.com',
+  accessToken: 'your-clerk-session-token'
+});
+
+const videosApi = new VideosApi(config);
+
+async function generateVideo() {
+  try {
+    const jobResponse = await videosApi.createVideoGenerationJob({
+      configuration: {
+        topic: "Pythagorean Theorem",
+        context: "Explain the mathematical proof",
+        quality: "medium",
+        use_rag: true
+      }
+    });
+    
+    console.log('Job created:', jobResponse.job_id);
+    
+    // Poll for completion
+    let status = 'queued';
+    while (status !== 'completed' && status !== 'failed') {
+      await new Promise(resolve => setTimeout(resolve, 5000));
+      
+      const statusResponse = await videosApi.getVideoJobStatus(jobResponse.job_id);
+      status = statusResponse.status;
+      
+      console.log(`Status: ${status} (${statusResponse.progress.percentage}%)`);
+    }
+    
+    if (status === 'completed') {
+      const videoBlob = await videosApi.downloadVideoFile(jobResponse.job_id);
+      console.log('Video downloaded');
+    }
+    
+  } catch (error) {
+    console.error('Error:', error);
+  }
+}
+```
+
+### Python
+
+```python
+import time
+from video_api_client import Configuration, ApiClient, VideosApi
+from video_api_client.models import JobCreateRequest, JobConfiguration
+
+configuration = Configuration(
+    host="https://api.example.com",
+    access_token="your-clerk-session-token"
+)
+
+with ApiClient(configuration) as api_client:
+    videos_api = VideosApi(api_client)
+    
+    try:
+        # Create job
+        job_request = JobCreateRequest(
+            configuration=JobConfiguration(
+                topic="Pythagorean Theorem",
+                context="Explain the mathematical proof",
+                quality="medium",
+                use_rag=True
+            )
+        )
+        
+        job_response = videos_api.create_video_generation_job(job_request)
+        print(f"Job created: {job_response.job_id}")
+        
+        # Poll for completion
+        status = "queued"
+        while status not in ["completed", "failed"]:
+            time.sleep(5)
+            
+            status_response = videos_api.get_video_job_status(job_response.job_id)
+            status = status_response.status
+            
+            print(f"Status: {status} ({status_response.progress.percentage}%)")
+        
+        if status == "completed":
+            video_data = videos_api.download_video_file(job_response.job_id)
+            with open("video.mp4", "wb") as f:
+                f.write(video_data)
+            print("Video downloaded")
+            
+    except Exception as e:
+        print(f"Error: {e}")
+```
+
+### Java
+
+```java
+import com.example.videoapiclient.ApiClient;
+import com.example.videoapiclient.Configuration;
+import com.example.videoapiclient.api.VideosApi;
+import com.example.videoapiclient.model.*;
+
+public class VideoApiExample {
+    public static void main(String[] args) {
+        ApiClient client = Configuration.getDefaultApiClient();
+        client.setBasePath("https://api.example.com");
+        client.setAccessToken("your-clerk-session-token");
+        
+        VideosApi videosApi = new VideosApi(client);
+        
+        try {
+            JobConfiguration config = new JobConfiguration()
+                .topic("Pythagorean Theorem")
+                .context("Explain the mathematical proof")
+                .quality(VideoQuality.MEDIUM)
+                .useRag(true);
+            
+            JobCreateRequest request = new JobCreateRequest().configuration(config);
+            JobResponse jobResponse = videosApi.createVideoGenerationJob(request);
+            
+            System.out.println("Job created: " + jobResponse.getJobId());
+            
+            // Poll for completion
+            String status = "queued";
+            while (!"completed".equals(status) && !"failed".equals(status)) {
+                Thread.sleep(5000);
+                
+                JobStatusResponse statusResponse = videosApi.getVideoJobStatus(jobResponse.getJobId());
+                status = statusResponse.getStatus().getValue();
+                
+                System.out.println("Status: " + status + " (" + 
+                    statusResponse.getProgress().getPercentage() + "%)");
+            }
+            
+            if ("completed".equals(status)) {
+                System.out.println("Video generation completed!");
+            }
+            
+        } catch (Exception e) {
+            System.err.println("Error: " + e.getMessage());
+        }
+    }
+}
+```
+
+## Authentication
+
+All clients support Clerk authentication. Set your session token when configuring the client:
+
+### TypeScript
+```typescript
+const config = new Configuration({
+  accessToken: 'your-clerk-session-token'
+});
+```
+
+### Python
+```python
+configuration.access_token = 'your-clerk-session-token'
+```
+
+### Java
+```java
+client.setAccessToken("your-clerk-session-token");
+```
+
+## Error Handling
+
+All clients provide structured error handling:
+
+### TypeScript
+```typescript
+try {
+  const response = await api.createVideoGenerationJob(request);
+} catch (error) {
+  if (error.status === 422) {
+    console.error('Validation error:', error.body);
+  } else if (error.status === 429) {
+    console.error('Rate limit exceeded');
+  } else {
+    console.error('API error:', error);
+  }
+}
+```
+
+### Python
+```python
+from video_api_client.exceptions import ApiException
+
+try:
+    response = api.create_video_generation_job(request)
+except ApiException as e:
+    if e.status == 422:
+        print(f"Validation error: {e.body}")
+    elif e.status == 429:
+        print("Rate limit exceeded")
+    else:
+        print(f"API error: {e}")
+```
+
+## Testing Generated Clients
+
+Use the provided testing script to validate generated clients:
+
+```bash
+# Test all generated clients
+python scripts/test_clients.py
+
+# Test with custom API URL
+python scripts/test_clients.py --api-url https://api.example.com
+
+# Save test results
+python scripts/test_clients.py --output-file test_results.json
+
+# Verbose output
+python scripts/test_clients.py --verbose
+```
+
+The test script validates:
+- Client structure and files
+- Build/compilation success
+- Import/usage capability
+- API connectivity
+- Basic functionality
+
+## Customization
+
+### Custom Templates
+
+Create custom templates in the `templates/` directory:
+
+```
+templates/
+├── typescript/
+│   ├── api.mustache
+│   ├── model.mustache
+│   └── README.mustache
+├── python/
+│   ├── api.mustache
+│   └── model.mustache
+└── ...
+```
+
+### Configuration File
+
+Modify `openapi-generator-config.yaml` to customize generation:
+
+```yaml
+typescript:
+  generatorName: typescript-fetch
+  additionalProperties:
+    npmName: my-custom-client
+    supportsES6: true
+    withInterfaces: true
+```
+
+### Custom Properties
+
+Pass additional properties during generation:
+
+```bash
+openapi-generator-cli generate \
+  -i openapi.json \
+  -g typescript-fetch \
+  -o clients/typescript \
+  --additional-properties=npmName=my-client,supportsES6=true
+```
+
+## Publishing Clients
+
+### NPM (TypeScript/JavaScript)
+
+```bash
+cd clients/typescript
+npm publish
+```
+
+### PyPI (Python)
+
+```bash
+cd clients/python
+python setup.py sdist bdist_wheel
+twine upload dist/*
+```
+
+### Maven Central (Java)
+
+```bash
+cd clients/java
+mvn deploy
+```
+
+### NuGet (C#)
+
+```bash
+cd clients/csharp
+dotnet pack
+dotnet nuget push *.nupkg
+```
+
+## Troubleshooting
+
+### Common Issues
+
+1. **OpenAPI Generator not found**
+   ```bash
+   npm install -g @openapitools/openapi-generator-cli
+   ```
+
+2. **API server not running**
+   ```bash
+   # Start the API server first
+   python -m uvicorn src.app.main:app --reload
+   ```
+
+3. **Build failures**
+   - Check language-specific requirements
+   - Verify generated code syntax
+   - Review error messages in build logs
+
+4. **Import errors**
+   - Ensure proper installation
+   - Check Python path and virtual environments
+   - Verify package structure
+
+### Debug Mode
+
+Enable debug output for troubleshooting:
+
+```bash
+# Python script
+python scripts/generate_clients.py --verbose
+
+# OpenAPI Generator
+openapi-generator-cli generate \
+  --verbose \
+  --debug-operations \
+  -i openapi.json \
+  -g typescript-fetch \
+  -o clients/typescript
+```
+
+### Validation
+
+Validate OpenAPI specification before generation:
+
+```bash
+# Using OpenAPI Generator
+openapi-generator-cli validate -i openapi.json
+
+# Using Swagger Editor online
+# Visit: https://editor.swagger.io/
+```
+
+## Best Practices
+
+1. **Version Management**
+   - Tag client versions with API versions
+   - Maintain backward compatibility
+   - Document breaking changes
+
+2. **Testing**
+   - Test clients against real API
+   - Include integration tests
+   - Validate error handling
+
+3. **Documentation**
+   - Include usage examples
+   - Document authentication setup
+   - Provide troubleshooting guides
+
+4. **Distribution**
+   - Use semantic versioning
+   - Publish to appropriate package managers
+   - Maintain changelogs
+
+## Support
+
+For issues with client generation:
+
+- Check the [OpenAPI Generator documentation](https://openapi-generator.tech/)
+- Review API documentation at `/docs`
+- Contact support at [email protected]
+- File issues on GitHub
+
+## Contributing
+
+To contribute to client generation:
+
+1. Fork the repository
+2. Create custom templates or improve scripts
+3. Test with multiple languages
+4. Submit pull request with documentation
+
+## License
+
+Generated clients inherit the same license as the API project (MIT License).

extract_token.html

@@ -0,0 +1,279 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>Clerk Token Extractor</title>
+    <style>
+        body {
+            font-family: Arial, sans-serif;
+            max-width: 800px;
+            margin: 0 auto;
+            padding: 20px;
+            background-color: #f5f5f5;
+        }
+        .container {
+            background: white;
+            padding: 30px;
+            border-radius: 10px;
+            box-shadow: 0 2px 10px rgba(0,0,0,0.1);
+        }
+        h1 {
+            color: #333;
+            text-align: center;
+        }
+        .step {
+            margin: 20px 0;
+            padding: 15px;
+            background: #f8f9fa;
+            border-left: 4px solid #007bff;
+            border-radius: 5px;
+        }
+        .step h3 {
+            margin-top: 0;
+            color: #007bff;
+        }
+        button {
+            background: #007bff;
+            color: white;
+            border: none;
+            padding: 10px 20px;
+            border-radius: 5px;
+            cursor: pointer;
+            font-size: 16px;
+            margin: 10px 5px;
+        }
+        button:hover {
+            background: #0056b3;
+        }
+        .token-display {
+            background: #e9ecef;
+            padding: 15px;
+            border-radius: 5px;
+            font-family: monospace;
+            word-break: break-all;
+            margin: 10px 0;
+            min-height: 50px;
+        }
+        .success {
+            color: #28a745;
+            font-weight: bold;
+        }
+        .error {
+            color: #dc3545;
+            font-weight: bold;
+        }
+        .info {
+            background: #d1ecf1;
+            border: 1px solid #bee5eb;
+            color: #0c5460;
+            padding: 10px;
+            border-radius: 5px;
+            margin: 10px 0;
+        }
+    </style>
+</head>
+<body>
+    <div class="container">
+        <h1>🎫 Clerk Token Extractor</h1>
+        <p>This tool helps you extract your Clerk authentication token for API testing.</p>
+        
+        <div class="info">
+            <strong>Prerequisites:</strong> You must be signed in to your application in this browser session.
+        </div>
+
+        <div class="step">
+            <h3>Step 1: Check if Clerk is Available</h3>
+            <button onclick="checkClerk()">Check Clerk Status</button>
+            <div id="clerkStatus"></div>
+        </div>
+
+        <div class="step">
+            <h3>Step 2: Extract Token</h3>
+            <button onclick="extractToken()">Get Current Token</button>
+            <button onclick="extractTokenAsync()">Get Fresh Token</button>
+            <div id="tokenResult"></div>
+            <div id="tokenDisplay" class="token-display"></div>
+        </div>
+
+        <div class="step">
+            <h3>Step 3: Copy Token</h3>
+            <button onclick="copyToken()" id="copyBtn" disabled>Copy Token to Clipboard</button>
+            <button onclick="downloadToken()" id="downloadBtn" disabled>Download as File</button>
+            <div id="copyResult"></div>
+        </div>
+
+        <div class="step">
+            <h3>Step 4: Test Your Token</h3>
+            <p>Use your token with the test scripts:</p>
+            <code>python test_video_simple.py https://your-api-url.com/api/v1 YOUR_TOKEN_HERE</code>
+        </div>
+
+        <div class="step">
+            <h3>Alternative Methods</h3>
+            <details>
+                <summary>Manual Browser Console Method</summary>
+                <ol>
+                    <li>Open Developer Tools (F12)</li>
+                    <li>Go to Console tab</li>
+                    <li>Run: <code>window.Clerk.session.getToken().then(token => console.log(token))</code></li>
+                    <li>Copy the token from console output</li>
+                </ol>
+            </details>
+            
+            <details>
+                <summary>Browser Storage Method</summary>
+                <ol>
+                    <li>Open Developer Tools (F12)</li>
+                    <li>Go to Application/Storage tab</li>
+                    <li>Look in Local Storage for keys starting with '__clerk_'</li>
+                    <li>Find the session data and extract the JWT token</li>
+                </ol>
+            </details>
+        </div>
+    </div>
+
+    <script>
+        let currentToken = null;
+
+        function checkClerk() {
+            const statusDiv = document.getElementById('clerkStatus');
+            
+            if (typeof window.Clerk === 'undefined') {
+                statusDiv.innerHTML = '<span class="error">❌ Clerk not found. Make sure you\'re on a page with Clerk loaded.</span>';
+                return false;
+            }
+
+            if (!window.Clerk.session) {
+                statusDiv.innerHTML = '<span class="error">❌ No active Clerk session. Please sign in first.</span>';
+                return false;
+            }
+
+            statusDiv.innerHTML = '<span class="success">✅ Clerk is available and you have an active session!</span>';
+            return true;
+        }
+
+        function extractToken() {
+            if (!checkClerk()) return;
+
+            const resultDiv = document.getElementById('tokenResult');
+            const tokenDiv = document.getElementById('tokenDisplay');
+
+            try {
+                // Try to get token synchronously first
+                const session = window.Clerk.session;
+                if (session && session.getToken) {
+                    // This might be async, so we'll handle both cases
+                    const tokenResult = session.getToken();
+                    
+                    if (tokenResult && typeof tokenResult.then === 'function') {
+                        // It's a promise
+                        resultDiv.innerHTML = '<span class="info">Getting token asynchronously...</span>';
+                        tokenResult.then(token => {
+                            if (token) {
+                                currentToken = token;
+                                tokenDiv.textContent = token;
+                                resultDiv.innerHTML = '<span class="success">✅ Token extracted successfully!</span>';
+                                enableButtons();
+                            } else {
+                                resultDiv.innerHTML = '<span class="error">❌ Token is null or empty</span>';
+                            }
+                        }).catch(error => {
+                            resultDiv.innerHTML = `<span class="error">❌ Error getting token: ${error.message}</span>`;
+                        });
+                    } else if (tokenResult) {
+                        // It's synchronous
+                        currentToken = tokenResult;
+                        tokenDiv.textContent = tokenResult;
+                        resultDiv.innerHTML = '<span class="success">✅ Token extracted successfully!</span>';
+                        enableButtons();
+                    } else {
+                        resultDiv.innerHTML = '<span class="error">❌ Could not get token</span>';
+                    }
+                } else {
+                    resultDiv.innerHTML = '<span class="error">❌ Session.getToken method not available</span>';
+                }
+            } catch (error) {
+                resultDiv.innerHTML = `<span class="error">❌ Error: ${error.message}</span>`;
+            }
+        }
+
+        function extractTokenAsync() {
+            if (!checkClerk()) return;
+
+            const resultDiv = document.getElementById('tokenResult');
+            const tokenDiv = document.getElementById('tokenDisplay');
+
+            try {
+                resultDiv.innerHTML = '<span class="info">Getting fresh token...</span>';
+                
+                window.Clerk.session.getToken()
+                    .then(token => {
+                        if (token) {
+                            currentToken = token;
+                            tokenDiv.textContent = token;
+                            resultDiv.innerHTML = '<span class="success">✅ Fresh token extracted successfully!</span>';
+                            enableButtons();
+                        } else {
+                            resultDiv.innerHTML = '<span class="error">❌ Token is null or empty</span>';
+                        }
+                    })
+                    .catch(error => {
+                        resultDiv.innerHTML = `<span class="error">❌ Error getting token: ${error.message}</span>`;
+                    });
+            } catch (error) {
+                resultDiv.innerHTML = `<span class="error">❌ Error: ${error.message}</span>`;
+            }
+        }
+
+        function enableButtons() {
+            document.getElementById('copyBtn').disabled = false;
+            document.getElementById('downloadBtn').disabled = false;
+        }
+
+        function copyToken() {
+            if (!currentToken) {
+                document.getElementById('copyResult').innerHTML = '<span class="error">❌ No token to copy</span>';
+                return;
+            }
+
+            navigator.clipboard.writeText(currentToken).then(() => {
+                document.getElementById('copyResult').innerHTML = '<span class="success">✅ Token copied to clipboard!</span>';
+            }).catch(err => {
+                // Fallback for older browsers
+                const textArea = document.createElement('textarea');
+                textArea.value = currentToken;
+                document.body.appendChild(textArea);
+                textArea.select();
+                document.execCommand('copy');
+                document.body.removeChild(textArea);
+                document.getElementById('copyResult').innerHTML = '<span class="success">✅ Token copied to clipboard!</span>';
+            });
+        }
+
+        function downloadToken() {
+            if (!currentToken) {
+                document.getElementById('copyResult').innerHTML = '<span class="error">❌ No token to download</span>';
+                return;
+            }
+
+            const blob = new Blob([currentToken], { type: 'text/plain' });
+            const url = window.URL.createObjectURL(blob);
+            const a = document.createElement('a');
+            a.href = url;
+            a.download = 'clerk_token.txt';
+            document.body.appendChild(a);
+            a.click();
+            document.body.removeChild(a);
+            window.URL.revokeObjectURL(url);
+            
+            document.getElementById('copyResult').innerHTML = '<span class="success">✅ Token downloaded as file!</span>';
+        }
+
+        // Auto-check Clerk status on page load
+        window.addEventListener('load', () => {
+            setTimeout(checkClerk, 1000);
+        });
+    </script>
+</body>
+</html>

fastapi-backend-pyproject.toml

@@ -0,0 +1,179 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "fastapi-video-backend"
+version = "0.1.0"
+description = "FastAPI backend for multi-agent video generation system"
+readme = "README.md"
+requires-python = ">=3.11"
+license = {text = "MIT"}
+authors = [
+    {name = "Video Generation Team"},
+]
+keywords = ["fastapi", "video", "generation", "api"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+]
+
+dependencies = [
+    # FastAPI and ASGI server
+    "fastapi>=0.104.0",
+    "uvicorn[standard]>=0.24.0",
+    
+    # Pydantic for data validation
+    "pydantic>=2.5.0",
+    "pydantic-settings>=2.1.0",
+    
+    # Redis for caching and job queuing
+    "redis>=5.0.0",
+    "hiredis>=2.2.0",  # C extension for better Redis performance
+    
+    # Clerk SDK for authentication
+    "clerk-backend-api>=1.0.0",
+    
+    # HTTP client for external API calls
+    "httpx>=0.25.0",
+    
+    # JSON Web Token handling
+    "pyjwt[crypto]>=2.8.0",
+    
+    # File handling and validation
+    "python-multipart>=0.0.6",  # For file uploads
+    "python-magic>=0.4.27",     # File type detection
+    
+    # Logging and monitoring
+    "structlog>=23.2.0",
+    
+    # Environment variable management
+    "python-dotenv>=1.0.0",
+    
+    # Date and time utilities
+    "python-dateutil>=2.8.2",
+    
+    # Async utilities
+    "asyncio-mqtt>=0.16.0",  # If needed for real-time updates
+]
+
+[project.optional-dependencies]
+dev = [
+    # Testing
+    "pytest>=7.4.0",
+    "pytest-asyncio>=0.21.0",
+    "pytest-cov>=4.1.0",
+    "httpx>=0.25.0",  # For testing FastAPI endpoints
+    
+    # Code quality
+    "black>=23.0.0",
+    "isort>=5.12.0",
+    "flake8>=6.0.0",
+    "mypy>=1.7.0",
+    
+    # Development tools
+    "pre-commit>=3.5.0",
+    "watchfiles>=0.21.0",  # For auto-reload during development
+]
+
+production = [
+    # Production ASGI server
+    "gunicorn>=21.2.0",
+    
+    # Monitoring and observability
+    "prometheus-client>=0.19.0",
+    "opentelemetry-api>=1.21.0",
+    "opentelemetry-sdk>=1.21.0",
+    "opentelemetry-instrumentation-fastapi>=0.42b0",
+]
+
+[project.urls]
+Homepage = "https://github.com/your-org/fastapi-video-backend"
+Documentation = "https://your-org.github.io/fastapi-video-backend"
+Repository = "https://github.com/your-org/fastapi-video-backend.git"
+Issues = "https://github.com/your-org/fastapi-video-backend/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/app"]
+
+[tool.black]
+line-length = 88
+target-version = ['py311']
+include = '\.pyi?$'
+extend-exclude = '''
+/(
+  # directories
+  \.eggs
+  | \.git
+  | \.hg
+  | \.mypy_cache
+  | \.tox
+  | \.venv
+  | build
+  | dist
+)/
+'''
+
+[tool.isort]
+profile = "black"
+multi_line_output = 3
+line_length = 88
+known_first_party = ["app"]
+
+[tool.mypy]
+python_version = "3.11"
+warn_return_any = true
+warn_unused_configs = true
+disallow_untyped_defs = true
+disallow_incomplete_defs = true
+check_untyped_defs = true
+disallow_untyped_decorators = true
+no_implicit_optional = true
+warn_redundant_casts = true
+warn_unused_ignores = true
+warn_no_return = true
+warn_unreachable = true
+strict_equality = true
+
+[[tool.mypy.overrides]]
+module = [
+    "redis.*",
+    "clerk_backend_api.*",
+    "structlog.*",
+]
+ignore_missing_imports = true
+
+[tool.pytest.ini_options]
+minversion = "7.0"
+addopts = "-ra -q --strict-markers --strict-config"
+testpaths = ["tests"]
+python_files = ["test_*.py", "*_test.py"]
+python_classes = ["Test*"]
+python_functions = ["test_*"]
+asyncio_mode = "auto"
+
+[tool.coverage.run]
+source = ["src"]
+omit = [
+    "*/tests/*",
+    "*/test_*",
+    "*/__pycache__/*",
+]
+
+[tool.coverage.report]
+exclude_lines = [
+    "pragma: no cover",
+    "def __repr__",
+    "if self.debug:",
+    "if settings.DEBUG",
+    "raise AssertionError",
+    "raise NotImplementedError",
+    "if 0:",
+    "if __name__ == .__main__.:",
+    "class .*\\bProtocol\\):",
+    "@(abc\\.)?abstractmethod",
+]

main.py

@@ -0,0 +1,6 @@
+def main():
+    print("Hello from t2m!")
+
+
+if __name__ == "__main__":
+    main()

ngrok-dev.yml

@@ -0,0 +1,12 @@
+version: "2"
+authtoken: ${NGROK_AUTHTOKEN}
+
+tunnels:
+  fastapi-dev:
+    addr: host.docker.internal:8000  # Points to localhost:8000 on host
+    proto: http
+    schemes: [https, http]
+    inspect: true
+    bind_tls: true
+
+web_addr: 0.0.0.0:4040

ngrok.yml

@@ -0,0 +1,12 @@
+version: "2"
+authtoken: ${NGROK_AUTHTOKEN}
+
+tunnels:
+  fastapi:
+    addr: fastapi:8000
+    proto: http
+    schemes: [https, http]
+    inspect: true
+    bind_tls: true
+
+web_addr: 0.0.0.0:4040

openapi-generator-config.yaml

@@ -0,0 +1,183 @@
+# OpenAPI Generator Configuration for Video Generation API
+# This file contains global configuration for generating client SDKs
+
+# Global properties
+globalProperties:
+  models: true
+  apis: true
+  supportingFiles: true
+  modelTests: true
+  apiTests: true
+  modelDocs: true
+  apiDocs: true
+
+# TypeScript configuration
+typescript:
+  generatorName: typescript-fetch
+  outputDir: clients/typescript
+  additionalProperties:
+    npmName: video-api-client
+    npmVersion: 1.0.0
+    supportsES6: true
+    withInterfaces: true
+    typescriptThreePlus: true
+    enumPropertyNaming: PascalCase
+    modelPropertyNaming: camelCase
+    paramNaming: camelCase
+    stringEnums: true
+    withSeparateModelsAndApi: true
+    apiPackage: api
+    modelPackage: models
+  templateDir: templates/typescript
+  
+# Python configuration  
+python:
+  generatorName: python
+  outputDir: clients/python
+  additionalProperties:
+    packageName: video_api_client
+    projectName: video-api-client
+    packageVersion: 1.0.0
+    packageUrl: https://github.com/example/video-api-client-python
+    packageDescription: Python client library for Video Generation API
+    authorName: API Team
+    authorEmail: [email protected]
+    library: urllib3
+    generateSourceCodeOnly: false
+  templateDir: templates/python
+
+# Java configuration
+java:
+  generatorName: java
+  outputDir: clients/java
+  additionalProperties:
+    groupId: com.example
+    artifactId: video-api-client
+    artifactVersion: 1.0.0
+    artifactDescription: Java client library for Video Generation API
+    library: okhttp-gson
+    java8: true
+    dateLibrary: java8
+    serializationLibrary: gson
+    hideGenerationTimestamp: true
+  templateDir: templates/java
+
+# C# configuration
+csharp:
+  generatorName: csharp
+  outputDir: clients/csharp
+  additionalProperties:
+    packageName: VideoApiClient
+    packageVersion: 1.0.0
+    clientPackage: VideoApiClient
+    packageCompany: Example Inc
+    packageAuthors: API Team
+    packageCopyright: Copyright 2024
+    packageDescription: C# client library for Video Generation API
+    targetFramework: netstandard2.0
+    library: httpclient
+    generatePropertyChanged: true
+  templateDir: templates/csharp
+
+# Go configuration
+go:
+  generatorName: go
+  outputDir: clients/go
+  additionalProperties:
+    packageName: videoapiclient
+    packageVersion: 1.0.0
+    packageUrl: github.com/example/video-api-client-go
+    hideGenerationTimestamp: true
+    withGoCodegenComment: true
+    enumClassPrefix: true
+  templateDir: templates/go
+
+# PHP configuration
+php:
+  generatorName: php
+  outputDir: clients/php
+  additionalProperties:
+    packageName: VideoApiClient
+    composerVendorName: example
+    composerProjectName: video-api-client
+    packageVersion: 1.0.0
+    invokerPackage: VideoApiClient
+    srcBasePath: src
+    hideGenerationTimestamp: true
+  templateDir: templates/php
+
+# Ruby configuration
+ruby:
+  generatorName: ruby
+  outputDir: clients/ruby
+  additionalProperties:
+    gemName: video_api_client
+    gemVersion: 1.0.0
+    gemHomepage: https://github.com/example/video-api-client-ruby
+    gemSummary: Ruby client library for Video Generation API
+    gemDescription: Ruby client library for the Video Generation API
+    gemAuthor: API Team
+    gemAuthorEmail: [email protected]
+    moduleName: VideoApiClient
+    hideGenerationTimestamp: true
+  templateDir: templates/ruby
+
+# Custom templates directory structure
+templates:
+  typescript:
+    - api.mustache
+    - model.mustache
+    - README.mustache
+    - package.mustache
+  python:
+    - api.mustache
+    - model.mustache
+    - README.mustache
+    - setup.mustache
+  java:
+    - api.mustache
+    - model.mustache
+    - README.mustache
+    - pom.mustache
+  csharp:
+    - api.mustache
+    - model.mustache
+    - README.mustache
+    - Project.mustache
+  go:
+    - api.mustache
+    - model.mustache
+    - README.mustache
+    - go.mustache
+  php:
+    - api.mustache
+    - model.mustache
+    - README.mustache
+    - composer.mustache
+  ruby:
+    - api.mustache
+    - model.mustache
+    - README.mustache
+    - gemspec.mustache
+
+# Documentation configuration
+documentation:
+  generateApiDocs: true
+  generateModelDocs: true
+  generateExamples: true
+  includeAuthentication: true
+  includeErrorHandling: true
+  includeRateLimiting: true
+
+# Validation rules
+validation:
+  validateSpec: true
+  strictMode: false
+  allowAdditionalPropertiesWithComposedSchema: true
+
+# Post-processing options
+postProcessing:
+  removeUnusedImports: true
+  formatCode: true
+  generateTests: true
+  generateExamples: true

pyproject.toml

@@ -0,0 +1,122 @@
+[project]
+name = "t2m"
+version = "0.1.0"
+description = "Add your description here"
+readme = "README.md"
+requires-python = ">=3.11"
+dependencies = [
+    "annotated-types~=0.7.0",
+    "asyncio-mqtt>=0.16.0",
+    "azure-cognitiveservices-speech~=1.41.1",
+    "boto3~=1.36.9",
+    "cachetools~=5.5.0",
+    "cairosvg>=2.8.2",
+    "certifi~=2024.8.30",
+    "charset-normalizer~=3.4.0",
+    "chromadb~=0.6.3",
+    "clerk-backend-api>=1.0.0",
+    "click~=8.1.7",
+    "cloup~=3.0.5",
+    "cython~=3.0.11",
+    "decorator~=5.1.1",
+    "fastapi>=0.116.1",
+    "ffmpeg-python~=0.2.0",
+    "glcontext~=3.0.0",
+    "google-ai-generativelanguage~=0.6.10",
+    "google-api-core~=2.22.0",
+    "google-api-python-client~=2.151.0",
+    "google-auth~=2.35.0",
+    "google-auth-httplib2~=0.2.0",
+    "google-cloud-aiplatform~=1.79.0",
+    "google-generativeai~=0.8.3",
+    "googleapis-common-protos~=1.65.0",
+    "gradio>=5.43.1",
+    "grpcio~=1.67.1",
+    "grpcio-status~=1.67.1",
+    "gtts~=2.5.3",
+    "hiredis>=2.2.0",
+    "httplib2~=0.22.0",
+    "httpx>=0.25.0",
+    "idna~=3.10",
+    "imageio-ffmpeg~=0.5.1",
+    "inquirer>=3.4.1",
+    "isosurfaces~=0.1.2",
+    "kokoro-onnx>=0.4.9",
+    "krippendorff~=0.8.1",
+    "langchain~=0.3.14",
+    "langchain-community~=0.3.14",
+    "langfuse~=2.58.1",
+    "litellm~=1.60.5",
+    "manim~=0.18.1",
+    "manim-chemistry~=0.4.4",
+    "manim-circuit~=0.0.3",
+    "manim-dsa~=0.2.0",
+    "manim-ml~=0.0.24",
+    "manim-physics~=0.4.0",
+    "manim-voiceover~=0.3.7",
+    "manimpango~=0.6.0",
+    "mapbox-earcut~=1.0.2",
+    "markdown-it-py~=3.0.0",
+    "mdurl~=0.1.2",
+    "moderngl~=5.12.0",
+    "moviepy~=2.1.2",
+    "multipledispatch~=1.0.0",
+    "mutagen~=1.47.0",
+    "networkx~=3.4.2",
+    "numpy~=2.2.2",
+    "openai~=1.61.0",
+    "opencv-python~=4.11.0",
+    "pillow>=10.4.0",
+    "proto-plus~=1.25.0",
+    "protobuf~=5.28.3",
+    "psutil>=7.0.0",
+    "pyasn1~=0.6.1",
+    "pyasn1-modules~=0.4.1",
+    "pyaudio~=0.2.14",
+    "pycairo~=1.27.0",
+    "pydantic>=2.5.0",
+    "pydantic-core~=2.23.4",
+    "pydantic-settings>=2.1.0",
+    "pydub~=0.25.1",
+    "pyglet~=2.0.18",
+    "pygments~=2.18.0",
+    "pyjwt[crypto]>=2.8.0",
+    "pylatexenc~=2.10",
+    "pyparsing~=3.2.0",
+    "pyrr~=0.10.3",
+    "pysrt>=1.1.2",
+    "pytest>=8.4.1",
+    "pytest-asyncio>=1.1.0",
+    "python-dateutil>=2.8.2",
+    "python-dotenv~=0.21.1",
+    "python-magic>=0.4.27",
+    "python-multipart>=0.0.6",
+    "python-slugify~=8.0.4",
+    "redis>=5.0.0",
+    "requests~=2.32.3",
+    "rich~=13.9.3",
+    "rsa~=4.9",
+    "scipy~=1.14.1",
+    "screeninfo~=0.8.1",
+    "sentence-transformers>=5.1.0",
+    "sentencepiece>=0.2.1",
+    "skia-pathops~=0.8.0.post2",
+    "soundfile~=0.13.1",
+    "sox~=1.5.0",
+    "speechrecognition~=3.14.1",
+    "srt~=3.5.3",
+    "statsmodels~=0.14.4",
+    "structlog>=23.2.0",
+    "svgelements~=1.9.6",
+    "text-unidecode~=1.3",
+    "tiktoken~=0.8.0",
+    "timm>=1.0.19",
+    "tqdm~=4.66.5",
+    "transformers>=4.55.4",
+    "typing-extensions~=4.12.2",
+    "uritemplate~=4.1.1",
+    "urllib3~=2.2.3",
+    "uvicorn[standard]>=0.24.0",
+    "watchdog~=5.0.3",
+    "yt-dlp>=2025.8.22",
+]

quick_api_test.py

@@ -0,0 +1,72 @@
+#!/usr/bin/env python3
+"""
+Quick API Test - Just check if your API is running
+"""
+
+import requests
+import sys
+
+def quick_test(base_url):
+    """Quick test to see if API is responding"""
+    print(f"🔍 Quick API Test: {base_url}")
+    print("-" * 40)
+    
+    # Test endpoints that should work
+    endpoints = [
+        ('/system/health', 'System Health'),
+        ('/auth/health', 'Auth Health'),
+        ('/auth/status', 'Auth Status'),
+        ('/', 'Root (may require auth)')
+    ]
+    
+    working_endpoints = 0
+    
+    for endpoint, name in endpoints:
+        try:
+            url = f"{base_url}{endpoint}"
+            response = requests.get(url, timeout=10)
+            
+            if response.status_code == 200:
+                print(f"✅ {name}: Working (200)")
+                working_endpoints += 1
+            elif response.status_code == 401:
+                print(f"🔐 {name}: Requires auth (401)")
+                working_endpoints += 1  # Still counts as working
+            else:
+                print(f"⚠️  {name}: Status {response.status_code}")
+        
+        except requests.exceptions.ConnectionError:
+            print(f"❌ {name}: Connection failed - API not running?")
+        except requests.exceptions.Timeout:
+            print(f"❌ {name}: Timeout")
+        except Exception as e:
+            print(f"❌ {name}: Error - {e}")
+    
+    print(f"\n📊 Result: {working_endpoints}/{len(endpoints)} endpoints responding")
+    
+    if working_endpoints >= 2:
+        print("✅ API appears to be running!")
+        print("\nNext steps:")
+        print("1. Get your Clerk token: python get_token_simple.py")
+        print("2. Test with token: python test_current_api.py <base_url> <token>")
+        return True
+    else:
+        print("❌ API may not be running or accessible")
+        print("\nTroubleshooting:")
+        print("- Check if your FastAPI server is running")
+        print("- Verify the URL is correct")
+        print("- Check for firewall/network issues")
+        return False
+
+def main():
+    if len(sys.argv) != 2:
+        print("Usage: python quick_api_test.py <base_url>")
+        print("Example: python quick_api_test.py http://localhost:8000/api/v1")
+        return 1
+    
+    base_url = sys.argv[1].rstrip('/')
+    success = quick_test(base_url)
+    return 0 if success else 1
+
+if __name__ == '__main__':
+    exit(main())

requirements-test.txt

@@ -0,0 +1,3 @@
+# Requirements for API testing
+requests>=2.31.0
+urllib3>=2.0.0

requirements.txt

@@ -97,4 +97,38 @@ soundfile~=0.13.1
 krippendorff~=0.8.1
 statsmodels~=0.14.4
 opencv-python~=4.11.0
-gradio
+gradio
+    # FastAPI and ASGI server
+fastapi
+uvicorn[standard]>=0.24.0
+    
+    # Pydantic for data validation
+pydantic>=2.5.0
+pydantic-settings>=2.1.0
+    
+    # Redis for caching and job queuing
+redis>=5.0.0
+hiredis>=2.2.0  # C extension for better Redis performanc
+    
+    # Clerk SDK for authentication
+clerk-backend-api>=1.0.0
+    
+    # HTTP client for external API calls
+httpx>=0.25.0
+    
+    # JSON Web Token handling
+pyjwt[crypto]>=2.8.0
+    
+    # File handling and validation
+python-multipart>=0.0.6  # For file uploads
+python-magic>=0.4.27   # File type detection
+    
+    # Logging and monitoring
+structlog>=23.2.0
+
+    
+    # Date and time utilities
+python-dateutil>=2.8.2
+    
+    # Async utilities
+asyncio-mqtt>=0.16.0 # If needed for real-time updates

run_api_tests.py

@@ -0,0 +1,54 @@
+#!/usr/bin/env python3
+"""
+Simple runner for T2M API tests with configuration file support
+"""
+
+import json
+import sys
+import os
+from pathlib import Path
+from test_api_endpoints import T2MAPITester
+
+def load_config(config_file: str = "test_config.json") -> dict:
+    """Load configuration from JSON file"""
+    try:
+        with open(config_file, 'r') as f:
+            return json.load(f)
+    except FileNotFoundError:
+        print(f"❌ Configuration file '{config_file}' not found")
+        print("Please create a test_config.json file or use test_api_endpoints.py directly")
+        return None
+    except json.JSONDecodeError as e:
+        print(f"❌ Invalid JSON in configuration file: {e}")
+        return None
+
+def main():
+    # Load configuration
+    config = load_config()
+    if not config:
+        return 1
+    
+    api_config = config.get('api_config', {})
+    base_url = api_config.get('base_url')
+    token = api_config.get('token')
+    
+    if not base_url:
+        print("❌ base_url not specified in configuration")
+        return 1
+    
+    if not token or token == "your-bearer-token-here":
+        print("⚠️  No valid token provided - only public endpoints will be tested")
+        token = None
+    
+    print("🔧 Configuration loaded:")
+    print(f"   Base URL: {base_url}")
+    print(f"   Token: {'Provided' if token else 'Not provided'}")
+    
+    # Create and run tester
+    tester = T2MAPITester(base_url, token)
+    tester.run_all_tests()
+    
+    return 0
+
+if __name__ == '__main__':
+    exit(main())

run_debug.py

@@ -0,0 +1,50 @@
+#!/usr/bin/env python3
+"""
+Run debug and comprehensive tests
+"""
+
+import subprocess
+import sys
+
+def run_debug():
+    print("🔍 Running Authentication Debug")
+    print("=" * 50)
+    
+    try:
+        result = subprocess.run([sys.executable, "debug_auth.py"], 
+                              capture_output=True, text=True, timeout=30)
+        print(result.stdout)
+        if result.stderr:
+            print("STDERR:", result.stderr)
+        
+        if result.returncode != 0:
+            print(f"Debug script failed with code {result.returncode}")
+        
+    except subprocess.TimeoutExpired:
+        print("Debug script timed out")
+    except Exception as e:
+        print(f"Error running debug script: {e}")
+    
+    print("\n" + "=" * 50)
+    print("🎬 Running Comprehensive Test")
+    print("=" * 50)
+    
+    try:
+        result = subprocess.run([sys.executable, "test_api_comprehensive.py"], 
+                              capture_output=True, text=True, timeout=60)
+        print(result.stdout)
+        if result.stderr:
+            print("STDERR:", result.stderr)
+        
+        if result.returncode == 0:
+            print("✅ All tests passed!")
+        else:
+            print(f"❌ Some tests failed (code {result.returncode})")
+        
+    except subprocess.TimeoutExpired:
+        print("Test script timed out")
+    except Exception as e:
+        print(f"Error running test script: {e}")
+
+if __name__ == '__main__':
+    run_debug()

run_video_test.py

@@ -0,0 +1,57 @@
+#!/usr/bin/env python3
+"""
+Simple runner for video generation API tests
+"""
+
+import json
+import sys
+import os
+from test_video_generation import VideoGenerationTester
+
+def load_config(config_file: str = "video_test_config.json") -> dict:
+    """Load configuration from JSON file"""
+    try:
+        with open(config_file, 'r') as f:
+            return json.load(f)
+    except FileNotFoundError:
+        print(f"❌ Configuration file '{config_file}' not found")
+        print("Please create a video_test_config.json file or use test_video_generation.py directly")
+        return None
+    except json.JSONDecodeError as e:
+        print(f"❌ Invalid JSON in configuration file: {e}")
+        return None
+
+def main():
+    # Load configuration
+    config = load_config()
+    if not config:
+        return 1
+    
+    api_config = config.get('api', {})
+    base_url = api_config.get('base_url')
+    token = api_config.get('token')
+    
+    if not base_url:
+        print("❌ base_url not specified in configuration")
+        return 1
+    
+    if not token or token == "your-bearer-token-here":
+        print("❌ Valid authentication token is required for video generation testing")
+        return 1
+    
+    print("🎬 Video Generation Test Configuration:")
+    print(f"   Base URL: {base_url}")
+    print(f"   Token: {'*' * (len(token) - 4) + token[-4:]}")
+    
+    # Get test settings
+    test_settings = config.get('test_settings', {})
+    monitor_progress = test_settings.get('monitor_progress', True)
+    
+    # Create and run tester
+    tester = VideoGenerationTester(base_url, token)
+    tester.run_comprehensive_test(monitor_progress)
+    
+    return 0
+
+if __name__ == '__main__':
+    exit(main())

scripts/generate_clients.py

@@ -0,0 +1,712 @@
+#!/usr/bin/env python3
+"""
+Client SDK generation script for FastAPI Video Generation Backend.
+
+This script generates client SDKs in multiple languages using OpenAPI Generator.
+It fetches the OpenAPI specification from the running API and generates clients
+for TypeScript, Python, Java, C#, Go, PHP, and Ruby.
+"""
+
+import os
+import sys
+import json
+import subprocess
+import argparse
+import requests
+from pathlib import Path
+from typing import Dict, List, Optional
+import tempfile
+import shutil
+
+
+class ClientGenerator:
+    """Client SDK generator using OpenAPI Generator."""
+    
+    SUPPORTED_LANGUAGES = {
+        "typescript": {
+            "generator": "typescript-fetch",
+            "output_dir": "clients/typescript",
+            "package_name": "video-api-client",
+            "additional_properties": {
+                "npmName": "video-api-client",
+                "npmVersion": "1.0.0",
+                "supportsES6": "true",
+                "withInterfaces": "true",
+                "typescriptThreePlus": "true"
+            }
+        },
+        "python": {
+            "generator": "python",
+            "output_dir": "clients/python",
+            "package_name": "video_api_client",
+            "additional_properties": {
+                "packageName": "video_api_client",
+                "projectName": "video-api-client",
+                "packageVersion": "1.0.0",
+                "packageUrl": "https://github.com/example/video-api-client-python"
+            }
+        },
+        "java": {
+            "generator": "java",
+            "output_dir": "clients/java",
+            "package_name": "com.example.videoapiclient",
+            "additional_properties": {
+                "groupId": "com.example",
+                "artifactId": "video-api-client",
+                "artifactVersion": "1.0.0",
+                "library": "okhttp-gson",
+                "java8": "true"
+            }
+        },
+        "csharp": {
+            "generator": "csharp",
+            "output_dir": "clients/csharp",
+            "package_name": "VideoApiClient",
+            "additional_properties": {
+                "packageName": "VideoApiClient",
+                "packageVersion": "1.0.0",
+                "clientPackage": "VideoApiClient",
+                "packageCompany": "Example Inc",
+                "packageAuthors": "API Team",
+                "packageCopyright": "Copyright 2024",
+                "packageDescription": "Video Generation API Client for .NET",
+                "targetFramework": "netstandard2.0"
+            }
+        },
+        "go": {
+            "generator": "go",
+            "output_dir": "clients/go",
+            "package_name": "videoapiclient",
+            "additional_properties": {
+                "packageName": "videoapiclient",
+                "packageVersion": "1.0.0",
+                "packageUrl": "github.com/example/video-api-client-go"
+            }
+        },
+        "php": {
+            "generator": "php",
+            "output_dir": "clients/php",
+            "package_name": "VideoApiClient",
+            "additional_properties": {
+                "packageName": "VideoApiClient",
+                "composerVendorName": "example",
+                "composerProjectName": "video-api-client",
+                "packageVersion": "1.0.0"
+            }
+        },
+        "ruby": {
+            "generator": "ruby",
+            "output_dir": "clients/ruby",
+            "package_name": "video_api_client",
+            "additional_properties": {
+                "gemName": "video_api_client",
+                "gemVersion": "1.0.0",
+                "gemHomepage": "https://github.com/example/video-api-client-ruby",
+                "gemSummary": "Video Generation API Client for Ruby",
+                "gemDescription": "Ruby client library for the Video Generation API"
+            }
+        }
+    }
+    
+    def __init__(self, api_url: str = "http://localhost:8000", output_base_dir: str = "generated_clients"):
+        self.api_url = api_url.rstrip("/")
+        self.output_base_dir = Path(output_base_dir)
+        self.openapi_spec_path: Optional[Path] = None
+        
+    def fetch_openapi_spec(self) -> Path:
+        """Fetch OpenAPI specification from the API."""
+        try:
+            print(f"Fetching OpenAPI specification from {self.api_url}/openapi.json")
+            response = requests.get(f"{self.api_url}/openapi.json", timeout=30)
+            response.raise_for_status()
+            
+            # Create temporary file for OpenAPI spec
+            temp_file = tempfile.NamedTemporaryFile(mode='w', suffix='.json', delete=False)
+            json.dump(response.json(), temp_file, indent=2)
+            temp_file.close()
+            
+            self.openapi_spec_path = Path(temp_file.name)
+            print(f"OpenAPI specification saved to {self.openapi_spec_path}")
+            return self.openapi_spec_path
+            
+        except requests.RequestException as e:
+            print(f"Error fetching OpenAPI specification: {e}")
+            sys.exit(1)
+    
+    def check_openapi_generator(self) -> bool:
+        """Check if OpenAPI Generator is available."""
+        try:
+            result = subprocess.run(
+                ["openapi-generator-cli", "version"],
+                capture_output=True,
+                text=True,
+                timeout=10
+            )
+            if result.returncode == 0:
+                print(f"OpenAPI Generator found: {result.stdout.strip()}")
+                return True
+            else:
+                print("OpenAPI Generator not found or not working properly")
+                return False
+        except (subprocess.TimeoutExpired, FileNotFoundError):
+            print("OpenAPI Generator CLI not found")
+            return False
+    
+    def install_openapi_generator(self) -> bool:
+        """Install OpenAPI Generator CLI using npm."""
+        try:
+            print("Installing OpenAPI Generator CLI...")
+            result = subprocess.run(
+                ["npm", "install", "-g", "@openapitools/openapi-generator-cli"],
+                capture_output=True,
+                text=True,
+                timeout=120
+            )
+            if result.returncode == 0:
+                print("OpenAPI Generator CLI installed successfully")
+                return True
+            else:
+                print(f"Failed to install OpenAPI Generator CLI: {result.stderr}")
+                return False
+        except (subprocess.TimeoutExpired, FileNotFoundError):
+            print("npm not found. Please install Node.js and npm first.")
+            return False
+    
+    def generate_client(self, language: str, custom_config: Optional[Dict] = None) -> bool:
+        """Generate client SDK for specified language."""
+        if language not in self.SUPPORTED_LANGUAGES:
+            print(f"Unsupported language: {language}")
+            return False
+        
+        config = self.SUPPORTED_LANGUAGES[language].copy()
+        if custom_config:
+            config.update(custom_config)
+        
+        output_dir = self.output_base_dir / config["output_dir"]
+        output_dir.mkdir(parents=True, exist_ok=True)
+        
+        # Build OpenAPI Generator command
+        cmd = [
+            "openapi-generator-cli",
+            "generate",
+            "-i", str(self.openapi_spec_path),
+            "-g", config["generator"],
+            "-o", str(output_dir),
+            "--package-name", config["package_name"]
+        ]
+        
+        # Add additional properties
+        if "additional_properties" in config:
+            for key, value in config["additional_properties"].items():
+                cmd.extend(["--additional-properties", f"{key}={value}"])
+        
+        # Add global properties for better client generation
+        cmd.extend([
+            "--global-property",
+            "models,apis,supportingFiles,modelTests,apiTests,modelDocs,apiDocs"
+        ])
+        
+        print(f"Generating {language} client...")
+        print(f"Command: {' '.join(cmd)}")
+        
+        try:
+            result = subprocess.run(cmd, capture_output=True, text=True, timeout=300)
+            if result.returncode == 0:
+                print(f"✅ {language} client generated successfully in {output_dir}")
+                self._post_process_client(language, output_dir)
+                return True
+            else:
+                print(f"❌ Failed to generate {language} client:")
+                print(result.stderr)
+                return False
+        except subprocess.TimeoutExpired:
+            print(f"❌ Timeout generating {language} client")
+            return False
+    
+    def _post_process_client(self, language: str, output_dir: Path) -> None:
+        """Post-process generated client with additional files and documentation."""
+        # Create README for the client
+        readme_content = self._generate_client_readme(language)
+        readme_path = output_dir / "README.md"
+        readme_path.write_text(readme_content)
+        
+        # Create example usage file
+        example_content = self._generate_client_example(language)
+        if example_content:
+            example_extensions = {
+                "typescript": "ts",
+                "python": "py",
+                "java": "java",
+                "csharp": "cs",
+                "go": "go",
+                "php": "php",
+                "ruby": "rb"
+            }
+            extension = example_extensions.get(language, "txt")
+            example_path = output_dir / f"example.{extension}"
+            example_path.write_text(example_content)
+        
+        # Language-specific post-processing
+        if language == "typescript":
+            self._post_process_typescript(output_dir)
+        elif language == "python":
+            self._post_process_python(output_dir)
+    
+    def _post_process_typescript(self, output_dir: Path) -> None:
+        """Post-process TypeScript client."""
+        # Create package.json if it doesn't exist
+        package_json_path = output_dir / "package.json"
+        if not package_json_path.exists():
+            package_json = {
+                "name": "video-api-client",
+                "version": "1.0.0",
+                "description": "TypeScript client for Video Generation API",
+                "main": "dist/index.js",
+                "types": "dist/index.d.ts",
+                "scripts": {
+                    "build": "tsc",
+                    "test": "jest",
+                    "lint": "eslint src/**/*.ts"
+                },
+                "dependencies": {
+                    "node-fetch": "^2.6.7"
+                },
+                "devDependencies": {
+                    "typescript": "^4.9.0",
+                    "@types/node": "^18.0.0",
+                    "jest": "^29.0.0",
+                    "@types/jest": "^29.0.0",
+                    "eslint": "^8.0.0",
+                    "@typescript-eslint/eslint-plugin": "^5.0.0",
+                    "@typescript-eslint/parser": "^5.0.0"
+                },
+                "keywords": ["video", "api", "client", "typescript"],
+                "author": "API Team",
+                "license": "MIT"
+            }
+            package_json_path.write_text(json.dumps(package_json, indent=2))
+    
+    def _post_process_python(self, output_dir: Path) -> None:
+        """Post-process Python client."""
+        # Create setup.py if it doesn't exist
+        setup_py_path = output_dir / "setup.py"
+        if not setup_py_path.exists():
+            setup_py_content = '''
+from setuptools import setup, find_packages
+
+setup(
+    name="video-api-client",
+    version="1.0.0",
+    description="Python client for Video Generation API",
+    long_description=open("README.md").read(),
+    long_description_content_type="text/markdown",
+    author="API Team",
+    author_email="[email protected]",
+    url="https://github.com/example/video-api-client-python",
+    packages=find_packages(),
+    install_requires=[
+        "requests>=2.25.0",
+        "urllib3>=1.26.0",
+        "python-dateutil>=2.8.0"
+    ],
+    extras_require={
+        "dev": [
+            "pytest>=6.0.0",
+            "pytest-cov>=2.10.0",
+            "black>=21.0.0",
+            "flake8>=3.8.0",
+            "mypy>=0.800"
+        ]
+    },
+    classifiers=[
+        "Development Status :: 4 - Beta",
+        "Intended Audience :: Developers",
+        "License :: OSI Approved :: MIT License",
+        "Programming Language :: Python :: 3",
+        "Programming Language :: Python :: 3.7",
+        "Programming Language :: Python :: 3.8",
+        "Programming Language :: Python :: 3.9",
+        "Programming Language :: Python :: 3.10",
+        "Programming Language :: Python :: 3.11",
+    ],
+    python_requires=">=3.7",
+)
+'''
+            setup_py_path.write_text(setup_py_content.strip())
+    
+    def _generate_client_readme(self, language: str) -> str:
+        """Generate README content for client SDK."""
+        return f"""# Video Generation API Client - {language.title()}
+
+This is an auto-generated client library for the Video Generation API.
+
+## Installation
+
+### {language.title()}
+{self._get_installation_instructions(language)}
+
+## Quick Start
+
+```{self._get_code_block_language(language)}
+{self._get_quick_start_example(language)}
+```
+
+## Authentication
+
+This API uses Clerk authentication. You need to provide a valid Clerk session token:
+
+```{self._get_code_block_language(language)}
+{self._get_auth_example(language)}
+```
+
+## API Documentation
+
+For complete API documentation, visit: https://docs.example.com
+
+## Examples
+
+See `example.{self._get_file_extension(language)}` for more usage examples.
+
+## Support
+
+- GitHub Issues: https://github.com/example/video-api-client-{language}/issues
+- Documentation: https://docs.example.com
+- Email: [email protected]
+
+## License
+
+MIT License - see LICENSE file for details.
+"""
+    
+    def _generate_client_example(self, language: str) -> Optional[str]:
+        """Generate example usage code for client SDK."""
+        examples = {
+            "typescript": '''
+import { Configuration, VideosApi, JobsApi } from './src';
+
+// Configure the client
+const config = new Configuration({
+  basePath: 'https://api.example.com',
+  accessToken: 'your-clerk-session-token'
+});
+
+const videosApi = new VideosApi(config);
+const jobsApi = new JobsApi(config);
+
+async function generateVideo() {
+  try {
+    // Create a video generation job
+    const jobResponse = await videosApi.createVideoGenerationJob({
+      configuration: {
+        topic: "Pythagorean Theorem",
+        context: "Explain the mathematical proof with visual demonstration",
+        quality: "medium",
+        use_rag: true
+      }
+    });
+    
+    console.log('Job created:', jobResponse.job_id);
+    
+    // Poll for job completion
+    let status = 'queued';
+    while (status !== 'completed' && status !== 'failed') {
+      await new Promise(resolve => setTimeout(resolve, 5000)); // Wait 5 seconds
+      
+      const statusResponse = await videosApi.getVideoJobStatus(jobResponse.job_id);
+      status = statusResponse.status;
+      
+      console.log(`Job status: ${status} (${statusResponse.progress.percentage}%)`);
+    }
+    
+    if (status === 'completed') {
+      console.log('Video generation completed!');
+      // Download the video
+      const videoBlob = await videosApi.downloadVideoFile(jobResponse.job_id);
+      console.log('Video downloaded');
+    } else {
+      console.log('Video generation failed');
+    }
+    
+  } catch (error) {
+    console.error('Error:', error);
+  }
+}
+
+generateVideo();
+''',
+            "python": '''
+import time
+from video_api_client import Configuration, ApiClient, VideosApi, JobsApi
+from video_api_client.models import JobCreateRequest, JobConfiguration
+
+# Configure the client
+configuration = Configuration(
+    host="https://api.example.com",
+    access_token="your-clerk-session-token"
+)
+
+with ApiClient(configuration) as api_client:
+    videos_api = VideosApi(api_client)
+    jobs_api = JobsApi(api_client)
+    
+    try:
+        # Create a video generation job
+        job_request = JobCreateRequest(
+            configuration=JobConfiguration(
+                topic="Pythagorean Theorem",
+                context="Explain the mathematical proof with visual demonstration",
+                quality="medium",
+                use_rag=True
+            )
+        )
+        
+        job_response = videos_api.create_video_generation_job(job_request)
+        print(f"Job created: {job_response.job_id}")
+        
+        # Poll for job completion
+        status = "queued"
+        while status not in ["completed", "failed"]:
+            time.sleep(5)  # Wait 5 seconds
+            
+            status_response = videos_api.get_video_job_status(job_response.job_id)
+            status = status_response.status
+            
+            print(f"Job status: {status} ({status_response.progress.percentage}%)")
+        
+        if status == "completed":
+            print("Video generation completed!")
+            # Download the video
+            video_data = videos_api.download_video_file(job_response.job_id)
+            with open("generated_video.mp4", "wb") as f:
+                f.write(video_data)
+            print("Video downloaded as generated_video.mp4")
+        else:
+            print("Video generation failed")
+            
+    except Exception as e:
+        print(f"Error: {e}")
+''',
+            "java": '''
+import com.example.videoapiclient.ApiClient;
+import com.example.videoapiclient.Configuration;
+import com.example.videoapiclient.api.VideosApi;
+import com.example.videoapiclient.api.JobsApi;
+import com.example.videoapiclient.model.*;
+
+public class VideoApiExample {
+    public static void main(String[] args) {
+        // Configure the client
+        ApiClient client = Configuration.getDefaultApiClient();
+        client.setBasePath("https://api.example.com");
+        client.setAccessToken("your-clerk-session-token");
+        
+        VideosApi videosApi = new VideosApi(client);
+        JobsApi jobsApi = new JobsApi(client);
+        
+        try {
+            // Create a video generation job
+            JobConfiguration config = new JobConfiguration()
+                .topic("Pythagorean Theorem")
+                .context("Explain the mathematical proof with visual demonstration")
+                .quality(VideoQuality.MEDIUM)
+                .useRag(true);
+            
+            JobCreateRequest request = new JobCreateRequest().configuration(config);
+            JobResponse jobResponse = videosApi.createVideoGenerationJob(request);
+            
+            System.out.println("Job created: " + jobResponse.getJobId());
+            
+            // Poll for job completion
+            String status = "queued";
+            while (!"completed".equals(status) && !"failed".equals(status)) {
+                Thread.sleep(5000); // Wait 5 seconds
+                
+                JobStatusResponse statusResponse = videosApi.getVideoJobStatus(jobResponse.getJobId());
+                status = statusResponse.getStatus().getValue();
+                
+                System.out.println("Job status: " + status + " (" + 
+                    statusResponse.getProgress().getPercentage() + "%)");
+            }
+            
+            if ("completed".equals(status)) {
+                System.out.println("Video generation completed!");
+                // Download logic would go here
+            } else {
+                System.out.println("Video generation failed");
+            }
+            
+        } catch (Exception e) {
+            System.err.println("Error: " + e.getMessage());
+        }
+    }
+}
+'''
+        }
+        
+        return examples.get(language)
+    
+    def _get_installation_instructions(self, language: str) -> str:
+        """Get installation instructions for each language."""
+        instructions = {
+            "typescript": "```bash\nnpm install video-api-client\n```",
+            "python": "```bash\npip install video-api-client\n```",
+            "java": "Add to your `pom.xml`:\n```xml\n<dependency>\n  <groupId>com.example</groupId>\n  <artifactId>video-api-client</artifactId>\n  <version>1.0.0</version>\n</dependency>\n```",
+            "csharp": "```bash\ndotnet add package VideoApiClient\n```",
+            "go": "```bash\ngo get github.com/example/video-api-client-go\n```",
+            "php": "```bash\ncomposer require example/video-api-client\n```",
+            "ruby": "```bash\ngem install video_api_client\n```"
+        }
+        return instructions.get(language, "See documentation for installation instructions.")
+    
+    def _get_code_block_language(self, language: str) -> str:
+        """Get code block language identifier."""
+        mapping = {
+            "typescript": "typescript",
+            "python": "python",
+            "java": "java",
+            "csharp": "csharp",
+            "go": "go",
+            "php": "php",
+            "ruby": "ruby"
+        }
+        return mapping.get(language, language)
+    
+    def _get_file_extension(self, language: str) -> str:
+        """Get file extension for each language."""
+        extensions = {
+            "typescript": "ts",
+            "python": "py",
+            "java": "java",
+            "csharp": "cs",
+            "go": "go",
+            "php": "php",
+            "ruby": "rb"
+        }
+        return extensions.get(language, "txt")
+    
+    def _get_quick_start_example(self, language: str) -> str:
+        """Get quick start example for each language."""
+        examples = {
+            "typescript": "import { VideosApi } from 'video-api-client';\n\nconst api = new VideosApi();\nconst job = await api.createVideoGenerationJob({...});",
+            "python": "from video_api_client import VideosApi\n\napi = VideosApi()\njob = api.create_video_generation_job(...)",
+            "java": "VideosApi api = new VideosApi();\nJobResponse job = api.createVideoGenerationJob(...);",
+            "csharp": "var api = new VideosApi();\nvar job = await api.CreateVideoGenerationJobAsync(...);",
+            "go": "client := videoapiclient.NewAPIClient(config)\njob, _, err := client.VideosApi.CreateVideoGenerationJob(...)",
+            "php": "$api = new VideosApi();\n$job = $api->createVideoGenerationJob(...);",
+            "ruby": "api = VideoApiClient::VideosApi.new\njob = api.create_video_generation_job(...)"
+        }
+        return examples.get(language, "// See documentation for usage examples")
+    
+    def _get_auth_example(self, language: str) -> str:
+        """Get authentication example for each language."""
+        examples = {
+            "typescript": "const config = new Configuration({\n  accessToken: 'your-clerk-session-token'\n});",
+            "python": "configuration.access_token = 'your-clerk-session-token'",
+            "java": "client.setAccessToken(\"your-clerk-session-token\");",
+            "csharp": "Configuration.Default.AccessToken = \"your-clerk-session-token\";",
+            "go": "auth := context.WithValue(context.Background(), sw.ContextAccessToken, \"your-clerk-session-token\")",
+            "php": "$config->setAccessToken('your-clerk-session-token');",
+            "ruby": "VideoApiClient.configure { |c| c.access_token = 'your-clerk-session-token' }"
+        }
+        return examples.get(language, "// Set your authentication token")
+    
+    def generate_all_clients(self, languages: Optional[List[str]] = None) -> Dict[str, bool]:
+        """Generate client SDKs for all specified languages."""
+        if languages is None:
+            languages = list(self.SUPPORTED_LANGUAGES.keys())
+        
+        # Ensure OpenAPI spec is available
+        if not self.openapi_spec_path:
+            self.fetch_openapi_spec()
+        
+        results = {}
+        for language in languages:
+            if language in self.SUPPORTED_LANGUAGES:
+                results[language] = self.generate_client(language)
+            else:
+                print(f"Skipping unsupported language: {language}")
+                results[language] = False
+        
+        return results
+    
+    def cleanup(self):
+        """Clean up temporary files."""
+        if self.openapi_spec_path and self.openapi_spec_path.exists():
+            self.openapi_spec_path.unlink()
+            print(f"Cleaned up temporary OpenAPI spec file")
+
+
+def main():
+    """Main function for command-line usage."""
+    parser = argparse.ArgumentParser(description="Generate client SDKs for Video Generation API")
+    parser.add_argument(
+        "--api-url",
+        default="http://localhost:8000",
+        help="Base URL of the API (default: http://localhost:8000)"
+    )
+    parser.add_argument(
+        "--output-dir",
+        default="generated_clients",
+        help="Output directory for generated clients (default: generated_clients)"
+    )
+    parser.add_argument(
+        "--languages",
+        nargs="+",
+        choices=list(ClientGenerator.SUPPORTED_LANGUAGES.keys()),
+        help="Languages to generate (default: all supported languages)"
+    )
+    parser.add_argument(
+        "--install-generator",
+        action="store_true",
+        help="Install OpenAPI Generator CLI if not found"
+    )
+    
+    args = parser.parse_args()
+    
+    generator = ClientGenerator(args.api_url, args.output_dir)
+    
+    # Check if OpenAPI Generator is available
+    if not generator.check_openapi_generator():
+        if args.install_generator:
+            if not generator.install_openapi_generator():
+                print("Failed to install OpenAPI Generator. Please install it manually.")
+                sys.exit(1)
+        else:
+            print("OpenAPI Generator CLI not found. Use --install-generator to install it automatically.")
+            sys.exit(1)
+    
+    try:
+        # Generate clients
+        results = generator.generate_all_clients(args.languages)
+        
+        # Print summary
+        print("\n" + "="*50)
+        print("CLIENT GENERATION SUMMARY")
+        print("="*50)
+        
+        successful = []
+        failed = []
+        
+        for language, success in results.items():
+            if success:
+                successful.append(language)
+                print(f"✅ {language}: SUCCESS")
+            else:
+                failed.append(language)
+                print(f"❌ {language}: FAILED")
+        
+        print(f"\nSuccessful: {len(successful)}")
+        print(f"Failed: {len(failed)}")
+        
+        if successful:
+            print(f"\nGenerated clients are available in: {generator.output_base_dir}")
+        
+        # Exit with error code if any generation failed
+        sys.exit(1 if failed else 0)
+        
+    finally:
+        generator.cleanup()
+
+
+if __name__ == "__main__":
+    main()

scripts/generate_clients.sh

@@ -0,0 +1,557 @@
+#!/bin/bash
+
+# Video Generation API Client Generator Script
+# This script generates client SDKs for multiple programming languages
+
+set -e  # Exit on any error
+
+# Configuration
+API_URL="${API_URL:-http://localhost:8000}"
+OUTPUT_DIR="${OUTPUT_DIR:-generated_clients}"
+CONFIG_FILE="openapi-generator-config.yaml"
+
+# Colors for output
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+BLUE='\033[0;34m'
+NC='\033[0m' # No Color
+
+# Logging functions
+log_info() {
+    echo -e "${BLUE}[INFO]${NC} $1"
+}
+
+log_success() {
+    echo -e "${GREEN}[SUCCESS]${NC} $1"
+}
+
+log_warning() {
+    echo -e "${YELLOW}[WARNING]${NC} $1"
+}
+
+log_error() {
+    echo -e "${RED}[ERROR]${NC} $1"
+}
+
+# Function to check if a command exists
+command_exists() {
+    command -v "$1" >/dev/null 2>&1
+}
+
+# Function to check prerequisites
+check_prerequisites() {
+    log_info "Checking prerequisites..."
+    
+    # Check if Node.js and npm are installed
+    if ! command_exists node; then
+        log_error "Node.js is not installed. Please install Node.js first."
+        exit 1
+    fi
+    
+    if ! command_exists npm; then
+        log_error "npm is not installed. Please install npm first."
+        exit 1
+    fi
+    
+    # Check if OpenAPI Generator CLI is installed
+    if ! command_exists openapi-generator-cli; then
+        log_warning "OpenAPI Generator CLI not found. Installing..."
+        npm install -g @openapitools/openapi-generator-cli
+        
+        if ! command_exists openapi-generator-cli; then
+            log_error "Failed to install OpenAPI Generator CLI"
+            exit 1
+        fi
+        log_success "OpenAPI Generator CLI installed successfully"
+    else
+        log_success "OpenAPI Generator CLI found"
+    fi
+    
+    # Check if Python is available (for the Python script)
+    if ! command_exists python3; then
+        log_warning "Python 3 not found. Some features may not work."
+    fi
+}
+
+# Function to fetch OpenAPI specification
+fetch_openapi_spec() {
+    log_info "Fetching OpenAPI specification from $API_URL..."
+    
+    # Create temporary directory
+    TEMP_DIR=$(mktemp -d)
+    OPENAPI_SPEC="$TEMP_DIR/openapi.json"
+    
+    # Fetch the OpenAPI spec
+    if curl -s -f "$API_URL/openapi.json" -o "$OPENAPI_SPEC"; then
+        log_success "OpenAPI specification fetched successfully"
+        echo "$OPENAPI_SPEC"
+    else
+        log_error "Failed to fetch OpenAPI specification from $API_URL"
+        log_error "Make sure the API server is running and accessible"
+        exit 1
+    fi
+}
+
+# Function to generate client for a specific language
+generate_client() {
+    local language=$1
+    local spec_file=$2
+    
+    log_info "Generating $language client..."
+    
+    case $language in
+        "typescript")
+            openapi-generator-cli generate \
+                -i "$spec_file" \
+                -g typescript-fetch \
+                -o "$OUTPUT_DIR/typescript" \
+                --package-name video-api-client \
+                --additional-properties=npmName=video-api-client,npmVersion=1.0.0,supportsES6=true,withInterfaces=true,typescriptThreePlus=true
+            ;;
+        "python")
+            openapi-generator-cli generate \
+                -i "$spec_file" \
+                -g python \
+                -o "$OUTPUT_DIR/python" \
+                --package-name video_api_client \
+                --additional-properties=packageName=video_api_client,projectName=video-api-client,packageVersion=1.0.0
+            ;;
+        "java")
+            openapi-generator-cli generate \
+                -i "$spec_file" \
+                -g java \
+                -o "$OUTPUT_DIR/java" \
+                --package-name com.example.videoapiclient \
+                --additional-properties=groupId=com.example,artifactId=video-api-client,artifactVersion=1.0.0,library=okhttp-gson,java8=true
+            ;;
+        "csharp")
+            openapi-generator-cli generate \
+                -i "$spec_file" \
+                -g csharp \
+                -o "$OUTPUT_DIR/csharp" \
+                --package-name VideoApiClient \
+                --additional-properties=packageName=VideoApiClient,packageVersion=1.0.0,clientPackage=VideoApiClient,targetFramework=netstandard2.0
+            ;;
+        "go")
+            openapi-generator-cli generate \
+                -i "$spec_file" \
+                -g go \
+                -o "$OUTPUT_DIR/go" \
+                --package-name videoapiclient \
+                --additional-properties=packageName=videoapiclient,packageVersion=1.0.0,packageUrl=github.com/example/video-api-client-go
+            ;;
+        "php")
+            openapi-generator-cli generate \
+                -i "$spec_file" \
+                -g php \
+                -o "$OUTPUT_DIR/php" \
+                --package-name VideoApiClient \
+                --additional-properties=packageName=VideoApiClient,composerVendorName=example,composerProjectName=video-api-client,packageVersion=1.0.0
+            ;;
+        "ruby")
+            openapi-generator-cli generate \
+                -i "$spec_file" \
+                -g ruby \
+                -o "$OUTPUT_DIR/ruby" \
+                --package-name video_api_client \
+                --additional-properties=gemName=video_api_client,gemVersion=1.0.0,moduleName=VideoApiClient
+            ;;
+        *)
+            log_error "Unsupported language: $language"
+            return 1
+            ;;
+    esac
+    
+    if [ $? -eq 0 ]; then
+        log_success "$language client generated successfully"
+        post_process_client "$language"
+        return 0
+    else
+        log_error "Failed to generate $language client"
+        return 1
+    fi
+}
+
+# Function to post-process generated clients
+post_process_client() {
+    local language=$1
+    local client_dir="$OUTPUT_DIR/$language"
+    
+    log_info "Post-processing $language client..."
+    
+    # Create README if it doesn't exist
+    if [ ! -f "$client_dir/README.md" ]; then
+        create_readme "$language" "$client_dir"
+    fi
+    
+    # Create example file
+    create_example "$language" "$client_dir"
+    
+    # Language-specific post-processing
+    case $language in
+        "typescript")
+            post_process_typescript "$client_dir"
+            ;;
+        "python")
+            post_process_python "$client_dir"
+            ;;
+        "java")
+            post_process_java "$client_dir"
+            ;;
+    esac
+}
+
+# Function to create README for client
+create_readme() {
+    local language=$1
+    local client_dir=$2
+    
+    cat > "$client_dir/README.md" << EOF
+# Video Generation API Client - ${language^}
+
+This is an auto-generated client library for the Video Generation API.
+
+## Installation
+
+See the installation instructions in the main documentation.
+
+## Quick Start
+
+\`\`\`${language}
+// See example.${language} for usage examples
+\`\`\`
+
+## Authentication
+
+This API uses Clerk authentication. You need to provide a valid Clerk session token.
+
+## Documentation
+
+For complete API documentation, visit: https://docs.example.com
+
+## Support
+
+- GitHub Issues: https://github.com/example/video-api-client-${language}/issues
+- Documentation: https://docs.example.com
+- Email: [email protected]
+
+## License
+
+MIT License - see LICENSE file for details.
+EOF
+}
+
+# Function to create example file
+create_example() {
+    local language=$1
+    local client_dir=$2
+    
+    case $language in
+        "typescript")
+            cat > "$client_dir/example.ts" << 'EOF'
+import { Configuration, VideosApi } from './src';
+
+const config = new Configuration({
+  basePath: 'https://api.example.com',
+  accessToken: 'your-clerk-session-token'
+});
+
+const videosApi = new VideosApi(config);
+
+async function generateVideo() {
+  try {
+    const jobResponse = await videosApi.createVideoGenerationJob({
+      configuration: {
+        topic: "Pythagorean Theorem",
+        context: "Explain the mathematical proof",
+        quality: "medium",
+        use_rag: true
+      }
+    });
+    
+    console.log('Job created:', jobResponse.job_id);
+  } catch (error) {
+    console.error('Error:', error);
+  }
+}
+
+generateVideo();
+EOF
+            ;;
+        "python")
+            cat > "$client_dir/example.py" << 'EOF'
+from video_api_client import Configuration, ApiClient, VideosApi
+from video_api_client.models import JobCreateRequest, JobConfiguration
+
+configuration = Configuration(
+    host="https://api.example.com",
+    access_token="your-clerk-session-token"
+)
+
+with ApiClient(configuration) as api_client:
+    videos_api = VideosApi(api_client)
+    
+    try:
+        job_request = JobCreateRequest(
+            configuration=JobConfiguration(
+                topic="Pythagorean Theorem",
+                context="Explain the mathematical proof",
+                quality="medium",
+                use_rag=True
+            )
+        )
+        
+        job_response = videos_api.create_video_generation_job(job_request)
+        print(f"Job created: {job_response.job_id}")
+        
+    except Exception as e:
+        print(f"Error: {e}")
+EOF
+            ;;
+    esac
+}
+
+# Language-specific post-processing functions
+post_process_typescript() {
+    local client_dir=$1
+    
+    # Create package.json if it doesn't exist
+    if [ ! -f "$client_dir/package.json" ]; then
+        cat > "$client_dir/package.json" << 'EOF'
+{
+  "name": "video-api-client",
+  "version": "1.0.0",
+  "description": "TypeScript client for Video Generation API",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc",
+    "test": "jest"
+  },
+  "dependencies": {
+    "node-fetch": "^2.6.7"
+  },
+  "devDependencies": {
+    "typescript": "^4.9.0",
+    "@types/node": "^18.0.0"
+  },
+  "keywords": ["video", "api", "client", "typescript"],
+  "author": "API Team",
+  "license": "MIT"
+}
+EOF
+    fi
+}
+
+post_process_python() {
+    local client_dir=$1
+    
+    # Create setup.py if it doesn't exist
+    if [ ! -f "$client_dir/setup.py" ]; then
+        cat > "$client_dir/setup.py" << 'EOF'
+from setuptools import setup, find_packages
+
+setup(
+    name="video-api-client",
+    version="1.0.0",
+    description="Python client for Video Generation API",
+    packages=find_packages(),
+    install_requires=[
+        "requests>=2.25.0",
+        "urllib3>=1.26.0",
+        "python-dateutil>=2.8.0"
+    ],
+    author="API Team",
+    author_email="[email protected]",
+    license="MIT"
+)
+EOF
+    fi
+}
+
+post_process_java() {
+    local client_dir=$1
+    
+    # Java post-processing would go here
+    log_info "Java client post-processing completed"
+}
+
+# Function to test generated clients
+test_clients() {
+    log_info "Testing generated clients..."
+    
+    # Test TypeScript client
+    if [ -d "$OUTPUT_DIR/typescript" ]; then
+        log_info "Testing TypeScript client..."
+        cd "$OUTPUT_DIR/typescript"
+        if [ -f "package.json" ]; then
+            npm install --silent
+            npm run build --silent 2>/dev/null || log_warning "TypeScript build failed"
+        fi
+        cd - > /dev/null
+    fi
+    
+    # Test Python client
+    if [ -d "$OUTPUT_DIR/python" ]; then
+        log_info "Testing Python client..."
+        cd "$OUTPUT_DIR/python"
+        if [ -f "setup.py" ] && command_exists python3; then
+            python3 setup.py check --quiet 2>/dev/null || log_warning "Python setup check failed"
+        fi
+        cd - > /dev/null
+    fi
+}
+
+# Function to create documentation
+create_documentation() {
+    log_info "Creating client documentation..."
+    
+    cat > "$OUTPUT_DIR/README.md" << EOF
+# Video Generation API Clients
+
+This directory contains auto-generated client libraries for the Video Generation API in multiple programming languages.
+
+## Available Clients
+
+EOF
+    
+    for dir in "$OUTPUT_DIR"/*; do
+        if [ -d "$dir" ]; then
+            language=$(basename "$dir")
+            echo "- [$language](./$language/)" >> "$OUTPUT_DIR/README.md"
+        fi
+    done
+    
+    cat >> "$OUTPUT_DIR/README.md" << EOF
+
+## Quick Start
+
+Each client directory contains:
+- Generated API client code
+- README with installation and usage instructions
+- Example code demonstrating basic usage
+- Package/project files for the respective language
+
+## Authentication
+
+All clients support Clerk authentication. Set your session token when configuring the client.
+
+## Documentation
+
+- API Documentation: https://docs.example.com
+- OpenAPI Specification: $API_URL/openapi.json
+
+## Support
+
+For issues with the generated clients:
+- Check the individual client README files
+- Visit our documentation at https://docs.example.com
+- Contact support at [email protected]
+
+Generated on: $(date)
+EOF
+}
+
+# Main function
+main() {
+    local languages=("$@")
+    
+    # Default to all languages if none specified
+    if [ ${#languages[@]} -eq 0 ]; then
+        languages=("typescript" "python" "java" "csharp" "go" "php" "ruby")
+    fi
+    
+    log_info "Starting client generation for languages: ${languages[*]}"
+    
+    # Check prerequisites
+    check_prerequisites
+    
+    # Fetch OpenAPI specification
+    OPENAPI_SPEC=$(fetch_openapi_spec)
+    
+    # Create output directory
+    mkdir -p "$OUTPUT_DIR"
+    
+    # Generate clients
+    local successful=()
+    local failed=()
+    
+    for language in "${languages[@]}"; do
+        if generate_client "$language" "$OPENAPI_SPEC"; then
+            successful+=("$language")
+        else
+            failed+=("$language")
+        fi
+    done
+    
+    # Test clients
+    test_clients
+    
+    # Create documentation
+    create_documentation
+    
+    # Print summary
+    echo
+    echo "=================================================="
+    echo "CLIENT GENERATION SUMMARY"
+    echo "=================================================="
+    
+    if [ ${#successful[@]} -gt 0 ]; then
+        log_success "Successfully generated: ${successful[*]}"
+    fi
+    
+    if [ ${#failed[@]} -gt 0 ]; then
+        log_error "Failed to generate: ${failed[*]}"
+    fi
+    
+    echo
+    log_info "Generated clients are available in: $OUTPUT_DIR"
+    
+    # Cleanup
+    rm -rf "$(dirname "$OPENAPI_SPEC")"
+    
+    # Exit with error if any generation failed
+    if [ ${#failed[@]} -gt 0 ]; then
+        exit 1
+    fi
+}
+
+# Parse command line arguments
+while [[ $# -gt 0 ]]; do
+    case $1 in
+        --api-url)
+            API_URL="$2"
+            shift 2
+            ;;
+        --output-dir)
+            OUTPUT_DIR="$2"
+            shift 2
+            ;;
+        --help)
+            echo "Usage: $0 [OPTIONS] [LANGUAGES...]"
+            echo ""
+            echo "Generate client SDKs for Video Generation API"
+            echo ""
+            echo "Options:"
+            echo "  --api-url URL      API base URL (default: http://localhost:8000)"
+            echo "  --output-dir DIR   Output directory (default: generated_clients)"
+            echo "  --help            Show this help message"
+            echo ""
+            echo "Languages:"
+            echo "  typescript python java csharp go php ruby"
+            echo ""
+            echo "Examples:"
+            echo "  $0                           # Generate all clients"
+            echo "  $0 typescript python        # Generate only TypeScript and Python"
+            echo "  $0 --api-url https://api.example.com typescript"
+            exit 0
+            ;;
+        *)
+            break
+            ;;
+    esac
+done
+
+# Run main function with remaining arguments as languages
+main "$@"

scripts/setup.py

@@ -0,0 +1,106 @@
+#!/usr/bin/env python3
+"""
+Development setup script.
+Creates necessary directories and validates configuration.
+"""
+
+import os
+import sys
+from pathlib import Path
+
+
+def create_directories():
+    """Create necessary directories for the application."""
+    directories = [
+        "uploads",
+        "videos", 
+        "logs",
+        "data",
+    ]
+    
+    for directory in directories:
+        Path(directory).mkdir(exist_ok=True)
+        print(f"✓ Created directory: {directory}")
+
+
+def check_env_file():
+    """Check if .env file exists and create from example if not."""
+    env_file = Path(".env")
+    env_example = Path(".env.example")
+    
+    if not env_file.exists():
+        if env_example.exists():
+            # Copy example to .env
+            env_file.write_text(env_example.read_text())
+            print("✓ Created .env file from .env.example")
+            print("⚠️  Please update the .env file with your actual configuration values")
+        else:
+            print("❌ .env.example file not found")
+            return False
+    else:
+        print("✓ .env file already exists")
+    
+    return True
+
+
+def validate_required_env_vars():
+    """Validate that required environment variables are set."""
+    from dotenv import load_dotenv
+    
+    load_dotenv()
+    
+    required_vars = [
+        "CLERK_SECRET_KEY",
+        "CLERK_PUBLISHABLE_KEY", 
+        "SECRET_KEY",
+    ]
+    
+    missing_vars = []
+    for var in required_vars:
+        if not os.getenv(var) or os.getenv(var) == f"your_{var.lower()}_here":
+            missing_vars.append(var)
+    
+    if missing_vars:
+        print("❌ Missing required environment variables:")
+        for var in missing_vars:
+            print(f"   - {var}")
+        print("\nPlease update your .env file with actual values.")
+        return False
+    
+    print("✓ All required environment variables are set")
+    return True
+
+
+def main():
+    """Main setup function."""
+    print("🚀 Setting up FastAPI Video Backend development environment...\n")
+    
+    # Create directories
+    create_directories()
+    print()
+    
+    # Check .env file
+    if not check_env_file():
+        sys.exit(1)
+    print()
+    
+    # Validate environment variables
+    try:
+        if not validate_required_env_vars():
+            print("\n⚠️  Setup completed with warnings. Please fix the issues above.")
+            sys.exit(1)
+    except ImportError:
+        print("⚠️  python-dotenv not installed. Skipping environment validation.")
+        print("   Install dependencies with: pip install -e .")
+    
+    print("\n✅ Development environment setup completed!")
+    print("\nNext steps:")
+    print("1. Install dependencies: pip install -e .")
+    print("2. Update .env file with your actual configuration values")
+    print("3. Start Redis server: redis-server")
+    print("4. Run the application: python -m src.app.main")
+    print("5. Visit http://localhost:8000/docs for API documentation")
+
+
+if __name__ == "__main__":
+    main()

scripts/test_clients.py

@@ -0,0 +1,579 @@
+#!/usr/bin/env python3
+"""
+Client SDK testing script for FastAPI Video Generation Backend.
+
+This script tests the generated client SDKs to ensure they work correctly
+with the API endpoints. It performs basic functionality tests and validates
+the client-server communication.
+"""
+
+import os
+import sys
+import json
+import time
+import asyncio
+import requests
+import subprocess
+from pathlib import Path
+from typing import Dict, List, Optional, Any
+import tempfile
+import logging
+
+# Set up logging
+logging.basicConfig(level=logging.INFO, format='%(asctime)s - %(levelname)s - %(message)s')
+logger = logging.getLogger(__name__)
+
+
+class ClientTester:
+    """Test suite for generated client SDKs."""
+    
+    def __init__(self, api_url: str = "http://localhost:8000", clients_dir: str = "generated_clients"):
+        self.api_url = api_url.rstrip("/")
+        self.clients_dir = Path(clients_dir)
+        self.test_results: Dict[str, Dict[str, Any]] = {}
+        
+    def check_api_availability(self) -> bool:
+        """Check if the API server is running and accessible."""
+        try:
+            logger.info(f"Checking API availability at {self.api_url}")
+            response = requests.get(f"{self.api_url}/health", timeout=10)
+            response.raise_for_status()
+            logger.info("API server is available")
+            return True
+        except requests.RequestException as e:
+            logger.error(f"API server is not available: {e}")
+            return False
+    
+    def test_openapi_spec(self) -> bool:
+        """Test if OpenAPI specification is accessible."""
+        try:
+            logger.info("Testing OpenAPI specification accessibility")
+            response = requests.get(f"{self.api_url}/openapi.json", timeout=10)
+            response.raise_for_status()
+            
+            spec = response.json()
+            
+            # Validate basic OpenAPI structure
+            required_fields = ["openapi", "info", "paths"]
+            for field in required_fields:
+                if field not in spec:
+                    logger.error(f"OpenAPI spec missing required field: {field}")
+                    return False
+            
+            logger.info("OpenAPI specification is valid")
+            return True
+            
+        except requests.RequestException as e:
+            logger.error(f"Failed to fetch OpenAPI specification: {e}")
+            return False
+        except json.JSONDecodeError as e:
+            logger.error(f"Invalid JSON in OpenAPI specification: {e}")
+            return False
+    
+    def test_typescript_client(self) -> Dict[str, Any]:
+        """Test TypeScript client."""
+        client_dir = self.clients_dir / "typescript"
+        result = {
+            "language": "typescript",
+            "exists": False,
+            "builds": False,
+            "has_examples": False,
+            "has_docs": False,
+            "errors": []
+        }
+        
+        try:
+            if not client_dir.exists():
+                result["errors"].append("Client directory does not exist")
+                return result
+            
+            result["exists"] = True
+            
+            # Check for essential files
+            essential_files = ["package.json", "README.md"]
+            for file in essential_files:
+                if not (client_dir / file).exists():
+                    result["errors"].append(f"Missing {file}")
+            
+            # Check for example file
+            if (client_dir / "example.ts").exists():
+                result["has_examples"] = True
+            
+            # Check for documentation
+            if (client_dir / "README.md").exists():
+                result["has_docs"] = True
+            
+            # Try to build the client
+            if (client_dir / "package.json").exists():
+                logger.info("Testing TypeScript client build")
+                
+                # Install dependencies
+                install_result = subprocess.run(
+                    ["npm", "install"],
+                    cwd=client_dir,
+                    capture_output=True,
+                    text=True,
+                    timeout=120
+                )
+                
+                if install_result.returncode != 0:
+                    result["errors"].append(f"npm install failed: {install_result.stderr}")
+                else:
+                    # Try to build
+                    build_result = subprocess.run(
+                        ["npm", "run", "build"],
+                        cwd=client_dir,
+                        capture_output=True,
+                        text=True,
+                        timeout=60
+                    )
+                    
+                    if build_result.returncode == 0:
+                        result["builds"] = True
+                    else:
+                        result["errors"].append(f"Build failed: {build_result.stderr}")
+            
+        except subprocess.TimeoutExpired:
+            result["errors"].append("Build timeout")
+        except Exception as e:
+            result["errors"].append(f"Unexpected error: {str(e)}")
+        
+        return result
+    
+    def test_python_client(self) -> Dict[str, Any]:
+        """Test Python client."""
+        client_dir = self.clients_dir / "python"
+        result = {
+            "language": "python",
+            "exists": False,
+            "installs": False,
+            "imports": False,
+            "has_examples": False,
+            "has_docs": False,
+            "errors": []
+        }
+        
+        try:
+            if not client_dir.exists():
+                result["errors"].append("Client directory does not exist")
+                return result
+            
+            result["exists"] = True
+            
+            # Check for essential files
+            essential_files = ["setup.py", "README.md"]
+            for file in essential_files:
+                if not (client_dir / file).exists():
+                    result["errors"].append(f"Missing {file}")
+            
+            # Check for example file
+            if (client_dir / "example.py").exists():
+                result["has_examples"] = True
+            
+            # Check for documentation
+            if (client_dir / "README.md").exists():
+                result["has_docs"] = True
+            
+            # Try to install the client in development mode
+            if (client_dir / "setup.py").exists():
+                logger.info("Testing Python client installation")
+                
+                install_result = subprocess.run(
+                    [sys.executable, "setup.py", "develop", "--user"],
+                    cwd=client_dir,
+                    capture_output=True,
+                    text=True,
+                    timeout=120
+                )
+                
+                if install_result.returncode == 0:
+                    result["installs"] = True
+                    
+                    # Try to import the client
+                    try:
+                        import importlib.util
+                        
+                        # Find the main module
+                        main_module_path = None
+                        for py_file in client_dir.rglob("*.py"):
+                            if "__init__.py" in py_file.name:
+                                main_module_path = py_file
+                                break
+                        
+                        if main_module_path:
+                            spec = importlib.util.spec_from_file_location("test_client", main_module_path)
+                            if spec and spec.loader:
+                                module = importlib.util.module_from_spec(spec)
+                                spec.loader.exec_module(module)
+                                result["imports"] = True
+                        
+                    except Exception as e:
+                        result["errors"].append(f"Import failed: {str(e)}")
+                else:
+                    result["errors"].append(f"Installation failed: {install_result.stderr}")
+            
+        except subprocess.TimeoutExpired:
+            result["errors"].append("Installation timeout")
+        except Exception as e:
+            result["errors"].append(f"Unexpected error: {str(e)}")
+        
+        return result
+    
+    def test_java_client(self) -> Dict[str, Any]:
+        """Test Java client."""
+        client_dir = self.clients_dir / "java"
+        result = {
+            "language": "java",
+            "exists": False,
+            "compiles": False,
+            "has_examples": False,
+            "has_docs": False,
+            "errors": []
+        }
+        
+        try:
+            if not client_dir.exists():
+                result["errors"].append("Client directory does not exist")
+                return result
+            
+            result["exists"] = True
+            
+            # Check for essential files
+            essential_files = ["pom.xml", "README.md"]
+            for file in essential_files:
+                if not (client_dir / file).exists():
+                    result["errors"].append(f"Missing {file}")
+            
+            # Check for example file
+            if (client_dir / "example.java").exists():
+                result["has_examples"] = True
+            
+            # Check for documentation
+            if (client_dir / "README.md").exists():
+                result["has_docs"] = True
+            
+            # Try to compile the client (if Maven is available)
+            if (client_dir / "pom.xml").exists():
+                logger.info("Testing Java client compilation")
+                
+                # Check if Maven is available
+                maven_check = subprocess.run(
+                    ["mvn", "--version"],
+                    capture_output=True,
+                    text=True,
+                    timeout=10
+                )
+                
+                if maven_check.returncode == 0:
+                    compile_result = subprocess.run(
+                        ["mvn", "compile"],
+                        cwd=client_dir,
+                        capture_output=True,
+                        text=True,
+                        timeout=180
+                    )
+                    
+                    if compile_result.returncode == 0:
+                        result["compiles"] = True
+                    else:
+                        result["errors"].append(f"Compilation failed: {compile_result.stderr}")
+                else:
+                    result["errors"].append("Maven not available for compilation test")
+            
+        except subprocess.TimeoutExpired:
+            result["errors"].append("Compilation timeout")
+        except Exception as e:
+            result["errors"].append(f"Unexpected error: {str(e)}")
+        
+        return result
+    
+    def test_client_structure(self, language: str) -> Dict[str, Any]:
+        """Test the structure of a generated client."""
+        client_dir = self.clients_dir / language
+        result = {
+            "language": language,
+            "exists": False,
+            "structure_valid": False,
+            "has_api_files": False,
+            "has_model_files": False,
+            "has_docs": False,
+            "file_count": 0,
+            "errors": []
+        }
+        
+        try:
+            if not client_dir.exists():
+                result["errors"].append("Client directory does not exist")
+                return result
+            
+            result["exists"] = True
+            
+            # Count files
+            all_files = list(client_dir.rglob("*"))
+            result["file_count"] = len([f for f in all_files if f.is_file()])
+            
+            # Check for API files
+            api_files = list(client_dir.rglob("*api*"))
+            if api_files:
+                result["has_api_files"] = True
+            
+            # Check for model files
+            model_files = list(client_dir.rglob("*model*"))
+            if model_files:
+                result["has_model_files"] = True
+            
+            # Check for documentation
+            doc_files = list(client_dir.rglob("README*")) + list(client_dir.rglob("*.md"))
+            if doc_files:
+                result["has_docs"] = True
+            
+            # Basic structure validation
+            if result["has_api_files"] and result["has_model_files"]:
+                result["structure_valid"] = True
+            
+        except Exception as e:
+            result["errors"].append(f"Unexpected error: {str(e)}")
+        
+        return result
+    
+    def run_functional_tests(self) -> Dict[str, Any]:
+        """Run functional tests against the API using generated clients."""
+        result = {
+            "api_reachable": False,
+            "openapi_valid": False,
+            "endpoints_tested": 0,
+            "endpoints_passed": 0,
+            "errors": []
+        }
+        
+        try:
+            # Test API availability
+            result["api_reachable"] = self.check_api_availability()
+            
+            # Test OpenAPI spec
+            result["openapi_valid"] = self.test_openapi_spec()
+            
+            if not result["api_reachable"]:
+                result["errors"].append("API not reachable - skipping functional tests")
+                return result
+            
+            # Test basic endpoints
+            endpoints_to_test = [
+                {"method": "GET", "path": "/health", "expected_status": 200},
+                {"method": "GET", "path": "/", "expected_status": 200},
+                {"method": "GET", "path": "/openapi.json", "expected_status": 200},
+            ]
+            
+            for endpoint in endpoints_to_test:
+                try:
+                    result["endpoints_tested"] += 1
+                    
+                    response = requests.request(
+                        endpoint["method"],
+                        f"{self.api_url}{endpoint['path']}",
+                        timeout=10
+                    )
+                    
+                    if response.status_code == endpoint["expected_status"]:
+                        result["endpoints_passed"] += 1
+                    else:
+                        result["errors"].append(
+                            f"{endpoint['method']} {endpoint['path']} returned {response.status_code}, "
+                            f"expected {endpoint['expected_status']}"
+                        )
+                        
+                except requests.RequestException as e:
+                    result["errors"].append(f"Failed to test {endpoint['path']}: {str(e)}")
+            
+        except Exception as e:
+            result["errors"].append(f"Functional test error: {str(e)}")
+        
+        return result
+    
+    def run_all_tests(self) -> Dict[str, Any]:
+        """Run all client tests."""
+        logger.info("Starting comprehensive client testing")
+        
+        # Test API functionality
+        functional_results = self.run_functional_tests()
+        
+        # Test individual clients
+        client_results = {}
+        
+        # Test TypeScript client
+        if (self.clients_dir / "typescript").exists():
+            logger.info("Testing TypeScript client")
+            client_results["typescript"] = self.test_typescript_client()
+        
+        # Test Python client
+        if (self.clients_dir / "python").exists():
+            logger.info("Testing Python client")
+            client_results["python"] = self.test_python_client()
+        
+        # Test Java client
+        if (self.clients_dir / "java").exists():
+            logger.info("Testing Java client")
+            client_results["java"] = self.test_java_client()
+        
+        # Test structure for all clients
+        structure_results = {}
+        for client_dir in self.clients_dir.iterdir():
+            if client_dir.is_dir():
+                language = client_dir.name
+                logger.info(f"Testing {language} client structure")
+                structure_results[language] = self.test_client_structure(language)
+        
+        return {
+            "functional_tests": functional_results,
+            "client_tests": client_results,
+            "structure_tests": structure_results,
+            "summary": self._generate_summary(functional_results, client_results, structure_results)
+        }
+    
+    def _generate_summary(self, functional: Dict, clients: Dict, structures: Dict) -> Dict[str, Any]:
+        """Generate test summary."""
+        total_clients = len(structures)
+        working_clients = 0
+        
+        for language, result in clients.items():
+            if language == "typescript" and result.get("builds", False):
+                working_clients += 1
+            elif language == "python" and result.get("imports", False):
+                working_clients += 1
+            elif language == "java" and result.get("compiles", False):
+                working_clients += 1
+        
+        return {
+            "total_clients_found": total_clients,
+            "clients_tested": len(clients),
+            "working_clients": working_clients,
+            "api_functional": functional.get("api_reachable", False),
+            "openapi_valid": functional.get("openapi_valid", False),
+            "endpoints_success_rate": (
+                functional.get("endpoints_passed", 0) / max(functional.get("endpoints_tested", 1), 1) * 100
+            )
+        }
+    
+    def print_results(self, results: Dict[str, Any]) -> None:
+        """Print test results in a formatted way."""
+        print("\n" + "="*60)
+        print("CLIENT SDK TEST RESULTS")
+        print("="*60)
+        
+        # Print summary
+        summary = results["summary"]
+        print(f"\nSUMMARY:")
+        print(f"  Total clients found: {summary['total_clients_found']}")
+        print(f"  Clients tested: {summary['clients_tested']}")
+        print(f"  Working clients: {summary['working_clients']}")
+        print(f"  API functional: {'✅' if summary['api_functional'] else '❌'}")
+        print(f"  OpenAPI valid: {'✅' if summary['openapi_valid'] else '❌'}")
+        print(f"  Endpoints success rate: {summary['endpoints_success_rate']:.1f}%")
+        
+        # Print functional test results
+        print(f"\nFUNCTIONAL TESTS:")
+        functional = results["functional_tests"]
+        print(f"  API reachable: {'✅' if functional['api_reachable'] else '❌'}")
+        print(f"  OpenAPI valid: {'✅' if functional['openapi_valid'] else '❌'}")
+        print(f"  Endpoints tested: {functional['endpoints_tested']}")
+        print(f"  Endpoints passed: {functional['endpoints_passed']}")
+        
+        if functional["errors"]:
+            print("  Errors:")
+            for error in functional["errors"]:
+                print(f"    - {error}")
+        
+        # Print client test results
+        print(f"\nCLIENT TESTS:")
+        for language, result in results["client_tests"].items():
+            print(f"\n  {language.upper()}:")
+            print(f"    Exists: {'✅' if result['exists'] else '❌'}")
+            
+            if language == "typescript":
+                print(f"    Builds: {'✅' if result['builds'] else '❌'}")
+            elif language == "python":
+                print(f"    Installs: {'✅' if result['installs'] else '❌'}")
+                print(f"    Imports: {'✅' if result['imports'] else '❌'}")
+            elif language == "java":
+                print(f"    Compiles: {'✅' if result['compiles'] else '❌'}")
+            
+            print(f"    Has examples: {'✅' if result['has_examples'] else '❌'}")
+            print(f"    Has docs: {'✅' if result['has_docs'] else '❌'}")
+            
+            if result["errors"]:
+                print("    Errors:")
+                for error in result["errors"]:
+                    print(f"      - {error}")
+        
+        # Print structure test results
+        print(f"\nSTRUCTURE TESTS:")
+        for language, result in results["structure_tests"].items():
+            print(f"\n  {language.upper()}:")
+            print(f"    Exists: {'✅' if result['exists'] else '❌'}")
+            print(f"    Structure valid: {'✅' if result['structure_valid'] else '❌'}")
+            print(f"    Has API files: {'✅' if result['has_api_files'] else '❌'}")
+            print(f"    Has model files: {'✅' if result['has_model_files'] else '❌'}")
+            print(f"    Has docs: {'✅' if result['has_docs'] else '❌'}")
+            print(f"    File count: {result['file_count']}")
+            
+            if result["errors"]:
+                print("    Errors:")
+                for error in result["errors"]:
+                    print(f"      - {error}")
+        
+        print("\n" + "="*60)
+
+
+def main():
+    """Main function for command-line usage."""
+    import argparse
+    
+    parser = argparse.ArgumentParser(description="Test generated client SDKs")
+    parser.add_argument(
+        "--api-url",
+        default="http://localhost:8000",
+        help="Base URL of the API (default: http://localhost:8000)"
+    )
+    parser.add_argument(
+        "--clients-dir",
+        default="generated_clients",
+        help="Directory containing generated clients (default: generated_clients)"
+    )
+    parser.add_argument(
+        "--output-file",
+        help="Save test results to JSON file"
+    )
+    parser.add_argument(
+        "--verbose",
+        action="store_true",
+        help="Enable verbose logging"
+    )
+    
+    args = parser.parse_args()
+    
+    if args.verbose:
+        logging.getLogger().setLevel(logging.DEBUG)
+    
+    # Create tester instance
+    tester = ClientTester(args.api_url, args.clients_dir)
+    
+    # Run tests
+    results = tester.run_all_tests()
+    
+    # Print results
+    tester.print_results(results)
+    
+    # Save results to file if requested
+    if args.output_file:
+        with open(args.output_file, 'w') as f:
+            json.dump(results, f, indent=2, default=str)
+        logger.info(f"Test results saved to {args.output_file}")
+    
+    # Exit with error code if tests failed
+    summary = results["summary"]
+    if not summary["api_functional"] or summary["working_clients"] == 0:
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

setup-dev.bat

@@ -0,0 +1,90 @@
+@echo off
+REM T2M FastAPI Development Setup Script for Windows
+REM This script sets up Redis, ngrok, and provides instructions for FastAPI
+
+echo 🚀 Setting up T2M FastAPI Development Environment
+echo ================================================
+
+REM Check if Docker is installed
+docker --version >nul 2>&1
+if %errorlevel% neq 0 (
+    echo ❌ Docker is not installed. Please install Docker Desktop first.
+    pause
+    exit /b 1
+)
+
+REM Check if Docker Compose is installed
+docker-compose --version >nul 2>&1
+if %errorlevel% neq 0 (
+    echo ❌ Docker Compose is not installed. Please install Docker Compose first.
+    pause
+    exit /b 1
+)
+
+REM Check if .env file exists
+if not exist ".env" (
+    echo ❌ .env file not found. Please copy .env.example to .env and configure it.
+    pause
+    exit /b 1
+)
+
+REM Check if NGROK_AUTHTOKEN is set
+findstr /C:"NGROK_AUTHTOKEN=" .env >nul
+if %errorlevel% neq 0 (
+    echo ❌ NGROK_AUTHTOKEN is not set in .env file.
+    echo    Please get your auth token from https://dashboard.ngrok.com/get-started/your-authtoken
+    echo    and add it to your .env file: NGROK_AUTHTOKEN=your_token_here
+    pause
+    exit /b 1
+)
+
+echo ✅ Prerequisites check passed
+echo.
+
+REM Start Redis and ngrok services
+echo 🔧 Starting Redis and ngrok services...
+docker-compose -f docker-compose.dev.yml up -d
+
+echo.
+echo ⏳ Waiting for services to start...
+timeout /t 5 /nobreak >nul
+
+REM Check if services are running
+docker-compose -f docker-compose.dev.yml ps
+
+echo.
+echo 🎯 Next Steps:
+echo ==============
+echo.
+echo 1. Start your FastAPI server locally:
+echo    python -m uvicorn src.app.main:app --reload --host 0.0.0.0 --port 8000
+echo.
+echo 2. Get your public ngrok URL:
+echo    - Visit: http://localhost:4040
+echo    - Copy the HTTPS URL (e.g., https://abc123.ngrok.io)
+echo.
+echo 3. Configure Clerk webhook:
+echo    - Go to https://dashboard.clerk.com/
+echo    - Navigate to Webhooks
+echo    - Add endpoint: https://your-ngrok-url.ngrok.io/api/v1/auth/webhooks/clerk
+echo    - Copy the signing secret to CLERK_WEBHOOK_SECRET in .env
+echo.
+echo 4. Test your setup:
+echo    curl https://your-ngrok-url.ngrok.io/health
+echo.
+echo 📝 Useful Commands:
+echo ==================
+echo • View logs: docker-compose -f docker-compose.dev.yml logs -f
+echo • Stop services: docker-compose -f docker-compose.dev.yml down
+echo • Restart services: docker-compose -f docker-compose.dev.yml restart
+echo • Check Redis: redis-cli ping
+echo.
+echo 🌐 URLs:
+echo ========
+echo • FastAPI (local): http://localhost:8000
+echo • FastAPI Docs: http://localhost:8000/docs
+echo • ngrok Dashboard: http://localhost:4040
+echo • Redis: localhost:6379
+echo.
+echo ✨ Development environment is ready!
+pause

setup-dev.sh

@@ -0,0 +1,108 @@
+#!/bin/bash
+
+# T2M FastAPI Development Setup Script
+# This script sets up Redis, ngrok, and provides instructions for FastAPI
+
+set -e
+
+echo "🚀 Setting up T2M FastAPI Development Environment"
+echo "================================================"
+
+# Check if Docker is installed
+if ! command -v docker &> /dev/null; then
+    echo "❌ Docker is not installed. Please install Docker first."
+    exit 1
+fi
+
+# Check if Docker Compose is installed
+if ! command -v docker-compose &> /dev/null; then
+    echo "❌ Docker Compose is not installed. Please install Docker Compose first."
+    exit 1
+fi
+
+# Check if .env file exists
+if [ ! -f ".env" ]; then
+    echo "❌ .env file not found. Please copy .env.example to .env and configure it."
+    exit 1
+fi
+
+# Check if NGROK_AUTHTOKEN is set
+if ! grep -q "NGROK_AUTHTOKEN=" .env || grep -q "NGROK_AUTHTOKEN=$" .env; then
+    echo "❌ NGROK_AUTHTOKEN is not set in .env file."
+    echo "   Please get your auth token from https://dashboard.ngrok.com/get-started/your-authtoken"
+    echo "   and add it to your .env file: NGROK_AUTHTOKEN=your_token_here"
+    exit 1
+fi
+
+echo "✅ Prerequisites check passed"
+echo ""
+
+# Start Redis and ngrok services
+echo "🔧 Starting Redis and ngrok services..."
+
+# Try the simple compose file first
+if docker-compose -f docker-compose.simple.yml up -d; then
+    echo "✅ Using simple Docker Compose configuration"
+    COMPOSE_FILE="docker-compose.simple.yml"
+else
+    echo "⚠️  Falling back to development configuration"
+    docker-compose -f docker-compose.dev.yml up -d
+    COMPOSE_FILE="docker-compose.dev.yml"
+fi
+
+echo ""
+echo "⏳ Waiting for services to start..."
+sleep 5
+
+# Check if Redis is running
+if docker-compose -f $COMPOSE_FILE ps redis | grep -q "Up"; then
+    echo "✅ Redis is running on localhost:6379"
+else
+    echo "❌ Redis failed to start"
+    exit 1
+fi
+
+# Check if ngrok is running
+if docker-compose -f $COMPOSE_FILE ps ngrok | grep -q "Up"; then
+    echo "✅ ngrok is running"
+    echo "   📊 ngrok Web Interface: http://localhost:4040"
+else
+    echo "❌ ngrok failed to start"
+    exit 1
+fi
+
+echo ""
+echo "🎯 Next Steps:"
+echo "=============="
+echo ""
+echo "1. Start your FastAPI server locally:"
+echo "   python -m uvicorn src.app.main:app --reload --host 0.0.0.0 --port 8000"
+echo ""
+echo "2. Get your public ngrok URL:"
+echo "   - Visit: http://localhost:4040"
+echo "   - Copy the HTTPS URL (e.g., https://abc123.ngrok.io)"
+echo ""
+echo "3. Configure Clerk webhook:"
+echo "   - Go to https://dashboard.clerk.com/"
+echo "   - Navigate to Webhooks"
+echo "   - Add endpoint: https://your-ngrok-url.ngrok.io/api/v1/auth/webhooks/clerk"
+echo "   - Copy the signing secret to CLERK_WEBHOOK_SECRET in .env"
+echo ""
+echo "4. Test your setup:"
+echo "   curl https://your-ngrok-url.ngrok.io/health"
+echo ""
+echo "📝 Useful Commands:"
+echo "=================="
+echo "• View logs: docker-compose -f $COMPOSE_FILE logs -f"
+echo "• Stop services: docker-compose -f $COMPOSE_FILE down"
+echo "• Restart services: docker-compose -f $COMPOSE_FILE restart"
+echo "• Check Redis: redis-cli ping"
+echo ""
+echo "🌐 URLs:"
+echo "========"
+echo "• FastAPI (local): http://localhost:8000"
+echo "• FastAPI Docs: http://localhost:8000/docs"
+echo "• ngrok Dashboard: http://localhost:4040"
+echo "• Redis: localhost:6379"
+echo ""
+echo "✨ Development environment is ready!"

simple_app.py

@@ -0,0 +1,76 @@
+#!/usr/bin/env python3
+
+from fastapi import FastAPI
+from pydantic import BaseModel
+from simple_config import SimpleSettings
+
+# Create settings
+settings = SimpleSettings()
+
+# Create FastAPI app
+app = FastAPI(
+    title=settings.app_name,
+    debug=settings.debug,
+    description="A simple FastAPI application for testing",
+    version="1.0.0",
+)
+
+# Pydantic models for API documentation
+class MessageRequest(BaseModel):
+    message: str
+    user_id: str = None
+
+class MessageResponse(BaseModel):
+    response: str
+    timestamp: str
+
+@app.get("/")
+async def root():
+    return {
+        "message": f"Welcome to {settings.app_name}",
+        "status": "running"
+    }
+
+@app.get("/health")
+async def health():
+    return {
+        "status": "healthy",
+        "app": settings.app_name,
+        "redis_host": settings.redis_host,
+        "redis_port": settings.redis_port,
+    }
+
+@app.get("/config")
+async def config():
+    return {
+        "origins": settings.get_allowed_origins(),
+        "methods": settings.get_allowed_methods(),
+        "clerk_configured": bool(settings.clerk_secret_key),
+    }
+
+@app.post("/api/message", response_model=MessageResponse)
+async def send_message(request: MessageRequest):
+    """Send a message and get a response."""
+    from datetime import datetime
+    return MessageResponse(
+        response=f"Received: {request.message}",
+        timestamp=datetime.now().isoformat()
+    )
+
+@app.get("/api/users/{user_id}")
+async def get_user(user_id: str):
+    """Get user information by ID."""
+    return {
+        "user_id": user_id,
+        "name": f"User {user_id}",
+        "status": "active"
+    }
+
+if __name__ == "__main__":
+    import uvicorn
+    uvicorn.run(
+        "simple_app:app",
+        host=settings.host,
+        port=settings.port,
+        reload=True,
+    )

simple_config.py

@@ -0,0 +1,48 @@
+#!/usr/bin/env python3
+
+from typing import List
+from pydantic import Field
+from pydantic_settings import BaseSettings
+
+
+class SimpleSettings(BaseSettings):
+    """Simple settings for testing."""
+    
+    # Application settings
+    app_name: str = Field(default="FastAPI Video Backend", env="APP_NAME")
+    debug: bool = Field(default=False, env="DEBUG")
+    host: str = Field(default="0.0.0.0", env="HOST")
+    port: int = Field(default=8000, env="PORT")
+    
+    # CORS settings as strings
+    allowed_origins: str = Field(
+        default="http://localhost:3000,http://localhost:8080",
+        env="ALLOWED_ORIGINS"
+    )
+    allowed_methods: str = Field(
+        default="GET,POST,PUT,DELETE,OPTIONS",
+        env="ALLOWED_METHODS"
+    )
+    
+    # Redis settings
+    redis_host: str = Field(default="localhost", env="REDIS_HOST")
+    redis_port: int = Field(default=6379, env="REDIS_PORT")
+    
+    # Clerk settings
+    clerk_secret_key: str = Field(default="", env="CLERK_SECRET_KEY")
+    clerk_publishable_key: str = Field(default="", env="CLERK_PUBLISHABLE_KEY")
+    
+    def get_allowed_origins(self) -> List[str]:
+        return [origin.strip() for origin in self.allowed_origins.split(",")]
+    
+    def get_allowed_methods(self) -> List[str]:
+        return [method.strip() for method in self.allowed_methods.split(",")]
+
+
+if __name__ == "__main__":
+    settings = SimpleSettings()
+    print("✅ Simple config loaded successfully!")
+    print(f"App: {settings.app_name}")
+    print(f"Origins: {settings.get_allowed_origins()}")
+    print(f"Methods: {settings.get_allowed_methods()}")
+    print(f"Clerk Secret: {settings.clerk_secret_key[:20]}..." if settings.clerk_secret_key else "No Clerk secret")

src/app/__init__.py

@@ -0,0 +1 @@
+# FastAPI Video Generation Backend

src/app/api/__init__.py

@@ -0,0 +1 @@
+# API layer

src/app/api/dependencies.py

@@ -0,0 +1,490 @@
+"""
+FastAPI dependencies for authentication, services, and common utilities.
+
+This module provides reusable dependencies for FastAPI endpoints,
+including authentication, service injection, and request validation.
+"""
+
+import logging
+from typing import Dict, Any, Optional
+from fastapi import Depends, HTTPException, status, Request, Header
+from redis.asyncio import Redis
+
+from ..core.auth import verify_clerk_token, AuthenticationError, extract_bearer_token
+from ..core.redis import get_redis
+from ..services.video_service import VideoService
+from ..services.job_service import JobService
+from ..services.queue_service import QueueService
+from ..services.file_service import FileService
+
+logger = logging.getLogger(__name__)
+
+
+async def get_current_user(
+    authorization: Optional[str] = Header(None),
+    redis_client: Redis = Depends(get_redis)
+) -> Dict[str, Any]:
+    """
+    FastAPI dependency to get current authenticated user.
+    
+    Extracts and validates the Clerk session token from the Authorization header,
+    then returns user information and token claims.
+    
+    Args:
+        authorization: Authorization header with Bearer token
+        redis_client: Redis client for caching user info
+        
+    Returns:
+        Dict containing user information and token claims
+        
+    Raises:
+        HTTPException: If authentication fails
+    """
+    try:
+        if not authorization:
+            raise AuthenticationError("Missing authorization header")
+        
+        # Extract bearer token
+        token = extract_bearer_token(authorization)
+        
+        # Verify token and get user info
+        auth_info = await verify_clerk_token(token)
+        
+        # Extract email safely for logging
+        user_info = auth_info["user_info"]
+        user_id = user_info.get("id", "unknown")
+        
+        # Extract email from email_addresses array if available
+        email = user_info.get("email")
+        if not email and "email_addresses" in user_info:
+            email_addresses = user_info.get("email_addresses", [])
+            if email_addresses:
+                primary_email_id = user_info.get("primary_email_address_id")
+                if primary_email_id:
+                    primary_email = next((e for e in email_addresses if e.get("id") == primary_email_id), None)
+                    if primary_email:
+                        email = primary_email.get("email_address")
+                # Fallback to first email
+                if not email:
+                    email = email_addresses[0].get("email_address")
+        
+        logger.debug(
+            "User authenticated successfully",
+            user_id=user_id,
+            email=email or "no-email"
+        )
+        
+        return auth_info
+        
+    except AuthenticationError as e:
+        logger.warning(f"Authentication failed: {e}")
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail=str(e),
+            headers={"WWW-Authenticate": "Bearer"}
+        )
+    except Exception as e:
+        logger.error(f"Authentication error: {e}", exc_info=True)
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail="Authentication service error"
+        )
+
+
+async def get_optional_user(
+    authorization: Optional[str] = Header(None),
+    redis_client: Redis = Depends(get_redis)
+) -> Optional[Dict[str, Any]]:
+    """
+    FastAPI dependency to get current user if authenticated (optional).
+    
+    Similar to get_current_user but returns None if no authentication
+    is provided instead of raising an exception.
+    
+    Args:
+        authorization: Authorization header with Bearer token (optional)
+        redis_client: Redis client for caching user info
+        
+    Returns:
+        Dict containing user information or None if not authenticated
+    """
+    try:
+        if not authorization:
+            return None
+        
+        return await get_current_user(authorization, redis_client)
+        
+    except HTTPException:
+        # Return None for optional authentication
+        return None
+    except Exception as e:
+        logger.error(f"Optional authentication error: {e}", exc_info=True)
+        return None
+
+
+def get_video_service(
+    redis_client: Redis = Depends(get_redis)
+) -> VideoService:
+    """
+    FastAPI dependency to get VideoService instance.
+    
+    Args:
+        redis_client: Redis client dependency
+        
+    Returns:
+        VideoService instance
+    """
+    return VideoService(redis_client)
+
+
+def get_job_service(
+    redis_client: Redis = Depends(get_redis)
+) -> JobService:
+    """
+    FastAPI dependency to get JobService instance.
+    
+    Args:
+        redis_client: Redis client dependency
+        
+    Returns:
+        JobService instance
+    """
+    return JobService(redis_client)
+
+
+def get_queue_service(
+    redis_client: Redis = Depends(get_redis)
+) -> QueueService:
+    """
+    FastAPI dependency to get QueueService instance.
+    
+    Args:
+        redis_client: Redis client dependency
+        
+    Returns:
+        QueueService instance
+    """
+    return QueueService(redis_client)
+
+
+def get_file_service(
+    redis_client: Redis = Depends(get_redis)
+) -> FileService:
+    """
+    FastAPI dependency to get FileService instance.
+    
+    Args:
+        redis_client: Redis client dependency
+        
+    Returns:
+        FileService instance
+    """
+    return FileService(redis_client)
+
+
+class PaginationParams:
+    """
+    Pagination parameters for list endpoints.
+    """
+    
+    def __init__(
+        self,
+        page: int = 1,
+        items_per_page: int = 10,
+        max_items_per_page: int = 100
+    ):
+        # Validate page number
+        if page < 1:
+            raise HTTPException(
+                status_code=status.HTTP_400_BAD_REQUEST,
+                detail="Page number must be greater than 0"
+            )
+        
+        # Validate items per page
+        if items_per_page < 1:
+            raise HTTPException(
+                status_code=status.HTTP_400_BAD_REQUEST,
+                detail="Items per page must be greater than 0"
+            )
+        
+        if items_per_page > max_items_per_page:
+            raise HTTPException(
+                status_code=status.HTTP_400_BAD_REQUEST,
+                detail=f"Items per page cannot exceed {max_items_per_page}"
+            )
+        
+        self.page = page
+        self.items_per_page = items_per_page
+        self.offset = (page - 1) * items_per_page
+    
+    @property
+    def limit(self) -> int:
+        """Get limit for database queries."""
+        return self.items_per_page
+
+
+def get_pagination_params(
+    page: int = 1,
+    items_per_page: int = 10
+) -> PaginationParams:
+    """
+    FastAPI dependency to get pagination parameters.
+    
+    Args:
+        page: Page number (1-based)
+        items_per_page: Number of items per page
+        
+    Returns:
+        PaginationParams instance
+        
+    Raises:
+        HTTPException: If parameters are invalid
+    """
+    return PaginationParams(page=page, items_per_page=items_per_page)
+
+
+class JobFilters:
+    """
+    Filtering parameters for job list endpoints.
+    """
+    
+    def __init__(
+        self,
+        status: Optional[str] = None,
+        job_type: Optional[str] = None,
+        priority: Optional[str] = None,
+        created_after: Optional[str] = None,
+        created_before: Optional[str] = None
+    ):
+        self.status = status
+        self.job_type = job_type
+        self.priority = priority
+        self.created_after = created_after
+        self.created_before = created_before
+    
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert filters to dictionary for service layer."""
+        return {
+            k: v for k, v in {
+                "status": self.status,
+                "job_type": self.job_type,
+                "priority": self.priority,
+                "created_after": self.created_after,
+                "created_before": self.created_before
+            }.items() if v is not None
+        }
+
+
+def get_job_filters(
+    status: Optional[str] = None,
+    job_type: Optional[str] = None,
+    priority: Optional[str] = None,
+    created_after: Optional[str] = None,
+    created_before: Optional[str] = None
+) -> JobFilters:
+    """
+    FastAPI dependency to get job filtering parameters.
+    
+    Args:
+        status: Filter by job status
+        job_type: Filter by job type
+        priority: Filter by job priority
+        created_after: Filter jobs created after this date (ISO format)
+        created_before: Filter jobs created before this date (ISO format)
+        
+    Returns:
+        JobFilters instance
+    """
+    return JobFilters(
+        status=status,
+        job_type=job_type,
+        priority=priority,
+        created_after=created_after,
+        created_before=created_before
+    )
+
+
+def validate_job_ownership(
+    job_user_id: str,
+    current_user: Dict[str, Any]
+) -> None:
+    """
+    Validate that the current user owns the specified job.
+    
+    Args:
+        job_user_id: User ID from the job
+        current_user: Current authenticated user
+        
+    Raises:
+        HTTPException: If user doesn't own the job
+    """
+    if job_user_id != current_user["user_info"]["id"]:
+        raise HTTPException(
+            status_code=status.HTTP_403_FORBIDDEN,
+            detail="Access denied: You don't own this resource"
+        )
+
+
+def validate_request_size(
+    request: Request,
+    max_size_mb: int = 10
+) -> None:
+    """
+    Validate request content size.
+    
+    Args:
+        request: FastAPI request object
+        max_size_mb: Maximum allowed size in MB
+        
+    Raises:
+        HTTPException: If request is too large
+    """
+    content_length = request.headers.get("content-length")
+    if content_length:
+        size_mb = int(content_length) / (1024 * 1024)
+        if size_mb > max_size_mb:
+            raise HTTPException(
+                status_code=status.HTTP_413_REQUEST_ENTITY_TOO_LARGE,
+                detail=f"Request too large. Maximum size: {max_size_mb}MB"
+            )
+
+
+async def rate_limit_check(
+    current_user: Dict[str, Any],
+    redis_client: Redis,
+    operation: str,
+    limit: int = 10,
+    window_seconds: int = 60
+) -> None:
+    """
+    Check rate limits for user operations.
+    
+    Args:
+        current_user: Current authenticated user
+        redis_client: Redis client for rate limit storage
+        operation: Operation name for rate limiting
+        limit: Maximum operations per window
+        window_seconds: Time window in seconds
+        
+    Raises:
+        HTTPException: If rate limit exceeded
+    """
+    user_id = current_user["user_info"]["id"]
+    key = f"rate_limit:{user_id}:{operation}"
+    
+    try:
+        # Get current count
+        current_count = await redis_client.get(key)
+        current_count = int(current_count) if current_count else 0
+        
+        if current_count >= limit:
+            raise HTTPException(
+                status_code=status.HTTP_429_TOO_MANY_REQUESTS,
+                detail=f"Rate limit exceeded for {operation}. Try again later.",
+                headers={"Retry-After": str(window_seconds)}
+            )
+        
+        # Increment counter
+        pipe = redis_client.pipeline()
+        pipe.incr(key)
+        pipe.expire(key, window_seconds)
+        await pipe.execute()
+        
+    except HTTPException:
+        raise
+    except Exception as e:
+        logger.error(f"Rate limit check failed: {e}", exc_info=True)
+        # Don't block requests if rate limiting fails
+        pass
+
+
+# Additional authentication dependencies for compatibility
+async def get_authenticated_user(
+    authorization: Optional[str] = Header(None),
+    redis_client: Redis = Depends(get_redis)
+) -> Dict[str, Any]:
+    """
+    Alias for get_current_user for backward compatibility.
+    
+    Returns the user_info portion of the authentication data.
+    """
+    auth_info = await get_current_user(authorization, redis_client)
+    return auth_info["user_info"]
+
+
+async def get_authenticated_user_id(
+    authorization: Optional[str] = Header(None),
+    redis_client: Redis = Depends(get_redis)
+) -> str:
+    """
+    Get just the user ID from authentication.
+    
+    Returns:
+        str: The authenticated user's ID
+    """
+    auth_info = await get_current_user(authorization, redis_client)
+    return auth_info["user_info"]["id"]
+
+
+async def get_verified_user(
+    authorization: Optional[str] = Header(None),
+    redis_client: Redis = Depends(get_redis)
+) -> Dict[str, Any]:
+    """
+    Get authenticated user that has verified email.
+    
+    Returns:
+        Dict containing verified user information
+        
+    Raises:
+        HTTPException: If user is not verified
+    """
+    auth_info = await get_current_user(authorization, redis_client)
+    user_info = auth_info["user_info"]
+    
+    # Check email verification status from email_addresses array
+    email_verified = user_info.get("email_verified", False)
+    
+    # If not directly available, check in email_addresses array
+    if not email_verified and "email_addresses" in user_info:
+        email_addresses = user_info.get("email_addresses", [])
+        if email_addresses:
+            primary_email_id = user_info.get("primary_email_address_id")
+            if primary_email_id:
+                primary_email = next((e for e in email_addresses if e.get("id") == primary_email_id), None)
+                if primary_email:
+                    verification = primary_email.get("verification", {})
+                    email_verified = verification.get("status") == "verified"
+            
+            # Fallback to first email verification
+            if not email_verified and email_addresses:
+                first_email = email_addresses[0]
+                verification = first_email.get("verification", {})
+                email_verified = verification.get("status") == "verified"
+    
+    if not email_verified:
+        raise HTTPException(
+            status_code=status.HTTP_403_FORBIDDEN,
+            detail="Email verification required"
+        )
+    
+    return user_info
+
+
+async def get_request_context(request: Request) -> Dict[str, Any]:
+    """
+    Get request context information.
+    
+    Args:
+        request: FastAPI request object
+        
+    Returns:
+        Dict containing request context
+    """
+    return {
+        "path": str(request.url.path),
+        "method": request.method,
+        "client_ip": request.client.host if request.client else "unknown",
+        "user_agent": request.headers.get("user-agent", "unknown"),
+        "timestamp": logger.info("Request context retrieved")
+    }

src/app/api/v1/__init__.py

@@ -0,0 +1 @@
+# API version 1

src/app/api/v1/auth.py

@@ -0,0 +1,392 @@
+"""
+Authentication endpoints for testing Clerk integration.
+
+This module provides endpoints for testing authentication functionality
+and retrieving user information.
+"""
+
+import logging
+from typing import Dict, Any, Optional
+from datetime import datetime
+from fastapi import APIRouter, Depends, HTTPException, status
+from fastapi.responses import JSONResponse
+
+from ...models.user import UserProfile, UserPermissions, UserRole, AuthResponse
+from ...api.dependencies import (
+    get_authenticated_user,
+    get_authenticated_user_id,
+    get_verified_user,
+    get_optional_user,
+    get_request_context
+)
+from ...core.auth import clerk_manager
+
+logger = logging.getLogger(__name__)
+
+router = APIRouter(prefix="/auth", tags=["Authentication"])
+
+
+@router.get("/me", response_model=UserProfile)
+async def get_current_user_profile(
+    user_info: Dict[str, Any] = Depends(get_authenticated_user)
+) -> UserProfile:
+    """
+    Get current authenticated user profile.
+    
+    Returns:
+        UserProfile: Current user's profile information
+    """
+    try:
+        # Handle potentially missing or invalid datetime fields from Clerk
+        def parse_datetime_field(value) -> Optional[datetime]:
+            """Parse datetime field that might be None, timestamp (ms), or string."""
+            if value is None:
+                return None
+            if isinstance(value, datetime):
+                return value
+            if isinstance(value, (int, float)):
+                try:
+                    # Convert milliseconds timestamp to datetime
+                    return datetime.fromtimestamp(value / 1000)
+                except (ValueError, OSError):
+                    return None
+            if isinstance(value, str):
+                try:
+                    # Handle ISO format with Z suffix
+                    return datetime.fromisoformat(value.replace('Z', '+00:00'))
+                except (ValueError, AttributeError):
+                    return None
+            return None
+        
+        # Extract actual user data from nested structure
+        # Handle both nested ('user_info') and direct user data structures
+        if isinstance(user_info, dict) and 'user_info' in user_info:
+            # Nested structure from get_current_user
+            actual_user_info = user_info['user_info']
+        else:
+            # Direct user_info from get_verified_user
+            actual_user_info = user_info
+        
+        # Debug logging to understand the Clerk API response structure
+        logger.debug(f"Processing user profile for user_id: {actual_user_info.get('id', 'unknown')}")
+        if "email_addresses" in actual_user_info:
+            logger.debug(f"Email addresses found: {len(actual_user_info['email_addresses'])} entries")
+        
+        # Validate we have the required user ID
+        if not actual_user_info.get('id'):
+            logger.error(f"No user ID found in user_info: {user_info}")
+            raise HTTPException(
+                status_code=status.HTTP_401_UNAUTHORIZED,
+                detail="Invalid user information"
+            )
+        
+        # Extract email from email_addresses array (Clerk standard structure)
+        email = actual_user_info.get("email")
+        email_verified = actual_user_info.get("email_verified", False)
+        
+        # Look for email in email_addresses array if not found directly
+        email_addresses = actual_user_info.get("email_addresses", [])
+        if not email and email_addresses:
+            # Get primary email or first verified email
+            primary_email_id = actual_user_info.get("primary_email_address_id")
+            if primary_email_id:
+                primary_email = next((e for e in email_addresses if e.get("id") == primary_email_id), None)
+                if primary_email:
+                    email = primary_email.get("email_address")
+                    # Check verification status from the email object
+                    verification = primary_email.get("verification", {})
+                    email_verified = verification.get("status") == "verified"
+            
+            # Fallback to first email if no primary found
+            if not email and email_addresses:
+                first_email = email_addresses[0]
+                email = first_email.get("email_address")
+                verification = first_email.get("verification", {})
+                email_verified = verification.get("status") == "verified"
+        
+        # Build full name with proper fallbacks
+        first_name = actual_user_info.get('first_name') or ''
+        last_name = actual_user_info.get('last_name') or ''
+        full_name = f"{first_name} {last_name}".strip()
+        
+        # Fallback chain for full_name
+        if not full_name:
+            full_name = actual_user_info.get("username") or email or "Unknown User"
+        
+        # Convert Clerk user info to UserProfile
+        user_profile = UserProfile(
+            id=actual_user_info["id"],
+            username=actual_user_info.get("username"),
+            full_name=full_name,
+            email=email,
+            image_url=actual_user_info.get("image_url"),
+            email_verified=email_verified,
+            created_at=parse_datetime_field(actual_user_info.get("created_at")),
+            last_sign_in_at=parse_datetime_field(actual_user_info.get("last_sign_in_at"))
+        )
+        
+        logger.info(f"User profile retrieved successfully for user {actual_user_info['id']}: {user_profile.dict()}")
+        return user_profile
+        
+    except Exception as e:
+        logger.error(f"Failed to get user profile: {e}", exc_info=True)
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail="Failed to retrieve user profile"
+        )
+
+
+@router.get("/permissions")
+async def get_user_permissions(
+    user_info: Dict[str, Any] = Depends(get_verified_user)
+) -> UserPermissions:
+    """
+    Get current user's permissions.
+    
+    Returns:
+        UserPermissions: User's permissions and access levels
+    """
+    try:
+        # Extract actual user data from nested structure
+        if isinstance(user_info, dict) and 'user_info' in user_info:
+            # Nested structure from get_current_user
+            actual_user_info = user_info['user_info']
+        else:
+            # Direct user_info from get_verified_user
+            actual_user_info = user_info
+        
+        # Validate user_info structure
+        if not actual_user_info or not actual_user_info.get("id"):
+            logger.error(f"Invalid user_info structure: {user_info}")
+            raise HTTPException(
+                status_code=status.HTTP_401_UNAUTHORIZED,
+                detail="Invalid user information"
+            )
+        
+        # For now, assign basic user role
+        # In a real implementation, you would check Clerk metadata or roles
+        user_role = UserRole.USER
+        
+        # Check if user is admin (placeholder logic)
+        # This would be based on Clerk metadata or roles
+        
+        # Extract email from email_addresses array (Clerk standard structure)
+        user_email = actual_user_info.get("email")
+        
+        # Look for email in email_addresses array if not found directly
+        email_addresses = actual_user_info.get("email_addresses", [])
+        if not user_email and email_addresses:
+            # Get primary email or first email
+            primary_email_id = actual_user_info.get("primary_email_address_id")
+            if primary_email_id:
+                primary_email = next((e for e in email_addresses if e.get("id") == primary_email_id), None)
+                if primary_email:
+                    user_email = primary_email.get("email_address")
+            
+            # Fallback to first email if no primary found
+            if not user_email and email_addresses:
+                first_email = email_addresses[0]
+                user_email = first_email.get("email_address")
+        
+        if user_email and user_email.endswith("@admin.com"):
+            user_role = UserRole.ADMIN
+        
+        permissions = UserPermissions.from_user_role(
+            user_id=actual_user_info["id"],
+            role=user_role
+        )
+        
+        logger.info(f"Permissions retrieved for user {actual_user_info['id']}: {user_role}")
+        return permissions
+        
+    except Exception as e:
+        logger.error(f"Failed to get user permissions: {e}")
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail="Failed to retrieve user permissions"
+        )
+
+
+@router.get("/status")
+async def get_auth_status(
+    user_info: Dict[str, Any] = Depends(get_optional_user),
+    request_context: Dict[str, Any] = Depends(get_request_context)
+) -> Dict[str, Any]:
+    """
+    Get authentication status for current request.
+    
+    This endpoint works with or without authentication to show auth status.
+    
+    Returns:
+        Dict containing authentication status and user info if authenticated
+    """
+    try:
+        # Debug logging to understand the structure
+        logger.info(f"Auth status check - user_info type: {type(user_info)}, content: {user_info}")
+        logger.info(f"Auth status check - request_context: {request_context}")
+        
+        # Extract actual user data from nested structure
+        if isinstance(user_info, dict) and 'user_info' in user_info:
+            # Nested structure from get_current_user
+            actual_user_info = user_info['user_info']
+        elif user_info:
+            # Direct user_info from get_verified_user
+            actual_user_info = user_info
+        else:
+            actual_user_info = {}
+        
+        if user_info and actual_user_info.get("id"):
+            # Extract email from email_addresses array (Clerk standard structure)
+            email = actual_user_info.get("email")
+            email_verified = actual_user_info.get("email_verified", False)
+            
+            # Look for email in email_addresses array if not found directly
+            email_addresses = actual_user_info.get("email_addresses", [])
+            if not email and email_addresses:
+                # Get primary email or first email
+                primary_email_id = actual_user_info.get("primary_email_address_id")
+                if primary_email_id:
+                    primary_email = next((e for e in email_addresses if e.get("id") == primary_email_id), None)
+                    if primary_email:
+                        email = primary_email.get("email_address")
+                        # Check verification status from the email object
+                        verification = primary_email.get("verification", {})
+                        email_verified = verification.get("status") == "verified"
+                
+                # Fallback to first email if no primary found
+                if not email and email_addresses:
+                    first_email = email_addresses[0]
+                    email = first_email.get("email_address")
+                    verification = first_email.get("verification", {})
+                    email_verified = verification.get("status") == "verified"
+            
+            return {
+                "authenticated": True,
+                "user_id": actual_user_info.get("id"),
+                "email": email,
+                "email_verified": email_verified,
+                "username": actual_user_info.get("username"),
+                "request_context": {
+                    "path": request_context.get("path", "unknown"),
+                    "method": request_context.get("method", "unknown"),
+                    "client_ip": request_context.get("client_ip", "unknown")
+                }
+            }
+        else:
+            return {
+                "authenticated": False,
+                "message": "No authentication provided",
+                "request_context": {
+                    "path": request_context.get("path", "unknown"),
+                    "method": request_context.get("method", "unknown"),
+                    "client_ip": request_context.get("client_ip", "unknown")
+                }
+            }
+            
+    except Exception as e:
+        logger.error(f"Failed to get auth status: {e}")
+        return {
+            "authenticated": False,
+            "error": f"Failed to determine authentication status: {str(e)}",
+            "request_context": {
+                "path": request_context.get("path", "unknown") if request_context else "unknown",
+                "method": request_context.get("method", "unknown") if request_context else "unknown",
+                "client_ip": request_context.get("client_ip", "unknown") if request_context else "unknown"
+            }
+        }
+
+
+@router.post("/verify")
+async def verify_token(
+    user_info: Dict[str, Any] = Depends(get_verified_user)
+) -> Dict[str, Any]:
+    """
+    Verify authentication token and return user information.
+    
+    This endpoint requires a verified user (email verified).
+    
+    Returns:
+        Dict containing verification status and user information
+    """
+    try:
+        return {
+            "verified": True,
+            "user_id": user_info["id"],
+            "email": user_info.get("email"),
+            "email_verified": user_info.get("email_verified", False),
+            "message": "Token verified successfully"
+        }
+        
+    except Exception as e:
+        logger.error(f"Token verification failed: {e}")
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail="Token verification failed"
+        )
+
+
+@router.get("/health")
+async def auth_health_check() -> Dict[str, Any]:
+    """
+    Check authentication service health.
+    
+    Returns:
+        Dict containing authentication service health status
+    """
+    try:
+        # Check Clerk manager health
+        clerk_health = clerk_manager.health_check()
+        
+        return {
+            "status": "healthy" if clerk_health["status"] == "healthy" else "unhealthy",
+            "clerk": clerk_health,
+            "message": "Authentication service health check completed"
+        }
+        
+    except Exception as e:
+        logger.error(f"Auth health check failed: {e}")
+        return {
+            "status": "unhealthy",
+            "error": str(e),
+            "message": "Authentication service health check failed"
+        }
+
+
+@router.get("/test-protected")
+async def test_protected_endpoint(
+    user_id: str = Depends(get_authenticated_user_id)
+) -> Dict[str, Any]:
+    """
+    Test endpoint that requires authentication.
+    
+    Returns:
+        Dict containing success message and user ID
+    """
+    logger.info(f"Protected endpoint accessed by user {user_id}")
+    
+    return {
+        "message": "Successfully accessed protected endpoint",
+        "user_id": user_id,
+        "timestamp": datetime.utcnow().isoformat() + "Z"
+    }
+
+
+@router.get("/test-verified")
+async def test_verified_endpoint(
+    user_info: Dict[str, Any] = Depends(get_verified_user)
+) -> Dict[str, Any]:
+    """
+    Test endpoint that requires verified user.
+    
+    Returns:
+        Dict containing success message and user information
+    """
+    logger.info(f"Verified endpoint accessed by user {user_info['id']}")
+    
+    return {
+        "message": "Successfully accessed verified user endpoint",
+        "user_id": user_info["id"],
+        "email": user_info.get("email"),
+        "email_verified": user_info.get("email_verified", False),
+        "timestamp": datetime.utcnow().isoformat() + "Z"
+    }

src/app/api/v1/files.py

@@ -0,0 +1,978 @@
+"""
+File management API endpoints.
+
+This module implements REST API endpoints for file operations including
+upload, download, metadata retrieval, and file management.
+"""
+
+import logging
+from typing import Optional, List, Dict, Any
+from pathlib import Path
+
+from fastapi import (
+    APIRouter, Depends, HTTPException, status, UploadFile, File, Form,
+    Request, Response, Query
+)
+from fastapi.responses import StreamingResponse, FileResponse
+from redis.asyncio import Redis
+import aiofiles
+
+from ...core.redis import get_redis
+from ...core.auth import verify_clerk_token
+from ...models.file import (
+    FileUploadRequest, FileUploadResponse, FileMetadataResponse,
+    FileListResponse, FileStatsResponse, FileCleanupRequest,
+    FileCleanupResponse, FileType, FileBatchUploadRequest,
+    FileBatchUploadResponse, FileSearchRequest
+)
+from ...models.common import PaginatedResponse
+from ...services.file_service import FileService
+from ...api.dependencies import get_current_user, get_file_service
+from ...utils.file_utils import FileMetadata
+
+logger = logging.getLogger(__name__)
+router = APIRouter(prefix="/files", tags=["files"])
+
+
+@router.post("/upload", response_model=FileUploadResponse, status_code=status.HTTP_201_CREATED)
+async def upload_file(
+    file: UploadFile = File(..., description="File to upload"),
+    file_type: Optional[FileType] = Form(None, description="File type category"),
+    subdirectory: Optional[str] = Form(None, description="Optional subdirectory"),
+    description: Optional[str] = Form(None, description="File description"),
+    current_user: Dict[str, Any] = Depends(get_current_user),
+    file_service: FileService = Depends(get_file_service)
+) -> FileUploadResponse:
+    """
+    Upload a single file.
+    
+    This endpoint accepts a file upload with optional metadata and stores it
+    securely with proper validation and access controls.
+    
+    Args:
+        file: File to upload
+        file_type: Optional file type category
+        subdirectory: Optional subdirectory for organization
+        description: Optional file description
+        current_user: Authenticated user information
+        file_service: File service dependency
+        
+    Returns:
+        FileUploadResponse with upload details
+        
+    Raises:
+        HTTPException: If upload fails or validation errors occur
+    """
+    try:
+        logger.info(
+            "Starting file upload",
+            filename=file.filename,
+            content_type=file.content_type,
+            user_id=current_user["user_info"]["id"],
+            file_type=file_type
+        )
+        
+        # Upload file
+        file_metadata = await file_service.upload_file(
+            file=file,
+            user_id=current_user["user_info"]["id"],
+            file_type=file_type.value if file_type else None,
+            subdirectory=subdirectory
+        )
+        
+        # Generate download URL
+        download_url = await file_service.generate_download_url(
+            file_id=Path(file_metadata.filename).stem,
+            user_id=current_user["user_info"]["id"]
+        )
+        
+        logger.info(
+            "File uploaded successfully",
+            file_id=Path(file_metadata.filename).stem,
+            filename=file_metadata.filename,
+            file_size=file_metadata.file_size,
+            user_id=current_user["user_info"]["id"]
+        )
+        
+        return FileUploadResponse(
+            file_id=Path(file_metadata.filename).stem,
+            filename=file_metadata.filename,
+            file_type=FileType(file_metadata.file_type),
+            file_size=file_metadata.file_size,
+            download_url=download_url or f"/api/v1/files/{Path(file_metadata.filename).stem}/download",
+            created_at=file_metadata.created_at
+        )
+        
+    except HTTPException:
+        raise
+    except Exception as e:
+        logger.error(
+            "Failed to upload file",
+            filename=file.filename,
+            user_id=current_user["user_info"]["id"],
+            error=str(e),
+            exc_info=True
+        )
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail=f"Failed to upload file: {str(e)}"
+        )
+
+
+@router.post("/batch-upload", response_model=FileBatchUploadResponse)
+async def batch_upload_files(
+    files: List[UploadFile] = File(..., description="Files to upload"),
+    file_type: Optional[FileType] = Form(None, description="File type for all files"),
+    subdirectory: Optional[str] = Form(None, description="Subdirectory for all files"),
+    description: Optional[str] = Form(None, description="Description for all files"),
+    current_user: Dict[str, Any] = Depends(get_current_user),
+    file_service: FileService = Depends(get_file_service)
+) -> FileBatchUploadResponse:
+    """
+    Upload multiple files in batch.
+    
+    Args:
+        files: List of files to upload
+        file_type: Optional file type for all files
+        subdirectory: Optional subdirectory for all files
+        description: Optional description for all files
+        current_user: Authenticated user information
+        file_service: File service dependency
+        
+    Returns:
+        FileBatchUploadResponse with batch upload results
+    """
+    try:
+        if len(files) > 50:
+            raise HTTPException(
+                status_code=status.HTTP_422_UNPROCESSABLE_ENTITY,
+                detail="Maximum 50 files allowed per batch"
+            )
+        
+        successful_uploads = []
+        failed_uploads = []
+        
+        logger.info(
+            "Starting batch file upload",
+            file_count=len(files),
+            user_id=current_user["user_info"]["id"]
+        )
+        
+        for file in files:
+            try:
+                # Upload individual file
+                file_metadata = await file_service.upload_file(
+                    file=file,
+                    user_id=current_user["user_info"]["id"],
+                    file_type=file_type.value if file_type else None,
+                    subdirectory=subdirectory
+                )
+                
+                # Generate download URL
+                download_url = await file_service.generate_download_url(
+                    file_id=Path(file_metadata.filename).stem,
+                    user_id=current_user["user_info"]["id"]
+                )
+                
+                successful_uploads.append(FileUploadResponse(
+                    file_id=Path(file_metadata.filename).stem,
+                    filename=file_metadata.filename,
+                    file_type=FileType(file_metadata.file_type),
+                    file_size=file_metadata.file_size,
+                    download_url=download_url or f"/api/v1/files/{Path(file_metadata.filename).stem}/download",
+                    created_at=file_metadata.created_at
+                ))
+                
+            except Exception as e:
+                failed_uploads.append({
+                    "filename": file.filename,
+                    "error": str(e),
+                    "error_type": type(e).__name__
+                })
+        
+        logger.info(
+            "Batch upload completed",
+            total_files=len(files),
+            successful=len(successful_uploads),
+            failed=len(failed_uploads),
+            user_id=current_user["user_info"]["id"]
+        )
+        
+        return FileBatchUploadResponse(
+            successful_uploads=successful_uploads,
+            failed_uploads=failed_uploads,
+            total_files=len(files),
+            success_count=len(successful_uploads),
+            failure_count=len(failed_uploads)
+        )
+        
+    except HTTPException:
+        raise
+    except Exception as e:
+        logger.error(f"Batch upload failed: {e}", exc_info=True)
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail=f"Batch upload failed: {str(e)}"
+        )
+
+
+@router.get("/{file_id}/download")
+async def download_file(
+    file_id: str,
+    request: Request,
+    inline: bool = Query(False, description="Serve file inline instead of attachment"),
+    current_user: Dict[str, Any] = Depends(get_current_user),
+    file_service: FileService = Depends(get_file_service)
+) -> StreamingResponse:
+    """
+    Download a file by ID with range request support and caching.
+    
+    Args:
+        file_id: File identifier
+        request: FastAPI request object
+        inline: Whether to serve inline or as attachment
+        current_user: Authenticated user information
+        file_service: File service dependency
+        
+    Returns:
+        StreamingResponse with file content
+        
+    Raises:
+        HTTPException: If file not found or access denied
+    """
+    try:
+        # Get file metadata
+        file_metadata = await file_service.get_file_metadata(
+            file_id=file_id,
+            user_id=current_user["user_info"]["id"]
+        )
+        
+        if not file_metadata:
+            raise HTTPException(
+                status_code=status.HTTP_404_NOT_FOUND,
+                detail="File not found"
+            )
+        
+        logger.info(
+            "Serving file download",
+            file_id=file_id,
+            filename=file_metadata.filename,
+            user_id=current_user["user_info"]["id"],
+            inline=inline
+        )
+        
+        # Track file access
+        from ...utils.file_cache import track_file_access
+        await track_file_access(
+            file_id=file_id,
+            user_id=current_user["user_info"]["id"],
+            access_type="download"
+        )
+        
+        # Use enhanced file serving with user context
+        from ...utils.file_serving import serve_file_secure
+        
+        return await serve_file_secure(
+            file_path=file_metadata.file_path,
+            file_type=file_metadata.file_type,
+            original_filename=file_metadata.original_filename,
+            request=request,
+            inline=inline,
+            enable_caching=True,
+            user_id=current_user["user_info"]["id"]
+        )
+        
+    except HTTPException:
+        raise
+    except Exception as e:
+        logger.error(f"Failed to download file: {e}", exc_info=True)
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail=f"Failed to download file: {str(e)}"
+        )
+
+
+@router.get("/{file_id}/metadata", response_model=FileMetadataResponse)
+async def get_file_metadata(
+    file_id: str,
+    current_user: Dict[str, Any] = Depends(get_current_user),
+    file_service: FileService = Depends(get_file_service)
+) -> FileMetadataResponse:
+    """
+    Get file metadata by ID.
+    
+    Args:
+        file_id: File identifier
+        current_user: Authenticated user information
+        file_service: File service dependency
+        
+    Returns:
+        FileMetadataResponse with file metadata
+        
+    Raises:
+        HTTPException: If file not found or access denied
+    """
+    try:
+        file_metadata = await file_service.get_file_metadata(
+            file_id=file_id,
+            user_id=current_user["user_info"]["id"]
+        )
+        
+        if not file_metadata:
+            raise HTTPException(
+                status_code=status.HTTP_404_NOT_FOUND,
+                detail="File not found"
+            )
+        
+        # Generate download URL
+        download_url = await file_service.generate_download_url(
+            file_id=file_id,
+            user_id=current_user["user_info"]["id"]
+        )
+        
+        return FileMetadataResponse(
+            id=file_id,
+            filename=file_metadata.filename,
+            original_filename=file_metadata.original_filename,
+            file_type=FileType(file_metadata.file_type),
+            mime_type=file_metadata.mime_type,
+            file_size=file_metadata.file_size,
+            checksum=file_metadata.checksum,
+            created_at=file_metadata.created_at,
+            download_url=download_url,
+            metadata=file_metadata.metadata
+        )
+        
+    except HTTPException:
+        raise
+    except Exception as e:
+        logger.error(f"Failed to get file metadata: {e}", exc_info=True)
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail=f"Failed to get file metadata: {str(e)}"
+        )
+
+
+@router.get("", response_model=FileListResponse)
+async def list_files(
+    file_type: Optional[FileType] = Query(None, description="Filter by file type"),
+    page: int = Query(1, ge=1, description="Page number"),
+    items_per_page: int = Query(20, ge=1, le=100, description="Items per page"),
+    current_user: Dict[str, Any] = Depends(get_current_user),
+    file_service: FileService = Depends(get_file_service)
+) -> FileListResponse:
+    """
+    List user's files with pagination and filtering.
+    
+    Args:
+        file_type: Optional file type filter
+        page: Page number
+        items_per_page: Items per page
+        current_user: Authenticated user information
+        file_service: File service dependency
+        
+    Returns:
+        FileListResponse with paginated file list
+    """
+    try:
+        # Get paginated files
+        paginated_response = await file_service.get_user_files(
+            user_id=current_user["user_info"]["id"],
+            file_type=file_type.value if file_type else None,
+            page=page,
+            items_per_page=items_per_page
+        )
+        
+        # Convert to response format
+        files = []
+        for file_metadata in paginated_response.data:
+            download_url = await file_service.generate_download_url(
+                file_id=Path(file_metadata.filename).stem,
+                user_id=current_user["user_info"]["id"]
+            )
+            
+            files.append(FileMetadataResponse(
+                id=Path(file_metadata.filename).stem,
+                filename=file_metadata.filename,
+                original_filename=file_metadata.original_filename,
+                file_type=FileType(file_metadata.file_type),
+                mime_type=file_metadata.mime_type,
+                file_size=file_metadata.file_size,
+                checksum=file_metadata.checksum,
+                created_at=file_metadata.created_at,
+                download_url=download_url,
+                metadata=file_metadata.metadata
+            ))
+        
+        return FileListResponse(
+            files=files,
+            total_count=paginated_response.total_count,
+            page=page,
+            items_per_page=items_per_page,
+            has_next=page * items_per_page < paginated_response.total_count,
+            has_previous=page > 1
+        )
+        
+    except Exception as e:
+        logger.error(f"Failed to list files: {e}", exc_info=True)
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail=f"Failed to list files: {str(e)}"
+        )
+
+
+@router.delete("/{file_id}")
+async def delete_file(
+    file_id: str,
+    current_user: Dict[str, Any] = Depends(get_current_user),
+    file_service: FileService = Depends(get_file_service)
+) -> Dict[str, Any]:
+    """
+    Delete a file by ID.
+    
+    Args:
+        file_id: File identifier
+        current_user: Authenticated user information
+        file_service: File service dependency
+        
+    Returns:
+        Success message
+        
+    Raises:
+        HTTPException: If file not found or deletion fails
+    """
+    try:
+        success = await file_service.delete_file(
+            file_id=file_id,
+            user_id=current_user["user_info"]["id"]
+        )
+        
+        if not success:
+            raise HTTPException(
+                status_code=status.HTTP_404_NOT_FOUND,
+                detail="File not found or already deleted"
+            )
+        
+        logger.info(
+            "File deleted successfully",
+            file_id=file_id,
+            user_id=current_user["user_info"]["id"]
+        )
+        
+        return {"message": "File deleted successfully", "file_id": file_id}
+        
+    except HTTPException:
+        raise
+    except Exception as e:
+        logger.error(f"Failed to delete file: {e}", exc_info=True)
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail=f"Failed to delete file: {str(e)}"
+        )
+
+
+@router.get("/stats", response_model=FileStatsResponse)
+async def get_file_stats(
+    current_user: Dict[str, Any] = Depends(get_current_user),
+    file_service: FileService = Depends(get_file_service)
+) -> FileStatsResponse:
+    """
+    Get file statistics for the current user.
+    
+    Args:
+        current_user: Authenticated user information
+        file_service: File service dependency
+        
+    Returns:
+        FileStatsResponse with user's file statistics
+    """
+    try:
+        stats = await file_service.get_file_stats(
+            user_id=current_user["user_info"]["id"]
+        )
+        
+        return FileStatsResponse(
+            total_files=stats.get("total_files", 0),
+            total_size=stats.get("total_size", 0),
+            by_type=stats.get("by_type", {}),
+            recent_uploads=stats.get("recent_uploads", 0)
+        )
+        
+    except Exception as e:
+        logger.error(f"Failed to get file stats: {e}", exc_info=True)
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail=f"Failed to get file stats: {str(e)}"
+        )
+
+
+@router.post("/cleanup", response_model=FileCleanupResponse)
+async def cleanup_files(
+    request: FileCleanupRequest,
+    current_user: Dict[str, Any] = Depends(get_current_user),
+    file_service: FileService = Depends(get_file_service)
+) -> FileCleanupResponse:
+    """
+    Clean up old files (admin only).
+    
+    Args:
+        request: Cleanup request parameters
+        current_user: Authenticated user information
+        file_service: File service dependency
+        
+    Returns:
+        FileCleanupResponse with cleanup results
+        
+    Raises:
+        HTTPException: If user is not admin or cleanup fails
+    """
+    try:
+        # Check if user is admin (you may need to implement admin role checking)
+        user_roles = current_user.get("user_info", {}).get("roles", [])
+        if "admin" not in user_roles:
+            raise HTTPException(
+                status_code=status.HTTP_403_FORBIDDEN,
+                detail="Admin access required"
+            )
+        
+        if request.dry_run:
+            # For dry run, just return what would be cleaned
+            return FileCleanupResponse(
+                files_cleaned=0,
+                metadata_cleaned=0,
+                retention_days=request.retention_days,
+                dry_run=True
+            )
+        
+        # Perform cleanup
+        cleanup_stats = await file_service.cleanup_expired_files(
+            retention_days=request.retention_days
+        )
+        
+        logger.info(
+            "File cleanup completed",
+            **cleanup_stats,
+            user_id=current_user["user_info"]["id"]
+        )
+        
+        return FileCleanupResponse(
+            files_cleaned=cleanup_stats.get("files_cleaned", 0),
+            metadata_cleaned=cleanup_stats.get("metadata_cleaned", 0),
+            retention_days=request.retention_days,
+            dry_run=False
+        )
+        
+    except HTTPException:
+        raise
+    except Exception as e:
+        logger.error(f"Failed to cleanup files: {e}", exc_info=True)
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail=f"Failed to cleanup files: {str(e)}"
+        )
+
+
+@router.get("/{file_id}/thumbnail")
+async def get_file_thumbnail(
+    file_id: str,
+    size: str = Query("medium", pattern="^(small|medium|large)$", description="Thumbnail size"),
+    request: Request = None,
+    current_user: Dict[str, Any] = Depends(get_current_user),
+    file_service: FileService = Depends(get_file_service)
+) -> StreamingResponse:
+    """
+    Get thumbnail for image or video file.
+    
+    Args:
+        file_id: File identifier
+        size: Thumbnail size (small, medium, large)
+        request: FastAPI request object
+        current_user: Authenticated user information
+        file_service: File service dependency
+        
+    Returns:
+        StreamingResponse with thumbnail image
+        
+    Raises:
+        HTTPException: If file not found or thumbnail not available
+    """
+    try:
+        # Get file metadata
+        file_metadata = await file_service.get_file_metadata(
+            file_id=file_id,
+            user_id=current_user["user_info"]["id"]
+        )
+        
+        if not file_metadata:
+            raise HTTPException(
+                status_code=status.HTTP_404_NOT_FOUND,
+                detail="File not found"
+            )
+        
+        # Check if file type supports thumbnails
+        if file_metadata.file_type not in ['image', 'video']:
+            raise HTTPException(
+                status_code=status.HTTP_422_UNPROCESSABLE_ENTITY,
+                detail="Thumbnails not available for this file type"
+            )
+        
+        # For now, return a placeholder response
+        # In a real implementation, you would generate/serve actual thumbnails
+        raise HTTPException(
+            status_code=status.HTTP_501_NOT_IMPLEMENTED,
+            detail="Thumbnail generation not yet implemented"
+        )
+        
+    except HTTPException:
+        raise
+    except Exception as e:
+        logger.error(f"Failed to get thumbnail: {e}", exc_info=True)
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail=f"Failed to get thumbnail: {str(e)}"
+        )
+
+
+@router.get("/{file_id}/stream")
+async def stream_file(
+    file_id: str,
+    quality: str = Query("auto", description="Stream quality"),
+    request: Request = None,
+    current_user: Dict[str, Any] = Depends(get_current_user),
+    file_service: FileService = Depends(get_file_service)
+) -> StreamingResponse:
+    """
+    Stream video or audio file with adaptive quality.
+    
+    Args:
+        file_id: File identifier
+        quality: Stream quality setting
+        request: FastAPI request object
+        current_user: Authenticated user information
+        file_service: File service dependency
+        
+    Returns:
+        StreamingResponse with media stream
+        
+    Raises:
+        HTTPException: If file not found or streaming not supported
+    """
+    try:
+        # Get file metadata
+        file_metadata = await file_service.get_file_metadata(
+            file_id=file_id,
+            user_id=current_user["user_info"]["id"]
+        )
+        
+        if not file_metadata:
+            raise HTTPException(
+                status_code=status.HTTP_404_NOT_FOUND,
+                detail="File not found"
+            )
+        
+        # Check if file type supports streaming
+        if file_metadata.file_type not in ['video', 'audio']:
+            raise HTTPException(
+                status_code=status.HTTP_422_UNPROCESSABLE_ENTITY,
+                detail="Streaming not available for this file type"
+            )
+        
+        logger.info(
+            "Serving file stream",
+            file_id=file_id,
+            filename=file_metadata.filename,
+            quality=quality,
+            user_id=current_user["user_info"]["id"]
+        )
+        
+        # Track file access
+        from ...utils.file_cache import track_file_access
+        await track_file_access(
+            file_id=file_id,
+            user_id=current_user["user_info"]["id"],
+            access_type="stream"
+        )
+        
+        # Use enhanced file serving with inline=True for streaming
+        from ...utils.file_serving import serve_file_secure
+        
+        return await serve_file_secure(
+            file_path=file_metadata.file_path,
+            file_type=file_metadata.file_type,
+            original_filename=file_metadata.original_filename,
+            request=request,
+            inline=True,  # Serve inline for streaming
+            enable_caching=True
+        )
+        
+    except HTTPException:
+        raise
+    except Exception as e:
+        logger.error(f"Failed to stream file: {e}", exc_info=True)
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail=f"Failed to stream file: {str(e)}"
+        )
+
+
+@router.get("/{file_id}/info")
+async def get_file_info(
+    file_id: str,
+    current_user: Dict[str, Any] = Depends(get_current_user),
+    file_service: FileService = Depends(get_file_service)
+) -> Dict[str, Any]:
+    """
+    Get comprehensive file information including URLs.
+    
+    Args:
+        file_id: File identifier
+        current_user: Authenticated user information
+        file_service: File service dependency
+        
+    Returns:
+        Dictionary with file information and access URLs
+        
+    Raises:
+        HTTPException: If file not found or access denied
+    """
+    try:
+        file_metadata = await file_service.get_file_metadata(
+            file_id=file_id,
+            user_id=current_user["user_info"]["id"]
+        )
+        
+        if not file_metadata:
+            raise HTTPException(
+                status_code=status.HTTP_404_NOT_FOUND,
+                detail="File not found"
+            )
+        
+        # Generate various URLs
+        from ...utils.file_serving import (
+            generate_secure_file_url,
+            generate_thumbnail_url,
+            generate_streaming_url
+        )
+        
+        urls = {
+            "download": generate_secure_file_url(file_id, file_metadata.file_type),
+            "download_inline": generate_secure_file_url(file_id, file_metadata.file_type, inline=True),
+        }
+        
+        # Add type-specific URLs
+        if file_metadata.file_type in ['image', 'video']:
+            urls["thumbnail_small"] = generate_thumbnail_url(file_id, "small")
+            urls["thumbnail_medium"] = generate_thumbnail_url(file_id, "medium")
+            urls["thumbnail_large"] = generate_thumbnail_url(file_id, "large")
+        
+        if file_metadata.file_type in ['video', 'audio']:
+            urls["stream"] = generate_streaming_url(file_id)
+        
+        return {
+            "file_id": file_id,
+            "filename": file_metadata.filename,
+            "original_filename": file_metadata.original_filename,
+            "file_type": file_metadata.file_type,
+            "mime_type": file_metadata.mime_type,
+            "file_size": file_metadata.file_size,
+            "created_at": file_metadata.created_at.isoformat(),
+            "metadata": file_metadata.metadata,
+            "urls": urls
+        }
+        
+    except HTTPException:
+        raise
+    except Exception as e:
+        logger.error(f"Failed to get file info: {e}", exc_info=True)
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail=f"Failed to get file info: {str(e)}"
+        )
+
+
+@router.get("/{file_id}/analytics")
+async def get_file_analytics(
+    file_id: str,
+    current_user: Dict[str, Any] = Depends(get_current_user),
+    file_service: FileService = Depends(get_file_service)
+) -> Dict[str, Any]:
+    """
+    Get file access analytics and statistics.
+    
+    Args:
+        file_id: File identifier
+        current_user: Authenticated user information
+        file_service: File service dependency
+        
+    Returns:
+        Dictionary with file analytics
+        
+    Raises:
+        HTTPException: If file not found or access denied
+    """
+    try:
+        # Verify file ownership
+        file_metadata = await file_service.get_file_metadata(
+            file_id=file_id,
+            user_id=current_user["user_info"]["id"]
+        )
+        
+        if not file_metadata:
+            raise HTTPException(
+                status_code=status.HTTP_404_NOT_FOUND,
+                detail="File not found"
+            )
+        
+        # Get access statistics
+        from ...utils.file_cache import get_file_access_statistics
+        access_stats = await get_file_access_statistics(file_id)
+        
+        return {
+            "file_id": file_id,
+            "filename": file_metadata.filename,
+            "access_statistics": access_stats,
+            "file_size": file_metadata.file_size,
+            "created_at": file_metadata.created_at.isoformat()
+        }
+        
+    except HTTPException:
+        raise
+    except Exception as e:
+        logger.error(f"Failed to get file analytics: {e}", exc_info=True)
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail=f"Failed to get file analytics: {str(e)}"
+        )
+
+
+@router.get("/{file_id}/secure")
+async def secure_file_access(
+    file_id: str,
+    request: Request,
+    user_id: str = Query(..., description="User ID from signed URL"),
+    expires: str = Query(..., description="Expiration timestamp"),
+    signature: str = Query(..., description="URL signature"),
+    file_type: Optional[str] = Query(None, description="File type"),
+    inline: Optional[str] = Query("false", description="Serve inline"),
+    size: Optional[str] = Query(None, description="Thumbnail size"),
+    quality: Optional[str] = Query(None, description="Stream quality"),
+    file_service: FileService = Depends(get_file_service)
+) -> StreamingResponse:
+    """
+    Secure file access endpoint using signed URLs.
+    
+    This endpoint provides secure file access without requiring authentication
+    headers, using signed URLs with expiration and integrity verification.
+    
+    Args:
+        file_id: File identifier
+        request: FastAPI request object
+        user_id: User ID from signed URL
+        expires: Expiration timestamp
+        signature: URL signature for verification
+        file_type: Optional file type
+        inline: Whether to serve inline
+        size: Thumbnail size (for thumbnails)
+        quality: Stream quality (for streaming)
+        file_service: File service dependency
+        
+    Returns:
+        StreamingResponse with file content
+        
+    Raises:
+        HTTPException: If URL is invalid, expired, or file not found
+    """
+    try:
+        # Verify signed URL
+        from ...utils.secure_url_generator import verify_url_signature
+        
+        params = {
+            'user_id': user_id,
+            'expires': expires,
+            'signature': signature
+        }
+        
+        if file_type:
+            params['file_type'] = file_type
+        if inline:
+            params['inline'] = inline
+        if size:
+            params['size'] = size
+        if quality:
+            params['quality'] = quality
+        
+        verification_result = verify_url_signature(file_id, params)
+        
+        if not verification_result['valid']:
+            logger.warning(
+                "Invalid signed URL access attempt",
+                file_id=file_id,
+                user_id=user_id,
+                error=verification_result['error']
+            )
+            raise HTTPException(
+                status_code=status.HTTP_403_FORBIDDEN,
+                detail=f"Invalid URL: {verification_result['error']}"
+            )
+        
+        # Get file metadata
+        file_metadata = await file_service.get_file_metadata(
+            file_id=file_id,
+            user_id=verification_result['user_id']
+        )
+        
+        if not file_metadata:
+            raise HTTPException(
+                status_code=status.HTTP_404_NOT_FOUND,
+                detail="File not found"
+            )
+        
+        logger.info(
+            "Serving secure file access",
+            file_id=file_id,
+            user_id=verification_result['user_id'],
+            file_type=verification_result.get('file_type'),
+            inline=verification_result['inline']
+        )
+        
+        # Track file access
+        from ...utils.file_cache import track_file_access
+        access_type = "download"
+        if verification_result.get('file_type') == "thumbnail":
+            access_type = "thumbnail"
+        elif verification_result.get('file_type') == "stream":
+            access_type = "stream"
+        
+        await track_file_access(
+            file_id=file_id,
+            user_id=verification_result['user_id'],
+            access_type=access_type
+        )
+        
+        # Serve file using enhanced file serving
+        from ...utils.file_serving import serve_file_secure
+        
+        return await serve_file_secure(
+            file_path=file_metadata.file_path,
+            file_type=file_metadata.file_type,
+            original_filename=file_metadata.original_filename,
+            request=request,
+            inline=verification_result['inline'],
+            enable_caching=True,
+            user_id=verification_result['user_id']
+        )
+        
+    except HTTPException:
+        raise
+    except Exception as e:
+        logger.error(
+            "Failed to serve secure file access",
+            file_id=file_id,
+            user_id=user_id,
+            error=str(e),
+            exc_info=True
+        )
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail=f"Failed to serve file: {str(e)}"
+        )

src/app/api/v1/jobs.py

@@ -0,0 +1,532 @@
+"""
+Job management API endpoints.
+
+This module implements REST API endpoints for job management operations,
+including job listing, cancellation, deletion, and log retrieval.
+"""
+
+import logging
+from typing import Optional, Dict, Any, List
+from datetime import datetime
+
+from fastapi import APIRouter, Depends, HTTPException, status, Query, Request
+from redis.asyncio import Redis
+
+from ...core.redis import get_redis, RedisKeyManager, redis_json_get, redis_json_set
+from ...core.cache import cache_response, CacheConfig
+from ...core.performance import performance_monitor
+from ...models.job import (
+    JobListResponse, JobResponse, JobStatus, Job,
+    JobStatusResponse, JobType, JobPriority
+)
+from ...services.job_service import JobService
+from ...api.dependencies import (
+    get_current_user, get_job_service, get_pagination_params,
+    get_job_filters, PaginationParams, JobFilters, validate_job_ownership
+)
+
+logger = logging.getLogger(__name__)
+router = APIRouter(prefix="/jobs", tags=["jobs"])
+
+
+@router.get("", response_model=JobListResponse)
+async def list_jobs(
+    request: Request,
+    current_user: Dict[str, Any] = Depends(get_current_user),
+    pagination: PaginationParams = Depends(get_pagination_params),
+    filters: JobFilters = Depends(get_job_filters),
+    job_service: JobService = Depends(get_job_service)
+) -> JobListResponse:
+    """
+    List jobs for the current user with pagination and filtering.
+    
+    This endpoint returns a paginated list of jobs belonging to the current user,
+    with optional filtering by status, type, priority, and creation date.
+    
+    Args:
+        current_user: Authenticated user information
+        pagination: Pagination parameters
+        filters: Job filtering parameters
+        job_service: Job service dependency
+        
+    Returns:
+        JobListResponse with paginated job list
+        
+    Raises:
+        HTTPException: If job retrieval fails
+    """
+    try:
+        user_id = current_user["user_info"]["id"]
+        
+        logger.info(
+            "Listing jobs for user",
+            user_id=user_id,
+            page=pagination.page,
+            items_per_page=pagination.items_per_page,
+            filters=filters.to_dict()
+        )
+        
+        # Get jobs from service
+        jobs_result = await job_service.get_jobs_paginated(
+            user_id=user_id,
+            limit=pagination.limit,
+            offset=pagination.offset,
+            filters=filters.to_dict()
+        )
+        
+        # Convert jobs to response format
+        job_responses = []
+        for job in jobs_result["jobs"]:
+            job_responses.append(JobResponse(
+                job_id=job.id,
+                status=job.status,
+                progress=job.progress,
+                created_at=job.created_at,
+                estimated_completion=job.progress.estimated_completion
+            ))
+        
+        # Calculate pagination info
+        total_count = jobs_result["total_count"]
+        has_next = (pagination.offset + pagination.items_per_page) < total_count
+        has_previous = pagination.page > 1
+        
+        logger.info(
+            "Retrieved jobs for user",
+            user_id=user_id,
+            job_count=len(job_responses),
+            total_count=total_count
+        )
+        
+        return JobListResponse(
+            jobs=job_responses,
+            total_count=total_count,
+            page=pagination.page,
+            items_per_page=pagination.items_per_page,
+            has_next=has_next,
+            has_previous=has_previous
+        )
+        
+    except Exception as e:
+        logger.error(
+            "Failed to list jobs",
+            user_id=current_user["user_info"]["id"],
+            error=str(e),
+            exc_info=True
+        )
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail=f"Failed to retrieve jobs: {str(e)}"
+        )
+
+
+@router.post("/{job_id}/cancel", response_model=Dict[str, Any])
+async def cancel_job(
+    job_id: str,
+    current_user: Dict[str, Any] = Depends(get_current_user),
+    job_service: JobService = Depends(get_job_service),
+    redis_client: Redis = Depends(get_redis)
+) -> Dict[str, Any]:
+    """
+    Cancel a specific job.
+    
+    This endpoint attempts to cancel a job if it's in a cancellable state
+    (queued or processing). Completed or already cancelled jobs cannot be cancelled.
+    
+    Args:
+        job_id: Unique job identifier
+        current_user: Authenticated user information
+        job_service: Job service dependency
+        redis_client: Redis client dependency
+        
+    Returns:
+        Dict with cancellation status and message
+        
+    Raises:
+        HTTPException: If job not found, access denied, or cancellation fails
+    """
+    try:
+        # Get job from Redis
+        job_key = RedisKeyManager.job_key(job_id)
+        job_data = await redis_json_get(redis_client, job_key)
+        
+        if not job_data:
+            raise HTTPException(
+                status_code=status.HTTP_404_NOT_FOUND,
+                detail=f"Job {job_id} not found"
+            )
+        
+        job = Job(**job_data)
+        
+        # Verify user owns this job
+        validate_job_ownership(job.user_id, current_user)
+        
+        # Check if job can be cancelled
+        if not job.can_be_cancelled:
+            raise HTTPException(
+                status_code=status.HTTP_409_CONFLICT,
+                detail=f"Job cannot be cancelled. Current status: {job.status}"
+            )
+        
+        logger.info(
+            "Cancelling job",
+            job_id=job_id,
+            current_status=job.status,
+            user_id=current_user["user_info"]["id"]
+        )
+        
+        # Cancel job using service
+        success = await job_service.cancel_job(job_id)
+        
+        if not success:
+            raise HTTPException(
+                status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+                detail="Failed to cancel job"
+            )
+        
+        logger.info(
+            "Job cancelled successfully",
+            job_id=job_id,
+            user_id=current_user["user_info"]["id"]
+        )
+        
+        return {
+            "success": True,
+            "message": f"Job {job_id} has been cancelled",
+            "job_id": job_id,
+            "previous_status": job.status,
+            "new_status": "cancelled",
+            "cancelled_at": datetime.utcnow().isoformat()
+        }
+        
+    except HTTPException:
+        raise
+    except Exception as e:
+        logger.error(
+            "Failed to cancel job",
+            job_id=job_id,
+            user_id=current_user["user_info"]["id"],
+            error=str(e),
+            exc_info=True
+        )
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail=f"Failed to cancel job: {str(e)}"
+        )
+
+
+@router.delete("/{job_id}", response_model=Dict[str, Any])
+async def delete_job(
+    job_id: str,
+    current_user: Dict[str, Any] = Depends(get_current_user),
+    job_service: JobService = Depends(get_job_service),
+    redis_client: Redis = Depends(get_redis)
+) -> Dict[str, Any]:
+    """
+    Delete a specific job (soft delete).
+    
+    This endpoint performs a soft delete on a job, marking it as deleted
+    but preserving the data for audit purposes. The job will no longer
+    appear in normal job listings.
+    
+    Args:
+        job_id: Unique job identifier
+        current_user: Authenticated user information
+        job_service: Job service dependency
+        redis_client: Redis client dependency
+        
+    Returns:
+        Dict with deletion status and message
+        
+    Raises:
+        HTTPException: If job not found, access denied, or deletion fails
+    """
+    try:
+        # Get job from Redis
+        job_key = RedisKeyManager.job_key(job_id)
+        job_data = await redis_json_get(redis_client, job_key)
+        
+        if not job_data:
+            raise HTTPException(
+                status_code=status.HTTP_404_NOT_FOUND,
+                detail=f"Job {job_id} not found"
+            )
+        
+        job = Job(**job_data)
+        
+        # Verify user owns this job
+        validate_job_ownership(job.user_id, current_user)
+        
+        # Check if job is already deleted
+        if job.is_deleted:
+            raise HTTPException(
+                status_code=status.HTTP_409_CONFLICT,
+                detail="Job is already deleted"
+            )
+        
+        logger.info(
+            "Deleting job",
+            job_id=job_id,
+            status=job.status,
+            user_id=current_user["user_info"]["id"]
+        )
+        
+        # Cancel job if it's still active
+        if job.can_be_cancelled:
+            await job_service.cancel_job(job_id)
+        
+        # Perform soft delete
+        success = await job_service.soft_delete_job(job_id)
+        
+        if not success:
+            raise HTTPException(
+                status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+                detail="Failed to delete job"
+            )
+        
+        # Remove from user's job index
+        user_jobs_key = RedisKeyManager.user_jobs_key(current_user["user_info"]["id"])
+        await redis_client.srem(user_jobs_key, job_id)
+        
+        # Clean up related data (video metadata, cache entries)
+        await job_service.cleanup_job_data(job_id)
+        
+        logger.info(
+            "Job deleted successfully",
+            job_id=job_id,
+            user_id=current_user["user_info"]["id"]
+        )
+        
+        return {
+            "success": True,
+            "message": f"Job {job_id} has been deleted",
+            "job_id": job_id,
+            "deleted_at": datetime.utcnow().isoformat()
+        }
+        
+    except HTTPException:
+        raise
+    except Exception as e:
+        logger.error(
+            "Failed to delete job",
+            job_id=job_id,
+            user_id=current_user["user_info"]["id"],
+            error=str(e),
+            exc_info=True
+        )
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail=f"Failed to delete job: {str(e)}"
+        )
+
+
+@router.get("/{job_id}/logs", response_model=Dict[str, Any])
+async def get_job_logs(
+    job_id: str,
+    current_user: Dict[str, Any] = Depends(get_current_user),
+    limit: int = Query(100, ge=1, le=1000, description="Maximum number of log entries"),
+    offset: int = Query(0, ge=0, description="Number of log entries to skip"),
+    level: Optional[str] = Query(None, description="Filter by log level (DEBUG, INFO, WARNING, ERROR)"),
+    redis_client: Redis = Depends(get_redis)
+) -> Dict[str, Any]:
+    """
+    Get processing logs for a specific job.
+    
+    This endpoint returns the processing logs for a job, which can be useful
+    for debugging failed jobs or monitoring progress in detail.
+    
+    Args:
+        job_id: Unique job identifier
+        current_user: Authenticated user information
+        limit: Maximum number of log entries to return
+        offset: Number of log entries to skip
+        level: Filter logs by level
+        redis_client: Redis client dependency
+        
+    Returns:
+        Dict with job logs and metadata
+        
+    Raises:
+        HTTPException: If job not found or access denied
+    """
+    try:
+        # Get job from Redis
+        job_key = RedisKeyManager.job_key(job_id)
+        job_data = await redis_json_get(redis_client, job_key)
+        
+        if not job_data:
+            raise HTTPException(
+                status_code=status.HTTP_404_NOT_FOUND,
+                detail=f"Job {job_id} not found"
+            )
+        
+        job = Job(**job_data)
+        
+        # Verify user owns this job
+        validate_job_ownership(job.user_id, current_user)
+        
+        logger.info(
+            "Retrieving job logs",
+            job_id=job_id,
+            limit=limit,
+            offset=offset,
+            level=level,
+            user_id=current_user["user_info"]["id"]
+        )
+        
+        # Get logs from Redis (stored as a list)
+        logs_key = f"job_logs:{job_id}"
+        
+        # Get total log count
+        total_logs = await redis_client.llen(logs_key)
+        
+        # Get log entries with pagination
+        log_entries = []
+        if total_logs > 0:
+            # Redis lists are 0-indexed, get range with offset and limit
+            end_index = offset + limit - 1
+            if end_index >= total_logs:
+                end_index = total_logs - 1
+            
+            if offset < total_logs:
+                raw_logs = await redis_client.lrange(logs_key, offset, end_index)
+                
+                # Parse and filter logs
+                for log_entry in raw_logs:
+                    try:
+                        import json
+                        log_data = json.loads(log_entry)
+                        
+                        # Filter by level if specified
+                        if level and log_data.get("level", "").upper() != level.upper():
+                            continue
+                        
+                        log_entries.append(log_data)
+                        
+                    except json.JSONDecodeError:
+                        # Handle plain text logs
+                        log_entries.append({
+                            "timestamp": datetime.utcnow().isoformat(),
+                            "level": "INFO",
+                            "message": log_entry,
+                            "source": "system"
+                        })
+        
+        # Calculate pagination info
+        has_more = (offset + limit) < total_logs
+        
+        logger.info(
+            "Retrieved job logs",
+            job_id=job_id,
+            log_count=len(log_entries),
+            total_logs=total_logs,
+            user_id=current_user["user_info"]["id"]
+        )
+        
+        return {
+            "job_id": job_id,
+            "logs": log_entries,
+            "pagination": {
+                "offset": offset,
+                "limit": limit,
+                "total_count": total_logs,
+                "returned_count": len(log_entries),
+                "has_more": has_more
+            },
+            "filters": {
+                "level": level
+            },
+            "job_info": {
+                "status": job.status,
+                "created_at": job.created_at.isoformat(),
+                "updated_at": job.updated_at.isoformat(),
+                "progress": job.progress.percentage
+            }
+        }
+        
+    except HTTPException:
+        raise
+    except Exception as e:
+        logger.error(
+            "Failed to get job logs",
+            job_id=job_id,
+            user_id=current_user["user_info"]["id"],
+            error=str(e),
+            exc_info=True
+        )
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail=f"Failed to retrieve job logs: {str(e)}"
+        )
+
+
+@router.get("/{job_id}", response_model=JobStatusResponse)
+async def get_job_details(
+    job_id: str,
+    current_user: Dict[str, Any] = Depends(get_current_user),
+    redis_client: Redis = Depends(get_redis)
+) -> JobStatusResponse:
+    """
+    Get detailed information about a specific job.
+    
+    This endpoint returns comprehensive job information including status,
+    progress, configuration, metrics, and error details if applicable.
+    
+    Args:
+        job_id: Unique job identifier
+        current_user: Authenticated user information
+        redis_client: Redis client dependency
+        
+    Returns:
+        JobStatusResponse with detailed job information
+        
+    Raises:
+        HTTPException: If job not found or access denied
+    """
+    try:
+        # Get job from Redis
+        job_key = RedisKeyManager.job_key(job_id)
+        job_data = await redis_json_get(redis_client, job_key)
+        
+        if not job_data:
+            raise HTTPException(
+                status_code=status.HTTP_404_NOT_FOUND,
+                detail=f"Job {job_id} not found"
+            )
+        
+        job = Job(**job_data)
+        
+        # Verify user owns this job
+        validate_job_ownership(job.user_id, current_user)
+        
+        logger.info(
+            "Retrieved job details",
+            job_id=job_id,
+            status=job.status,
+            user_id=current_user["user_info"]["id"]
+        )
+        
+        return JobStatusResponse(
+            job_id=job.id,
+            status=job.status,
+            progress=job.progress,
+            error=job.error,
+            metrics=job.metrics,
+            created_at=job.created_at,
+            updated_at=job.updated_at,
+            completed_at=job.completed_at
+        )
+        
+    except HTTPException:
+        raise
+    except Exception as e:
+        logger.error(
+            "Failed to get job details",
+            job_id=job_id,
+            user_id=current_user["user_info"]["id"],
+            error=str(e),
+            exc_info=True
+        )
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail=f"Failed to retrieve job details: {str(e)}"
+        )