agnt5 0.2.3__cp39-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl

agnt5/__init__.py

@@ -0,0 +1,86 @@
+"""
+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, AgentRegistry, AgentResult, Handoff, agent, handoff
+from .client import Client, RunError
+from .context import Context
+from .entity import (
+    DurableEntity,
+    SessionEntity,
+    MemoryEntity,
+    WorkflowEntity,
+    EntityInstance,
+    EntityRegistry,
+    EntityType,
+    entity,
+)
+from .exceptions import (
+    AGNT5Error,
+    CheckpointError,
+    ConfigurationError,
+    ExecutionError,
+    RetryError,
+    StateError,
+)
+from .function import FunctionRegistry, function
+from .tool import 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
+
+__version__ = _get_version()
+
+__all__ = [
+    # Version
+    "__version__",
+    # Core components
+    "Context",
+    "Client",
+    "Worker",
+    "function",
+    "FunctionRegistry",
+    "entity",
+    "EntityType",
+    "EntityInstance",
+    "EntityRegistry",
+    "DurableEntity",
+    "SessionEntity",
+    "MemoryEntity",
+    "WorkflowEntity",
+    "workflow",
+    "WorkflowRegistry",
+    "tool",
+    "Tool",
+    "ToolRegistry",
+    "agent",
+    "Agent",
+    "AgentRegistry",
+    "AgentResult",
+    "Handoff",
+    "handoff",
+    # Types
+    "RetryPolicy",
+    "BackoffPolicy",
+    "BackoffType",
+    "FunctionConfig",
+    "WorkflowConfig",
+    # Exceptions
+    "AGNT5Error",
+    "ConfigurationError",
+    "ExecutionError",
+    "RetryError",
+    "StateError",
+    "CheckpointError",
+    "RunError",
+    # Language Model (Simplified API)
+    "lm",
+]

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/_telemetry.py

@@ -0,0 +1,146 @@
+"""
+OpenTelemetry integration for Python logging.
+
+This module bridges Python's standard logging to Rust's tracing/OpenTelemetry system,
+ensuring all logs from ctx.logger are sent to both the console and OTLP exporters.
+"""
+
+import logging
+from typing import Optional
+
+
+class OpenTelemetryHandler(logging.Handler):
+    """
+    Custom logging handler that forwards Python logs to Rust OpenTelemetry system.
+
+    This handler routes all Python log records through the Rust `log_from_python()`
+    function, which integrates with the tracing ecosystem. This ensures:
+
+    1. Logs are sent to OpenTelemetry OTLP exporter
+    2. Logs appear in console output (via Rust's fmt layer)
+    3. Logs inherit span context (invocation.id, trace_id, etc.)
+    4. Structured logging with proper attributes
+
+    The Rust side handles both console output and OTLP export, so we only
+    need one handler on the Python side.
+    """
+
+    def __init__(self, level=logging.NOTSET):
+        """Initialize the OpenTelemetry handler.
+
+        Args:
+            level: Minimum log level to process (default: NOTSET processes all)
+        """
+        super().__init__(level)
+
+        # Import Rust bridge function
+        try:
+            from ._core import log_from_python
+            self._log_from_python = log_from_python
+        except ImportError as e:
+            # Fallback if Rust core not available (development/testing)
+            import warnings
+            warnings.warn(
+                f"Failed to import Rust telemetry bridge: {e}. "
+                "Logs will not be sent to OpenTelemetry.",
+                RuntimeWarning
+            )
+            self._log_from_python = None
+
+    def emit(self, record: logging.LogRecord):
+        """
+        Process a log record and forward to Rust telemetry.
+
+        Args:
+            record: Python logging record to process
+        """
+        if self._log_from_python is None:
+            # No Rust bridge available, silently skip
+            return
+
+        # Filter out gRPC internal logs to avoid noise
+        # These are low-level HTTP/2 protocol logs that aren't useful for application debugging
+        if record.name.startswith(('grpc.', 'h2.', '_grpc_', 'h2-')):
+            return
+
+        try:
+            # Format the message (applies any formatters)
+            message = self.format(record)
+
+            # Forward to Rust tracing system
+            # Rust side will:
+            # - Add to current span context (inherits invocation.id)
+            # - Send to OTLP exporter
+            # - Print to console via fmt layer
+            self._log_from_python(
+                level=record.levelname,
+                message=message,
+                target=record.name,
+                module_path=record.module,
+                filename=record.pathname,
+                line=record.lineno
+            )
+        except Exception:
+            # Don't let logging errors crash the application
+            # Use handleError to report the issue via logging system
+            self.handleError(record)
+
+
+def setup_context_logger(logger: logging.Logger, log_level: Optional[int] = None) -> None:
+    """
+    Configure a Context logger with OpenTelemetry integration.
+
+    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
+
+    Args:
+        logger: Logger instance to configure
+        log_level: Optional log level (default: DEBUG)
+    """
+    # Remove existing handlers to avoid duplicate logs
+    logger.handlers.clear()
+
+    # Add OpenTelemetry handler
+    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)
+    if log_level is None:
+        log_level = logging.DEBUG
+    logger.setLevel(log_level)
+
+    # Don't propagate to root logger (we handle everything via OpenTelemetry)
+    logger.propagate = False
+
+
+def setup_module_logger(module_name: str, log_level: Optional[int] = None) -> logging.Logger:
+    """
+    Create and configure a logger for a module with OpenTelemetry integration.
+
+    Convenience function for setting up loggers in SDK modules.
+
+    Args:
+        module_name: Name of the module (e.g., "agnt5.worker")
+        log_level: Optional log level (default: INFO for modules)
+
+    Returns:
+        Configured logger instance
+    """
+    logger = logging.getLogger(module_name)
+
+    # For module loggers, default to INFO level
+    if log_level is None:
+        log_level = logging.INFO
+
+    setup_context_logger(logger, log_level)
+    return logger