Upload src/models/schemas.py

src/models/schemas.py

@@ -1,25 +1,18 @@
 """
-Pydantic models for AI Reel Creator Platform.
-Defines all data schemas for the end-to-end pipeline.
+Pydantic Schemas -- AI Reel Creator Platform
+=============================================
+
+Defines all request / response / internal data schemas used across the API,
+pipelines, and LLM orchestrator.
 """
 
-from typing import Optional, List, Dict, Any, Literal
-from pydantic import BaseModel, Field, UUID4
-from datetime import datetime
+from typing import List, Dict, Optional, Any, Literal
 from enum import Enum
+from datetime import datetime
+from pydantic import BaseModel, Field, validator
 
 
-# ============================================================
-# ENUMS
-# ============================================================
-
-class AssetType(str, Enum):
-    VIDEO = "video"
-    IMAGE = "image"
-    AUDIO = "audio"
-
-
-class SectionType(str, Enum):
+class Section(str, Enum):
     EXTERIOR = "Exterior"
     INTERIOR = "Interior"
     PERFORMANCE = "Performance"
@@ -41,6 +34,53 @@ class Tone(str, Enum):
     SERENE = "serene"
 
 
+class DurationTarget(str, Enum):
+    S10 = "10s"
+    S20 = "20s"
+    S30 = "30s"
+    S60 = "60s"
+    CUSTOM = "custom"
+
+
+class Platform(str, Enum):
+    INSTAGRAM_REELS = "instagram_reels"
+    TIKTOK = "tiktok"
+    YOUTUBE_SHORTS = "youtube_shorts"
+    LINKEDIN = "linkedin"
+    TWITTER = "twitter"
+    FACEBOOK = "facebook"
+    CUSTOM = "custom"
+
+
+class AspectRatio(str, Enum):
+    R9_16 = "9:16"
+    R16_9 = "16:9"
+    R1_1 = "1:1"
+    R4_5 = "4:5"
+
+
+class TransitionType(str, Enum):
+    CUT = "cut"
+    CROSS_DISSOLVE = "cross_dissolve"
+    FLASH_WHITE = "flash_white"
+    ZOOM_IN = "zoom_in"
+    SLIDE_LEFT = "slide_left"
+    SLIDE_RIGHT = "slide_right"
+
+
+class FilterPreset(str, Enum):
+    CINEMATIC = "cinematic"
+    SPORTY = "sporty"
+    ELEGANT = "elegant"
+    TECHNICAL = "technical"
+
+
+class AssetType(str, Enum):
+    VIDEO = "video"
+    IMAGE = "image"
+    AUDIO = "audio"
+
+
 class ShotType(str, Enum):
     CLOSE_UP = "close_up"
     MEDIUM_SHOT = "medium_shot"
@@ -53,7 +93,7 @@ class ShotType(str, Enum):
     PAN = "pan"
     TILT = "tilt"
     DRONE = "drone"
-    THREE_SIXTY = "360"
+    R360 = "360"
 
 
 class CameraAngle(str, Enum):
@@ -69,38 +109,34 @@ class CameraAngle(str, Enum):
     DETAIL = "detail"
 
 
-class Platform(str, Enum):
-    INSTAGRAM_REELS = "instagram_reels"
-    TIKTOK = "tiktok"
-    YOUTUBE_SHORTS = "youtube_shorts"
-    LINKEDIN = "linkedin"
-    TWITTER = "twitter"
-    FACEBOOK = "facebook"
-    CUSTOM = "custom"
+class ReelStatus(str, Enum):
+    PENDING = "pending"
+    PLANNING = "planning"
+    GENERATING = "generating"
+    REVIEW = "review"
+    COMPLETED = "completed"
+    FAILED = "failed"
 
 
-class DurationTarget(str, Enum):
-    TEN_SECONDS = "10s"
-    TWENTY_SECONDS = "20s"
-    THIRTY_SECONDS = "30s"
-    SIXTY_SECONDS = "60s"
-    CUSTOM = "custom"
+class RenderStatus(str, Enum):
+    PENDING = "pending"
+    RENDERING = "rendering"
+    COMPLETED = "completed"
+    FAILED = "failed"
 
 
-class AspectRatio(str, Enum):
-    NINE_SIXTEEN = "9:16"
-    SIXTEEN_NINE = "16:9"
-    ONE_ONE = "1:1"
-    FOUR_FIVE = "4:5"
+class MappingType(str, Enum):
+    SEMANTIC = "semantic"
+    RULE_BASED = "rule_based"
+    MANUAL = "manual"
+    OVERRIDE = "override"
 
 
-class TransitionType(str, Enum):
-    CUT = "cut"
-    CROSS_DISSOLVE = "cross_dissolve"
-    FLASH_WHITE = "flash_white"
-    ZOOM_IN = "zoom_in"
-    SLIDE_LEFT = "slide_left"
-    SLIDE_RIGHT = "slide_right"
+class MappingSource(str, Enum):
+    SEMANTIC = "semantic"
+    BROCHURE_MAP = "brochure_map"
+    RULE_BASED = "rule_based"
+    FALLBACK = "fallback"
 
 
 class DurationClass(str, Enum):
