agnt5 0.3.2a1__cp310-abi3-manylinux_2_34_aarch64.whl

agnt5/__init__.py

@@ -0,0 +1,119 @@
+"""
+AGNT5 Python SDK - Build durable, resilient agent-first applications.
+
+This SDK provides high-level components for building agents, tools, and workflows
+with built-in durability guarantees and state management.
+"""
+
+from ._compat import _import_error, _rust_available
+from .agent import Agent, AgentContext, AgentRegistry, AgentResult, Handoff, agent, handoff
+from .checkpoint import CheckpointClient
+from .client import AsyncClient, Client, RunError
+from .context import Context
+from .function import FunctionContext
+from .workflow import WorkflowContext
+from .entity import (
+    Entity,
+    EntityRegistry,
+    EntityStateAdapter,
+    EntityType,
+    StateType,
+    create_entity_context,
+    query,
+    with_entity_context,
+)
+from .exceptions import (
+    AGNT5Error,
+    CheckpointError,
+    ConfigurationError,
+    ExecutionError,
+    RetryError,
+    StateError,
+    WaitingForUserInputException,
+)
+from .function import FunctionRegistry, function
+from .memory import ConversationMemory, MemoryMessage, MemoryMetadata, MemoryResult, MemoryScope, SemanticMemory
+from .tool import AskUserTool, RequestApprovalTool, Tool, ToolRegistry, tool
+from .types import BackoffPolicy, BackoffType, FunctionConfig, RetryPolicy, WorkflowConfig
+from .version import _get_version
+from .worker import Worker
+from .workflow import WorkflowRegistry, workflow
+
+# Expose simplified language model API (recommended)
+from . import lm
+
+# Expose streaming events module for typed event streaming
+from . import events
+from .events import Event, EventType
+
+# Expose Sentry utilities for custom error tracking (optional)
+from . import _sentry as sentry
+
+__version__ = _get_version()
+
+__all__ = [
+    # Version
+    "__version__",
+    # Core components
+    "Context",
+    "FunctionContext",
+    "WorkflowContext",
+    "AgentContext",
+    "CheckpointClient",
+    "Client",
+    "AsyncClient",
+    "Worker",
+    "function",
+    "FunctionRegistry",
+    "Entity",
+    "EntityType",
+    "EntityRegistry",
+    "EntityStateAdapter",
+    "StateType",
+    "query",
+    "with_entity_context",
+    "create_entity_context",
+    "workflow",
+    "WorkflowRegistry",
+    "tool",
+    "Tool",
+    "ToolRegistry",
+    "AskUserTool",
+    "RequestApprovalTool",
+    "agent",
+    "Agent",
+    "AgentRegistry",
+    "AgentResult",
+    "Handoff",
+    "handoff",
+    # Memory
+    "ConversationMemory",
+    "MemoryMessage",
+    "MemoryMetadata",
+    "MemoryResult",
+    "MemoryScope",
+    "SemanticMemory",
+    # Types
+    "RetryPolicy",
+    "BackoffPolicy",
+    "BackoffType",
+    "FunctionConfig",
+    "WorkflowConfig",
+    # Exceptions
+    "AGNT5Error",
+    "ConfigurationError",
+    "ExecutionError",
+    "RetryError",
+    "StateError",
+    "CheckpointError",
+    "WaitingForUserInputException",
+    "RunError",
+    # Language Model (Simplified API)
+    "lm",
+    # Streaming Events (for typed SSE events)
+    "events",
+    "Event",
+    "EventType",
+    # Sentry integration (Optional)
+    "sentry",
+]

agnt5/_compat.py

@@ -0,0 +1,16 @@
+"""
+Compatibility utilities for the AGNT5 Python SDK.
+
+This module handles runtime compatibility checks and provides utilities
+for cross-referencing throughout the project.
+"""
+
+# Check if Rust core is available
+try:
+    from . import _core
+
+    _rust_available = True
+    _import_error = None
+except ImportError as e:
+    _rust_available = False
+    _import_error = e

agnt5/_retry_utils.py

