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

agentle/agents/apis/file_upload.py

@@ -0,0 +1,23 @@
+"""File upload support for endpoints."""
+
+from __future__ import annotations
+
+import mimetypes
+from rsb.models.base_model import BaseModel
+
+
+class FileUpload(BaseModel):
+    """Represents a file to be uploaded."""
+
+    filename: str
+    content: bytes
+    mime_type: str | None = None
+
+    def to_form_part(self) -> tuple[str, bytes, str]:
+        """Convert to multipart form part."""
+        mime = (
+            self.mime_type
+            or mimetypes.guess_type(self.filename)[0]
+            or "application/octet-stream"
+        )
+        return (self.filename, self.content, mime)

agentle/agents/apis/hmac_authentication.py

@@ -0,0 +1,56 @@
+"""HMAC signature authentication."""
+
+from __future__ import annotations
+
+import hashlib
+import hmac
+import time
+from collections.abc import MutableMapping
+from typing import Any
+
+import aiohttp
+from agentle.agents.apis.authentication_base import AuthenticationBase
+
+
+class HMACAuthentication(AuthenticationBase):
+    """HMAC signature authentication."""
+
+    def __init__(
+        self,
+        secret_key: str,
+        algorithm: str = "sha256",
+        header_name: str = "X-Signature",
+        include_timestamp: bool = True,
+    ):
+        self.secret_key = secret_key
+        self.algorithm = algorithm
+        self.header_name = header_name
+        self.include_timestamp = include_timestamp
+
+    async def apply_auth(
+        self,
+        session: aiohttp.ClientSession,
+        url: str,
+        headers: MutableMapping[str, str],
+        params: MutableMapping[str, Any],
+    ) -> None:
+        """Add HMAC signature to headers."""
+        # Build signature string
+        timestamp = str(int(time.time()))
+        signature_string = url
+
+        if self.include_timestamp:
+            signature_string = f"{timestamp}:{signature_string}"
+            headers["X-Timestamp"] = timestamp
+
+        # Calculate HMAC
+        hash_func = getattr(hashlib, self.algorithm)
+        signature = hmac.new(
+            self.secret_key.encode(), signature_string.encode(), hash_func
+        ).hexdigest()
+
+        headers[self.header_name] = signature
+
+    async def refresh_if_needed(self) -> bool:
+        """No refresh needed for HMAC."""
+        return False

agentle/agents/apis/no_authentication.py

@@ -0,0 +1,27 @@
+"""No authentication handler."""
+
+from __future__ import annotations
+
+from collections.abc import MutableMapping
+from typing import Any
+
+import aiohttp
+from agentle.agents.apis.authentication_base import AuthenticationBase
+
+
+class NoAuthentication(AuthenticationBase):
+    """No authentication."""
+
+    async def apply_auth(
+        self,
+        session: aiohttp.ClientSession,
+        url: str,
+        headers: MutableMapping[str, str],
+        params: MutableMapping[str, Any],
+    ) -> None:
+        """No authentication to apply."""
+        pass
+
+    async def refresh_if_needed(self) -> bool:
+        """No refresh needed."""
+        return False

agentle/agents/apis/oauth2_authentication.py

