agentle 0.9.4__py3-none-any.whl → 0.9.28__py3-none-any.whl

agentle/agents/apis/api_metrics.py

@@ -0,0 +1,16 @@
+"""API metrics tracking."""
+
+from __future__ import annotations
+
+from rsb.models.base_model import BaseModel
+
+
+class APIMetrics(BaseModel):
+    """Metrics for API usage."""
+
+    total_requests: int = 0
+    successful_requests: int = 0
+    failed_requests: int = 0
+    total_latency_ms: float = 0.0
+    average_latency_ms: float = 0.0
+    requests_by_endpoint: dict[str, int] = {}

agentle/agents/apis/auth_type.py

@@ -0,0 +1,17 @@
+"""Authentication types."""
+
+from enum import StrEnum
+
+
+class AuthType(StrEnum):
+    """Types of authentication supported."""
+
+    NONE = "none"
+    BEARER = "bearer"
+    BASIC = "basic"
+    API_KEY = "api_key"
+    OAUTH2 = "oauth2"
+    JWT = "jwt"
+    CUSTOM = "custom"
+    AWS_SIGNATURE = "aws_signature"
+    HMAC = "hmac"

agentle/agents/apis/authentication.py

@@ -0,0 +1,32 @@
+"""
+Authentication support for API endpoints.
+
+Provides various authentication methods including Bearer, Basic, OAuth2, API Key, and custom schemes.
+"""
+
+# Import and re-export for backward compatibility
+from agentle.agents.apis.api_key_location import ApiKeyLocation
+from agentle.agents.apis.api_key_authentication import ApiKeyAuthentication
+from agentle.agents.apis.auth_type import AuthType
+from agentle.agents.apis.authentication_base import AuthenticationBase
+from agentle.agents.apis.authentication_config import AuthenticationConfig
+from agentle.agents.apis.basic_authentication import BasicAuthentication
+from agentle.agents.apis.bearer_authentication import BearerAuthentication
+from agentle.agents.apis.hmac_authentication import HMACAuthentication
+from agentle.agents.apis.no_authentication import NoAuthentication
+from agentle.agents.apis.oauth2_authentication import OAuth2Authentication
+from agentle.agents.apis.oauth2_grant_type import OAuth2GrantType
+
+__all__ = [
+    "AuthType",
+    "ApiKeyLocation",
+    "OAuth2GrantType",
+    "AuthenticationBase",
+    "NoAuthentication",
+    "BearerAuthentication",
+    "BasicAuthentication",
+    "ApiKeyAuthentication",
+    "OAuth2Authentication",
+    "HMACAuthentication",
+    "AuthenticationConfig",
+]

agentle/agents/apis/authentication_base.py

