llmadapterevs 0.1.0__py3-none-any.whl

llmadapter/__init__.py

@@ -0,0 +1,205 @@
+import logging
+
+__version__ = "0.1.0"
+logging.getLogger(__name__).addHandler(logging.NullHandler())
+
+for _lib in ("openai", "httpcore", "httpx"):
+    logging.getLogger(_lib).addHandler(logging.NullHandler())
+del _lib
+
+from .core import AsyncLLMAdapter, LLMAdapter
+from .core.responses_capabilities import CapabilityStatus, ResponseCapabilities, ResponseCreateRequest
+from .errors import (
+    APIConnectionError,
+    AuthenticationError,
+    ChatCompletionError,
+    ConfigurationError,
+    ContentFilterError,
+    ContextLengthExceededError,
+    EmbeddingGenerationError,
+    InvalidResponseError,
+    InvalidResponseRequestError,
+    LLMAdapterError,
+    ModelNotFoundError,
+    RateLimitBackendUnavailableError,
+    RateLimitExceededError,
+    ResponseNotFoundError,
+    ResponsesError,
+    TimeOutError,
+    UnsupportedCapabilityError,
+)
+from .models import (
+    CompactedResponse,
+    Conversation,
+    ConversationDeleted,
+    InputTokenCountResponse,
+    Response,
+    ResponseCodeInterpreterCallItem,
+    ResponseCompletedEvent,
+    ResponseComputerCallItem,
+    ResponseDeleted,
+    ResponseFileSearchCallItem,
+    ResponseFunctionCallArgumentsDeltaEvent,
+    ResponseFunctionCallItem,
+    ResponseImageGenerationCallItem,
+    ResponseItem,
+    ResponseItemList,
+    ResponseMcpApprovalRequestItem,
+    ResponseMcpCallItem,
+    ResponseMcpListToolsItem,
+    ResponseMessageItem,
+    ResponseOutputItem,
+    ResponseOutputTextDeltaEvent,
+    ProviderExtensions,
+    ResponseReasoningItem,
+    ResponseReasoningSummaryDeltaEvent,
+    ResponseStreamEvent,
+    ResponseUsage,
+    ResponseWebSearchCallItem,
+    FileSearchResult,
+    CodeInterpreterOutput,
+    GeneratedImage,
+    ComputerAction,
+    WebSearchSource,
+)
+from .responses_tools import CodeInterpreterTool, ComputerTool, ConnectorTool, FileSearchTool, ImageGenerationTool, McpApprovalDecision, McpTool, WebSearchTool
+
+__all__ = [
+    "__version__",
+    # Adapters
+    "LLMAdapter",
+    "AsyncLLMAdapter",
+    "CapabilityStatus",
+    "ResponseCapabilities",
+    "ResponseCreateRequest",
+    # Errors
+    "LLMAdapterError",
+    "ConfigurationError",
+    "ContextLengthExceededError",
+    "InvalidResponseRequestError",
+    "UnsupportedCapabilityError",
+    "ModelNotFoundError",
+    "APIConnectionError",
+    "AuthenticationError",
+    "RateLimitExceededError",
+    "RateLimitBackendUnavailableError",
+    "ChatCompletionError",
+    "EmbeddingGenerationError",
+    "InvalidResponseError",
+    "ContentFilterError",
+    "TimeOutError",
+    "ResponsesError",
+    "ResponseNotFoundError",
+    # Responses API models
+    "Response",
+    "ResponseOutputItem",
+    "ResponseMessageItem",
+    "ResponseReasoningItem",
+    "ResponseFunctionCallItem",
+    "ResponseWebSearchCallItem",
+    "WebSearchSource",
+    "FileSearchResult",
+    "CodeInterpreterOutput",
+    "GeneratedImage",
+    "ComputerAction",
+    "WebSearchTool",
+    "FileSearchTool",
+    "CodeInterpreterTool",
+    "ImageGenerationTool",
+    "ComputerTool",
+    "McpTool",
+    "ConnectorTool",
+    "McpApprovalDecision",
+    "ResponseFileSearchCallItem",
+    "ResponseCodeInterpreterCallItem",
+    "ResponseImageGenerationCallItem",
+    "ResponseComputerCallItem",
+    "ResponseMcpListToolsItem",
+    "ResponseMcpApprovalRequestItem",
+    "ResponseMcpCallItem",
+    "ResponseUsage",
+    "ResponseItem",
+    "ResponseItemList",
+    "ResponseStreamEvent",
+    "ResponseCompletedEvent",
+    "ResponseOutputTextDeltaEvent",
+    "ResponseFunctionCallArgumentsDeltaEvent",
+    "ResponseReasoningSummaryDeltaEvent",
+    "ResponseDeleted",
+    "CompactedResponse",
+    "Conversation",
+    "ConversationDeleted",
+    "InputTokenCountResponse",
+    "ProviderExtensions",
+]
+
+# LangChain compatibility — optional import (requires langchain-core)
+try:
+    from .integrations.langchain import ChatLLMAdapter
+
+    __all__.append("ChatLLMAdapter")
+except ModuleNotFoundError as exc:
+    if exc.name != "langchain_core":
+        raise
+
+try:
+    from .orchestration import (
+        AdvancedAgentConfig,
+        AggregatedResult,
+        BaseAggregator,
+        BaseRoutingPolicy,
+        aaggregate_specialists,
+        ainvoke_specialists,
+        CollectingAgentEventHandler,
+        CostAwareRoutingPolicy,
+        CheckpointStore,
+        EscalationRoutingPolicy,
+        JsonMergeAggregator,
+        LLMAdapterAgent,
+        InMemoryCheckpointStore,
+        FileCheckpointStore,
+        LoggingAgentEventHandler,
+        MajorityVoteAggregator,
+        RoundRobinRoutingPolicy,
+        SharedState,
+        SpecialistContract,
+        WeightedScoreAggregator,
+        aggregate_specialists,
+        create_llmadapter_agent,
+        invoke_specialists,
+        make_specialist_tools,
+        make_subagent_tool,
+    )
+
+    __all__.extend(
+        [
+            "AdvancedAgentConfig",
+            "LLMAdapterAgent",
+            "create_llmadapter_agent",
+            "make_subagent_tool",
+            "make_specialist_tools",
+            "ainvoke_specialists",
+            "invoke_specialists",
+            "aaggregate_specialists",
+            "aggregate_specialists",
+            "AggregatedResult",
+            "BaseAggregator",
+            "JsonMergeAggregator",
+            "MajorityVoteAggregator",
+            "WeightedScoreAggregator",
+            "SharedState",
+            "SpecialistContract",
+            "CollectingAgentEventHandler",
+            "LoggingAgentEventHandler",
+            "BaseRoutingPolicy",
+            "RoundRobinRoutingPolicy",
+            "EscalationRoutingPolicy",
+            "CostAwareRoutingPolicy",
+            "CheckpointStore",
+            "InMemoryCheckpointStore",
+            "FileCheckpointStore",
+        ]
+    )
+except ModuleNotFoundError as exc:
+    if exc.name != "langchain_core":
+        raise