@@ -0,0 +1,111 @@
+"""OAuth2 authentication."""
+
+from __future__ import annotations
+
+import asyncio
+from collections.abc import MutableMapping
+from datetime import datetime, timedelta
+from typing import Any
+
+import aiohttp
+from agentle.agents.apis.authentication_base import AuthenticationBase
+from agentle.agents.apis.oauth2_grant_type import OAuth2GrantType
+
+
+class OAuth2Authentication(AuthenticationBase):
+    """OAuth2 authentication with token refresh."""
+
+    def __init__(
+        self,
+        token_url: str,
+        client_id: str,
+        client_secret: str,
+        grant_type: OAuth2GrantType = OAuth2GrantType.CLIENT_CREDENTIALS,
+        scope: str | None = None,
+        refresh_token: str | None = None,
+        scopes: list[str] | None = None,
+    ):
+        self.token_url = token_url
+        self.client_id = client_id
+        self.client_secret = client_secret
+        self.grant_type = grant_type
+        # Support both single scope and multiple scopes
+        # If scopes list is provided, use it; otherwise fall back to single scope
+        self.scopes = scopes
+        self.scope = scope
+        self.refresh_token_value = refresh_token
+
+        self.access_token: str | None = None
+        self.token_expiry: datetime | None = None
+        self._refresh_lock = asyncio.Lock()
+
+    async def apply_auth(
+        self,
+        session: aiohttp.ClientSession,
+        url: str,
+        headers: MutableMapping[str, str],
+        params: MutableMapping[str, Any],
+    ) -> None:
+        """Add OAuth2 token to Authorization header."""
+        # Ensure we have a valid token
+        await self.refresh_if_needed()
+
+        if self.access_token:
+            headers["Authorization"] = f"Bearer {self.access_token}"
+
+    async def refresh_if_needed(self) -> bool:
+        """Refresh token if expired or missing."""
+        # Check if token needs refresh
+        if self.access_token and self.token_expiry:
+            # Add 60 second buffer before expiry
+            if datetime.now() < self.token_expiry - timedelta(seconds=60):
+                return False
+
+        # Use lock to prevent concurrent refreshes
+        async with self._refresh_lock:
+            # Double-check after acquiring lock
+            if self.access_token and self.token_expiry:
+                if datetime.now() < self.token_expiry - timedelta(seconds=60):
+                    return False
+
+            # Refresh the token
+            await self._fetch_token()
+            return True
+
+    async def _fetch_token(self) -> None:
+        """Fetch a new access token."""
+        data: dict[str, str] = {
+            "client_id": self.client_id,
+            "client_secret": self.client_secret,
+            "grant_type": self.grant_type.value,
+        }
+
+        # Handle scopes - prefer scopes list over single scope
+        if self.scopes:
+            data["scope"] = " ".join(self.scopes)
+        elif self.scope:
+            data["scope"] = self.scope
+
+        if (
+            self.grant_type == OAuth2GrantType.REFRESH_TOKEN
+            and self.refresh_token_value
+        ):
+            data["refresh_token"] = self.refresh_token_value
+
+        async with aiohttp.ClientSession() as session:
+            async with session.post(self.token_url, data=data) as response:
+                if response.status == 200:
+                    token_data = await response.json()
+                    self.access_token = token_data["access_token"]
+
+                    # Calculate expiry
+                    expires_in = token_data.get("expires_in", 3600)
+                    self.token_expiry = datetime.now() + timedelta(seconds=expires_in)
+
+                    # Update refresh token if provided
+                    if "refresh_token" in token_data:
+                        self.refresh_token_value = token_data["refresh_token"]
+                else:
+                    raise ValueError(
+                        f"Failed to fetch OAuth2 token: HTTP {response.status}"
+                    )

agentle/agents/apis/oauth2_grant_type.py

@@ -0,0 +1,12 @@
+"""OAuth2 grant types."""
+
+from enum import StrEnum
+
+
+class OAuth2GrantType(StrEnum):
+    """OAuth2 grant types."""
+
+    CLIENT_CREDENTIALS = "client_credentials"
+    AUTHORIZATION_CODE = "authorization_code"
+    REFRESH_TOKEN = "refresh_token"
+    PASSWORD = "password"

agentle/agents/apis/object_schema.py

@@ -8,7 +8,7 @@ Simply replace the existing EndpointParameter and related classes with these imp
 from __future__ import annotations
 
 from collections.abc import Mapping, Sequence
-from typing import TYPE_CHECKING, Any, Literal
+from typing import TYPE_CHECKING, Any, Literal, cast
 
 from rsb.models.base_model import BaseModel
 from rsb.models.field import Field
@@ -39,3 +39,88 @@ class ObjectSchema(BaseModel):
     example: Mapping[str, Any] | None = Field(
         default=None, description="Example value for the object"
     )