@@ -109,41 +145,46 @@ class DurationClass(str, Enum):
     LONG = "long"
 
 
-class MappingType(str, Enum):
-    SEMANTIC = "semantic"
-    RULE_BASED = "rule_based"
-    MANUAL = "manual"
-    OVERRIDE = "override"
-
-
-class RequestStatus(str, Enum):
-    PENDING = "pending"
-    PLANNING = "planning"
-    GENERATING = "generating"
-    REVIEW = "review"
-    COMPLETED = "completed"
-    FAILED = "failed"
+class BrochureNodeSchema(BaseModel):
+    id: Optional[str] = None
+    section: Section
+    title: str = Field(..., max_length=200)
+    content: str = Field(..., min_length=20)
+    key_features: List[str] = Field(default_factory=list)
+    taglines: List[str] = Field(default_factory=list)
+    spec_highlights: Dict[str, str] = Field(default_factory=dict)
+    car_part_referenced: List[str] = Field(default_factory=list)
+    tone_tags: List[Tone] = Field(default_factory=list)
+    page_numbers: List[int] = Field(default_factory=list)
+    embedding_768: Optional[List[float]] = None
+    embedding_model: str = "openai/clip-vit-large-patch14"
+    source_pdf: Optional[str] = None
+    created_at: Optional[datetime] = None
+    updated_at: Optional[datetime] = None
 
+    @validator("car_part_referenced", each_item=True)
+    def lower_parts(cls, v: str) -> str:
+        return v.lower().strip().rstrip("s")
 
-# ============================================================
-# ASSET MODELS
-# ============================================================
 
-class AssetMetadata(BaseModel):
-    """Rich metadata for an asset extracted by vision models."""
-    description: str = Field(description="Natural language description of the asset")
-    shot_type: Optional[ShotType] = Field(None, description="Camera shot type")
-    camera_angle: Optional[CameraAngle] = Field(None, description="Camera angle")
-    subject_part: Optional[str] = Field(None, description="Subject part shown (e.g., 'headlight', 'wheel')")
-    mood: Optional[Tone] = Field(None, description="Visual mood/tone")
-    dominant_colours: Optional[List[str]] = Field(None, description="Dominant hex colour codes")
-    confidence_score: float = Field(default=1.0, ge=0.0, le=1.0, description="Extraction confidence")
-    review_flag: bool = Field(default=False, description="Flag for manual review")
+class AssetMetadataSchema(BaseModel):
+    id: Optional[str] = None
+    asset_id: str
+    description: Optional[str] = None
+    shot_type: Optional[ShotType] = None
+    camera_angle: Optional[CameraAngle] = None
+    subject_part: Optional[str] = None
+    mood: Optional[Tone] = None
+    dominant_colours: Optional[List[str]] = None
+    confidence_score: Optional[float] = Field(None, ge=0.0, le=1.0)
+    review_flag: bool = False
+    embedding_768: Optional[List[float]] = None
+    embedding_model: str = "openai/clip-vit-large-patch14"
+    extracted_at: Optional[datetime] = None
 
 
-class Asset(BaseModel):
-    """Represents a raw video, image, or audio asset."""
-    id: Optional[UUID4] = None
+class AssetSchema(BaseModel):
+    id: Optional[str] = None
     file_path: str
     file_name: str
     asset_type: AssetType
@@ -152,15 +193,14 @@ class Asset(BaseModel):
     duration_ms: Optional[int] = None
     frame_rate: Optional[float] = None
     file_size_bytes: Optional[int] = None
-    metadata: Optional[AssetMetadata] = None
+    metadata: Optional[AssetMetadataSchema] = None
     created_at: Optional[datetime] = None
     updated_at: Optional[datetime] = None
 
 
