LLM providers¶

The vendor-neutral provider protocol and its implementations (OpenAI, Anthropic, and a deterministic mock for tests), so the agent loop is decoupled from any single LLM vendor. The real providers import their SDKs lazily, so this layer is importable without the optional llm extra and only fails if a real provider is instantiated without its SDK.

llm ¶

Vendor-neutral LLM provider layer for the Fugacio copilot.

Importing this package pulls in only the neutral types and the in-memory MockProvider; the real providers (OpenAIProvider, AnthropicProvider) import their SDKs lazily, so they are importable here without the optional llm extra installed and only fail if instantiated without the SDK.

Modules:

Name	Description
`anthropic`	Anthropic (Claude) Messages-API adapter for the Fugacio copilot.
`base`	Provider-neutral chat/tool-calling types for the Fugacio copilot.
`mock`	A deterministic in-memory provider for testing the agent loop without an API.
`openai`	OpenAI chat-completions adapter for the Fugacio copilot.

Classes:

Name	Description
`AnthropicProvider`	An `LLMProvider` backed by the Anthropic API.
`ChatResponse`	A model's reply: free-text content and/or requested tool calls.
`LLMProvider`	A function-calling chat model.
`Message`	One turn in a chat transcript.
`ToolCall`	A model's request to invoke a tool.
`MockProvider`	A scripted `LLMProvider`.
`OpenAIProvider`	An `LLMProvider` backed by the OpenAI API.

Functions:

Name	Description
`anthropic_tools`	Map engine tool schemas to Anthropic's `{"name", "description", "input_schema"}`.
`openai_tools`	Wrap engine tool schemas in OpenAI's `{"type": "function", ...}` envelope.

AnthropicProvider ¶

AnthropicProvider(
    model: str = "claude-3-5-sonnet-latest",
    *,
    client: Any | None = None,
    api_key: str | None = None,
)

An LLMProvider backed by the Anthropic API.

Parameters:

Name	Type	Description	Default
`model`	`str`	Claude model name (e.g. `"claude-3-5-sonnet-latest"`).	`'claude-3-5-sonnet-latest'`
`client`	`Any \| None`	An existing `anthropic.Anthropic` client; one is created if omitted.	`None`
`api_key`	`str \| None`	API key passed to a freshly created client.	`None`

Methods:

Name	Description
`chat`	Call the Messages API and parse the reply into a `ChatResponse`.

chat ¶

chat(
    messages: Sequence[Message],
    *,
    tools: Sequence[JsonDict] = (),
    temperature: float = 0.0,
    max_tokens: int = 1024,
) -> ChatResponse

Call the Messages API and parse the reply into a ChatResponse.

ChatResponse `dataclass` ¶

ChatResponse(
    content: str = "",
    tool_calls: tuple[ToolCall, ...] = (),
    raw: Any = None,
)

A model's reply: free-text content and/or requested tool calls.

Attributes:

Name	Type	Description
`content`	`str`	The assistant's text (the final answer when there are no calls).
`tool_calls`	`tuple[ToolCall, ...]`	Any tool calls the model wants executed before continuing.
`raw`	`Any`	The provider's raw response object, for debugging (not portable).

has_tool_calls `property` ¶

has_tool_calls: bool

Whether the model requested at least one tool call.

LLMProvider ¶

Bases: Protocol

A function-calling chat model.

Implementations translate the neutral Message / tool-schema inputs to their own API and parse the reply into a ChatResponse.

Methods:

Name	Description
`chat`	Return the model's reply to `messages` with `tools` available.

chat ¶

chat(
    messages: Sequence[Message],
    *,
    tools: Sequence[JsonDict] = (),
    temperature: float = 0.0,
    max_tokens: int = 1024,
) -> ChatResponse

Return the model's reply to messages with tools available.

Message `dataclass` ¶

Message(
    role: str,
    content: str = "",
    tool_calls: tuple[ToolCall, ...] = (),
    tool_call_id: str | None = None,
    name: str | None = None,
)

One turn in a chat transcript.

Attributes:

Name	Type	Description
`role`	`str`	`"system"`, `"user"`, `"assistant"` or `"tool"`.
`content`	`str`	Text content (may be empty for an assistant tool-call turn).
`tool_calls`	`tuple[ToolCall, ...]`	Tool calls requested by an assistant turn.
`tool_call_id`	`str \| None`	For a `"tool"` turn, the id of the call it answers.
`name`	`str \| None`	For a `"tool"` turn, the tool name (some providers want it).