+
+    @classmethod
+    def from_json_schema(
+        cls, schema: Mapping[str, Any]
+    ) -> ObjectSchema | ArraySchema | PrimitiveSchema:
+        """
+        Recursively convert a JSON Schema definition to Agentle schema types.
+        
+        This method handles deeply nested objects, arrays, and primitives,
+        making it easy to convert complex JSON Schema definitions.
+        
+        Args:
+            schema: JSON Schema definition (dict with 'type', 'properties', etc.)
+            
+        Returns:
+            Appropriate schema type (ObjectSchema, ArraySchema, or PrimitiveSchema)
+            
+        Example:
+            ```python
+            from agentle.agents.apis.object_schema import ObjectSchema
+            
+            json_schema = {
+                "type": "object",
+                "properties": {
+                    "user": {
+                        "type": "object",
+                        "properties": {
+                            "name": {"type": "string"},
+                            "age": {"type": "integer"},
+                            "settings": {
+                                "type": "object",
+                                "properties": {
+                                    "theme": {"type": "string"},
+                                    "notifications": {"type": "boolean"}
+                                }
+                            }
+                        }
+                    }
+                }
+            }
+            
+            schema = ObjectSchema.from_json_schema(json_schema)
+            ```
+        """
+        from agentle.agents.apis.array_schema import ArraySchema
+        from agentle.agents.apis.primitive_schema import PrimitiveSchema
+
+        schema_type = schema.get("type", "string")
+
+        if schema_type == "object":
+            properties: dict[str, ObjectSchema | ArraySchema | PrimitiveSchema] = {}
+            for prop_name, prop_schema in schema.get("properties", {}).items():
+                properties[prop_name] = cls.from_json_schema(prop_schema)
+
+            return cls(
+                properties=properties,
+                required=list(schema.get("required", [])),
+                additional_properties=schema.get("additionalProperties", True),
+                example=schema.get("example"),
+            )
+
+        elif schema_type == "array":
+            items_schema = schema.get("items", {"type": "string"})
+            return ArraySchema(
+                items=cls.from_json_schema(items_schema),
+                min_items=schema.get("minItems"),
+                max_items=schema.get("maxItems"),
+                example=schema.get("example"),
+            )
+
+        else:
+            # Primitive type
+            return PrimitiveSchema(
+                type=cast(
+                    Literal["string", "integer", "boolean", "number"], schema_type
+                )
+                if schema_type in ["string", "integer", "number", "boolean"]
+                else "string",
+                format=schema.get("format"),
+                enum=schema.get("enum"),
+                minimum=schema.get("minimum"),
+                maximum=schema.get("maximum"),
+                pattern=schema.get("pattern"),
+                example=schema.get("example"),
+            )

agentle/agents/apis/params/__init__.py

@@ -1,6 +1,15 @@
 from .array_param import array_param
+from .boolean_param import boolean_param
 from .integer_param import integer_param
+from .number_param import number_param
 from .object_param import object_param
 from .string_param import string_param
 
-__all__: list[str] = ["array_param", "integer_param", "object_param", "string_param"]
+__all__: list[str] = [
+    "array_param",
+    "boolean_param",
+    "integer_param",
+    "number_param",
+    "object_param",
+    "string_param",
+]

agentle/agents/apis/params/boolean_param.py

@@ -0,0 +1,44 @@
+from agentle.agents.apis.endpoint_parameter import EndpointParameter
+from agentle.agents.apis.parameter_location import ParameterLocation
+from agentle.agents.apis.primitive_schema import PrimitiveSchema
+
+
+def boolean_param(
+    name: str,
+    description: str,
+    required: bool = False,
+    default: bool | None = None,
+    location: ParameterLocation = ParameterLocation.QUERY,
+) -> EndpointParameter:
+    """Create a boolean parameter.
+    
+    Args:
+        name: Parameter name
+        description: Parameter description
+        required: Whether the parameter is required
+        default: Default value for the parameter
+        location: Where the parameter should be placed in the request
+        
+    Returns:
+        EndpointParameter configured for boolean values
+        
+    Example:
+        ```python
+        from agentle.agents.apis.params.boolean_param import boolean_param
+        
+        boolean_param(
+            name="enabled",
+            description="Enable feature",
+            required=False,
+            default=True
+        )
+        ```
+    """
+    return EndpointParameter(
+        name=name,
+        description=description,
+        parameter_schema=PrimitiveSchema(type="boolean"),
+        location=location,
+        required=required,
+        default=default,
+    )

agentle/agents/apis/params/number_param.py