@@ -0,0 +1,42 @@
+"""Base authentication handler."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from collections.abc import MutableMapping
+from typing import Any
+
+import aiohttp
+
+
+class AuthenticationBase(ABC):
+    """Base class for authentication handlers."""
+
+    @abstractmethod
+    async def apply_auth(
+        self,
+        session: aiohttp.ClientSession,
+        url: str,
+        headers: MutableMapping[str, str],
+        params: MutableMapping[str, Any],
+    ) -> None:
+        """
+        Apply authentication to the request.
+
+        Args:
+            session: aiohttp session
+            url: Request URL
+            headers: Request headers (will be modified)
+            params: Request parameters (will be modified)
+        """
+        pass
+
+    @abstractmethod
+    async def refresh_if_needed(self) -> bool:
+        """
+        Refresh authentication if needed (e.g., expired tokens).
+
+        Returns:
+            True if refresh was performed, False otherwise
+        """
+        pass

agentle/agents/apis/authentication_config.py

@@ -0,0 +1,117 @@
+"""Authentication configuration."""
+
+from __future__ import annotations
+
+from collections.abc import MutableMapping
+
+from rsb.models.base_model import BaseModel
+from rsb.models.field import Field
+
+from agentle.agents.apis.api_key_authentication import ApiKeyAuthentication
+from agentle.agents.apis.api_key_location import ApiKeyLocation
+from agentle.agents.apis.auth_type import AuthType
+from agentle.agents.apis.authentication_base import AuthenticationBase
+from agentle.agents.apis.basic_authentication import BasicAuthentication
+from agentle.agents.apis.bearer_authentication import BearerAuthentication
+from agentle.agents.apis.hmac_authentication import HMACAuthentication
+from agentle.agents.apis.no_authentication import NoAuthentication
+from agentle.agents.apis.oauth2_authentication import OAuth2Authentication
+from agentle.agents.apis.oauth2_grant_type import OAuth2GrantType
+
+
+class AuthenticationConfig(BaseModel):
+    """Configuration for API authentication."""
+
+    type: AuthType = Field(default=AuthType.NONE)
+
+    # Bearer token
+    bearer_token: str | None = Field(default=None)
+
+    # Basic auth
+    username: str | None = Field(default=None)
+    password: str | None = Field(default=None)
+
+    # API Key
+    api_key: str | None = Field(default=None)
+    api_key_location: ApiKeyLocation = Field(default=ApiKeyLocation.HEADER)
+    api_key_name: str = Field(default="X-API-Key")
+
+    # OAuth2
+    oauth2_token_url: str | None = Field(default=None)
+    oauth2_client_id: str | None = Field(default=None)
+    oauth2_client_secret: str | None = Field(default=None)
+    oauth2_grant_type: OAuth2GrantType = Field(
+        default=OAuth2GrantType.CLIENT_CREDENTIALS
+    )
+    oauth2_scope: str | None = Field(
+        default=None,
+        description="Single scope string (deprecated, use oauth2_scopes for multiple)",
+    )
+    oauth2_scopes: list[str] | None = Field(
+        default=None,
+        description="List of OAuth2 scopes to request (e.g., ['read', 'write', 'admin'])",
+    )
+    oauth2_refresh_token: str | None = Field(default=None)
+
+    # HMAC
+    hmac_secret_key: str | None = Field(default=None)
+    hmac_algorithm: str = Field(default="sha256")
+    hmac_header_name: str = Field(default="X-Signature")
+
+    # Custom
+    custom_headers: MutableMapping[str, str] = Field(default_factory=dict)
+
+    def create_handler(self) -> AuthenticationBase:
+        """Create authentication handler from config."""
+        if self.type == AuthType.NONE:
+            return NoAuthentication()
+
+        elif self.type == AuthType.BEARER:
+            if not self.bearer_token:
+                raise ValueError("Bearer token required for Bearer authentication")
+            return BearerAuthentication(self.bearer_token)
+
+        elif self.type == AuthType.BASIC:
+            if not self.username or not self.password:
+                raise ValueError(
+                    "Username and password required for Basic authentication"
+                )
+            return BasicAuthentication(self.username, self.password)
+
+        elif self.type == AuthType.API_KEY:
+            if not self.api_key:
+                raise ValueError("API key required for API Key authentication")
+            return ApiKeyAuthentication(
+                self.api_key, self.api_key_location, self.api_key_name
+            )
+
+        elif self.type == AuthType.OAUTH2:
+            if not all(
+                [
+                    self.oauth2_token_url,
+                    self.oauth2_client_id,
+                    self.oauth2_client_secret,
+                ]
+            ):
+                raise ValueError(
+                    "OAuth2 credentials required for OAuth2 authentication"
+                )
+            return OAuth2Authentication(
+                self.oauth2_token_url,  # type: ignore
+                self.oauth2_client_id,  # type: ignore
+                self.oauth2_client_secret,  # type: ignore
+                self.oauth2_grant_type,
+                self.oauth2_scope,
+                self.oauth2_refresh_token,
+                self.oauth2_scopes,
+            )
+
+        elif self.type == AuthType.HMAC:
+            if not self.hmac_secret_key:
+                raise ValueError("HMAC secret key required for HMAC authentication")
+            return HMACAuthentication(
+                self.hmac_secret_key, self.hmac_algorithm, self.hmac_header_name
+            )
+
+        else:
+            return NoAuthentication()

agentle/agents/apis/basic_authentication.py

@@ -0,0 +1,34 @@
+"""Basic authentication."""
+
+from __future__ import annotations
+
+import base64
+from collections.abc import MutableMapping
+from typing import Any
+
+import aiohttp
+from agentle.agents.apis.authentication_base import AuthenticationBase
+
+
+class BasicAuthentication(AuthenticationBase):
+    """HTTP Basic authentication."""
+
+    def __init__(self, username: str, password: str):
+        self.username = username
+        self.password = password
+
+    async def apply_auth(
+        self,
+        session: aiohttp.ClientSession,
+        url: str,
+        headers: MutableMapping[str, str],
+        params: MutableMapping[str, Any],
+    ) -> None:
+        """Add Basic auth to Authorization header."""
+        credentials = f"{self.username}:{self.password}"
+        encoded = base64.b64encode(credentials.encode()).decode()
+        headers["Authorization"] = f"Basic {encoded}"
+
+    async def refresh_if_needed(self) -> bool:
+        """No refresh needed for Basic auth."""
+        return False

agentle/agents/apis/bearer_authentication.py

@@ -0,0 +1,52 @@
+"""Bearer token authentication."""
+
+from __future__ import annotations
+
+from collections.abc import MutableMapping
+from datetime import datetime, timedelta
+from typing import Any
+
+import aiohttp
+from agentle.agents.apis.authentication_base import AuthenticationBase
+
+
+class BearerAuthentication(AuthenticationBase):
+    """Bearer token authentication."""
+
+    def __init__(self, token: str, auto_refresh: bool = False):
+        self.token = token
+        self.auto_refresh = auto_refresh
+        self._token_expiry: datetime | None = None
+
+    async def apply_auth(
+        self,
+        session: aiohttp.ClientSession,
+        url: str,
+        headers: MutableMapping[str, str],
+        params: MutableMapping[str, Any],
+    ) -> None:
+        """Add Bearer token to Authorization header."""
+        headers["Authorization"] = f"Bearer {self.token}"
+
+    async def refresh_if_needed(self) -> bool:
+        """Check if token needs refresh."""
+        if not self.auto_refresh:
+            return False
+
+        if self._token_expiry and datetime.now() >= self._token_expiry:
+            # Token expired - subclass should implement refresh logic
+            return False
+
+        return False
+
+    def set_token(self, token: str, expires_in: int | None = None) -> None:
+        """
+        Update the token.
+
+        Args:
+            token: New token
+            expires_in: Token expiry in seconds
+        """
+        self.token = token
+        if expires_in:
+            self._token_expiry = datetime.now() + timedelta(seconds=expires_in)

agentle/agents/apis/cache_strategy.py

@@ -0,0 +1,12 @@
+"""Cache strategies."""
+
+from enum import StrEnum
+
+
+class CacheStrategy(StrEnum):
+    """Cache strategies."""
+
+    NONE = "none"
+    MEMORY = "memory"
+    REDIS = "redis"
+    CUSTOM = "custom"

agentle/agents/apis/circuit_breaker.py

@@ -0,0 +1,69 @@
+"""Circuit breaker for resilient API calls.
+
+This module adapts the resilience module's circuit breaker implementations
+for use in the APIs module, maintaining backward compatibility.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import Any
+
+from agentle.agents.apis.circuit_breaker_error import CircuitBreakerError
+from agentle.agents.apis.request_config import RequestConfig
+from agentle.resilience.circuit_breaker.in_memory_circuit_breaker import (
+    InMemoryCircuitBreaker,
+)
+
+
+class CircuitBreaker:
+    """
+    Circuit breaker implementation for resilient API calls.
+
+    This wraps the resilience module's InMemoryCircuitBreaker to provide
+    a simpler call-based API for endpoint usage.
+    """
+
+    def __init__(self, config: RequestConfig):
+        self.config = config
+        self._circuit_id = "default"  # Single circuit per endpoint
+        # Initialize the underlying circuit breaker from resilience module
+        self._impl = InMemoryCircuitBreaker(
+            failure_threshold=config.circuit_breaker_failure_threshold,
+            recovery_timeout=config.circuit_breaker_recovery_timeout,
+            half_open_success_threshold=config.circuit_breaker_success_threshold,
+            enable_metrics=config.enable_metrics,
+        )
+
+    async def call(self, func: Callable[[], Any]) -> Any:
+        """
+        Execute function with circuit breaker protection.
+
+        Args:
+            func: Async function to execute
+
+        Returns:
+            Result of func call
+
+        Raises:
+            CircuitBreakerError: If circuit is open
+        """
+        # Check if circuit is open
+        if await self._impl.is_open(self._circuit_id):
+            # Get circuit state for more details
+            state = await self._impl.get_circuit_state(self._circuit_id)
+            next_retry_seconds = state.get("next_recovery_attempt_in_seconds", 0)
+
+            if next_retry_seconds > 0:
+                raise CircuitBreakerError(
+                    f"Circuit breaker is OPEN. Retry after {next_retry_seconds:.1f}s"
+                )
+
+        # Execute the function
+        try:
+            result = await func()
+            await self._impl.record_success(self._circuit_id)
+            return result
+        except Exception:
+            await self._impl.record_failure(self._circuit_id)
+            raise

agentle/agents/apis/circuit_breaker_error.py

@@ -0,0 +1,7 @@
+"""Circuit breaker errors."""
+
+
+class CircuitBreakerError(Exception):
+    """Raised when circuit breaker is open."""
+
+    pass

agentle/agents/apis/circuit_breaker_state.py

@@ -0,0 +1,11 @@
+"""Circuit breaker states."""
+
+from enum import StrEnum
+
+
+class CircuitBreakerState(StrEnum):
+    """Circuit breaker states."""
+
+    CLOSED = "closed"  # Normal operation
+    OPEN = "open"  # Failing, reject requests
+    HALF_OPEN = "half_open"  # Testing if service recovered