Methods:

Name	Description
`system`	A system instruction message.
`user`	A user message.
`assistant`	An assistant message, optionally requesting tool calls.
`tool`	A tool-result message answering a specific tool call.

system `classmethod` ¶

system(content: str) -> Message

A system instruction message.

user `classmethod` ¶

user(content: str) -> Message

A user message.

assistant `classmethod` ¶

assistant(
    content: str = "", tool_calls: Sequence[ToolCall] = ()
) -> Message

An assistant message, optionally requesting tool calls.

tool `classmethod` ¶

tool(
    content: str, tool_call_id: str, name: str | None = None
) -> Message

A tool-result message answering a specific tool call.

ToolCall `dataclass` ¶

ToolCall(id: str, name: str, arguments: JsonDict = dict())

A model's request to invoke a tool.

Attributes:

Name	Type	Description
`id`	`str`	Provider-assigned call id (echoed back with the result).
`name`	`str`	Tool name (must exist in the registry).
`arguments`	`JsonDict`	Parsed JSON arguments for the tool.

MockProvider `dataclass` ¶

MockProvider(
    script: Script,
    calls: list[
        tuple[list[Message], list[JsonDict]]
    ] = list(),
    _index: int = 0,
)

A scripted LLMProvider.

Attributes:

Name	Type	Description
`script`	`Script`	Either a list of replies returned in order, or a function `(messages) -> ChatResponse` evaluated on each call.
`calls`	`list[tuple[list[Message], list[JsonDict]]]`	Recorded `(messages, tools)` for each `chat` invocation.

Methods:

Name	Description
`chat`	Return the next scripted reply (or evaluate the script callable).

chat ¶

chat(
    messages: Sequence[Message],
    *,
    tools: Sequence[JsonDict] = (),
    temperature: float = 0.0,
    max_tokens: int = 1024,
) -> ChatResponse

Return the next scripted reply (or evaluate the script callable).

OpenAIProvider ¶

OpenAIProvider(
    model: str = "gpt-4o-mini",
    *,
    client: Any | None = None,
    api_key: str | None = None,
)

An LLMProvider backed by the OpenAI API.

Parameters:

Name	Type	Description	Default
`model`	`str`	Chat model name (e.g. `"gpt-4o"`, `"gpt-4o-mini"`).	`'gpt-4o-mini'`
`client`	`Any \| None`	An existing `openai.OpenAI` client; one is created if omitted.	`None`
`api_key`	`str \| None`	API key passed to a freshly created client.	`None`

Methods:

Name	Description
`chat`	Call chat-completions and parse the reply into a `ChatResponse`.

chat ¶

chat(
    messages: Sequence[Message],
    *,
    tools: Sequence[JsonDict] = (),
    temperature: float = 0.0,
    max_tokens: int = 1024,
) -> ChatResponse

Call chat-completions and parse the reply into a ChatResponse.

anthropic_tools ¶

anthropic_tools(
    schemas: Sequence[JsonDict],
) -> list[JsonDict]

Map engine tool schemas to Anthropic's {"name", "description", "input_schema"}.

openai_tools ¶

openai_tools(schemas: Sequence[JsonDict]) -> list[JsonDict]

Wrap engine tool schemas in OpenAI's {"type": "function", ...} envelope.

LLM providers¶

llm ¶

AnthropicProvider ¶

chat ¶

ChatResponse dataclass ¶

has_tool_calls property ¶

LLMProvider ¶

chat ¶

Message dataclass ¶

system classmethod ¶

user classmethod ¶

assistant classmethod ¶

tool classmethod ¶

ToolCall dataclass ¶

MockProvider dataclass ¶

chat ¶

OpenAIProvider ¶

chat ¶

anthropic_tools ¶

openai_tools ¶

ChatResponse `dataclass` ¶

has_tool_calls `property` ¶

Message `dataclass` ¶

system `classmethod` ¶

user `classmethod` ¶

assistant `classmethod` ¶

tool `classmethod` ¶

ToolCall `dataclass` ¶

MockProvider `dataclass` ¶