@@ -0,0 +1,56 @@
+from agentle.agents.apis.endpoint_parameter import EndpointParameter
+from agentle.agents.apis.parameter_location import ParameterLocation
+from agentle.agents.apis.primitive_schema import PrimitiveSchema
+
+
+def number_param(
+    name: str,
+    description: str,
+    required: bool = False,
+    minimum: float | None = None,
+    maximum: float | None = None,
+    default: float | None = None,
+    location: ParameterLocation = ParameterLocation.QUERY,
+    format: str | None = None,
+) -> EndpointParameter:
+    """Create a number (float/decimal) parameter.
+    
+    Args:
+        name: Parameter name
+        description: Parameter description
+        required: Whether the parameter is required
+        minimum: Minimum allowed value
+        maximum: Maximum allowed value
+        default: Default value for the parameter
+        location: Where the parameter should be placed in the request
+        format: Format hint (e.g., 'float', 'double', 'decimal')
+        
+    Returns:
+        EndpointParameter configured for number values
+        
+    Example:
+        ```python
+        from agentle.agents.apis.params.number_param import number_param
+        
+        number_param(
+            name="price",
+            description="Product price",
+            required=True,
+            minimum=0.0,
+            default=99.99
+        )
+        ```
+    """
+    return EndpointParameter(
+        name=name,
+        description=description,
+        parameter_schema=PrimitiveSchema(
+            type="number",
+            minimum=minimum,
+            maximum=maximum,
+            format=format,
+        ),
+        location=location,
+        required=required,
+        default=default,
+    )

agentle/agents/apis/rate_limit_error.py

@@ -0,0 +1,7 @@
+"""Rate limit errors."""
+
+
+class RateLimitError(Exception):
+    """Raised when rate limit is exceeded."""
+
+    pass

agentle/agents/apis/rate_limiter.py

@@ -0,0 +1,57 @@
+"""Rate limiter for API calls.
+
+This module adapts the resilience module's rate limiter implementations
+for use in the APIs module, maintaining backward compatibility.
+"""
+
+from __future__ import annotations
+
+import asyncio
+
+from agentle.agents.apis.request_config import RequestConfig
+from agentle.resilience.rate_limiting.rate_limit_config import RateLimitConfig
+from agentle.resilience.rate_limiting.in_memory_rate_limiter import (
+    InMemoryRateLimiter as ResilienceRateLimiter,
+)
+
+
+class RateLimiter:
+    """
+    Rate limiter for API calls.
+
+    This wraps the resilience module's InMemoryRateLimiter to provide
+    a simpler acquire-based API for endpoint usage.
+    """
+
+    def __init__(self, config: RequestConfig):
+        self.config = config
+        self._identifier = "default"  # Single rate limit per endpoint
+
+        # Convert rate limit config to resilience module format
+        rate_limit_config: RateLimitConfig = {
+            "max_requests_per_minute": int(
+                config.rate_limit_calls * (60 / config.rate_limit_period)
+            )
+            if config.rate_limit_period <= 60
+            else config.rate_limit_calls,
+        }
+
+        # Initialize the underlying rate limiter from resilience module
+        self._impl = ResilienceRateLimiter(
+            default_config=rate_limit_config,
+            enable_metrics=config.enable_metrics,
+        )
+
+    async def acquire(self) -> None:
+        """
+        Acquire rate limit slot, waiting if necessary.
+
+        This will block until a slot is available.
+        """
+        # Wait until we can proceed
+        while not await self._impl.can_proceed(self._identifier):
+            # Wait a short time before checking again
+            await asyncio.sleep(0.1)
+
+        # Record the request
+        await self._impl.record_request(self._identifier)

agentle/agents/apis/request_config.py

@@ -1,20 +1,142 @@
+"""
+Enhanced request configuration with advanced features.
+
+Includes timeouts, retries, circuit breakers, rate limiting, caching, and more.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+
 from rsb.models.base_model import BaseModel
 from rsb.models.field import Field
 
+from agentle.agents.apis.cache_strategy import CacheStrategy
+from agentle.agents.apis.retry_strategy import RetryStrategy
+
 
 class RequestConfig(BaseModel):
-    """Configuration for HTTP requests."""
+    """
+    Enhanced configuration for HTTP requests.
 
