Provider API

All retained providers use HTTPX and ship in the core installation. No vendor SDK is required. Import classes from seqoria_agent.providers; each backend exposes async and synchronous variants. Use async providers with AsyncAIClient. AIClient adapts either variant for blocking scripts.

Backend	Async class	Sync class	Service required
OpenAI	AsyncOpenAIProvider	OpenAIProvider	OpenAI API credentials and model access
OpenAI-compatible HTTP	AsyncOpenAICompatibleProvider	OpenAICompatibleProvider	Compatible endpoint and its credentials
Anthropic	AsyncAnthropicProvider	AnthropicProvider	Anthropic API credentials and model access
Ollama	AsyncOllamaProvider	OllamaProvider	Running Ollama service and a suitable model

Use explicit model IDs supported by the endpoint. OpenAI-compatible services differ in tool, streaming, image, and reasoning support; an accepted HTTP schema does not guarantee all capabilities. Default tests use deterministic HTTP transports. They do not certify every hosted model or endpoint.

The application owns provider resources. Enter provider context managers before client context managers, then close clients before providers. A provider must stay within its owning event loop when used asynchronously. Failed streams after partial output raise rather than replaying output through a fallback provider.

OpenAI

seqoria_agent.providers.openai_provider.AsyncOpenAIProvider

Bases: AsyncBaseProvider, _OpenAIProviderMixin

Asynchronous provider implementation for OpenAI Responses API via HTTPX.

async_generate(chat_history: ChatHistory, tools: Optional[List[Dict[str, Any]]] = None, tool_choice: Optional[Union[str, Dict[str, Any]]] = None, model: Optional[str] = None, **kwargs) -> Union[LLMResponse, ToolCallList] async

Asynchronously generate a completion for provided chat history.

async_stream(chat_history: ChatHistory, tools: Optional[List[Dict[str, Any]]] = None, tool_choice: Optional[Union[str, Dict[str, Any]]] = None, model: Optional[str] = None, **kwargs) -> AsyncGenerator[Union[LLMResponse, ToolCallList], None] async

Asynchronously stream a completion for provided chat history.

validate_model() -> None async

Validate that configured model is available via API.

seqoria_agent.providers.openai_provider.OpenAIProvider

Bases: BaseProvider, _OpenAIProviderMixin

Synchronous provider implementation for OpenAI Responses API via HTTPX.

generate(chat_history: ChatHistory, tools: Optional[List[Dict[str, Any]]] = None, tool_choice: Optional[Union[str, Dict[str, Any]]] = None, model: Optional[str] = None, **kwargs) -> Union[LLMResponse, ToolCallList]

Synchronously generate a completion for provided chat history.

stream(chat_history: ChatHistory, tools: Optional[List[Dict[str, Any]]] = None, tool_choice: Optional[Union[str, Dict[str, Any]]] = None, model: Optional[str] = None, **kwargs) -> Generator[Union[LLMResponse, ToolCallList], None, None]

Synchronously stream a completion for provided chat history.

validate_model() -> None

Validate that configured model is available via API.

OpenAI-compatible HTTP

seqoria_agent.providers.openai_compatible_provider.AsyncOpenAICompatibleProvider

Bases: AsyncBaseProvider, _OpenAICompatibleProviderMixin

Async OpenAI-compatible provider using HTTPX + Chat Completions API.

validate_model() -> None async

Validate that configured model exists for this endpoint.

seqoria_agent.providers.openai_compatible_provider.OpenAICompatibleProvider

Bases: BaseProvider, _OpenAICompatibleProviderMixin

Sync OpenAI-compatible provider using HTTPX + Chat Completions API.

validate_model() -> None

Validate that configured model exists for this endpoint.

Anthropic

seqoria_agent.providers.anthropic_provider.AsyncAnthropicProvider

Bases: AsyncBaseProvider, _AnthropicProviderMixin

Asynchronous Anthropic provider implemented with HTTPX.

async_generate(chat_history: ChatHistory, tools: Optional[List[Dict[str, Any]]] = None, tool_choice: Optional[Union[str, Dict[str, Any]]] = None, model: Optional[str] = None, **kwargs) -> Union[LLMResponse, ToolCallList] async

Asynchronously generate an Anthropic message completion.

async_stream(chat_history: ChatHistory, tools: Optional[List[Dict[str, Any]]] = None, tool_choice: Optional[Union[str, Dict[str, Any]]] = None, model: Optional[str] = None, **kwargs) -> AsyncGenerator[Union[LLMResponse, ToolCallList], None] async

