pyagent-providers 0.1.0__py3-none-any.whl

pyagent_providers/__init__.py

@@ -0,0 +1,30 @@
+"""PyAgent Providers — multi-provider abstraction with capability negotiation and fallback chains."""
+
+from pyagent_providers.base import (
+    HealthStatus,
+    ProviderCapabilities,
+    ProviderInfo,
+    ProviderProtocol,
+)
+from pyagent_providers.cost import CostOptimizer, ProviderCostEstimate
+from pyagent_providers.fallback import FallbackChain, FallbackResult
+from pyagent_providers.negotiation import CapabilityNegotiator, NegotiationResult
+from pyagent_providers.registry import ProviderRegistry
+from pyagent_providers.router import ProviderRouter, RoutingStrategy
+
+__all__ = [
+    "CapabilityNegotiator",
+    "CostOptimizer",
+    "FallbackChain",
+    "FallbackResult",
+    "HealthStatus",
+    "NegotiationResult",
+    "ProviderCapabilities",
+    "ProviderCostEstimate",
+    "ProviderInfo",
+    "ProviderProtocol",
+    "ProviderRegistry",
+    "ProviderRouter",
+    "RoutingStrategy",
+]
+__version__ = "0.1.0"

pyagent_providers/adapters/__init__.py

@@ -0,0 +1,27 @@
+"""Provider adapters — concrete implementations of ProviderProtocol."""
+
+from pyagent_providers.adapters.mock import MockProvider
+
+__all__ = ["MockProvider"]
+
+# Optional adapters — import fails gracefully if deps not installed
+try:
+    from pyagent_providers.adapters.openai import OpenAIProvider
+
+    __all__.append("OpenAIProvider")
+except ImportError:
+    pass
+
+try:
+    from pyagent_providers.adapters.anthropic import AnthropicProvider
+
+    __all__.append("AnthropicProvider")
+except ImportError:
+    pass
+
+try:
+    from pyagent_providers.adapters.litellm import LiteLLMProvider
+
+    __all__.append("LiteLLMProvider")
+except ImportError:
+    pass

pyagent_providers/adapters/anthropic.py

@@ -0,0 +1,106 @@
+"""AnthropicProvider: wraps the Anthropic Python client as a ProviderProtocol."""
+
+from __future__ import annotations
+
+import anthropic
+
+from pyagent_patterns.base import Message, Role
+from pyagent_providers.base import HealthStatus, ProviderCapabilities
+from pyagent_router.selector import Capability
+
+
+class AnthropicProvider:
+    """Anthropic provider implementing ``ProviderProtocol``.
+
+    Requires: ``pip install pyagent-providers[anthropic]``
+
+    Args:
+        api_key: Anthropic API key. Falls back to ``ANTHROPIC_API_KEY`` env var.
+        models: Models this provider exposes.
+        default_model: Model to use when none is specified.
+        name: Provider identifier. Defaults to ``"anthropic"``.
+        max_tokens: Default max tokens for completions.
+    """
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        models: list[str] | None = None,
+        default_model: str = "claude-sonnet-4-20250514",
+        name: str = "anthropic",
+        max_tokens: int = 4096,
+    ) -> None:
+        self._client = anthropic.AsyncAnthropic(api_key=api_key)
+        self._default_model = default_model
+        self._name = name
+        self._max_tokens = max_tokens
+        self._models = models or [
+            "claude-haiku-3-5-20241022",
+            "claude-sonnet-4-20250514",
+        ]
+        self._capabilities = ProviderCapabilities(
+            models=self._models,
+            capabilities={
+                Capability.GENERAL,
+                Capability.CODE,
+                Capability.REASONING,
+                Capability.CREATIVE,
+                Capability.VISION,
+            },
+            max_context=200_000,
+            supports_streaming=True,
+            supports_tools=True,
+            supports_vision=True,
+        )
+
+    @property
+    def name(self) -> str:
+        return self._name
+
+    @property
+    def capabilities(self) -> ProviderCapabilities:
+        return self._capabilities
+
+    async def health(self) -> HealthStatus:
+        """Check connectivity by counting available tokens (lightweight call)."""
+        try:
+            await self._client.messages.count_tokens(
+                model=self._default_model,
+                messages=[{"role": "user", "content": "ping"}],
+            )
+            return HealthStatus.HEALTHY
+        except Exception:
+            return HealthStatus.UNHEALTHY
+
+    async def complete(self, messages: list[Message], model: str | None = None) -> str:
+        """Generate a completion using the Anthropic Messages API.
+
+        Anthropic requires system messages to be passed separately from the
+        conversation history.
+
+        Args:
+            messages: Conversation history.
+            model: Model override. Uses ``default_model`` if ``None``.
+
+        Returns:
+            The assistant response text.
+        """
+        system = next(
+            (m.content for m in messages if m.role == Role.SYSTEM),
+            "You are a helpful assistant.",
+        )
+        chat_msgs = [
+            {"role": m.role.value, "content": m.content}
+            for m in messages
+            if m.role != Role.SYSTEM
+        ]
+        response = await self._client.messages.create(
+            model=model or self._default_model,
+            max_tokens=self._max_tokens,
+            system=system,
+            messages=chat_msgs,
+        )
+        return response.content[0].text
+
+    async def __call__(self, messages: list[Message]) -> str:
+        return await self.complete(messages)

