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

agentle/agents/apis/api.py

@@ -1,6 +1,27 @@
+"""
+Complete enhanced API module with comprehensive OpenAPI support.
+
+Provides advanced features for managing collections of related endpoints with:
+- Full OpenAPI 3.0/3.1 and Swagger 2.0 support
+- Shared authentication across endpoints
+- Request/response interceptors
+- API-level rate limiting and circuit breaking
+- Batch request support
+- GraphQL support
+- And more...
+"""
+
 from __future__ import annotations
 
-from collections.abc import Mapping, MutableMapping, MutableSequence, Sequence
+import logging
+import re
+from collections.abc import (
+    Coroutine,
+    Mapping,
+    MutableMapping,
+    MutableSequence,
+    Sequence,
+)
 from pathlib import Path
 from typing import Any, Literal, cast
 
@@ -10,22 +31,32 @@ import yaml
 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,
+    AuthType,
+    AuthenticationConfig,
+    OAuth2GrantType,
+)
 from agentle.agents.apis.endpoint import Endpoint
 from agentle.agents.apis.endpoint_parameter import EndpointParameter
+from agentle.agents.apis.http_method import HTTPMethod
 from agentle.agents.apis.object_schema import ObjectSchema
+from agentle.agents.apis.parameter_location import ParameterLocation
 from agentle.agents.apis.primitive_schema import PrimitiveSchema
 from agentle.agents.apis.request_config import RequestConfig
 from agentle.generations.tools.tool import Tool
 
+logger = logging.getLogger(__name__)
+
 
 class API(BaseModel):
     """
-    Represents a collection of related API endpoints with shared configuration.
+    Enhanced API collection with comprehensive features.
 
-    This class groups multiple endpoints that share common settings like base URL,
-    authentication headers, and request configuration. It provides a convenient
-    way to define complete APIs that can be used by agents.
+    Represents a collection of related API endpoints with shared configuration,
+    authentication, rate limiting, and monitoring capabilities.
     """
 
     name: str = Field(description="Name of the API")
@@ -46,10 +77,59 @@ class API(BaseModel):
         default_factory=RequestConfig,
     )
 
+    auth_config: AuthenticationConfig | None = Field(
+        description="Authentication configuration for the API",
+        default=None,
+    )
+
     endpoints: Sequence[Endpoint] = Field(
         description="List of endpoints in this API", default_factory=list
     )
 
+    # API-level features
+    enable_batch_requests: bool = Field(
+        description="Enable batch request support", default=False
+    )
+
+    enable_graphql: bool = Field(description="Enable GraphQL support", default=False)
+
+    graphql_endpoint: str | None = Field(
+        description="GraphQL endpoint path", default=None
+    )
+
+    # Monitoring
+    enable_metrics: bool = Field(
+        description="Enable API metrics collection", default=False
+    )
+
+    # API version
+    version: str = Field(description="API version", default="1.0.0")
+
+    # OpenAPI spec reference
+    openapi_spec_url: str | None = Field(
+        description="URL to OpenAPI specification", default=None
+    )
+
+    # Internal state
+    _metrics: APIMetrics | None = None
+
+    def model_post_init(self, __context: Any) -> None:
+        """Initialize API components."""
+        super().model_post_init(__context)
+
+        if self.enable_metrics:
+            self._metrics = APIMetrics()
+
+        # Apply API-level config to endpoints that don't have their own
+        for endpoint in self.endpoints:
+            # Inherit auth config if endpoint doesn't have one
+            if not endpoint.auth_config and self.auth_config:
+                endpoint.auth_config = self.auth_config
+
+            # Inherit request config settings
+            if endpoint.request_config == RequestConfig():
+                endpoint.request_config = self.request_config
+
     @classmethod
     async def from_openapi_spec(
         cls,
@@ -60,42 +140,30 @@ class API(BaseModel):
         base_url_override: str | None = None,
         headers: MutableMapping[str, str] | None = None,
         request_config: RequestConfig | None = None,
+        auth_config: AuthenticationConfig | None = None,
         include_operations: Sequence[str] | None = None,
         exclude_operations: Sequence[str] | None = None,
+        include_tags: Sequence[str] | None = None,
+        exclude_tags: Sequence[str] | None = None,
     ) -> API:
         """
         Create an API instance from an OpenAPI specification.
 
         Args:
             spec: OpenAPI specification as dict, file path, or URL
-            name: Override the API name (uses info.title from spec if not provided)
-            description: Override the API description (uses info.description from spec if not provided)
-            base_url_override: Override the base URL (uses first server from spec if not provided)
-            headers: Additional headers to include with all requests
-            request_config: Request configuration for all endpoints
-            include_operations: List of operationIds to include (if None, includes all)
+            name: Override the API name
+            description: Override the API description
+            base_url_override: Override the base URL
+            headers: Additional headers
+            request_config: Request configuration
+            auth_config: Authentication configuration
+            include_operations: List of operationIds to include
             exclude_operations: List of operationIds to exclude
+            include_tags: List of tags to include
+            exclude_tags: List of tags to exclude
 
         Returns:
             API instance configured from the OpenAPI spec
-
-        Example:
-            ```python
-            # From URL
-            api = await API.from_openapi_spec("https://petstore.swagger.io/v2/swagger.json")
-
-            # From local file
-            api = await API.from_openapi_spec(Path("./api-spec.yaml"))
-
-            # From dict with custom settings
-            api = await API.from_openapi_spec(
-                spec_dict,
-                name="Custom Pet Store",
-                base_url_override="https://api.example.com",
-                headers={"Authorization": "Bearer token"},
-                include_operations=["getPetById", "updatePet"]
-            )
-            ```
         """
         # Load the OpenAPI spec
         spec_dict = await cls._load_openapi_spec(spec)
