📐 Contratos limpos (lição do intelecto)

from abc import ABC, abstractmethod
from dataclasses import dataclass, field

@dataclass(frozen=True)
class ToolCall:
    name: str
    arguments: dict
    call_id: str

@dataclass(frozen=True)
class LLMResponse:
    content: str
    tool_calls: list[ToolCall] = field(default_factory=list)
    finish_reason: str = "stop"  # "stop" | "tool_calls" | "length" | "filter"
    tokens_in: int = 0
    tokens_out: int = 0
    model: str = ""

class Provider(ABC):
    @abstractmethod
    async def chat(
        self,
        messages: list[dict],
        tools: list[dict] | None = None,
        model: str | None = None,
        temperature: float = 0.7,
        max_tokens: int = 4096,
    ) -> LLMResponse: ...

from abc import ABC, abstractmethod
from dataclasses import dataclass, field
from typing import Callable, Awaitable

@dataclass(frozen=True)
class IncomingMessage:
    user_id: str               # ID externo (telegram chat_id, slack user, etc)
    text: str
    timestamp: float
    metadata: dict = field(default_factory=dict)  # canal-específico

@dataclass(frozen=True)
class OutgoingMessage:
    user_id: str
    text: str
    parse_mode: str = "markdown"   # "markdown" | "html" | "plain"
    reply_to: str | None = None    # message_id pra resposta

class Channel(ABC):
    @abstractmethod
    async def start(self, on_message: Callable[[IncomingMessage], Awaitable[None]]) -> None:
        """Inicia listener. Chama on_message a cada mensagem recebida."""
        ...

    @abstractmethod
    async def send(self, msg: OutgoingMessage) -> str:
        """Envia mensagem. Retorna message_id externo."""
        ...

    @abstractmethod
    async def stop(self) -> None: ...

@dataclass(frozen=True)
class MemoryEntry:
    id: str
    content: str
    category: str            # 'fact' | 'preference' | 'decision' | 'interaction'
    user_id: str
    created_at: float
    metadata: dict = field(default_factory=dict)

class MemoryStore(ABC):
    @abstractmethod
    async def save(self, content: str, category: str, user_id: str, metadata: dict | None = None) -> str:
        """Retorna ID da entry."""
        ...

    @abstractmethod
    async def search(self, query: str, user_id: str, limit: int = 10) -> list[MemoryEntry]:
        """Busca textual ou semântica. SEMPRE filtra por user_id."""
        ...

    @abstractmethod
    async def forget(self, entry_id: str, user_id: str) -> bool:
        """Hard delete. Audit log obrigatório no chamador."""
        ...

    @abstractmethod
    async def recent(self, user_id: str, limit: int = 20) -> list[MemoryEntry]: ...

@dataclass(frozen=True)
class ToolResult:
    output: str | None        # texto que volta pro LLM
    error: str | None         # mensagem se falhou
    metadata: dict | None = None  # latência, custo, etc

class Tool(ABC):
    name: str                 # snake_case, verbo: search_web, send_email
    description: str          # 1-3 frases. Inclui exemplo + quando NÃO usar
    parameters: dict          # JSON Schema. required estrito.
    requires_approval: bool = False  # human-in-the-loop

    @abstractmethod
    async def execute(self, session: "Session", **kwargs) -> ToolResult: ...

    def to_openai_schema(self) -> dict:
        return {
            "type": "function",
            "function": {
                "name": self.name,
                "description": self.description,
                "parameters": self.parameters
            }
        }

class Agent:
    def __init__(self, provider, channel, memory, tools, system_prompt):
        self.provider = provider
        self.channel = channel
        self.memory = memory
        self.tools = {t.name: t for t in tools}
        self.system_prompt = system_prompt

    async def start(self):
        await self.channel.start(self.handle)

    async def handle(self, msg: IncomingMessage):
        user = await load_user_by_external(msg.user_id, channel="telegram")
        session = Session(user=user)
        log.info("turn_start", request_id=session.request_id, user_id=user.id)

        history = await self.memory.recent(user.id, limit=10)
        messages = [
            {"role": "system", "content": self.system_prompt},
            *[{"role": "user", "content": h.content} for h in history],
            {"role": "user", "content": msg.text}
        ]

        for turn in range(5):  # max 5 tool turns
            resp = await self.provider.chat(
                messages,
                tools=[t.to_openai_schema() for t in self.tools.values()]
            )
            if resp.finish_reason != "tool_calls":
                break
            for call in resp.tool_calls:
                tool = self.tools[call.name]
                result = await tool.execute(session=session, **call.arguments)
                messages.append({"role": "tool", "tool_call_id": call.call_id,
                                 "content": result.output or f"ERROR: {result.error}"})

        await self.memory.save(f"Q: {msg.text}\nA: {resp.content}",
                                category="interaction", user_id=user.id)
        await self.channel.send(OutgoingMessage(user_id=msg.user_id, text=resp.content))
        log.info("turn_end", request_id=session.request_id,
                 tokens_in=resp.tokens_in, tokens_out=resp.tokens_out)