pyagent_providers/adapters/litellm.py

@@ -0,0 +1,90 @@
+"""LiteLLMProvider: wraps LiteLLM as a ProviderProtocol (100+ model providers)."""
+
+from __future__ import annotations
+
+import litellm
+
+from pyagent_patterns.base import Message
+from pyagent_providers.base import HealthStatus, ProviderCapabilities
+from pyagent_router.selector import Capability
+
+
+class LiteLLMProvider:
+    """LiteLLM provider implementing ``ProviderProtocol``.
+
+    LiteLLM proxies 100+ model providers (OpenAI, Anthropic, Gemini, Ollama,
+    Bedrock, Azure, etc.) through a unified interface.
+
+    Requires: ``pip install pyagent-providers[litellm]``
+
+    Args:
+        models: List of LiteLLM model strings this provider exposes.
+        default_model: Model to use when none is specified.
+        name: Provider identifier. Defaults to ``"litellm"``.
+        capabilities: Capability set. Defaults to broad general capabilities.
+        max_context: Max context window.
+    """
+
+    def __init__(
+        self,
+        models: list[str] | None = None,
+        default_model: str = "gpt-4o-mini",
+        name: str = "litellm",
+        capabilities: set[Capability] | None = None,
+        max_context: int = 128_000,
+    ) -> None:
+        self._default_model = default_model
+        self._name = name
+        self._models = models or [
+            "gpt-4o-mini",
+            "gpt-4o",
+            "anthropic/claude-sonnet-4-20250514",
+            "gemini/gemini-2.5-flash",
+        ]
+        self._capabilities = ProviderCapabilities(
+            models=self._models,
+            capabilities=capabilities
+            or {Capability.GENERAL, Capability.CODE, Capability.REASONING},
+            max_context=max_context,
+            supports_streaming=True,
+            supports_tools=True,
+        )
+
+    @property
+    def name(self) -> str:
+        return self._name
+
+    @property
+    def capabilities(self) -> ProviderCapabilities:
+        return self._capabilities
+
+    async def health(self) -> HealthStatus:
+        """Verify LiteLLM can reach at least one provider."""
+        try:
+            response = await litellm.acompletion(
+                model=self._default_model,
+                messages=[{"role": "user", "content": "ping"}],
+                max_tokens=1,
+            )
+            return HealthStatus.HEALTHY
+        except Exception:
+            return HealthStatus.DEGRADED
+
+    async def complete(self, messages: list[Message], model: str | None = None) -> str:
+        """Generate a completion using LiteLLM's unified API.
+
+        Args:
+            messages: Conversation history.
+            model: LiteLLM model string override. Uses ``default_model`` if ``None``.
+
+        Returns:
+            The assistant response text.
+        """
+        response = await litellm.acompletion(
+            model=model or self._default_model,
+            messages=[{"role": m.role.value, "content": m.content} for m in messages],
+        )
+        return response.choices[0].message.content or ""
+
+    async def __call__(self, messages: list[Message]) -> str:
+        return await self.complete(messages)