-class VideoEvent(BaseModel):
-    """A temporal segment within a video asset."""
-    id: Optional[UUID4] = None
-    asset_id: UUID4
+class VideoEventSchema(BaseModel):
+    id: Optional[str] = None
+    asset_id: str
     start_ms: int
     end_ms: int
     duration_ms: Optional[int] = None
@@ -169,101 +209,32 @@ class VideoEvent(BaseModel):
     camera_angle: Optional[CameraAngle] = None
     subject_part: Optional[str] = None
     mood: Optional[Tone] = None
-    confidence_score: Optional[float] = None
+    embedding_768: Optional[List[float]] = None
+    confidence_score: Optional[float] = Field(None, ge=0.0, le=1.0)
     keyframe_path: Optional[str] = None
     created_at: Optional[datetime] = None
 
 
-# ============================================================
-# BRAND CONFIG MODELS
-# ============================================================
-
-class BrandColours(BaseModel):
-    primary: str
-    secondary: str
-    accent: Optional[str] = None
-    background: Optional[str] = None
-    text: Optional[str] = None
-
-
-class BrandTypography(BaseModel):
-    primary_font: str
-    secondary_font: Optional[str] = None
-    heading_size: Optional[str] = None
-    body_size: Optional[str] = None
-    caption_size: Optional[str] = None
-
-
-class BrandToneOfVoice(BaseModel):
-    adjectives: List[str]
-    forbidden_words: Optional[List[str]] = None
-    preferred_phrases: Optional[List[str]] = None
-
-
-class BrandConfig(BaseModel):
-    """Structured brand guidelines for compliance checking."""
-    id: Optional[UUID4] = None
+class BrandConfigSchema(BaseModel):
+    id: Optional[str] = None
     name: str
     version: int = 1
-    colours: BrandColours
-    typography: BrandTypography
-    tone_of_voice: BrandToneOfVoice
-    approved_terminology: Optional[List[str]] = None
-    restricted_visuals: Optional[List[str]] = None
+    colours: Dict[str, str] = Field(default_factory=dict)
+    typography: Dict[str, str] = Field(default_factory=dict)
+    tone_of_voice: Dict[str, Any] = Field(default_factory=dict)
+    approved_terminology: List[str] = Field(default_factory=list)
+    restricted_visuals: List[str] = Field(default_factory=list)
     logo_paths: Optional[Dict[str, str]] = None
     created_at: Optional[datetime] = None
     updated_at: Optional[datetime] = None
 
 
-# ============================================================
-# BROCHURE MODELS
-# ============================================================
-
-class BrochureNode(BaseModel):
-    """A knowledge node extracted from a brochure section."""
-    id: Optional[UUID4] = None
-    section: SectionType
-    title: str
-    content: str
-    key_features: Optional[List[str]] = Field(default_factory=list)
-    taglines: Optional[List[str]] = Field(default_factory=list)
-    spec_highlights: Optional[Dict[str, Any]] = None
-    car_part_referenced: Optional[List[str]] = Field(default_factory=list)
-    tone_tags: Optional[List[Tone]] = Field(default_factory=list)
-    page_number: Optional[int] = None
-    source_pdf: Optional[str] = None
-    embedding_768: Optional[List[float]] = None
-    created_at: Optional[datetime] = None
-    updated_at: Optional[datetime] = None
-
-
-class BrochureAssetMap(BaseModel):
-    """Mapping between a brochure node and visual assets."""
-    id: Optional[UUID4] = None
-    brochure_node_id: UUID4
-    asset_id: UUID4
-    video_event_id: Optional[UUID4] = None
-    similarity_score: float = Field(ge=0.0, le=1.0)
-    mapping_type: MappingType = MappingType.SEMANTIC
-    confidence_score: float
-    is_approved: Optional[bool] = None
-    reviewer_notes: Optional[str] = None
-    rank: int
-    created_at: Optional[datetime] = None
-    updated_at: Optional[datetime] = None
-
-
-# ============================================================
-# CAPTION & VOICEOVER MODELS
-# ============================================================
-
-class CaptionVariant(BaseModel):
-    """A pre-generated caption variant."""
-    id: Optional[UUID4] = None
-    brochure_node_id: Optional[UUID4] = None
+class CaptionSchema(BaseModel):
+    id: Optional[str] = None
+    brochure_node_id: Optional[str] = None
     car_part: Optional[str] = None
     tone: Tone
