""" @provider BaseLLMProvider (swarm/providers/base.py) @purpose Abstract provider contract & token usage telemetry. """ from abc import ABC, abstractmethod from typing import Type, TypeVar, List, Dict, Tuple from pydantic import BaseModel, Field T = TypeVar("T", bound=BaseModel) class TokenUsage(BaseModel): prompt_tokens: int = 0 completion_tokens: int = 0 total_tokens: int = 0 latency_ms: int = 0 model_name: str = "mock" estimated_cost_usd: float = 0.0 class BaseLLMProvider(ABC): @abstractmethod async def generate_structured( self, prompt: str, schema: Type[T], system_prompt: str = "" ) -> Tuple[T, TokenUsage]: """ Executes a prompt and guarantees a response parsed into the requested Pydantic schema. Returns the parsed model and precise token telemetry. """ pass @abstractmethod async def chat( self, messages: List[Dict[str, str]], system_prompt: str = "" ) -> Tuple[str, TokenUsage]: """ Executes a multi-turn chat completion (used for interactive persona interviews). Returns the response string and token telemetry. """ pass