pyagent_providers/adapters/mock.py

@@ -0,0 +1,72 @@
+"""MockProvider: wraps MockLLM with ProviderProtocol for testing."""
+
+from __future__ import annotations
+
+from pyagent_patterns.base import Message, MockLLM
+from pyagent_providers.base import HealthStatus, ProviderCapabilities
+from pyagent_router.selector import Capability
+
+
+class MockProvider:
+    """A mock provider for testing that wraps ``MockLLM``.
+
+    Implements the full ``ProviderProtocol`` interface with configurable
+    capabilities and health status.
+
+    Args:
+        name: Unique provider name.
+        responses: Canned responses passed to ``MockLLM``.
+        models: List of model names this mock exposes.
+        capabilities: Capability set.
+        max_context: Max context window.
+        health_status: Fixed health status to return.
+        delay: Simulated latency in seconds.
+    """
+
+    def __init__(
+        self,
+        name: str = "mock",
+        responses: list[str] | None = None,
+        models: list[str] | None = None,
+        capabilities: set[Capability] | None = None,
+        max_context: int = 128_000,
+        health_status: HealthStatus = HealthStatus.HEALTHY,
+        delay: float = 0.0,
+    ) -> None:
+        self._name = name
+        self._llm = MockLLM(responses=responses, delay=delay)
+        self._capabilities = ProviderCapabilities(
+            models=models or ["mock-model"],
+            capabilities=capabilities or {Capability.GENERAL},
+            max_context=max_context,
+        )
+        self._health_status = health_status
+
+    @property
+    def name(self) -> str:
+        return self._name
+
+    @property
+    def capabilities(self) -> ProviderCapabilities:
+        return self._capabilities
+
+    async def health(self) -> HealthStatus:
+        return self._health_status
+
+    async def complete(self, messages: list[Message], model: str | None = None) -> str:
+        return await self._llm(messages)
+
+    async def __call__(self, messages: list[Message]) -> str:
+        return await self.complete(messages)
+
+    def set_health(self, status: HealthStatus) -> None:
+        """Change health status (for test scenarios)."""
+        self._health_status = status
+
+    @property
+    def call_count(self) -> int:
+        return self._llm.call_count
+
+    @property
+    def call_log(self) -> list[list[Message]]:
+        return self._llm.call_log

pyagent_providers/adapters/openai.py