Asynchronously stream Anthropic message deltas and final response.

validate_model() -> None async

Validate configured model is available via Anthropic API.

seqoria_agent.providers.anthropic_provider.AnthropicProvider

Bases: BaseProvider, _AnthropicProviderMixin

Synchronous Anthropic provider implemented with HTTPX.

generate(chat_history: ChatHistory, tools: Optional[List[Dict[str, Any]]] = None, tool_choice: Optional[Union[str, Dict[str, Any]]] = None, model: Optional[str] = None, **kwargs) -> Union[LLMResponse, ToolCallList]

Synchronously generate an Anthropic message completion.

stream(chat_history: ChatHistory, tools: Optional[List[Dict[str, Any]]] = None, tool_choice: Optional[Union[str, Dict[str, Any]]] = None, model: Optional[str] = None, **kwargs) -> Generator[Union[LLMResponse, ToolCallList], None, None]

Synchronously stream Anthropic message deltas and final response.

validate_model() -> None

Validate configured model is available via Anthropic API.

Ollama

seqoria_agent.providers.ollama_provider.AsyncOllamaProvider

Bases: AsyncBaseProvider, _OllamaProviderMixin

Asynchronous provider implementation for Ollama HTTP API.

async_generate(chat_history: ChatHistory, tools: Optional[List[Dict[str, Any]]] = None, tool_choice: Optional[Union[str, Dict[str, Any]]] = None, model: Optional[str] = None, **kwargs) -> Union[LLMResponse, ToolCallList] async

Asynchronously generate a completion for provided chat history.

async_stream(chat_history: ChatHistory, tools: Optional[List[Dict[str, Any]]] = None, tool_choice: Optional[Union[str, Dict[str, Any]]] = None, model: Optional[str] = None, **kwargs) -> AsyncGenerator[Union[LLMResponse, ToolCallList], None] async

Asynchronously stream a completion for provided chat history.

validate_model() -> None async

Validate that configured model is available.

seqoria_agent.providers.ollama_provider.OllamaProvider

Bases: BaseProvider, _OllamaProviderMixin

Synchronous provider implementation for Ollama HTTP API.

generate(chat_history: ChatHistory, tools: Optional[List[Dict[str, Any]]] = None, tool_choice: Optional[Union[str, Dict[str, Any]]] = None, model: Optional[str] = None, **kwargs) -> Union[LLMResponse, ToolCallList]

Synchronously generate a completion for provided chat history.

stream(chat_history: ChatHistory, tools: Optional[List[Dict[str, Any]]] = None, tool_choice: Optional[Union[str, Dict[str, Any]]] = None, model: Optional[str] = None, **kwargs) -> Generator[Union[LLMResponse, ToolCallList], None, None]

Synchronously stream a completion for provided chat history.

validate_model() -> None

Validate that configured model is available.

Custom provider interfaces

seqoria_agent.providers.base_provider

Base provider abstract class for standardizing LLM provider interfaces.

This module defines the BaseProvider abstract base class that all LLM providers must inherit from, ensuring a consistent interface across different providers like OpenAI, Anthropic, Bedrock, and SambaNova.

Two variants are provided: - AsyncBaseProvider: For asynchronous operations (async/await) - BaseProvider: For synchronous operations (blocking calls)

AsyncBaseProvider

Bases: ABC

Abstract base class for all asynchronous LLM providers.

This class defines the standard interface that all async provider implementations must follow, ensuring consistency and type safety across different LLM providers.

__init__(model_id: Optional[str] = None, **kwargs) -> None

No-op default constructor.

Concrete provider implementations MAY override this to perform real client setup. The default implementation exists so that lightweight test stubs (e.g. DummyProvider inside the unit-test suite) do not have to implement an unnecessary __init__ just to satisfy the abstract base-class requirements. Runtime code never relies on any state established here.

aclose() -> None async

Release this provider's HTTP client after all requests have finished.

async_generate(chat_history: ChatHistory, tools: Optional[List[Dict[str, Any]]] = None, tool_choice: Optional[Union[str, Dict[str, Any]]] = None, model: Optional[str] = None, **kwargs) -> Union[LLMResponse, ToolCallList] abstractmethod async

Asynchronously generate a completion for the provided chat history.

Args: chat_history: List of message dictionaries (e.g., [{"role": "user", "content": "Hi"}]). tools: Optional list of tool definitions for function calling. Each tool should have 'name', 'description', and 'input_schema' fields. tool_choice: Optional tool choice configuration. Format may vary by provider. model: Optional identifier for the model. **kwargs: Generation parameters overriding defaults (e.g., temperature, max_tokens).