llmadapter/base.py

@@ -0,0 +1,120 @@
+from abc import ABC, abstractmethod
+
+
+class BaseProvider:
+    """
+    Global base class for all providers (Chat, Embeddings, etc.).
+    """
+
+
+class BaseChatProvider(BaseProvider, ABC):
+    """
+    Abstract base class for chat providers.
+    """
+
+    @abstractmethod
+    def create(self, messages, **kwargs):
+        """
+        Create a chat completion.
+
+        Args:
+            messages: List of message dicts or objects.
+            **kwargs: Additional parameters for provider.
+
+        Returns:
+            ChatCompletion or generator of ChatCompletionChunk.
+        """
+
+
+class BaseEmbeddingProvider(BaseProvider, ABC):
+    """
+    Abstract base class for embedding providers.
+    """
+
+    @abstractmethod
+    def create(self, inputs, **kwargs):
+        """
+        Create embeddings for the given inputs.
+
+        Args:
+            inputs: List of input strings or objects.
+            **kwargs: Additional parameters for provider.
+
+        Returns:
+            Embedding response object.
+        """
+
+
+class BaseResponsesProvider(BaseProvider, ABC):
+    """
+    Abstract base class for Responses API providers.
+
+    Only ``create`` is required; the remaining verbs raise
+    :class:`~llmadapter.errors.ResponsesError` by default so a provider can
+    implement a partial surface without breaking the adapter.
+    """
+
+    @abstractmethod
+    def create(self, input, **kwargs):  # noqa: A002
+        """
+        Create a model response.
+
+        Args:
+            input: A string or list of input items.
+            **kwargs: Additional parameters for provider (``stream``, ``tools``, …).
+
+        Returns:
+            Response, or a generator of ResponseStreamEvent when streaming.
+        """
+
+    def _unsupported(self, operation: str):
+        from .errors import ResponsesError
+        raise ResponsesError(
+            f"{type(self).__name__} does not support responses.{operation}",
+            status_code=501,
+        )
+
+    def retrieve(self, response_id, **kwargs):
+        """Retrieve a previously created response by id."""
+        return self._unsupported("retrieve")
+
+    def delete(self, response_id, **kwargs):
+        """Delete a stored response by id."""
+        return self._unsupported("delete")
+
+    def cancel(self, response_id, **kwargs):
+        """Cancel an in-progress background response."""
+        return self._unsupported("cancel")
+
+    def compact(self, **kwargs):
+        """Compact a response's conversation history."""
+        return self._unsupported("compact")
+
+    def list_input_items(self, response_id, **kwargs):
+        """List the input items of a response."""
+        return self._unsupported("input_items.list")
+
+    def count_input_tokens(self, **kwargs):
+        """Count the input tokens a request would consume."""
+        return self._unsupported("input_tokens.count")
+
+    def create_conversation(self, items=None, **kwargs):
+        return self._unsupported("conversations.create")
+
+    def retrieve_conversation(self, conversation_id, **kwargs):
+        return self._unsupported("conversations.retrieve")
+
+    def update_conversation(self, conversation_id, **kwargs):
+        return self._unsupported("conversations.update")
+
+    def delete_conversation(self, conversation_id, **kwargs):
+        return self._unsupported("conversations.delete")
+
+    def list_conversation_items(self, conversation_id, **kwargs):
+        return self._unsupported("conversations.items.list")
+
+    def retrieve_conversation_item(self, conversation_id, item_id, **kwargs):
+        return self._unsupported("conversations.items.retrieve")
+
+    def delete_conversation_item(self, conversation_id, item_id, **kwargs):
+        return self._unsupported("conversations.items.delete")

