feat(apis): new boolen type, recursive object schema serialization, request config and more

Author: arthurbrenno

agentle/agents/apis/api.py

@@ -271,12 +271,15 @@ def _extract_auth_from_spec(
         elif scheme_type == "oauth2":
             flows = scheme.get("flows", {})
             if "clientCredentials" in flows:
-                token_url = flows["clientCredentials"].get("tokenUrl")
+                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
@@ -535,14 +538,19 @@ def _parse_openapi_paths(
                     components,
                 )
 
-                # Determine response format
+                # 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:
@@ -555,6 +563,8 @@ def _parse_openapi_paths(
                     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)

agentle/agents/apis/authentication_config.py

@@ -43,7 +43,14 @@ class AuthenticationConfig(BaseModel):
     oauth2_grant_type: OAuth2GrantType = Field(
         default=OAuth2GrantType.CLIENT_CREDENTIALS
     )
-    oauth2_scope: str | None = Field(default=None)
+    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
@@ -96,6 +103,7 @@ def create_handler(self) -> AuthenticationBase:
                 self.oauth2_grant_type,
                 self.oauth2_scope,
                 self.oauth2_refresh_token,
+                self.oauth2_scopes,
             )
 
         elif self.type == AuthType.HMAC:

agentle/agents/apis/endpoint.py

@@ -18,9 +18,8 @@
 
 import asyncio
 import logging
-import mimetypes
 import random
-from collections.abc import AsyncIterator, Callable, MutableMapping, Sequence
+from collections.abc import AsyncIterator, MutableMapping, Sequence
 from typing import Any, Literal
 
 import aiohttp
@@ -42,7 +41,6 @@
 from agentle.agents.apis.request_config import RequestConfig
 from agentle.agents.apis.response_cache import ResponseCache
 from agentle.agents.apis.retry_strategy import RetryStrategy
-from agentle.agents.apis.request_hook import RequestHook
 from agentle.generations.tools.tool import Tool
 
 logger = logging.getLogger(__name__)
@@ -326,13 +324,22 @@ async def make_request(
                 files[param_name] = value
                 continue
 
-            # Place parameter in appropriate location
+            # Place parameter in appropriate location with proper type handling
             if param.location == ParameterLocation.QUERY:
-                query_params[param_name] = value
+                # Handle boolean conversion for query params
+                if isinstance(value, bool):
+                    # Convert Python bool to lowercase string for URL compatibility
+                    query_params[param_name] = str(value).lower()
+                else:
+                    query_params[param_name] = value
             elif param.location == ParameterLocation.BODY:
                 body_params[param_name] = value
             elif param.location == ParameterLocation.HEADER:
-                header_params[param_name] = str(value)
+                # Convert to string for headers
+                if isinstance(value, bool):
+                    header_params[param_name] = str(value).lower()
+                else:
+                    header_params[param_name] = str(value)
             elif param.location == ParameterLocation.PATH:
                 path_params[param_name] = value
 
@@ -547,8 +554,10 @@ async def endpoint_callable(**kwargs: Any) -> Any:
 
         for param in self.parameters:
             if hasattr(param, "to_tool_parameter_schema"):
+                # Use the parameter's own schema conversion method
                 tool_parameters[param.name] = param.to_tool_parameter_schema()
             else:
+                # Fallback for parameters without schema method
                 param_info: dict[str, object] = {
                     "type": getattr(param, "param_type", "string") or "string",
                     "description": param.description,
@@ -560,6 +569,20 @@ async def endpoint_callable(**kwargs: Any) -> Any:
 
                 if hasattr(param, "enum") and param.enum:
                     param_info["enum"] = list(param.enum)
+                
+                # Add constraints for number/primitive types
+                if hasattr(param, "parameter_schema") and param.parameter_schema:
+                    from agentle.agents.apis.primitive_schema import PrimitiveSchema
+                    
+                    schema = param.parameter_schema
+                    # Only PrimitiveSchema has minimum, maximum, format
+                    if isinstance(schema, PrimitiveSchema):
+                        if schema.minimum is not None:
+                            param_info["minimum"] = schema.minimum
+                        if schema.maximum is not None:
+                            param_info["maximum"] = schema.maximum
+                        if schema.format:
+                            param_info["format"] = schema.format
 
                 tool_parameters[param.name] = param_info
 

agentle/agents/apis/oauth2_authentication.py

@@ -23,11 +23,15 @@ def __init__(
         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
 
@@ -76,7 +80,10 @@ async def _fetch_token(self) -> None:
             "grant_type": self.grant_type.value,
         }
 
-        if self.scope:
+        # Handle scopes - prefer scopes list over single scope
+        if self.scopes:
+            data["scope"] = " ".join(self.scopes)
+        elif self.scope:
             data["scope"] = self.scope
 
         if (

agentle/agents/apis/object_schema.py

@@ -8,7 +8,7 @@
 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,
+    )