-    timeout: float = Field(description="Request timeout in seconds", default=30.0)
+    This configuration can be set at both API-level and per-endpoint level.
+    Endpoint-level configs override API-level configs.
+
+    Example:
+        ```python
+        # API-level config (applies to all endpoints)
+        api_config = RequestConfig(
+            timeout=30.0,
+            max_retries=3,
+            enable_caching=True
+        )
+
+        # Per-endpoint override
+        endpoint_config = RequestConfig(
+            timeout=60.0,  # Override for this specific endpoint
+            max_retries=5,
+            cache_ttl=600.0
+        )
+        ```
+    """
+
+    # Timeouts (in seconds)
+    timeout: float = Field(description="Total request timeout in seconds", default=30.0)
+    connect_timeout: float | None = Field(
+        description="Connection timeout in seconds", default=None
+    )
+    read_timeout: float | None = Field(
+        description="Read timeout in seconds", default=None
+    )
 
+    # Retry configuration
     max_retries: int = Field(
         description="Maximum number of retries for failed requests", default=3
     )
-
     retry_delay: float = Field(
-        description="Delay between retries in seconds", default=1.0
+        description="Base delay between retries in seconds", default=1.0
+    )
+    retry_strategy: RetryStrategy = Field(
+        description="Strategy for calculating retry delays",
+        default=RetryStrategy.EXPONENTIAL,
+    )
+    retry_on_status_codes: Sequence[int] = Field(
+        description="HTTP status codes that should trigger retries",
+        default_factory=lambda: [408, 429, 500, 502, 503, 504],
+    )
+    retry_on_exceptions: bool = Field(
+        description="Whether to retry on network exceptions", default=True
+    )
+
+    # Circuit breaker configuration
+    enable_circuit_breaker: bool = Field(
+        description="Enable circuit breaker pattern", default=False
+    )
+    circuit_breaker_failure_threshold: int = Field(
+        description="Number of failures before opening circuit", default=5
+    )
+    circuit_breaker_recovery_timeout: float = Field(
+        description="Seconds to wait before attempting recovery", default=60.0
+    )
+    circuit_breaker_success_threshold: int = Field(
+        description="Number of successes in half-open state to close circuit", default=2
     )
 
+    # Rate limiting
+    enable_rate_limiting: bool = Field(
+        description="Enable rate limiting", default=False
+    )
+    rate_limit_calls: int = Field(
+        description="Maximum number of calls per period", default=100
+    )
+    rate_limit_period: float = Field(
+        description="Rate limit period in seconds", default=60.0
+    )
+    respect_retry_after: bool = Field(
+        description="Respect Retry-After header from server", default=True
+    )
+
+    # Caching
+    enable_caching: bool = Field(description="Enable response caching", default=False)
+    cache_strategy: CacheStrategy = Field(
+        description="Caching strategy to use", default=CacheStrategy.MEMORY
+    )
+    cache_ttl: float = Field(description="Cache TTL in seconds", default=300.0)
+    cache_only_get: bool = Field(description="Only cache GET requests", default=True)
+
+    # Request/Response hooks
+    enable_request_logging: bool = Field(
+        description="Enable request logging", default=False
+    )
+    enable_response_logging: bool = Field(
+        description="Enable response logging", default=False
+    )
+    enable_metrics: bool = Field(description="Enable metrics collection", default=False)
+
+    # Connection settings
     follow_redirects: bool = Field(
         description="Whether to follow HTTP redirects", default=True
     )
+    max_redirects: int = Field(
+        description="Maximum number of redirects to follow", default=10
+    )
+    verify_ssl: bool = Field(description="Verify SSL certificates", default=True)
+    ssl_cert_path: str | None = Field(
+        description="Path to custom SSL certificate", default=None
+    )
+
+    # Proxy configuration
+    proxy_url: str | None = Field(
+        description="Proxy URL (http://host:port)", default=None
+    )
+    proxy_auth: tuple[str, str] | None = Field(
+        description="Proxy authentication (username, password)", default=None
+    )
+
+    # Content handling
+    compress_request: bool = Field(
+        description="Enable request compression", default=False
+    )
+    decompress_response: bool = Field(
+        description="Enable response decompression", default=True
+    )

agentle/agents/apis/request_hook.py

@@ -0,0 +1,16 @@
+"""Request hooks for endpoints."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import Any
+
+from rsb.models.base_model import BaseModel
+from rsb.models.field import Field
+
+
+class RequestHook(BaseModel):
+    """Hook for request/response interception."""
+
+    name: str
+    callback: Callable[[dict[str, Any]], Any] | None = None