@@ -0,0 +1,90 @@
+"""OpenAIProvider: wraps the OpenAI Python client as a ProviderProtocol."""
+
+from __future__ import annotations
+
+from openai import AsyncOpenAI
+
+from pyagent_patterns.base import Message, Role
+from pyagent_providers.base import HealthStatus, ProviderCapabilities
+from pyagent_router.selector import Capability
+
+
+class OpenAIProvider:
+    """OpenAI provider implementing ``ProviderProtocol``.
+
+    Requires: ``pip install pyagent-providers[openai]``
+
+    Args:
+        api_key: OpenAI API key. Falls back to ``OPENAI_API_KEY`` env var.
+        models: Models this provider exposes. Defaults to common GPT models.
+        default_model: Model to use when none is specified in ``complete()``.
+        name: Provider identifier. Defaults to ``"openai"``.
+    """
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        models: list[str] | None = None,
+        default_model: str = "gpt-4o-mini",
+        name: str = "openai",
+    ) -> None:
+        self._client = AsyncOpenAI(api_key=api_key)
+        self._default_model = default_model
+        self._name = name
+        self._models = models or [
+            "gpt-4.1-nano",
+            "gpt-4o-mini",
+            "gpt-4.1-mini",
+            "gpt-4o",
+            "gpt-4.1",
+            "o3-mini",
+        ]
+        self._capabilities = ProviderCapabilities(
+            models=self._models,
+            capabilities={
+                Capability.GENERAL,
+                Capability.CODE,
+                Capability.REASONING,
+                Capability.CREATIVE,
+                Capability.VISION,
+            },
+            max_context=1_000_000,
+            supports_streaming=True,
+            supports_tools=True,
+            supports_vision=True,
+        )
+
+    @property
+    def name(self) -> str:
+        return self._name
+
+    @property
+    def capabilities(self) -> ProviderCapabilities:
+        return self._capabilities
+
+    async def health(self) -> HealthStatus:
+        """Ping the models endpoint to verify connectivity."""
+        try:
+            await self._client.models.list()
+            return HealthStatus.HEALTHY
+        except Exception:
+            return HealthStatus.UNHEALTHY
+
+    async def complete(self, messages: list[Message], model: str | None = None) -> str:
+        """Generate a completion using the OpenAI Chat API.
+
+        Args:
+            messages: Conversation history.
+            model: Model override. Uses ``default_model`` if ``None``.
+
+        Returns:
+            The assistant response text.
+        """
+        response = await self._client.chat.completions.create(
+            model=model or self._default_model,
+            messages=[{"role": m.role.value, "content": m.content} for m in messages],
+        )
+        return response.choices[0].message.content or ""
+
+    async def __call__(self, messages: list[Message]) -> str:
+        return await self.complete(messages)

pyagent_providers/base.py