@@ -0,0 +1,196 @@
+"""Retry and backoff utilities for durable execution.
+
+This module provides utilities for parsing retry policies, calculating backoff delays,
+and executing functions with retry logic.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import inspect
+from typing import Any, Dict, Optional, Union
+
+from .exceptions import RetryError
+from .types import BackoffPolicy, BackoffType, HandlerFunc, RetryPolicy
+
+
+def parse_retry_policy(retries: Optional[Union[int, Dict[str, Any], RetryPolicy]]) -> RetryPolicy:
+    """Parse retry configuration from various forms.
+
+    Args:
+        retries: Can be:
+            - int: max_attempts (e.g., 5)
+            - dict: RetryPolicy parameters (e.g., {"max_attempts": 5, "initial_interval_ms": 1000})
+            - RetryPolicy: pass through
+            - None: use default
+
+    Returns:
+        RetryPolicy instance
+    """
+    if retries is None:
+        return RetryPolicy()
+    elif isinstance(retries, int):
+        return RetryPolicy(max_attempts=retries)
+    elif isinstance(retries, dict):
+        return RetryPolicy(**retries)
+    elif isinstance(retries, RetryPolicy):
+        return retries
+    else:
+        raise TypeError(f"retries must be int, dict, or RetryPolicy, got {type(retries)}")
+
+
+def parse_backoff_policy(backoff: Optional[Union[str, Dict[str, Any], BackoffPolicy]]) -> BackoffPolicy:
+    """Parse backoff configuration from various forms.
+
+    Args:
+        backoff: Can be:
+            - str: backoff type ("constant", "linear", "exponential")
+            - dict: BackoffPolicy parameters (e.g., {"type": "exponential", "multiplier": 2.0})
+            - BackoffPolicy: pass through
+            - None: use default
+
+    Returns:
+        BackoffPolicy instance
+    """
+    if backoff is None:
+        return BackoffPolicy()
+    elif isinstance(backoff, str):
+        backoff_type = BackoffType(backoff.lower())
+        return BackoffPolicy(type=backoff_type)
+    elif isinstance(backoff, dict):
+        # Convert string type to enum if present
+        if "type" in backoff and isinstance(backoff["type"], str):
+            backoff = {**backoff, "type": BackoffType(backoff["type"].lower())}
+        return BackoffPolicy(**backoff)
+    elif isinstance(backoff, BackoffPolicy):
+        return backoff
+    else:
+        raise TypeError(f"backoff must be str, dict, or BackoffPolicy, got {type(backoff)}")
+
+
+def calculate_backoff_delay(
+    attempt: int,
+    retry_policy: RetryPolicy,
+    backoff_policy: BackoffPolicy,
+) -> float:
+    """Calculate backoff delay in seconds based on attempt number.
+
+    Args:
+        attempt: Current attempt number (0-indexed)
+        retry_policy: Retry configuration
+        backoff_policy: Backoff configuration
+
+    Returns:
+        Delay in seconds
+    """
+    if backoff_policy.type == BackoffType.CONSTANT:
+        delay_ms = retry_policy.initial_interval_ms
+    elif backoff_policy.type == BackoffType.LINEAR:
+        delay_ms = retry_policy.initial_interval_ms * (attempt + 1)
+    else:  # EXPONENTIAL
+        delay_ms = retry_policy.initial_interval_ms * (backoff_policy.multiplier**attempt)
+
+    # Cap at max_interval_ms
+    delay_ms = min(delay_ms, retry_policy.max_interval_ms)
+    return delay_ms / 1000.0  # Convert to seconds
+
+
+async def execute_with_retry(
+    handler: HandlerFunc,
+    ctx: Any,  # FunctionContext, but avoid circular import
+    retry_policy: RetryPolicy,
+    backoff_policy: BackoffPolicy,
+    needs_context: bool,
+    timeout_ms: Optional[int],
+    *args: Any,
+    **kwargs: Any,
+) -> Any:
+    """Execute handler with retry logic and optional timeout.
+
+    Args:
+        handler: The function handler to execute
+        ctx: Context for logging and attempt tracking (FunctionContext)
+        retry_policy: Retry configuration
+        backoff_policy: Backoff configuration
+        needs_context: Whether handler accepts ctx parameter
+        timeout_ms: Maximum execution time in milliseconds (None for no timeout)
+        *args: Arguments to pass to handler (excluding ctx if needs_context=False)
+        **kwargs: Keyword arguments to pass to handler
+
+    Returns:
+        Result of successful execution
+
+    Raises:
+        RetryError: If all retry attempts fail
+        asyncio.TimeoutError: If function execution exceeds timeout_ms
+    """
+    # Import here to avoid circular dependency
+    from .function import FunctionContext
+
+    last_error: Optional[Exception] = None
+
+    for attempt in range(retry_policy.max_attempts):
+        try:
+            # Create context for this attempt (FunctionContext is immutable)
+            # Propagate streaming context from parent for real-time SSE log delivery
+            attempt_ctx = FunctionContext(
+                run_id=ctx.run_id,
+                attempt=attempt,
+                retry_policy=retry_policy,
+                is_streaming=getattr(ctx, '_is_streaming', False),
+                tenant_id=getattr(ctx, '_tenant_id', None),
+            )
+
+            # Execute handler (pass context only if needed)
+            if needs_context:
+                result = handler(attempt_ctx, *args, **kwargs)
+            else:
+                result = handler(*args, **kwargs)
+
+            # Check if result is an async generator (streaming function)
+            # Async generators cannot be retried - return immediately for streaming consumption
+            if inspect.isasyncgen(result):
+                return result
+
+            # For coroutines, apply timeout and await
+            if inspect.iscoroutine(result):
+                if timeout_ms is not None:
+                    timeout_seconds = timeout_ms / 1000.0
+                    try:
+                        result = await asyncio.wait_for(result, timeout=timeout_seconds)
+                    except asyncio.TimeoutError:
+                        # Re-raise with more context
+                        raise asyncio.TimeoutError(
+                            f"Function execution timed out after {timeout_ms}ms"
+                        )
+                else:
+                    result = await result
+
+            return result
+
+        except Exception as e:
+            last_error = e
+            ctx.logger.warning(
+                f"Function execution failed (attempt {attempt + 1}/{retry_policy.max_attempts}): {e}"
+            )
+
+            # If this was the last attempt, raise RetryError
+            if attempt == retry_policy.max_attempts - 1:
+                raise RetryError(
+                    f"Function failed after {retry_policy.max_attempts} attempts",
+                    attempts=retry_policy.max_attempts,
+                    last_error=e,
+                )
+
+            # Calculate backoff delay
+            delay = calculate_backoff_delay(attempt, retry_policy, backoff_policy)
+            ctx.logger.info(f"Retrying in {delay:.2f} seconds...")
+            await asyncio.sleep(delay)
+
+    # Should never reach here, but for type safety
+    assert last_error is not None
+    raise RetryError(
+        f"Function failed after {retry_policy.max_attempts} attempts",
+        attempts=retry_policy.max_attempts,
+        last_error=last_error,
+    )

agnt5/_schema_utils.py

@@ -0,0 +1,312 @@
+"""Schema conversion utilities for structured output support.
+
+This module provides utilities to convert Python dataclasses and Pydantic models
+to JSON Schema format for LLM structured output generation, function signatures,
+and tool definitions.
+"""
+
+from __future__ import annotations
+
+import dataclasses
+import inspect
+from typing import Any, Callable, Dict, Optional, Tuple, get_args, get_origin, get_type_hints
+
+try:
+    from pydantic import BaseModel
+    PYDANTIC_AVAILABLE = True
+except ImportError:
+    BaseModel = None  # type: ignore
+    PYDANTIC_AVAILABLE = False
+
+
+def detect_format_type(response_format: Any) -> Tuple[str, Dict[str, Any]]:
+    """Auto-detect format type and convert to JSON schema.
+
+    Args:
+        response_format: Pydantic model, dataclass, or dict
+
+    Returns:
+        Tuple of (format_type, json_schema)
+        - format_type: "pydantic", "dataclass", or "raw"
+        - json_schema: JSON schema dictionary
+
+    Raises:
+        ValueError: If format type is not supported
+    """
+    # Check for Pydantic model
+    if PYDANTIC_AVAILABLE and isinstance(response_format, type) and issubclass(response_format, BaseModel):
+        return 'pydantic', pydantic_to_json_schema(response_format)
+
+    # Check for dataclass
+    if dataclasses.is_dataclass(response_format):
+        return 'dataclass', dataclass_to_json_schema(response_format)
+
+    # Check for raw dict
+    if isinstance(response_format, dict):
+        return 'raw', response_format
+
+    raise ValueError(
+        f"Unsupported response_format type: {type(response_format)}. "
+        f"Expected Pydantic model, dataclass, or dict."
+    )
+
+
+def pydantic_to_json_schema(model: type) -> Dict[str, Any]:
+    """Convert Pydantic model to JSON schema.
+
+    Supports both Pydantic v1 and v2 APIs.
+
+    Args:
+        model: Pydantic BaseModel class
+
+    Returns:
+        JSON schema dictionary
+    """
+    if not PYDANTIC_AVAILABLE:
+        raise ImportError("Pydantic is not installed. Install with: pip install pydantic")
+
+    if not (isinstance(model, type) and issubclass(model, BaseModel)):
+        raise ValueError(f"Expected Pydantic BaseModel class, got {type(model)}")
+
+    try:
+        # Try Pydantic v2 API first
+        if hasattr(model, 'model_json_schema'):
+            schema = model.model_json_schema()
+        # Fall back to Pydantic v1 API
+        elif hasattr(model, 'schema'):
+            schema = model.schema()
+        else:
+            # Fallback for edge cases
+            schema = {"type": "object"}
+    except Exception:
+        # If schema generation fails, return basic object schema
+        schema = {"type": "object"}
+
+    # Ensure we have the required fields
+    if "type" not in schema:
+        schema["type"] = "object"
+
+    return schema
+
+
+def dataclass_to_json_schema(cls: type) -> Dict[str, Any]:
+    """Convert Python dataclass to JSON schema.
+
+    Args:
+        cls: Dataclass type
+
+    Returns:
+        JSON schema dictionary
+    """
+    if not dataclasses.is_dataclass(cls):
+        raise ValueError(f"Expected dataclass, got {type(cls)}")
+
+    properties: Dict[str, Any] = {}
+    required: list[str] = []
+
+    for field in dataclasses.fields(cls):
+        # Convert field type to JSON schema
+        field_schema = _type_to_schema(field.type)
+        properties[field.name] = field_schema
+
+        # Check if field is required (no default value)
+        if field.default == dataclasses.MISSING and field.default_factory == dataclasses.MISSING:  # type: ignore
+            required.append(field.name)
+
+    schema = {
+        "type": "object",
+        "properties": properties,
+        "required": required,
+        "additionalProperties": False
+    }
+
+    return schema
+
+
+def _type_to_schema(python_type: Any) -> Dict[str, Any]:
+    """Convert Python type hint to JSON schema type.
+
+    Args:
+        python_type: Python type annotation
+
+    Returns:
+        JSON schema type definition
+    """
+    # Handle Optional types
+    origin = get_origin(python_type)
+    args = get_args(python_type)
+
+    # Handle Optional[X] which is Union[X, None]
+    if origin is type(None) or python_type is type(None):
+        return {"type": "null"}
+
+    # Handle Union types (including Optional)
+    if origin is Union:  # type: ignore
+        # Filter out None from union types
+        non_none_types = [t for t in args if t is not type(None)]
+        if len(non_none_types) == 1:
+            # Optional[X] case
+            return _type_to_schema(non_none_types[0])
+        else:
+            # True Union - use anyOf
+            return {"anyOf": [_type_to_schema(t) for t in non_none_types]}
+
+    # Handle List types
+    if origin is list:
+        item_type = args[0] if args else Any
+        return {
+            "type": "array",
+            "items": _type_to_schema(item_type)
+        }
+
+    # Handle Dict types
+    if origin is dict:
+        value_type = args[1] if len(args) > 1 else Any
+        return {
+            "type": "object",
+            "additionalProperties": _type_to_schema(value_type)
+        }
+
+    # Handle basic types
+    if python_type == str:
+        return {"type": "string"}
+    elif python_type == int:
+        return {"type": "integer"}
+    elif python_type == float:
+        return {"type": "number"}
+    elif python_type == bool:
+        return {"type": "boolean"}
+    elif python_type == dict:
+        return {"type": "object"}
+    elif python_type == list:
+        return {"type": "array"}
+    elif python_type == Any:
+        return {}  # Any type - no restrictions
+
+    # Fallback for unknown types
+    return {"type": "string", "description": f"Type: {python_type}"}
+
+
+# Import Union for type checking
+try:
+    from typing import Union
+except ImportError:
+    Union = None  # type: ignore
+
+
+def is_pydantic_model(type_hint: Any) -> bool:
+    """Check if a type hint is a Pydantic model.
+
+    Args:
+        type_hint: Type annotation to check
+
+    Returns:
+        True if type_hint is a Pydantic BaseModel subclass
+    """
+    if not PYDANTIC_AVAILABLE:
+        return False
+
+    try:
+        return isinstance(type_hint, type) and issubclass(type_hint, BaseModel)
+    except TypeError:
+        return False
+
+
+def extract_function_schemas(func: Callable[..., Any]) -> Tuple[Optional[Dict[str, Any]], Optional[Dict[str, Any]]]:
+    """Extract input and output schemas from function type hints.
+
+    Supports both plain Python types and Pydantic models.
+    Pydantic models provide richer validation and schema generation.
+
+    Args:
+        func: Function to extract schemas from
+
+    Returns:
+        Tuple of (input_schema, output_schema) where each is a JSON Schema dict or None
+    """
+    try:
+        # Get type hints
+        hints = get_type_hints(func)
+        sig = inspect.signature(func)
+
+        # Build input schema from parameters (excluding 'ctx')
+        input_properties = {}
+        required_params = []
+
+        for param_name, param in sig.parameters.items():
+            if param_name == "ctx":
+                continue
+
+            # Get type hint for this parameter
+            if param_name in hints:
+                param_type = hints[param_name]
+
+                # Check if it's a Pydantic model
+                if is_pydantic_model(param_type):
+                    # Use Pydantic's schema generation
+                    input_properties[param_name] = pydantic_to_json_schema(param_type)
+                else:
+                    # Use basic type conversion
+                    input_properties[param_name] = _type_to_schema(param_type)
+            else:
+                # No type hint, use generic object
+                input_properties[param_name] = {"type": "object"}
+
+            # Check if parameter is required (no default value)
+            if param.default is inspect.Parameter.empty:
+                required_params.append(param_name)
+
+        input_schema = None
+        if input_properties:
+            input_schema = {
+                "type": "object",
+                "properties": input_properties,
+            }
+            if required_params:
+                input_schema["required"] = required_params
+
+            # Add description from docstring if available
+            if func.__doc__:
+                docstring = inspect.cleandoc(func.__doc__)
+                first_line = docstring.split('\n')[0].strip()
+                if first_line:
+                    input_schema["description"] = first_line
+
+        # Build output schema from return type hint
+        output_schema = None
+        if "return" in hints:
+            return_type = hints["return"]
+
+            # Check if return type is a Pydantic model
+            if is_pydantic_model(return_type):
+                output_schema = pydantic_to_json_schema(return_type)
+            else:
+                output_schema = _type_to_schema(return_type)
+
+        return input_schema, output_schema
+
+    except Exception:
+        # If schema extraction fails, return None schemas
+        return None, None
+
+
+def extract_function_metadata(func: Callable[..., Any]) -> Dict[str, str]:
+    """Extract metadata from function including description from docstring.
+
+    Args:
+        func: Function to extract metadata from
+
+    Returns:
+        Dictionary with metadata fields like 'description'
+    """
+    metadata = {}
+
+    # Extract description from docstring
+    if func.__doc__:
+        # Get first line of docstring as description
+        docstring = inspect.cleandoc(func.__doc__)
+        first_line = docstring.split('\n')[0].strip()
+        if first_line:
+            metadata["description"] = first_line
+
+    return metadata