feat(api): Introduce comprehensive authentication and request management features

- Added various authentication methods including API Key, Basic, Bearer, and OAuth2.
- Implemented request configuration options such as rate limiting, circuit breakers, and caching strategies.
- Enhanced API metrics tracking for better performance monitoring.
- Introduced file upload support and request/response hooks for improved endpoint functionality.
- Reorganized API module for better structure and maintainability.

Author: arthurbrenno

agentle/agents/apis/__init__.py

@@ -1,17 +1,90 @@
-# yourpkg/__init__.py
-from .object_schema import ObjectSchema
-from .array_schema import ArraySchema
-from .primitive_schema import PrimitiveSchema
-from .endpoint_parameter import EndpointParameter
+# Import all classes for public API
+from agentle.agents.apis.api import API
+from agentle.agents.apis.api_metrics import APIMetrics
+from agentle.agents.apis.authentication import (
+    ApiKeyLocation,
+    AuthType,
+    AuthenticationConfig,
+    AuthenticationBase,
+    NoAuthentication,
+    BearerAuthentication,
+    BasicAuthentication,
+    ApiKeyAuthentication,
+    OAuth2Authentication,
+    HMACAuthentication,
+    OAuth2GrantType,
+)
+from agentle.agents.apis.endpoint import Endpoint
+from agentle.agents.apis.endpoint_parameter import EndpointParameter
+from agentle.agents.apis.file_upload import FileUpload
+from agentle.agents.apis.http_method import HTTPMethod
+from agentle.agents.apis.object_serialization_style import ObjectSerializationStyle
+from agentle.agents.apis.parameter_location import ParameterLocation
+from agentle.agents.apis.request_config import (
+    CacheStrategy,
+    CircuitBreaker,
+    CircuitBreakerError,
+    RateLimiter,
+    RequestConfig,
+    ResponseCache,
+    RetryStrategy,
+    RateLimitError,
+)
+from agentle.agents.apis.request_hook import RequestHook
+from agentle.agents.apis.object_schema import ObjectSchema
+from agentle.agents.apis.array_schema import ArraySchema
+from agentle.agents.apis.primitive_schema import PrimitiveSchema
+from agentle.agents.apis.endpoints_to_tools import endpoints_to_tools
 
 _types = {
     "ObjectSchema": ObjectSchema,
     "ArraySchema": ArraySchema,
     "PrimitiveSchema": PrimitiveSchema,
 }
 
-
+# Rebuild models for proper type resolution
 ObjectSchema.model_rebuild(_types_namespace=_types)
 ArraySchema.model_rebuild(_types_namespace=_types)
 PrimitiveSchema.model_rebuild(_types_namespace=_types)
 EndpointParameter.model_rebuild(_types_namespace=_types)
+
+__all__ = [
+    # API classes
+    "API",
+    "APIMetrics",
+    # Endpoint classes
+    "Endpoint",
+    "EndpointParameter",
+    "FileUpload",
+    "RequestHook",
+    "HTTPMethod",
+    "ParameterLocation",
+    "ObjectSerializationStyle",
+    # Authentication classes
+    "AuthType",
+    "ApiKeyLocation",
+    "OAuth2GrantType",
+    "AuthenticationBase",
+    "NoAuthentication",
+    "BearerAuthentication",
+    "BasicAuthentication",
+    "ApiKeyAuthentication",
+    "OAuth2Authentication",
+    "HMACAuthentication",
+    "AuthenticationConfig",
+    # Request configuration classes
+    "RequestConfig",
+    "RetryStrategy",
+    "CacheStrategy",
+    "CircuitBreaker",
+    "RateLimiter",
+    "ResponseCache",
+    "CircuitBreakerError",
+    "RateLimitError",
+    # Schema classes
+    "ObjectSchema",
+    "ArraySchema",
+    "PrimitiveSchema",
+    # Utilities
+    "endpoints_to_tools",
+]

agentle/agents/apis/api.py

@@ -14,7 +14,13 @@
 from __future__ import annotations
 
 import logging
-from collections.abc import Coroutine, Mapping, MutableMapping, MutableSequence, Sequence
+from collections.abc import (
+    Coroutine,
+    Mapping,
+    MutableMapping,
+    MutableSequence,
+    Sequence,
+)
 from pathlib import Path
 from typing import Any, Literal, cast
 
@@ -24,6 +30,7 @@
 from rsb.models.base_model import BaseModel
 from rsb.models.field import Field
 
+from agentle.agents.apis.api_metrics import APIMetrics
 from agentle.agents.apis.array_schema import ArraySchema
 from agentle.agents.apis.authentication import (
     ApiKeyLocation,
@@ -43,17 +50,6 @@
 logger = logging.getLogger(__name__)
 
 
-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] = {}
-
-
 class API(BaseModel):
     """
     Enhanced API collection with comprehensive features.

agentle/agents/apis/api_key_authentication.py

@@ -0,0 +1,43 @@
+"""API key authentication."""
+
+from __future__ import annotations
+
+from collections.abc import MutableMapping
+from typing import Any
+
+import aiohttp
+from agentle.agents.apis.api_key_location import ApiKeyLocation
+from agentle.agents.apis.authentication_base import AuthenticationBase
+
+
+class ApiKeyAuthentication(AuthenticationBase):
+    """API Key authentication."""
+
+    def __init__(
+        self,
+        api_key: str,
+        location: ApiKeyLocation = ApiKeyLocation.HEADER,
+        key_name: str = "X-API-Key",
+    ):
+        self.api_key = api_key
+        self.location = location
+        self.key_name = key_name
+
+    async def apply_auth(
+        self,
+        session: aiohttp.ClientSession,
+        url: str,
+        headers: MutableMapping[str, str],
+        params: MutableMapping[str, Any],
+    ) -> None:
+        """Add API key to the appropriate location."""
+        if self.location == ApiKeyLocation.HEADER:
+            headers[self.key_name] = self.api_key
+        elif self.location == ApiKeyLocation.QUERY:
+            params[self.key_name] = self.api_key
+        elif self.location == ApiKeyLocation.COOKIE:
+            headers["Cookie"] = f"{self.key_name}={self.api_key}"
+
+    async def refresh_if_needed(self) -> bool:
+        """No refresh needed for API key."""
+        return False

agentle/agents/apis/api_key_location.py

@@ -0,0 +1,11 @@
+"""API key location types."""
+
+from enum import StrEnum
+
+
+class ApiKeyLocation(StrEnum):
+    """Where to place API key."""
+
+    HEADER = "header"
+    QUERY = "query"
+    COOKIE = "cookie"

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"