ctx.llm

class Llm:
    def generate(
        self,
        messages: list[dict[str, str]],
        *,
        model: str | None = None,
        max_tokens: int | None = None,
        temperature: float | None = None,
        provider_options: dict | None = None,
    ) -> LlmResponse: ...

    def generate_object(
        self,
        messages: list[dict[str, str]],
        schema: dict,
        *,
        model: str | None = None,
        max_tokens: int | None = None,
        temperature: float | None = None,
        provider_options: dict | None = None,
    ) -> LlmResponse: ...

result = ctx.llm.generate(
    messages=[{"role": "user", "content": "Summarise this article"}],
    model="anthropic:claude-sonnet-4-6",
    max_tokens=1000,
    temperature=0.7,
)
print(result.text)

schema = {
    "type": "object",
    "properties": {
        "summary": {"type": "string"},
        "tags": {"type": "array", "items": {"type": "string"}},
    },
    "required": ["summary"],
}

result = ctx.llm.generate_object(
    messages=[{"role": "user", "content": "Analyse this"}],
    schema=schema,
    model="anthropic:claude-haiku-4-5",
)

data = result.object  # Parsed JSON object
print(data["summary"])
print(data.get("tags", []))

@dataclass
class LlmResponse:
    text: str | None           # Generated text (None for generate_object)
    object: dict | None        # Structured output dict (None for generate)
    model: str                 # Model identifier used (e.g., "anthropic:claude-sonnet-4-6")
    usage: dict                # {"prompt_tokens": 120, "completion_tokens": 250}
    finish_reason: str         # "stop", "length", "content_filter", etc.

from friday_agent_sdk import LlmError, agent, err, ok

@agent(id="resilient", version="1.0.0", description="Handles LLM failures")
def execute(prompt, ctx):
    try:
        result = ctx.llm.generate(..., model="expensive-model")
    except LlmError as e:
        # Error message from host (e.g., "Rate limit exceeded", "Invalid API key")
        return err(f"Primary model failed: {e}")

    return ok({"output": result.text})

result = ctx.llm.generate(
    messages=[...],
    model="claude-code:sonnet",
    provider_options={
        "systemPrompt": {
            "type": "preset",
            "preset": "claude_code",
        },
        "effort": "high",
        "repo": "owner/repo",
    },
)

messages = [
    {"role": "system", "content": "You are a helpful assistant."},
    {"role": "user", "content": "Hello!"},
    {"role": "assistant", "content": "Hi there!"},
    {"role": "user", "content": "Analyse this code..."},
]