clara.agent package

Submodules

clara.agent.open_router module

OpenRouter Integration and Agent Orchestration Module.

This module provides the OpenRouterClient and helper classes to communicate with the OpenRouter API for large language model inference, streaming responses, prompt formatting, and multi-turn agent interactions.

class clara.agent.open_router.Message(role, content, name=None)[source]

Bases: object

Represents a single chat message in a conversation thread.

Parameters:

  • role (str)

  • content (str)

  • name (str | None)

role

The role of the message author (e.g., ‘system’, ‘user’).

Type:

str

content

The textual content of the message.

Type:

str

name

Optional author name or function name.

Type:

Optional[str]

class clara.agent.open_router.ModelResponse(content, model, raw_response=None, usage=None)[source]

Bases: object

Structured response container from OpenRouter completion calls.

Parameters:

  • content (str)

  • model (str)

  • raw_response (Dict[str, Any] | None)

  • usage (Dict[str, Any] | None)

content

The primary generated text response from the model.

Type:

str

model

The model identifier that fulfilled the request.

Type:

str

raw_response

Full JSON response dictionary.

Type:

Dict[str, Any]

usage

Token usage metrics for the call.

Type:

Dict[str, Any]

class clara.agent.open_router.OpenRouterClient(api_key=None, default_model=None, base_url=None, site_url=None, site_name=None, timeout=60.0)[source]

Bases: object

Client for querying LLM models through the OpenRouter unified API.

Handles authentication, payload construction, retry logic, tool specifications, and completions.

Parameters:

  • api_key (str | None)

  • default_model (str | None)

  • base_url (str | None)

  • site_url (str | None)

  • site_name (str | None)

  • timeout (float)

api_key

OpenRouter API bearer token.

Type:

str

default_model

Default LLM model identifier.

Type:

str

base_url

OpenRouter API base endpoint URL.

Type:

str

site_url

Optional app URL for OpenRouter rankings.

Type:

Optional[str]

site_name

Optional app title for OpenRouter rankings.

Type:

Optional[str]

Example

>>> client = OpenRouterClient(api_key="sk-or-v1-...")
>>> response = client.generate_completion(
...     messages=[{"role": "user", "content": "Hello, Clara!"}],
...     model="openai/gpt-4o"
... )
>>> print(response.content)
DEFAULT_BASE_URL: str = 'https://openrouter.ai/api/v1'
DEFAULT_MODEL: str = 'openai/gpt-4o-mini'
generate_completion(messages, model=None, temperature=0.7, max_tokens=None, tools=None, **kwargs)[source]

Sends a synchronous chat completion request to OpenRouter.

Parameters:

  • messages (List[Dict[str, Any] | Message]) – Sequence of message turns representing history.

  • model (str | None) – Model identifier override.

  • temperature (float) – Sampling temperature between 0.0 and 2.0.

  • max_tokens (int | None) – Maximum number of completion tokens to generate.

  • tools (List[Dict[str, Any]] | None) – Optional tool/function definitions.

  • **kwargs (Any) – Additional parameters for OpenRouter API.

Returns:

Parsed model response.

Return type:

ModelResponse

Raises:

RuntimeError – If the HTTP request fails.

async a_generate_completion(messages, model=None, temperature=0.7, max_tokens=None, tools=None, **kwargs)[source]

Asynchronously sends a chat completion request to OpenRouter.

Parameters:

  • messages (List[Dict[str, Any] | Message]) – Sequence of message turns representing history.

  • model (str | None) – Model identifier override.

  • temperature (float) – Sampling temperature.

  • max_tokens (int | None) – Maximum tokens to generate.

  • tools (List[Dict[str, Any]] | None) – Optional tool definitions.

  • **kwargs (Any) – Extra parameters for OpenRouter payload.

Returns:

Parsed model response.

Return type:

ModelResponse

Raises:

RuntimeError – If the HTTP request fails.

Module contents

Agent orchestration and LLM provider interfaces for Clara Core.

This subpackage contains modules responsible for interacting with large language models, orchestrating agent reasoning steps, managing conversation context, and handling external model providers such as OpenRouter.