-    duration_class: DurationClass
+    duration_class: DurationClass = DurationClass.MEDIUM
     text: str
     word_count: Optional[int] = None
     is_brand_compliant: bool = True
@@ -272,13 +243,12 @@ class CaptionVariant(BaseModel):
     created_at: Optional[datetime] = None
 
 
-class VoiceoverLine(BaseModel):
-    """A pre-generated voiceover script line."""
-    id: Optional[UUID4] = None
-    brochure_node_id: Optional[UUID4] = None
+class VoiceoverSchema(BaseModel):
+    id: Optional[str] = None
+    brochure_node_id: Optional[str] = None
     car_part: Optional[str] = None
     tone: Tone
-    duration_class: DurationClass
+    duration_class: DurationClass = DurationClass.MEDIUM
     text: str
     estimated_duration_ms: Optional[int] = None
     is_brand_compliant: bool = True
@@ -287,207 +257,150 @@ class VoiceoverLine(BaseModel):
     created_at: Optional[datetime] = None
 
 
-# ============================================================
-# QUERY & REEL REQUEST MODELS
-# ============================================================
+class ReelRequestCreate(BaseModel):
+    user_query: str = Field(..., min_length=5, description="Free-text description of the desired reel")
+    duration_target: DurationTarget
+    duration_ms: Optional[int] = Field(None, description="Exact duration in ms if duration_target='custom'")
+    platform: Platform
+    tone: Tone
+    aspect_ratio: AspectRatio = AspectRatio.R9_16
+    brand_config_id: Optional[str] = None
+    additional_constraints: Optional[Dict[str, Any]] = Field(default_factory=dict)
+
 
-class ReelRequest(BaseModel):
-    """User request for a reel generation."""
-    id: Optional[UUID4] = None
-    user_query: str = Field(description="Free-text description of desired reel")
+class ReelRequestResponse(BaseModel):
+    id: str
+    user_query: str
     duration_target: DurationTarget
-    duration_ms: Optional[int] = None
+    duration_ms: Optional[int]
     platform: Platform
     tone: Tone
-    aspect_ratio: AspectRatio = AspectRatio.NINE_SIXTEEN
-    brand_config_id: Optional[UUID4] = None
-    additional_constraints: Optional[Dict[str, Any]] = None
-    status: RequestStatus = RequestStatus.PENDING
+    aspect_ratio: AspectRatio
+    brand_config_id: Optional[str]
+    additional_constraints: Optional[Dict[str, Any]]
+    status: ReelStatus
     error_message: Optional[str] = None
     created_at: Optional[datetime] = None
     updated_at: Optional[datetime] = None
 
 
-class BeatDefinition(BaseModel):
-    """A single beat in a reel script."""
-    beat_number: int
-    duration_ms: int
-    intent: str = Field(description="Creative intent for this beat")
-    car_parts: Optional[List[str]] = Field(default_factory=list)
+class ReelBeatSchema(BaseModel):
+    beat_number: int = Field(..., ge=1)
+    duration_ms: int = Field(..., gt=0)
+    intent: str = Field(..., description="What this beat should communicate")
+    car_parts: List[str] = Field(default_factory=list)
     tone: Optional[Tone] = None
     caption_variant: Optional[str] = None
     voiceover_line: Optional[str] = None
     transition_type: Optional[TransitionType] = TransitionType.CUT
-    filter_suggestion: Optional[str] = None
-    start_ms: Optional[int] = None  # Will be computed during assembly
-    end_ms: Optional[int] = None
+    filter_suggestion: Optional[FilterPreset] = FilterPreset.CINEMATIC
 
 
-class ReelScript(BaseModel):
-    """Beat-by-beat reel script generated by the LLM orchestrator."""
-    id: Optional[UUID4] = None
-    reel_request_id: UUID4
-    title: Optional[str] = None
-    beats: List[BeatDefinition]
-    total_duration_ms: int
-    total_beats: int
-    platform: Optional[Platform] = None
-    aspect_ratio: Optional[AspectRatio] = None
-    filter_preset: Optional[str] = None
-    voiceover_script: Optional[str] = None
-    validation_status: str = "pending"
-    validation_errors: Optional[List[str]] = None
-    generation_attempts: int = 1
-    created_at: Optional[datetime] = None
+class ReelScriptSchema(BaseModel):
+    title: str
+    beats: List[ReelBeatSchema] = Field(..., min_length=1)
+    total_duration_ms: int = Field(..., gt=0)
+    platform: Platform
+    tone: Tone
+    aspect_ratio: AspectRatio
+    voiceover_summary: Optional[str] = None
 
