app/contracts/engine_contract.py

from pydantic import BaseModel
from typing import Optional, Dict, Any, List


class EngineRequest(BaseModel):
    engine_name: str
    user_id: str
    intent: str
    context: Dict[str, Any] = {}
    refs: Dict[str, Any] = {}
    inputs: Dict[str, Any] = {}  # keep flexible; passive/active both read from here


class SuggestedAction(BaseModel):
    action_id: str
    label: str
    payload: Dict[str, Any]


class CitationPointer(BaseModel):
    source: str
    pointer: str
    note: Optional[str] = None


class EngineResponse(BaseModel):
    ok: bool
    output: Dict[str, Any] = {}
    messages: List[str] = []
    suggested_actions: List[SuggestedAction] = []
    citations: List[CitationPointer] = []
    error: Optional[str] = None
    trace: Dict[str, Any] = {}