llmadapter/config.py

@@ -0,0 +1,191 @@
+"""
+config.py
+
+This module defines configuration classes for different LLM providers using Pydantic models. These classes validate and store provider-specific settings such as API keys, endpoints, rate limits, and deployment information. The CONFIG_REGISTRY dictionary maps provider names to their configuration classes for easy lookup.
+
+Classes:
+    BaseLLMConfig: Base configuration for all providers.
+    AzureOpenAIConfig, AzureFoundryConfig, VertexAIConfig, OpenAIConfig, AnthropicConfig:
+        Provider-specific configuration models.
+
+Constants:
+    CONFIG_REGISTRY: Maps provider names to their config classes.
+"""
+
+from typing import Any, Literal, Optional
+
+from pydantic import BaseModel, ConfigDict, Field, ValidationInfo, field_validator
+
+from .constants import (
+    DEFAULT_COMPLETION_CONTEXT_WINDOW,
+    DEFAULT_EMBEDDING_RPM,
+    DEFAULT_EMBEDDING_TPM,
+    DEFAULT_MAX_RETRIES,
+    DEFAULT_RETRY_BASE_DELAY,
+    DEFAULT_RPM,
+    DEFAULT_TPM,
+)
+
+
+class BaseLLMConfig(BaseModel):
+    """
+    Base configuration for LLM providers, including model, rate limits, and Redis settings.
+    All provider-specific configs should inherit from this class.
+    """
+    # A unified adapter accepts the union of provider-specific constructor
+    # signatures. Providers consume their own fields and safely ignore the rest.
+    model_config = ConfigDict(extra="allow", str_strip_whitespace=True)
+
+    provider: str = Field(..., min_length=1, description="Provider name (openai, azure_openai, azure_foundry, etc.)")
+    model: Optional[str] = Field(default=None, description="Model name or ID")
+    deployment_name: Optional[str] = Field(
+        default=None,
+        description="Provider deployment/model alias; when supplied it is the default effective model",
+    )
+
+    @property
+    def effective_model(self) -> Optional[str]:
+        """Return the unified deployment-first default model identifier."""
+        return self.deployment_name or self.model
+    rpm: int = Field(default=DEFAULT_RPM, ge=0, description="Requests per minute limit (chat)")
+    tpm: int = Field(default=DEFAULT_TPM, ge=0, description="Tokens per minute limit (chat)")
+    embedding_rpm: int = Field(default=DEFAULT_EMBEDDING_RPM, ge=0,
+                               description="Requests per minute limit (embeddings)")
+    embedding_tpm: int = Field(default=DEFAULT_EMBEDDING_TPM, ge=0,
+                               description="Tokens per minute limit (embeddings)")
+    completion_context_window: int = Field(default=DEFAULT_COMPLETION_CONTEXT_WINDOW, gt=0,
+                                           description="Context window size for completion models")
+    context_output_reserve_tokens: int = Field(default=0, ge=0,
+                                                description="Output-token capacity reserved for every request")
+    context_overhead_tokens: int = Field(default=0, ge=0,
+                                         description="Additional caller-known protocol overhead tokens")
+    responses_capabilities: dict[str, bool] = Field(
+        default_factory=dict,
+        description="Per-target Responses capability overrides; False rejects a feature before dispatch",
+    )
+    mcp_policy: Optional[dict[str, Any]] = Field(
+        default=None, description="Explicit policy required before remote MCP or connector tools are sent"
+    )
+    redis_url: Optional[str] = Field(default=None,
+                                     description="Redis URL for distributed rate limiting; None uses process-local limits")
+    rate_limit_failure_policy: Literal["memory_fallback", "fail_open", "fail_closed"] = Field(
+        default="memory_fallback",
+        description="Behavior when a configured Redis rate-limit backend is unavailable",
+    )
+    redis_connect_timeout: float = Field(default=1.0, gt=0, allow_inf_nan=False,
+                                         description="Redis connect/read timeout in seconds")
+    user_id: str = Field(default="global", min_length=1, description="User identifier for rate limiting")
+    backup: Optional[dict[str, Any]] = Field(default=None, description="Backup provider config for failover")
+    timeout: Optional[float] = Field(default=None, gt=0, allow_inf_nan=False,
+                                     description="Request timeout in seconds (applies to all providers)")
+    max_retries: int = Field(default=DEFAULT_MAX_RETRIES, ge=0,
+                             description="Number of retry attempts for transient errors (429, 5xx, connection). 0 = no retry.")
+    retry_base_delay: float = Field(default=DEFAULT_RETRY_BASE_DELAY, ge=0, allow_inf_nan=False,
+                                    description="Base delay in seconds for exponential back-off between retries.")
+
+    @field_validator("provider", "user_id", mode="before")
+    def required_string_fields(cls, v, info: ValidationInfo):
+        """
+        Validate required string fields to ensure they are not empty.
+        """
+        if v is None or (isinstance(v, str) and not v.strip()):
+            raise ValueError(f"{info.field_name} is required and cannot be empty")
+        return v
+
+    @field_validator("backup")
+    @classmethod
+    def validate_backup_shape(cls, value: Optional[dict[str, Any]]) -> Optional[dict[str, Any]]:
+        if value is None:
+            return None
+        if not value.get("provider") or not isinstance(value["provider"], str):
+            raise ValueError("backup.provider is required and must be a non-empty string")
+        return value
+
+
+class AzureOpenAIConfig(BaseLLMConfig):
+    """
+    Configuration for Azure OpenAI provider, including API key, endpoint, and deployment info.
+    Inherits from BaseLLMConfig.
+    """
+    api_key: str = Field(..., min_length=1, description="API key for authentication")
+    endpoint: str = Field(..., min_length=1, description="Custom endpoint or base URL")
+    api_version: str = Field(..., min_length=1, description="API version (e.g., for Azure OpenAI)")
+    responses_api_version: Optional[str] = Field(
+        default=None, description="API version override for responses.* calls (Azure OpenAI)")
+    deployment_name: str = Field(..., min_length=1, description="Deployment name for Azure OpenAI")
+    region: Optional[str] = Field(default=None, description="Region for Azure services")
+
+
+class AzureFoundryConfig(BaseLLMConfig):
+    """
+    Configuration for Azure Foundry provider, including API key, endpoint, and deployment info.
+    Inherits from BaseLLMConfig.
+    """
+    api_key: str = Field(..., min_length=1, description="API key for authentication")
+    endpoint: str = Field(..., min_length=1, description="Custom endpoint or base URL")
+    deployment_name: str = Field(..., min_length=1, description="Deployment Name or Model name for Azure Foundry")
+    api_version: str = Field(..., min_length=1, description="API version (e.g., for Azure Foundry)")
+
+
+class VertexAIConfig(BaseLLMConfig):
+    """
+    Configuration for VertexAI provider, including location, scopes, and model info.
+    Inherits from BaseLLMConfig.
+    """
+    location: str = Field(..., min_length=1, description="GCP location (e.g., us-central1)")
+    credentials_path: str = Field(..., min_length=1, description="Path to GCP credentials JSON file")
+    scopes: list[str] = Field(default_factory=lambda: ["https://www.googleapis.com/auth/cloud-platform"],
+                              description="OAuth scopes for GCP authentication")
+
+
+class OpenAIConfig(BaseLLMConfig):
+    """
+    Configuration for native OpenAI provider, including API key and optional base URL.
+    Inherits from BaseLLMConfig.
+    """
+    api_key: str = Field(..., min_length=1, description="API key for OpenAI authentication")
+    endpoint: Optional[str] = Field(default=None, description="Custom base URL (e.g., for proxies or compatible APIs)")
+    organization: Optional[str] = Field(default=None, description="OpenAI organization ID")
+    project: Optional[str] = Field(default=None, description="OpenAI project ID to scope requests")
+
+
+class AnthropicConfig(BaseLLMConfig):
+    """
+    Configuration for the Anthropic (Claude) provider.
+
+    Prompt caching is enabled by default (``enable_prompt_caching=True``).
+    When enabled, the provider automatically injects ``cache_control`` on
+    system messages and tool definitions so repeated calls reuse the cached
+    prefix instead of re-charging full input-token cost.
+
+    Inherits from BaseLLMConfig.
+    """
+    api_key: str = Field(..., min_length=1, description="Anthropic API key")
+    deployment_name: Optional[str] = Field(
+        default=None,
+        description=(
+            "Preferred deployment/model identifier for Anthropic-compatible endpoints. "
+            "If provided with model, deployment_name takes precedence."
+        ),
+    )
+    endpoint: Optional[str] = Field(
+        default=None,
+        description="Custom base URL (e.g., for an Anthropic-compatible proxy or gateway)",
+    )
+    enable_prompt_caching: bool = Field(
+        default=True,
+        description=(
+            "Auto-inject cache_control on system messages and tool definitions. "
+            "Requires ≥2048 cacheable tokens for Claude Sonnet/Opus, ≥1024 for Haiku."
+        ),
+    )
+
+
+# Register in config registry
+CONFIG_REGISTRY = {
+    "azure_openai": AzureOpenAIConfig,
+    "azure_foundry": AzureFoundryConfig,
+    "vertexai": VertexAIConfig,
+    "openai": OpenAIConfig,
+    "anthropic": AnthropicConfig,
+}