+    @validator("beats")
+    def check_total_duration(cls, beats: List[ReelBeatSchema], values: Dict[str, Any]) -> List[ReelBeatSchema]:
+        total = sum(b.duration_ms for b in beats)
+        declared = values.get("total_duration_ms", total)
+        if total and abs(total - declared) / max(declared, 1) > 0.10:
+            raise ValueError(f"Beat durations sum to {total}ms but declared total is {declared}ms")
+        return beats
 
-# ============================================================
-# ASSET CANDIDATE MODELS
-# ============================================================
 
-class AssetCandidate(BaseModel):
-    """A candidate asset for a specific beat."""
-    asset_id: UUID4
-    video_event_id: Optional[UUID4] = None
-    file_path: str
-    asset_type: AssetType
-    description: Optional[str] = None
-    shot_type: Optional[ShotType] = None
-    camera_angle: Optional[CameraAngle] = None
-    subject_part: Optional[str] = None
-    mood: Optional[Tone] = None
-    similarity_score: float
-    rank: int
-    mapping_source: str = "semantic"
+class ResolvedAssetSchema(BaseModel):
+    beat_number: int
+    asset_id: str
+    video_event_id: Optional[str] = None
     start_ms: Optional[int] = None
     end_ms: Optional[int] = None
-    is_selected: bool = False
-
-
-class BeatWithCandidates(BaseModel):
-    """A beat enriched with top-k asset candidates."""
-    beat: BeatDefinition
-    candidates: List[AssetCandidate]
-    selected_candidate_index: Optional[int] = None
-    caption: Optional[str] = None
-    voiceover: Optional[str] = None
-
-
-# ============================================================
-# REEL MANIFEST MODELS
-# ============================================================
-
-class BeatManifest(BaseModel):
-    """A fully-resolved beat ready for rendering."""
-    beat_number: int
-    asset_id: UUID4
-    video_event_id: Optional[UUID4] = None
-    file_path: str
-    asset_type: AssetType
-    start_ms: int  # Start time within the source asset
-    end_ms: int    # End time within the source asset
-    duration_ms: int  # Target duration for this beat
     caption: Optional[str] = None
     voiceover_line: Optional[str] = None
-    voiceover_start_ms: Optional[int] = None
-    transition_type: TransitionType = TransitionType.CUT
-    filter_preset: Optional[str] = None
-    speed_adjustment: Optional[float] = Field(None, description="Speed multiplier if clip needs adjustment")
-    description: Optional[str] = None
-
-
-class AudioTrack(BaseModel):
-    """Audio track definition for the reel."""
-    voiceover_segments: List[Dict[str, Any]]  # {start_ms, end_ms, text, audio_file}
-    background_music_path: Optional[str] = None
-    background_music_volume: float = 0.2
-    fade_in_ms: int = 500
-    fade_out_ms: int = 1000
+    transition: TransitionType = TransitionType.CUT
+    filter: FilterPreset = FilterPreset.CINEMATIC
+    speed_adjustment: Optional[float] = Field(None, ge=0.5, le=1.5)
 
 
-class ReelManifest(BaseModel):
-    """Complete reel manifest for the composition engine."""
-    id: Optional[UUID4] = None
-    reel_request_id: UUID4
-    title: Optional[str] = None
+class ReelManifestSchema(BaseModel):
+    reel_request_id: str
+    title: str
+    total_duration_ms: int
+    beat_count: int
+    asset_count: int
     platform: Platform
+    tone: Tone
     aspect_ratio: AspectRatio
-    total_duration_ms: int
-    total_beats: int
-    beats: List[BeatManifest]
-    audio_track: Optional[AudioTrack] = None
-    filter_preset: Optional[str] = None
-    brand_config_id: Optional[UUID4] = None
+    brand_config_id: Optional[str] = None
+    beats: List[ResolvedAssetSchema] = Field(..., min_length=1)
+    background_music_track: Optional[str] = None
     is_validated: bool = False
     validation_report: Optional[Dict[str, Any]] = None