async_stream(chat_history: ChatHistory, tools: Optional[List[Dict[str, Any]]] = None, tool_choice: Optional[Union[str, Dict[str, Any]]] = None, model: Optional[str] = None, **kwargs) -> AsyncGenerator[Union[LLMResponse, ToolCallList], None] abstractmethod

Asynchronously stream a completion for the provided chat history.

Yields LLMResponse deltas as they arrive, and finally yields a single LLMResponse or ToolCallList containing the complete result and token usage.

Args: chat_history: List of message dictionaries. tools: Optional list of tool definitions for function calling. tool_choice: Optional tool choice configuration. model: Optional identifier for the model. **kwargs: Generation parameters overriding defaults.

Yields:

Type	Description
LLMResponse: Incremental text or thinking chunks.	LLMResponse: The final, complete response object.

BaseProvider

Bases: ABC

Abstract base class for all synchronous LLM providers.

This class defines the standard interface that all sync provider implementations must follow, ensuring consistency and type safety across different LLM providers.

__init__(model_id: Optional[str] = None, **kwargs) -> None

No-op default constructor.

Concrete provider implementations MAY override this to perform real client setup. The default implementation exists so that lightweight test stubs (e.g. DummyProvider inside the unit-test suite) do not have to implement an unnecessary __init__ just to satisfy the abstract base-class requirements. Runtime code never relies on any state established here.

close() -> None

Release this provider's HTTP client.

generate(chat_history: ChatHistory, tools: Optional[List[Dict[str, Any]]] = None, tool_choice: Optional[Union[str, Dict[str, Any]]] = None, model: Optional[str] = None, **kwargs) -> Union[LLMResponse, ToolCallList] abstractmethod

Synchronously generate a completion for the provided chat history.

Args: chat_history: List of message dictionaries (e.g., [{"role": "user", "content": "Hi"}]). tools: Optional list of tool definitions for function calling. Each tool should have 'name', 'description', and 'input_schema' fields. tool_choice: Optional tool choice configuration. Format may vary by provider. model: Optional identifier for the model. **kwargs: Generation parameters overriding defaults (e.g., temperature, max_tokens).

stream(chat_history: ChatHistory, tools: Optional[List[Dict[str, Any]]] = None, tool_choice: Optional[Union[str, Dict[str, Any]]] = None, model: Optional[str] = None, **kwargs) -> Generator[Union[LLMResponse, ToolCallList], None, None] abstractmethod

Synchronously stream a completion for the provided chat history.

Yields LLMResponse deltas as they arrive, and finally yields a single LLMResponse or ToolCallList containing the complete result and token usage.

Args: chat_history: List of message dictionaries. tools: Optional list of tool definitions for function calling. tool_choice: Optional tool choice configuration. model: Optional identifier for the model. **kwargs: Generation parameters overriding defaults.

Yields:

Type	Description
LLMResponse: Incremental text or thinking chunks.	LLMResponse: The final, complete response object.

Factory helpers

seqoria_agent.providers.get_provider(name: str, async_variant: bool = True) -> type

Get a provider class by name.

Example

provider_cls = get_provider("openai") provider = provider_cls(model_id="gpt-4o")

seqoria_agent.providers.list_available_providers() -> dict[str, bool]

List all providers and their availability status.

Example

list_available_providers() {'openai': True, 'openai_compatible': True, 'anthropic': True, 'ollama': True}

list_available_providers() checks local dependency availability, not endpoint health, credentials, installed models, or tool support.

Schemas and errors

seqoria_agent.providers.schemas

Standardized Pydantic schemas for data exchange with LLM providers.

These models define a canonical structure for LLM responses, including text content, tool calls, and token usage, ensuring that the AIClient can interact with any provider in a uniform way.

LLMResponse

Bases: BaseModel

Standardized response object from an LLM provider call.

This object is returned by a provider's async_generate method and is the final object yielded by the async_stream method.

LLMUsage

Bases: BaseModel

Standardized token usage information.

ToolCall

Bases: BaseModel

Standardized representation of a tool call requested by the LLM.

This structure is modeled after OpenAI's format, which has become a de-facto standard. Providers are responsible for mapping their native tool-call format to this structure.

ToolCallList

Bases: BaseModel

Standardized representation of a list of tool calls.

seqoria_agent.providers.errors