@@ -107,10 +175,13 @@ class API(BaseModel):
                 "Invalid OpenAPI specification: missing 'openapi' or 'swagger' field"
             )
 
+        logger.info(f"Loading OpenAPI spec version: {openapi_version}")
+
         # Extract API info
         info = spec_dict.get("info", {})
         api_name = name or info.get("title", "Generated API")
         api_description = description or info.get("description")
+        api_version = info.get("version", "1.0.0")
 
         # Extract base URL
         if base_url_override:
@@ -126,55 +197,216 @@ class API(BaseModel):
                 base_path = spec_dict.get("basePath", "")
                 api_base_url = f"{schemes[0]}://{host}{base_path}"
 
+        # Extract authentication from OpenAPI spec if not provided
+        if not auth_config:
+            auth_config = cls._extract_auth_from_spec(spec_dict)
+
         # Parse endpoints from paths
         endpoints = cls._parse_openapi_paths(
             spec_dict,
             include_operations=include_operations,
             exclude_operations=exclude_operations,
+            include_tags=include_tags,
+            exclude_tags=exclude_tags,
         )
 
+        logger.info(f"Loaded {len(endpoints)} endpoints from OpenAPI spec")
+
         return cls(
             name=api_name,
             description=api_description,
             base_url=api_base_url,
             headers=headers or {},
             request_config=request_config or RequestConfig(),
+            auth_config=auth_config,
             endpoints=endpoints,
+            version=api_version,
         )
 
