# Story 4.3: Multi-video Analysis with Multi-Agent System

## Story Overview

**Story ID**: 4.3  
**Epic**: 4 - Advanced Intelligence & Developer Platform  
**Title**: Multi-video Analysis with Multi-Agent System  
**Status**: 📋 READY FOR IMPLEMENTATION  
**Priority**: High  

**Goal**: Implement playlist and multi-video analysis using a multi-agent AI system with three different perspective agents (Technical, Business, User) and a synthesis agent for unified comprehensive summaries.

**Value Proposition**: Provide comprehensive multi-faceted analysis of YouTube playlists and channels, leveraging existing AI ecosystem infrastructure to generate insights from multiple AI perspectives.

**Dependencies**: 
- ✅ Story 4.2 (API Endpoints & Developer SDK) - Complete
- ✅ Existing AI ecosystem at `/src/agents/ecosystem/`
- ✅ ChromaDB integration patterns from `/tests/framework-comparison/`

**Estimated Effort**: 40 hours (enhanced with multi-agent system)

## Technical Requirements

### Core Features

#### 1. Multi-Agent Summarization System
- **Three Perspective Agents**: Technical Analyst, Business Analyst, User Experience Analyst
- **Synthesis Agent**: Combines perspectives into unified comprehensive summary  
- **AI Ecosystem Integration**: Leverages existing `/src/agents/ecosystem/` infrastructure
- **Agent Orchestration**: Uses BaseAgent and AgentOrchestrator patterns
- **State Management**: LangGraph-based workflow coordination

#### 2. Playlist Processing
- **Playlist URL Parser**: Extract video IDs from YouTube playlist URLs
- **Batch Video Processing**: Process all videos in playlist sequentially
- **Cross-Video Analysis**: Identify themes, patterns, and progression across videos
- **Series Tracking**: Detect content evolution and learning paths

#### 3. Multi-Video Intelligence
- **Theme Analysis**: Identify common topics across multiple videos
- **Content Evolution**: Track how topics develop across series
- **Channel Analysis**: Comprehensive channel content analysis  
- **Trend Detection**: Identify patterns in content creation and topics

#### 4. Enhanced Export Features  
- **Multi-Agent Summaries**: Export includes all three perspective summaries plus synthesis
- **Cross-Video Insights**: Aggregated insights from playlist analysis
- **Comparison Reports**: Side-by-side analysis of videos in series
- **Bulk Export**: Export all playlist summaries with agent analysis

### Technical Architecture

#### Multi-Agent System Components

```python
# Agent Perspective Definitions
class PerspectiveAgent:
    TECHNICAL = "technical"     # Focus on technical concepts, implementation, tools
    BUSINESS = "business"       # Focus on business value, ROI, market implications  
    USER_EXPERIENCE = "user"    # Focus on user journey, usability, accessibility
    SYNTHESIS = "synthesis"     # Combines all perspectives into unified view

# Agent Orchestration
class PlaylistAnalysisOrchestrator(BaseAgent):
    def __init__(self):
        self.technical_agent = TechnicalAnalysisAgent()
        self.business_agent = BusinessAnalysisAgent()
        self.ux_agent = UserExperienceAgent()
        self.synthesis_agent = SynthesisAgent()
    
    async def analyze_playlist(self, playlist_url: str) -> MultiAgentAnalysisResult:
        # Extract videos and process with multiple agents
        # Orchestrate agent communication and synthesis
```

#### Database Schema Extensions

```sql
-- Multi-agent analysis storage
CREATE TABLE agent_summaries (
    id UUID PRIMARY KEY,
    summary_id UUID REFERENCES summaries(id),
    agent_type VARCHAR(20), -- 'technical', 'business', 'user', 'synthesis'
    agent_summary TEXT,
    key_insights JSONB,
    confidence_score FLOAT,
    processing_time_seconds FLOAT,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

-- Playlist analysis
CREATE TABLE playlists (
    id UUID PRIMARY KEY,
    playlist_id VARCHAR(50),
    playlist_url TEXT,
    title VARCHAR(500),
    channel_name VARCHAR(200),
    video_count INTEGER,
    total_duration INTEGER,
    analyzed_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

-- Cross-video analysis
CREATE TABLE playlist_analysis (
    id UUID PRIMARY KEY,
    playlist_id UUID REFERENCES playlists(id),
    themes JSONB,
    content_progression JSONB,
    key_insights JSONB,
    agent_perspectives JSONB,
    synthesis_summary TEXT,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);
```

## Implementation Tasks

### Task 4.3.1: Multi-Agent System Integration (12 hours)

#### Subtasks:
1. **Agent Interface Setup** (3 hours)
   - Import and configure BaseAgent from `/src/agents/ecosystem/`
   - Set up AgentOrchestrator for workflow management  
   - Configure DeepSeek integration for all agents (no Anthropic)
   - Test agent communication and state management

