Source code for trader.llm.base

"""The LLM interface the Core depends on.

A Protocol for the same reason `BrokerAdapter` is one: the Core holds no HTTP
client, tests need no server, and a second provider is an addition rather than
a rewrite.

Anthropic is a **deferred future feature**, not a planned step — see
`docs/ideas.md` for the trigger conditions. This Protocol exists so that
decision stays cheap to revisit, not because a second provider is scheduled.
"""

from typing import Protocol, runtime_checkable

from trader.errors import TraderError

__all__ = ["LlmError", "LlmProvider"]




class LlmError(TraderError):
    """The language model call failed or returned something unusable.

    Derives from `TraderError` so the pipeline's per-symbol handler treats a
    model failure the way it treats a market-data failure: abort that symbol,
    record why, continue the cycle.
    """





@runtime_checkable
class LlmProvider(Protocol):
    """A model that returns structured JSON."""

    model: str



    def generate_json(
        self, system: str, user: str, schema: dict[str, object]
    ) -> dict[str, object]:
        """Return parsed JSON conforming to `schema`. Raises `LlmError`."""
        ...




    def health(self) -> str:
        """Return the reachable model's name. Raises `LlmError` if not."""
        ...