app/contracts.py

"""
Standard Engine Contracts
"""
from pydantic import BaseModel, Field
from typing import Dict, Any, List, Optional


class Actor(BaseModel):
    """Actor information"""
    user_id: str
    session_id: Optional[str] = None


class InputItem(BaseModel):
    """Individual input item"""
    type: str  # text|audio|image|video|doc
    text: Optional[str] = None
    ref: Optional[str] = None


class Input(BaseModel):
    """Input container"""
    text: Optional[str] = None
    items: List[InputItem] = Field(default_factory=list)
    refs: Dict[str, Any] = Field(default_factory=dict)


class EngineRequest(BaseModel):
    """Standard engine request format"""
    request_id: str
    engine: str = "avatar-tutor-engine"
    action: str
    actor: Actor
    input: Input
    context: Dict[str, Any] = Field(default_factory=dict)
    options: Dict[str, Any] = Field(default_factory=dict)


class ErrorDetail(BaseModel):
    """Error detail structure"""
    code: str
    detail: str


class EngineResponse(BaseModel):
    """Standard engine response format"""
    request_id: str
    ok: bool
    status: str  # success|error
    engine: str
    action: str
    result: Dict[str, Any] = Field(default_factory=dict)
    messages: List[str] = Field(default_factory=list)
    suggested_actions: List[str] = Field(default_factory=list)
    citations: List[Dict[str, Any]] = Field(default_factory=list)
    error: Optional[ErrorDetail] = None