2. **Perspective Agent Implementation** (6 hours)
   - Create TechnicalAnalysisAgent with technical focus prompts
   - Create BusinessAnalysisAgent with business value prompts
   - Create UserExperienceAgent with UX/accessibility prompts  
   - Implement agent-specific prompt templates and analysis patterns

3. **Synthesis Agent Development** (3 hours)
   - Create SynthesisAgent to combine multiple perspectives
   - Implement perspective weighting and conflict resolution
   - Design unified summary generation logic
   - Test multi-agent coordination and output quality

### Task 4.3.2: Playlist Processing Engine (16 hours)

#### Subtasks:
1. **Playlist URL Parser** (4 hours)
   - Extract playlist ID from various YouTube playlist URL formats
   - Validate playlist accessibility and permissions
   - Handle private/unlisted playlist edge cases
   - Integrate with YouTube Data API for metadata

2. **Video Discovery Service** (4 hours)
   - Fetch all video IDs from playlist using YouTube Data API
   - Extract video metadata (title, duration, upload date)
   - Handle pagination for large playlists (100+ videos)
   - Implement error handling for deleted/private videos

3. **Batch Processing Pipeline** (6 hours)
   - Process videos sequentially with progress tracking
   - Integrate with existing SummaryPipeline for individual videos
   - Implement multi-agent analysis for each video
   - Handle failures and retry logic for individual videos

4. **Cross-Video Analysis Engine** (2 hours)
   - Identify common themes across multiple videos
   - Track content progression and evolution
   - Generate playlist-level insights and patterns
   - Create aggregated analysis from agent perspectives

### Task 4.3.3: API Endpoints and Integration (8 hours)

#### Subtasks:
1. **Multi-Agent API Endpoints** (4 hours)
   - `POST /api/analysis/multi-agent/{video_id}` - Analyze single video with all agents
   - `GET /api/analysis/agent-perspectives/{summary_id}` - Get all agent perspectives
   - `POST /api/analysis/playlist` - Start playlist analysis
   - `GET /api/analysis/playlist/{job_id}/status` - Monitor playlist processing

2. **Frontend Integration** (3 hours)
   - Create MultiAgentAnalysisView component
   - Add playlist URL input and validation  
   - Display agent perspectives in tabbed interface
   - Show synthesis summary with highlighting from each perspective

3. **Background Job Management** (1 hour)
   - Integrate playlist processing with existing job system
   - Add WebSocket progress updates for multi-video processing
   - Implement job cancellation for long-running playlist analysis
   - Add monitoring and statistics endpoints

### Task 4.3.4: Enhanced Export and Reporting (4 hours)

#### Subtasks:
1. **Multi-Agent Export Formats** (2 hours)
   - Enhanced markdown with agent perspective sections
   - JSON export with structured agent analysis data
   - CSV export for playlist comparison and analysis
   - Add agent analysis to existing PDF export

2. **Playlist Reports** (2 hours)
   - Generate comprehensive playlist analysis reports
   - Include cross-video insights and theme analysis
   - Create comparison tables for video progression
   - Add executive summary with key playlist insights

## Data Models

### Multi-Agent Analysis Models

```python
from pydantic import BaseModel
from typing import List, Dict, Optional, Any
from enum import Enum

class AgentType(str, Enum):
    TECHNICAL = "technical"
    BUSINESS = "business"  
    USER_EXPERIENCE = "user"
    SYNTHESIS = "synthesis"

class AgentPerspective(BaseModel):
    agent_type: AgentType
    summary: str
    key_insights: List[str]
    confidence_score: float
    focus_areas: List[str]
    recommendations: List[str]

class MultiAgentAnalysisResult(BaseModel):
    video_id: str
    perspectives: List[AgentPerspective]
    synthesis_summary: str
    unified_insights: List[str]
    processing_time_seconds: float
    
class PlaylistAnalysisRequest(BaseModel):
    playlist_url: str
    include_cross_video_analysis: bool = True
    agent_types: List[AgentType] = [AgentType.TECHNICAL, AgentType.BUSINESS, AgentType.USER_EXPERIENCE]
    
class PlaylistAnalysisResult(BaseModel):
    playlist_id: str
    video_summaries: List[MultiAgentAnalysisResult]
    cross_video_analysis: Dict[str, Any]
    playlist_insights: List[str]
    themes: List[str]
    content_progression: Dict[str, Any]
```

## Testing Strategy

### Unit Tests
- **Agent Integration Tests**: Test BaseAgent and orchestrator integration
- **Perspective Analysis Tests**: Validate each agent's analysis quality
- **Synthesis Logic Tests**: Test perspective combination and conflict resolution
- **Playlist Parser Tests**: Validate URL parsing and video discovery
- **Cross-Video Analysis Tests**: Test theme detection and progression analysis