@@ -0,0 +1,95 @@
+"""Core types: ProviderProtocol, ProviderCapabilities, HealthStatus, ProviderInfo."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import StrEnum
+from typing import Any, Protocol, runtime_checkable
+
+from pyagent_patterns.base import Message
+from pyagent_router.selector import Capability
+
+
+class HealthStatus(StrEnum):
+    """Health status of a provider."""
+
+    HEALTHY = "healthy"
+    DEGRADED = "degraded"
+    UNHEALTHY = "unhealthy"
+
+
+@dataclass(frozen=True)
+class ProviderCapabilities:
+    """Declares what a provider can do.
+
+    Attributes:
+        models: List of model identifiers this provider exposes.
+        capabilities: Set of capability tags (reuses pyagent_router.Capability).
+        max_context: Maximum context window in tokens across all models.
+        supports_streaming: Whether the provider supports token-level streaming.
+        supports_tools: Whether the provider supports tool/function calling.
+        supports_vision: Whether the provider supports image inputs.
+    """
+
+    models: list[str]
+    capabilities: set[Capability] = field(default_factory=lambda: {Capability.GENERAL})
+    max_context: int = 128_000
+    supports_streaming: bool = True
+    supports_tools: bool = False
+    supports_vision: bool = False
+
+
+@dataclass(frozen=True)
+class ProviderInfo:
+    """Snapshot of provider state returned by the registry.
+
+    Attributes:
+        name: Provider name.
+        capabilities: Provider capabilities.
+        health: Current health status.
+        metadata: Arbitrary extra metadata (e.g. region, version).
+    """
+
+    name: str
+    capabilities: ProviderCapabilities
+    health: HealthStatus
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+
+@runtime_checkable
+class ProviderProtocol(Protocol):
+    """Interface that every LLM provider must implement.
+
+    Also satisfies ``LLMCallable`` via ``__call__`` which delegates to
+    ``complete`` with a default model.
+    """
+
+    @property
+    def name(self) -> str:
+        """Unique identifier for this provider."""
+        ...
+
+    @property
+    def capabilities(self) -> ProviderCapabilities:
+        """Declared capabilities."""
+        ...
+
+    async def health(self) -> HealthStatus:
+        """Check current health of the provider endpoint."""
+        ...
+
+    async def complete(self, messages: list[Message], model: str | None = None) -> str:
+        """Generate a completion.
+
+        Args:
+            messages: Conversation history.
+            model: Optional model override. Uses provider default if ``None``.
+
+        Returns:
+            The assistant response text.
+        """
+        ...
+
+    async def __call__(self, messages: list[Message]) -> str:
+        """LLMCallable-compatible entry point — delegates to ``complete``."""
+        ...

pyagent_providers/cost.py

@@ -0,0 +1,113 @@
+"""CostOptimizer: multi-provider cost comparison wrapping CostEstimator."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+from pyagent_providers.base import ProviderProtocol
+from pyagent_providers.registry import ProviderRegistry
+from pyagent_router.estimator import CostEstimate, CostEstimator
+
+
+@dataclass(frozen=True)
+class ProviderCostEstimate:
+    """Cost estimate for a specific provider + model pair.
+
+    Attributes:
+        provider_name: Provider that would serve this request.
+        model: Model within that provider.
+        estimate: The underlying cost estimate.
+    """
+
+    provider_name: str
+    model: str
+    estimate: CostEstimate
+
+
+class CostOptimizer:
+    """Compare costs across all registered providers.
+
+    Wraps ``CostEstimator`` from ``pyagent-router`` and iterates over every
+    provider's model list to find the cheapest option.
+
+    Args:
+        registry: Provider registry to draw models from.
+        cost_estimator: Optional ``CostEstimator`` instance.
+    """
+
+    def __init__(
+        self,
+        registry: ProviderRegistry,
+        cost_estimator: CostEstimator | None = None,
+    ) -> None:
+        self._registry = registry
+        self._estimator = cost_estimator or CostEstimator()
+
+    def compare(
+        self,
+        task: str,
+        *,
+        healthy_only: bool = True,
+        limit: int = 10,
+    ) -> list[ProviderCostEstimate]:
+        """Estimate cost for every provider + model pair and rank cheapest first.
+
+        Args:
+            task: The task text to estimate.
+            healthy_only: If ``True`` (default), only include healthy providers.
+            limit: Maximum number of results to return.
+
+        Returns:
+            Sorted list of ``ProviderCostEstimate`` objects, cheapest first.
+        """
+        candidates = self._registry.discover(healthy_only=healthy_only)
+        results: list[ProviderCostEstimate] = []
+
+        for provider in candidates:
+            for model_name in provider.capabilities.models:
+                try:
+                    est = self._estimator.estimate_from_text(model_name, task)
+                    results.append(
+                        ProviderCostEstimate(
+                            provider_name=provider.name,
+                            model=model_name,
+                            estimate=est,
+                        )
+                    )
+                except KeyError:
+                    continue
+
+        results.sort(key=lambda x: x.estimate.total_cost)
+        return results[:limit]
+
+    def cheapest(
+        self,
+        task: str,
+        *,
+        healthy_only: bool = True,
+    ) -> ProviderCostEstimate | None:
+        """Return the single cheapest provider + model for a task.
+
+        Returns:
+            The cheapest option, or ``None`` if no estimates could be computed.
+        """
+        estimates = self.compare(task, healthy_only=healthy_only, limit=1)
+        return estimates[0] if estimates else None
+
+    def cheapest_provider(
+        self,
+        task: str,
+        *,
+        healthy_only: bool = True,
+    ) -> tuple[ProviderProtocol, str] | None:
+        """Return the cheapest provider object + model name.
+
+        Convenience method for passing directly to ``Agent`` or patterns.
+        """
+        est = self.cheapest(task, healthy_only=healthy_only)
+        if est is None:
+            return None
+        provider = self._registry.get(est.provider_name)
+        if provider is None:
+            return None
+        return provider, est.model