LLM Provider Error Hierarchy and Unified Error Mapping.

This module defines the exception hierarchy for LLM provider errors and provides utilities for mapping provider-specific exceptions to our standardized error types.

ConnectionError

Bases: LLMError

Raised when connection to the LLM provider fails.

__init__(provider, message='Cannot connect to LLM provider') -> None

Initialize the error with provider information.

Args: provider: Name of the provider that couldn't be connected to message: Error description message

ContentFilterError

Bases: LLMError

Raised when content is filtered for safety reasons.

__init__(provider, filter_reason=None) -> None

Initialize the error with filter information.

Args: provider: Name of the provider that filtered the content filter_reason: Reason for filtering, if provided

ContextLengthExceededError

Bases: LLMError

Raised when prompt exceeds model's context window.

__init__(model_id, tokens=None, max_tokens=None) -> None

Initialize the error with context length details.

Args: model_id: ID of the model whose context length was exceeded tokens: Number of tokens in the prompt (if known) max_tokens: Maximum allowed tokens (if known)

EnvironmentError

Bases: LLMError

Raised when required environment variables are missing.

__init__(message='Required environment variables are missing', missing_vars=None) -> None

Initialize the error with detailed information.

Args: message: Error description message missing_vars: List of missing environment variable names

ErrorMapper

Unified error mapper for converting provider-specific exceptions.

This class provides a declarative way to map provider exceptions to our standardized error hierarchy, reducing boilerplate in providers.

Example

class AuthenticationError(Exception): ... class RateLimitError(Exception): ... mapper = ErrorMapper("OpenAI") mapper.register(AuthenticationError, ... lambda e, m: EnvironmentError(f"Auth failed: {e}", missing_vars=["OPENAI_API_KEY"])) mapper.register(RateLimitError, ... lambda e, m: QuotaExceededError(provider="OpenAI", limit_type="rate"))

In provider code:

try: ... result = await client.chat.create(...) except Exception as e: ... raise mapper.map(e, model_id="gpt-4o")

__call__(error: Exception, model_id: str | None = None) -> LLMError

Callable shorthand for map().

__init__(provider_name: str) -> None

Initialize the error mapper.

map(error: Exception, model_id: str | None = None) -> LLMError

Map an exception to our error hierarchy.

register(exc_type: Type[Exception], handler: Callable[[Exception, str | None], LLMError]) -> 'ErrorMapper'

Register a handler for a specific exception type.

register_pattern(pattern: str, handler: Callable[[Exception, str | None, re.Match], LLMError]) -> 'ErrorMapper'

Register a handler for exceptions matching a regex pattern.

register_status_code(status_code: int, handler: Callable[[Exception, str | None], LLMError]) -> 'ErrorMapper'

Register a handler for a specific HTTP status code.

InvalidRequestError

Bases: LLMError

Raised when request parameters are invalid.

__init__(message, param=None) -> None

Initialize the error with parameter details.

Args: message: Error description message param: Name of the invalid parameter, if specific

LLMError

Bases: Exception

Base class for all LLM-related errors.

MaxRetriesExceededError

Bases: LLMError

Raised when maximum retry attempts have been exceeded.

__init__(operation, max_retries, last_error=None) -> None

Initialize the error with retry information.

Args: operation: Description of the operation that failed max_retries: Maximum number of retries that were attempted last_error: The last error encountered (if available)

ModelNotFoundError

Bases: LLMError

Raised when the requested model doesn't exist or isn't accessible.

__init__(model_id, provider, fallback_model=None, available_models=None) -> None

Initialize the error with model information.

Args: model_id: ID of the requested model that wasn't found provider: Name of the provider fallback_model: Model ID being used as fallback, if any available_models: List of available model IDs from the provider

QuotaExceededError

Bases: LLMError

Raised when provider quota or rate limit is exceeded.

__init__(provider, limit_type='quota') -> None

Initialize the error with quota information.

Args: provider: Name of the provider whose quota was exceeded limit_type: Type of limit exceeded (e.g., "quota", "rate", "budget")

ServerError

Bases: LLMError

Raised when the provider experiences an internal server error.

__init__(provider, status_code=None) -> None

Initialize the error with server information.

Args: provider: Name of the provider experiencing the error status_code: HTTP status code if applicable

create_anthropic_error_mapper() -> ErrorMapper

Create an error mapper pre-configured for Anthropic.

create_openai_error_mapper() -> ErrorMapper

Create an error mapper pre-configured for OpenAI.