-    def add_endpoint(self, endpoint: Endpoint) -> None:
-        """
-        Add an endpoint to this API.
+    @classmethod
+    def _extract_auth_from_spec(
+        cls, spec_dict: Mapping[str, Any]
+    ) -> AuthenticationConfig | None:
+        """Extract authentication configuration from OpenAPI spec."""
+        # OpenAPI 3.x security schemes
+        components = spec_dict.get("components", {})
+        security_schemes = components.get("securitySchemes", {})
 
-        Args:
-            endpoint: Endpoint to add
-        """
+        # OpenAPI 2.x security definitions
+        if not security_schemes:
+            security_schemes = spec_dict.get("securityDefinitions", {})
+
+        if not security_schemes:
+            return None
+
+        # Get the first security scheme (simplified - real implementation would handle multiple)
+        scheme_name, scheme = next(iter(security_schemes.items()))
+        scheme_type = scheme.get("type", "").lower()
+
+        logger.debug(f"Detected security scheme: {scheme_name} ({scheme_type})")
+
+        if scheme_type == "http":
+            http_scheme = scheme.get("scheme", "").lower()
+            if http_scheme == "bearer":
+                return AuthenticationConfig(type=AuthType.BEARER)
+            elif http_scheme == "basic":
+                return AuthenticationConfig(type=AuthType.BASIC)
+
+        elif scheme_type == "apikey":
+            location = scheme.get("in", "header")
+            name = scheme.get("name", "X-API-Key")
+
+            if location == "header":
+                return AuthenticationConfig(
+                    type=AuthType.API_KEY,
+                    api_key_location=ApiKeyLocation.HEADER,
+                    api_key_name=name,
+                )
+            elif location == "query":
+                return AuthenticationConfig(
+                    type=AuthType.API_KEY,
+                    api_key_location=ApiKeyLocation.QUERY,
+                    api_key_name=name,
+                )
+
+        elif scheme_type == "oauth2":
+            flows = scheme.get("flows", {})
+            if "clientCredentials" in flows:
+                flow = flows["clientCredentials"]
+                token_url = flow.get("tokenUrl")
+                scopes = flow.get("scopes", {})
+                if token_url:
+                    return AuthenticationConfig(
+                        type=AuthType.OAUTH2,
+                        oauth2_token_url=token_url,
+                        oauth2_grant_type=OAuth2GrantType.CLIENT_CREDENTIALS,
+                        oauth2_scopes=list(scopes.keys()) if scopes else None,
+                    )
+
+        return None
+
+    def add_endpoint(self, endpoint: Endpoint) -> None:
+        """Add an endpoint to this API."""
         if not isinstance(self.endpoints, list):
             self.endpoints = list(self.endpoints)
+
+        # Apply API-level configs
+        if not endpoint.auth_config and self.auth_config:
+            endpoint.auth_config = self.auth_config
+
+        if endpoint.request_config == RequestConfig():
+            endpoint.request_config = self.request_config
+
         self.endpoints.append(endpoint)
+        logger.debug(f"Added endpoint '{endpoint.name}' to API '{self.name}'")
 
     def get_endpoint(self, name: str) -> Endpoint | None:
+        """Get an endpoint by name."""
+        for endpoint in self.endpoints:
+            if endpoint.name == name:
+                return endpoint
+        return None
+
+    def get_endpoints_by_tag(self, tag: str) -> Sequence[Endpoint]:
+        """Get all endpoints with a specific tag."""
+        # This would require adding tags to Endpoint model
+        # For now, return empty list
+        return []
+
+    async def batch_request(
+        self,
+        requests: Sequence[tuple[str, dict[str, Any]]],
+    ) -> Sequence[Any]:
         """
-        Get an endpoint by name.
+        Execute multiple requests in batch.
 
         Args:
-            name: Name of the endpoint to find
+            requests: List of (endpoint_name, kwargs) tuples
 
         Returns:
-            Endpoint if found, None otherwise
+            List of results in the same order as requests
         """
-        for endpoint in self.endpoints:
-            if endpoint.name == name:
-                return endpoint
-        return None
-
-    def to_tools(self) -> Sequence[Tool[Any]]:
+        if not self.enable_batch_requests:
+            raise ValueError("Batch requests not enabled for this API")
+
+        import asyncio
+
+        tasks: list[Coroutine[None, None, Any]] = []
+        for endpoint_name, kwargs in requests:
+            endpoint = self.get_endpoint(endpoint_name)
+            if not endpoint:
+                raise ValueError(f"Endpoint '{endpoint_name}' not found")
+
+            # Create task for this request
+            task = endpoint.make_request(
+                base_url=self.base_url,
+                global_headers=self.headers,
+                **kwargs,
+            )
+            tasks.append(task)
+
+        # Execute all requests concurrently
+        results = await asyncio.gather(*tasks, return_exceptions=True)
+        return results
+
+    async def graphql_query(
+        self,
+        query: str,
+        variables: dict[str, Any] | None = None,
+        operation_name: str | None = None,
+    ) -> Any:
         """
-        Convert all endpoints in this API to Tool instances.
+        Execute a GraphQL query.
+
+        Args:
+            query: GraphQL query string
+            variables: Query variables
+            operation_name: Operation name
 
         Returns:
-            List of Tool instances for all endpoints
+            Query result
         """
