agnt5 0.2.2__cp39-abi3-manylinux_2_34_x86_64.whl → 0.2.6__cp39-abi3-manylinux_2_34_x86_64.whl

agnt5/__init__.py

@@ -9,15 +9,15 @@ from ._compat import _import_error, _rust_available
 from .agent import Agent, AgentRegistry, AgentResult, Handoff, agent, handoff
 from .client import Client, RunError
 from .context import Context
+from .function import FunctionContext
+from .workflow import WorkflowContext
 from .entity import (
-    DurableEntity,
-    SessionEntity,
-    MemoryEntity,
-    WorkflowEntity,
-    EntityInstance,
+    Entity,
     EntityRegistry,
+    EntityStateManager,
     EntityType,
-    entity,
+    create_entity_context,
+    with_entity_context,
 )
 from .exceptions import (
     AGNT5Error,
@@ -44,18 +44,18 @@ __all__ = [
     "__version__",
     # Core components
     "Context",
+    "FunctionContext",
+    "WorkflowContext",
     "Client",
     "Worker",
     "function",
     "FunctionRegistry",
-    "entity",
+    "Entity",
     "EntityType",
-    "EntityInstance",
     "EntityRegistry",
-    "DurableEntity",
-    "SessionEntity",
-    "MemoryEntity",
-    "WorkflowEntity",
+    "EntityStateManager",
+    "with_entity_context",
+    "create_entity_context",
     "workflow",
     "WorkflowRegistry",
     "tool",

agnt5/_retry_utils.py

@@ -0,0 +1,169 @@
+"""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
+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,
+    *args: Any,
+    **kwargs: Any,
+) -> Any:
+    """Execute handler with retry logic.
+
+    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
+        *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
+    """
+    # 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)
+            attempt_ctx = FunctionContext(
+                run_id=ctx.run_id,
+                attempt=attempt,
+                retry_policy=retry_policy
+            )
+
+            # Execute handler (pass context only if needed)
+            if needs_context:
+                result = await handler(attempt_ctx, *args, **kwargs)
+            else:
+                result = await handler(*args, **kwargs)
+            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

agnt5/_telemetry.py

@@ -67,6 +67,12 @@ class OpenTelemetryHandler(logging.Handler):
             # Format the message (applies any formatters)
             message = self.format(record)
 
+            # Include exception traceback if present (from logger.exception() or exc_info=True)
+            if record.exc_info:
+                # formatException() returns the formatted traceback string
+                exc_text = self.formatException(record.exc_info)
+                message = f"{message}\n{exc_text}"
+
             # Forward to Rust tracing system
             # Rust side will:
             # - Add to current span context (inherits invocation.id)
@@ -92,9 +98,10 @@ def setup_context_logger(logger: logging.Logger, log_level: Optional[int] = None
 
     This function:
     1. Removes any existing handlers (avoid duplicates)
-    2. Adds OpenTelemetry handler for OTLP + console output
-    3. Sets appropriate log level
-    4. Disables propagation to avoid duplicate logs
+    2. Adds OpenTelemetry handler for OTLP + console output (when Worker is running)
+    3. Adds console handler for local testing (fallback)
+    4. Sets appropriate log level
+    5. Disables propagation to avoid duplicate logs
 
     Args:
         logger: Logger instance to configure
@@ -103,23 +110,37 @@ def setup_context_logger(logger: logging.Logger, log_level: Optional[int] = None
     # Remove existing handlers to avoid duplicate logs
     logger.handlers.clear()
 
-    # Add OpenTelemetry handler
+    # Add OpenTelemetry handler (for Worker/platform execution)
     otel_handler = OpenTelemetryHandler()
     otel_handler.setLevel(logging.DEBUG)
 
     # Use simple formatter - Rust side handles structured logging
-    # We just want the message here
     formatter = logging.Formatter('%(message)s')
     otel_handler.setFormatter(formatter)
 
     logger.addHandler(otel_handler)
 
-    # Set log level (default to DEBUG to let Rust side filter)
+    # Add console handler for local testing (fallback when Rust bridge not available)
+    # This ensures logs appear when testing functions locally without Worker
+    console_handler = logging.StreamHandler()
+    console_handler.setLevel(logging.DEBUG)
+
+    # Console format includes level, message, and exception info if present
+    # exc_info=True in the format string means "include traceback if present"
+    console_formatter = logging.Formatter(
+        '[%(levelname)s] %(message)s',
+        # Python automatically appends exception traceback when exc_info is set
+    )
+    console_handler.setFormatter(console_formatter)
+
+    logger.addHandler(console_handler)
+
+    # Set log level (default to DEBUG to let handlers filter)
     if log_level is None:
         log_level = logging.DEBUG
     logger.setLevel(log_level)
 
-    # Don't propagate to root logger (we handle everything via OpenTelemetry)
+    # Don't propagate to root logger (we handle everything ourselves)
     logger.propagate = False