-    created_at: Optional[datetime] = None
+    render_status: RenderStatus = RenderStatus.PENDING
+    render_output_path: Optional[str] = None
+    remotion_export_path: Optional[str] = None
 
 
-# ============================================================
-# API REQUEST/RESPONSE MODELS
-# ============================================================
-
-class ReelQueryRequest(BaseModel):
-    """API request for creating a new reel."""
-    user_query: str = Field(..., min_length=5, max_length=2000, description="Description of desired reel")
-    duration_target: DurationTarget = DurationTarget.TWENTY_SECONDS
-    platform: Platform = Platform.INSTAGRAM_REELS
-    tone: Tone = Tone.CINEMATIC if False else Tone.DYNAMIC  # default
-    aspect_ratio: Optional[AspectRatio] = None
-    brand_config_id: Optional[str] = None
-    additional_constraints: Optional[Dict[str, Any]] = None
-
-
-class ReelQueryResponse(BaseModel):
-    """API response with reel generation status."""
-    request_id: str
-    status: RequestStatus
-    reel_script: Optional[ReelScript] = None
-    reel_manifest: Optional[ReelManifest] = None
-    message: Optional[str] = None
-    estimated_completion_seconds: Optional[int] = None
-
-
-class ReelManifestResponse(BaseModel):
-    """API response for a completed reel manifest."""
-    request_id: str
-    manifest: ReelManifest
-    preview_url: Optional[str] = None
-    render_status: str = "pending"
-
-
-class AssetSwapRequest(BaseModel):
-    """Request to swap an asset for a specific beat."""
-    request_id: str
+class BeatAssetCandidateSchema(BaseModel):
+    reel_request_id: str
     beat_number: int
-    new_asset_id: str
-    new_video_event_id: Optional[str] = None
-
-
-class RegenerateRequest(BaseModel):
-    """Request to regenerate a reel with modified parameters."""
-    request_id: str
-    user_query: Optional[str] = None
+    beat_intent: str
+    car_parts: List[str] = Field(default_factory=list)
     tone: Optional[Tone] = None
-    duration_target: Optional[DurationTarget] = None
-    additional_constraints: Optional[Dict[str, Any]] = None
+    asset_id: Optional[str] = None
+    video_event_id: Optional[str] = None
+    similarity_score: Optional[float] = None
+    rank: int = Field(..., ge=1)
+    mapping_source: MappingSource = MappingSource.SEMANTIC
+    is_selected: bool = False
 
 
-# ============================================================
-# VALIDATION & ERROR MODELS
-# ============================================================
+class ReelSummarySchema(BaseModel):
+    reel_request_id: str
+    title: str
+    duration_ms: int
+    beat_count: int
+    asset_count: int
+    platform: Platform
+    tone: Tone
+    aspect_ratio: AspectRatio
+    assets_used: List[str] = Field(default_factory=list)
+    brochure_facts_referenced: List[str] = Field(default_factory=list)
+    brand_compliance_score: Optional[float] = None
+    render_output_url: Optional[str] = None
+    remotion_download_url: Optional[str] = None
+
+
+class BrochureAssetMapSchema(BaseModel):
+    id: Optional[str] = None
+    brochure_node_id: str
+    asset_id: str
+    video_event_id: Optional[str] = None
+    similarity_score: float = Field(..., ge=0.0, le=1.0)
+    mapping_type: MappingType = MappingType.SEMANTIC
+    confidence_score: float = Field(..., ge=0.0, le=1.0)
+    is_approved: Optional[bool] = None
+    reviewer_notes: Optional[str] = None
+    rank: int = Field(..., ge=1)
+    created_at: Optional[datetime] = None
+    updated_at: Optional[datetime] = None
+
 
-class ValidationResult(BaseModel):
-    """Result of validating a reel script or manifest."""
-    is_valid: bool
-    errors: List[str] = Field(default_factory=list)
-    warnings: List[str] = Field(default_factory=list)
-    suggestions: List[str] = Field(default_factory=list)
+class APIResponse(BaseModel):
+    success: bool
+    data: Optional[Any] = None
+    message: Optional[str] = None
+    error: Optional[str] = None
+    request_id: Optional[str] = None
 
 
-class PipelineError(BaseModel):
-    """Standard error response from the API."""
-    error_code: str
-    message: str
-    details: Optional[Dict[str, Any]] = None
-    timestamp: datetime = Field(default_factory=datetime.utcnow)
+class PaginatedResponse(APIResponse):
+    total: int = 0
+    page: int = 1
+    per_page: int = 20
+    has_next: bool = False