+        if not self.enable_graphql:
+            raise ValueError("GraphQL not enabled for this API")
+
+        if not self.graphql_endpoint:
+            raise ValueError("GraphQL endpoint not configured")
+
+        # Build GraphQL request
+        payload: dict[str, Any] = {"query": query}
+        if variables:
+            payload["variables"] = variables
+        if operation_name:
+            payload["operationName"] = operation_name
+
+        # Make request
+        url = f"{self.base_url.rstrip('/')}/{self.graphql_endpoint.lstrip('/')}"
+
+        async with aiohttp.ClientSession() as session:
+            async with session.post(
+                url,
+                json=payload,
+                headers=self.headers,
+            ) as response:
+                if response.status == 200:
+                    result = await response.json()
+                    if "errors" in result:
+                        raise ValueError(f"GraphQL errors: {result['errors']}")
+                    return result.get("data")
+                else:
+                    raise ValueError(f"GraphQL request failed: HTTP {response.status}")
+
+    def get_metrics(self) -> APIMetrics | None:
+        """Get API usage metrics."""
+        return self._metrics
+
+    def reset_metrics(self) -> None:
+        """Reset API metrics."""
+        if self._metrics:
+            self._metrics = APIMetrics()
+
+    def to_tools(self) -> Sequence[Tool[Any]]:
+        """Convert all endpoints to Tool instances."""
         tools: list[Tool[Any]] = []
 
         for endpoint in self.endpoints:
@@ -182,15 +414,12 @@ class API(BaseModel):
             merged_headers = dict(self.headers)
             merged_headers.update(endpoint.headers)
 
-            # Use endpoint's request config or fall back to API's
-            if endpoint.request_config == RequestConfig():
-                endpoint.request_config = self.request_config
-
             tool = endpoint.to_tool(
                 base_url=self.base_url, global_headers=merged_headers
             )
             tools.append(tool)
 
+        logger.info(f"Created {len(tools)} tools from API '{self.name}'")
         return tools
 
     @classmethod
@@ -208,6 +437,7 @@ class API(BaseModel):
             if isinstance(spec, str) and (
                 spec.startswith("http://") or spec.startswith("https://")
             ):
+                logger.info(f"Fetching OpenAPI spec from URL: {spec}")
                 async with aiohttp.ClientSession() as session:
                     async with session.get(spec) as response:
                         if response.status != 200:
@@ -226,6 +456,7 @@ class API(BaseModel):
             if not spec_path.exists():
                 raise FileNotFoundError(f"OpenAPI spec file not found: {spec_path}")
 
+            logger.info(f"Loading OpenAPI spec from file: {spec_path}")
             content = spec_path.read_text()
             if spec_path.suffix.lower() in [".yaml", ".yml"]:
                 return yaml.safe_load(content)
@@ -242,11 +473,10 @@ class API(BaseModel):
         spec_dict: Mapping[str, Any],
         include_operations: Sequence[str] | None = None,
         exclude_operations: Sequence[str] | None = None,
+        include_tags: Sequence[str] | None = None,
+        exclude_tags: Sequence[str] | None = None,
     ) -> Sequence[Endpoint]:
         """Parse OpenAPI paths into Endpoint instances."""
-        from agentle.agents.apis.endpoint import Endpoint
-        from agentle.agents.apis.http_method import HTTPMethod
-
         endpoints: MutableSequence[Endpoint] = []
         paths: Mapping[str, Any] = spec_dict.get("paths", {})
         components = spec_dict.get("components", {})
@@ -267,21 +497,47 @@ class API(BaseModel):
                     continue
 
                 operation_id = operation.get("operationId")
+                operation_tags = operation.get("tags", [])
 
-                # Apply include/exclude filters
+                # Apply operation filters
                 if include_operations and operation_id not in include_operations:
                     continue
                 if exclude_operations and operation_id in exclude_operations:
                     continue
 
+                # Apply tag filters
+                if include_tags and not any(
+                    tag in include_tags for tag in operation_tags
+                ):
+                    continue
+                if exclude_tags and any(tag in exclude_tags for tag in operation_tags):
+                    continue
+
                 # Create endpoint