llmadapter/constants.py

@@ -0,0 +1,13 @@
+DEFAULT_RPM = 10000
+DEFAULT_TPM = 1000000
+DEFAULT_EMBEDDING_RPM = 10000
+DEFAULT_EMBEDDING_TPM = 1000000
+DEFAULT_WINDOW_SECONDS = 60
+DEFAULT_COMPLETION_CONTEXT_WINDOW = 123000  # (based on 124000 token limit minus some buffer)
+
+# Retry / exponential back-off defaults
+DEFAULT_MAX_RETRIES = 3  # number of *retries* (not total attempts)
+DEFAULT_RETRY_BASE_DELAY = 1.0  # seconds — doubling each attempt
+DEFAULT_RETRY_MAX_DELAY = 60.0  # seconds — cap on the backoff ceiling
+
+DEFAULT_ANTHROPIC_MODEL = "claude-opus-4-5"

llmadapter/core/__init__.py

@@ -0,0 +1,32 @@
+"""
+core
+
+The adapter engine: public ``LLMAdapter`` / ``AsyncLLMAdapter`` entry points plus
+the internal handlers, provider registries, retry/failover/preprocess helpers,
+and log redaction.
+"""
+from __future__ import annotations
+
+from .async_adapter import AsyncLLMAdapter
+from .failover import merge_backup_config, prepare_backup_provider
+from .preprocess import ProviderCache, prepare_messages
+from .redaction import redact_sensitive
+from .registry import (
+    ASYNC_CHAT_PROVIDER_REGISTRY,
+    CHAT_PROVIDER_REGISTRY,
+    EMBEDDING_PROVIDER_REGISTRY,
+)
+from .sync_adapter import LLMAdapter
+
+__all__ = [
+    "LLMAdapter",
+    "AsyncLLMAdapter",
+    "CHAT_PROVIDER_REGISTRY",
+    "ASYNC_CHAT_PROVIDER_REGISTRY",
+    "EMBEDDING_PROVIDER_REGISTRY",
+    "redact_sensitive",
+    "prepare_messages",
+    "ProviderCache",
+    "prepare_backup_provider",
+    "merge_backup_config",
+]