### Integration Tests  
- **Multi-Agent API Tests**: Test all new API endpoints
- **Playlist Processing Tests**: End-to-end playlist analysis workflow
- **Database Integration Tests**: Validate agent_summaries and playlist schema
- **Export Format Tests**: Test enhanced export with agent perspectives

### Performance Tests
- **Large Playlist Tests**: Test with 50+ video playlists
- **Concurrent Analysis Tests**: Multiple playlists processing simultaneously  
- **Agent Response Time Tests**: Measure individual agent processing times
- **Memory Usage Tests**: Monitor resource usage during large batch processing

## API Specification

### Multi-Agent Analysis Endpoints

```yaml
/api/analysis/multi-agent/{video_id}:
  post:
    summary: Analyze video with multiple agent perspectives
    parameters:
      - name: video_id
        in: path
        required: true
        schema:
          type: string
    requestBody:
      required: true
      content:
        application/json:
          schema:
            type: object
            properties:
              agent_types:
                type: array
                items:
                  type: string
                  enum: [technical, business, user]
              include_synthesis:
                type: boolean
                default: true
    responses:
      200:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MultiAgentAnalysisResult'

/api/analysis/playlist:
  post:
    summary: Start playlist analysis with multi-agent system
    requestBody:
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/PlaylistAnalysisRequest'
    responses:
      202:
        content:
          application/json:
            schema:
              type: object
              properties:
                job_id:
                  type: string
                status:
                  type: string
                  enum: [pending, processing]
                estimated_completion_time:
                  type: string
                  format: date-time
```

## Success Criteria

### Functional Requirements ✅
- [ ] Multi-agent system analyzes videos with 3 different perspectives (Technical, Business, UX)
- [ ] Synthesis agent combines perspectives into unified comprehensive summary
- [ ] Playlist URL parser extracts and validates playlist information
- [ ] Batch processing handles playlists of 20+ videos
- [ ] Cross-video analysis identifies themes and content progression
- [ ] Enhanced export includes all agent perspectives and synthesis
- [ ] API endpoints support multi-agent analysis and playlist processing

### Quality Requirements ✅
- [ ] Agent perspectives show distinct focus areas and insights
- [ ] Synthesis summary effectively combines perspectives without redundancy  
- [ ] Processing time under 45 seconds per video for multi-agent analysis
- [ ] Cross-video analysis provides meaningful insights for playlists
- [ ] Export formats maintain readability with multi-agent content
- [ ] Error handling gracefully manages failed videos in playlists

### Performance Requirements ✅  
- [ ] Handle playlists up to 100 videos
- [ ] Process 3 agent perspectives + synthesis in under 60 seconds per video
- [ ] Support concurrent playlist processing (2-3 simultaneous jobs)
- [ ] Memory usage remains stable during large playlist processing
- [ ] WebSocket progress updates every 10 seconds during processing

## Implementation Notes

### AI Ecosystem Integration
- Use existing BaseAgent class from `/src/agents/ecosystem/core/base_agent.py`
- Leverage AgentOrchestrator from `/src/agents/ecosystem/orchestration/orchestrator.py`  
- Follow LangGraph patterns from `/tests/framework-comparison/test_langgraph_chromadb.py`
- Implement DeepSeek integration for all agents (avoid Anthropic per user requirements)

### Agent Perspective Design
- **Technical Agent**: Focus on implementation details, tools, technical concepts, architecture
- **Business Agent**: Analyze ROI, market implications, business value, competitive analysis
- **UX Agent**: Evaluate user journey, accessibility, usability, user experience patterns
- **Synthesis Agent**: Combine insights, resolve conflicts, create unified narrative

### Cross-Video Analysis Patterns
- Theme extraction using semantic similarity across video summaries
- Content progression tracking through timestamp and topic analysis
- Series detection through title patterns and content similarity
- Channel analysis through upload patterns and topic evolution

### Performance Considerations
- Parallel agent processing where possible (Technical, Business, UX can run concurrently)
- Intelligent caching of agent analyses for repeated playlist processing
- Batch database operations for playlist video processing
- WebSocket connection management for long-running playlist jobs

## Risk Mitigation

### High Risk: Agent Analysis Quality
- **Risk**: Agents provide similar or redundant perspectives  
- **Mitigation**: Distinct prompt engineering with clear focus areas, quality scoring, and validation

### Medium Risk: Processing Time
- **Risk**: Multi-agent analysis too slow for user experience
- **Mitigation**: Parallel agent processing, progress indicators, background processing

### Medium Risk: Large Playlist Performance  
- **Risk**: Memory/resource exhaustion with 50+ video playlists
- **Mitigation**: Batch processing limits, resource monitoring, job queuing system

---

**Story Owner**: Development Team  
**Architecture Reference**: BMad Method Epic-Story Structure  
**Implementation Status**: Ready for Development  
**Last Updated**: 2025-08-27