ractogateway.adapters.base

Base adapter and shared response models.

Every LLM provider adapter inherits from BaseLLMAdapter and implements the same interface: tool translation, request building, execution, and response normalisation.

class ractogateway.adapters.base.FinishReason(*values)

Bases: str, Enum

Why the model stopped generating.

STOP = 'stop'

TOOL_CALL = 'tool_call'

LENGTH = 'length'

CONTENT_FILTER = 'content_filter'

ERROR = 'error'

class ractogateway.adapters.base.ToolCallResult(**data)

Bases: BaseModel

A single tool/function call returned by the model.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

id: str

name: str

arguments: dict[str, Any]

model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class ractogateway.adapters.base.ChatTurn

Bases: TypedDict

One prior chat message used as conversational history.

role: Literal['system', 'user', 'assistant']

content: str

class ractogateway.adapters.base.LLMResponse(**data)

Bases: BaseModel

Unified, provider-agnostic response envelope.

Every adapter’s run() method returns one of these, regardless of whether the underlying provider is OpenAI, Gemini, or Anthropic.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

content: str | None

thinking: str | None

parsed: dict[str, Any] | list[Any] | None

tool_calls: list[ToolCallResult]

finish_reason: FinishReason

usage: dict[str, int]

raw: Any

model_config: ClassVar[ConfigDict] = {'arbitrary_types_allowed': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

ractogateway.adapters.base.strip_markdown_fences(text)

Remove markdown code fences that wrap JSON payloads.

Return type:

str

ractogateway.adapters.base.try_parse_json(text)

Attempt to parse text as JSON after stripping fences.

Returns None if the text is not valid JSON or is a JSON primitive (number, boolean, string) — only JSON objects and arrays are returned.

Return type:

dict[str, Any] | list[Any] | None

class ractogateway.adapters.base.BaseLLMAdapter(model, *, api_key=None, **kwargs)

Bases: ABC

Abstract base class that every provider adapter must implement.

Parameters:

• model (str) – The model identifier (e.g. "gpt-4o", "gemini-2.0-flash").

• api_key (str | None) – Provider API key. When None, each concrete adapter should fall back to an environment variable.

provider: str = 'base'

abstractmethod translate_tools(registry)

Convert canonical ToolSchema objects into the provider’s native tool/function-calling format.

Return type:

list[dict[str, Any]]

abstractmethod run(prompt, user_message, *, history=None, tools=None, temperature=0.0, max_tokens=4096, **kwargs)

Execute a prompt against the provider and return a normalised response.

Return type:

LLMResponse

abstractmethod async arun(prompt, user_message, *, history=None, tools=None, temperature=0.0, max_tokens=4096, **kwargs)

Async variant of run().

Return type:

LLMResponse