-                endpoint_name: str = cast(
-                    str,
-                    (
-                        operation_id
-                        or f"{method}_{path.replace('/', '_').replace('{', '').replace('}', '')}"
-                    ),
-                )
+                # Generate a valid function name from the path
+                if operation_id:
+                    endpoint_name = operation_id
+                else:
+                    # Clean the path to create a valid function name
+                    # Remove leading/trailing slashes and replace special chars
+                    clean_path = (
+                        path.strip("/")
+                        .replace("/", "_")
+                        .replace("{", "")
+                        .replace("}", "")
+                        .replace("-", "_")
+                    )
+                    # Remove any consecutive underscores
+                    clean_path = re.sub(r"_+", "_", clean_path)
+                    # Ensure it doesn't start with a number
+                    if clean_path and clean_path[0].isdigit():
+                        clean_path = f"n{clean_path}"
+                    # If empty after cleaning, use a generic name
+                    if not clean_path:
+                        clean_path = "root"
+                    endpoint_name = f"{method.lower()}_{clean_path}"
+
+                endpoint_name = cast(str, endpoint_name)
 
                 endpoint_description: str = cast(
                     str,
@@ -300,12 +556,33 @@ class API(BaseModel):
                     components,
                 )
 
+                # Determine response format and extract response schema
+                response_format = "json"  # Default
+                response_schema = None
+                responses = operation.get("responses", {})
+                if "200" in responses:
+                    response_200 = responses["200"]
+                    content = response_200.get("content", {})
+                    if "application/json" in content:
+                        response_format = "json"
+                        # Extract response schema if available
+                        json_content = content["application/json"]
+                        if "schema" in json_content:
+                            response_schema = json_content["schema"]
+                    elif "text/plain" in content:
+                        response_format = "text"
+                    elif "application/xml" in content:
+                        response_format = "xml"
+
                 endpoint = Endpoint(
                     name=endpoint_name,
                     description=endpoint_description,
                     path=path,
                     method=HTTPMethod(method.upper()),
                     parameters=endpoint_parameters,
+                    response_format=response_format,  # type: ignore
+                    response_schema=response_schema,
+                    validate_response_schema=bool(response_schema),
                 )
 
                 endpoints.append(endpoint)
@@ -320,15 +597,12 @@ class API(BaseModel):
         components: Mapping[str, Any],
     ) -> Sequence[EndpointParameter]:
         """Parse OpenAPI parameters into EndpointParameter instances."""
-        from agentle.agents.apis.endpoint_parameter import EndpointParameter
-        from agentle.agents.apis.parameter_location import ParameterLocation
-
         endpoint_params: MutableSequence[EndpointParameter] = []
 
         # Process standard parameters
         for param in parameters:
             if "$ref" in param:
-                # Resolve reference (simplified - doesn't handle complex nested refs)
+                # Resolve reference
                 ref_path = param["$ref"].split("/")
                 if len(ref_path) >= 4 and ref_path[1] == "components":
                     param = components.get(ref_path[2], {}).get(ref_path[3], {})
@@ -343,7 +617,7 @@ class API(BaseModel):
                 "query": ParameterLocation.QUERY,
                 "header": ParameterLocation.HEADER,
                 "path": ParameterLocation.PATH,
-                "cookie": ParameterLocation.HEADER,  # Treat cookies as headers
+                "cookie": ParameterLocation.HEADER,
             }
             param_location = location_map.get(param_in, ParameterLocation.QUERY)
 
@@ -366,23 +640,22 @@ class API(BaseModel):
         if request_body:
             content = request_body.get("content", {})
 
-            # Look for JSON content first, then any other content type
+            # Look for JSON content first
             schema = None
             for content_type in [
                 "application/json",
                 "application/x-www-form-urlencoded",
+                "multipart/form-data",
             ]:
                 if content_type in content:
                     schema = content[content_type].get("schema", {})
                     break
 
             if not schema and content:
-                # Take the first available content type
                 first_content = next(iter(content.values()))
                 schema = first_content.get("schema", {})
 
             if schema:
-                # For request body, create a single parameter representing the body
                 body_param = EndpointParameter(
                     name="requestBody",
                     description=request_body.get("description", "Request body"),
@@ -401,10 +674,6 @@ class API(BaseModel):
         components: Mapping[str, Any],
     ) -> PrimitiveSchema | ObjectSchema | ArraySchema:
         """Parse OpenAPI schema into our schema types."""
-        from agentle.agents.apis.array_schema import ArraySchema
-        from agentle.agents.apis.object_schema import ObjectSchema
-        from agentle.agents.apis.primitive_schema import PrimitiveSchema
-
         # Handle references
         if "$ref" in schema:
             ref_path = schema["$ref"].split("/")

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"