agnt5 0.1.3__cp39-abi3-musllinux_1_2_x86_64.whl

agnt5/__init__.py

@@ -0,0 +1,23 @@
+"""
+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, backed by a high-performance
+Rust core.
+"""
+
+from .version import _get_version
+from ._compat import _rust_available, _import_error
+from .decorators import function
+from .worker import Worker
+from .logging import install_opentelemetry_logging, remove_opentelemetry_logging
+
+__version__ = _get_version()
+
+__all__ = [
+    'function',
+    'Worker',
+    'install_opentelemetry_logging',
+    'remove_opentelemetry_logging',
+    '__version__',
+]

agnt5/_compat.py

@@ -0,0 +1,15 @@
+"""
+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/components.py

@@ -0,0 +1,278 @@
+"""
+Component abstraction layer for AGNT5 SDK.
+
+This module defines the base classes for all component types:
+- Functions: Stateless operations
+- Objects: Virtual objects with persistent state  
+- Flows: Multi-step workflows with orchestration
+"""
+
+from abc import ABC, abstractmethod
+from enum import Enum
+from typing import Any, Callable, Dict, List, Optional, Type, Union
+import uuid
+import json
+import time
+
+
+class ComponentType(Enum):
+    """Component types matching protobuf enum"""
+    FUNCTION = "function"
+    OBJECT = "object" 
+    FLOW = "flow"
+
+
+class ExecutionContext:
+    """
+    Unified execution context for all component types.
+    
+    Provides methods for:
+    - Functions: Simple input/output
+    - Objects: State management and mutations
+    - Flows: Orchestration and step coordination
+    """
+    
+    def __init__(self, invocation_id: str, component_type: ComponentType):
+        self.invocation_id = invocation_id
+        self.component_type = component_type
+        
+        # Object-specific state management
+        self.object_id: Optional[str] = None
+        self.state: Optional[Dict[str, Any]] = None
+        self.state_mutations: List[Dict[str, Any]] = []
+        
+        # Flow-specific orchestration
+        self.flow_instance_id: Optional[str] = None
+        self.flow_step: int = 0
+        self.checkpoint_data: Optional[Dict[str, Any]] = None
+        
+        # Extensible metadata
+        self.metadata: Dict[str, str] = {}
+    
+    # State management methods (for Objects)
+    def get_state(self, key: str, default: Any = None) -> Any:
+        """Get a value from object state"""
+        if self.state is None:
+            return default
+        return self.state.get(key, default)
+    
+    def set_state(self, key: str, value: Any) -> None:
+        """Set a value in object state (records mutation)"""
+        if self.state is None:
+            self.state = {}
+        
+        old_value = self.state.get(key)
+        self.state[key] = value
+        
+        # Record mutation for persistence
+        self.state_mutations.append({
+            "operation": "set",
+            "key": key,
+            "old_value": old_value,
+            "new_value": value,
+            "timestamp": int(time.time() * 1000)
+        })
+    
+    def delete_state(self, key: str) -> Any:
+        """Delete a value from object state"""
+        if self.state is None or key not in self.state:
+            return None
+            
+        old_value = self.state.pop(key)
+        
+        # Record mutation
+        self.state_mutations.append({
+            "operation": "delete", 
+            "key": key,
+            "old_value": old_value,
+            "new_value": None,
+            "timestamp": int(time.time() * 1000)
+        })
+        
+        return old_value
+    
+    # Flow orchestration methods (for Flows - future implementation)
+    async def call_function(self, function_name: str, input_data: Any) -> Any:
+        """Call another function from within a flow"""
+        # TODO: Implement in Phase 3 (Flows)
+        raise NotImplementedError("Flow orchestration coming in Phase 3")
+    
+    async def call_object(self, object_type: str, object_id: str, 
+                         method: str, input_data: Any) -> Any:
+        """Call a method on a virtual object from within a flow"""
+        # TODO: Implement in Phase 3 (Flows)
+        raise NotImplementedError("Flow orchestration coming in Phase 3")
+    
+    async def sleep(self, duration_seconds: int) -> None:
+        """Durable sleep in a flow"""
+        # TODO: Implement in Phase 3 (Flows)
+        raise NotImplementedError("Flow orchestration coming in Phase 3")
+    
+    async def wait_for_event(self, event_type: str, timeout_seconds: int = None) -> Any:
+        """Wait for external event in a flow"""
+        # TODO: Implement in Phase 3 (Flows)
+        raise NotImplementedError("Flow orchestration coming in Phase 3")
+
+
+class Component(ABC):
+    """Base class for all component types"""
+    
+    def __init__(self, name: str, component_type: ComponentType):
+        self.name = name
+        self.component_type = component_type
+        self.metadata: Dict[str, str] = {}
+    
+    @abstractmethod
+    async def invoke(self, context: ExecutionContext, input_data: Any) -> Any:
+        """Execute the component with given context and input"""
+        pass
+    
+    def to_component_info(self) -> Dict[str, Any]:
+        """Convert to ComponentInfo for registration"""
+        return {
+            "name": self.name,
+            "component_type": self.component_type.value,
+            "metadata": self.metadata
+        }
+
+
+class FunctionComponent(Component):
+    """Function component - stateless operation"""
+    
+    def __init__(self, name: str, handler: Callable, **kwargs):
+        super().__init__(name, ComponentType.FUNCTION)
+        self.handler = handler
+        self.streaming = kwargs.get('streaming', False)
+        
+        # Add function-specific metadata
+        self.metadata.update({
+            'streaming': str(self.streaming),
+            'handler_name': handler.__name__
+        })
+    
+    async def invoke(self, context: ExecutionContext, input_data: Any) -> Any:
+        """Execute the function"""
+        # Functions get simple context and input
+        if self.streaming:
+            # For streaming functions, return async generator
+            result = self.handler(context, input_data)
+            if hasattr(result, '__aiter__'):
+                return result
+            else:
+                # Convert sync generator to async
+                async def async_generator():
+                    for item in result:
+                        yield item
+                return async_generator()
+        else:
+            # Regular function call
+            result = self.handler(context, input_data)
+            # Handle both sync and async functions
+            if hasattr(result, '__await__'):
+                return await result
+            return result
+
+
+class ObjectComponent(Component):
+    """Virtual Object component - stateful entity"""
+    
+    def __init__(self, name: str, object_class: Type, **kwargs):
+        super().__init__(name, ComponentType.OBJECT)
+        self.object_class = object_class
+        
+        # Add object-specific metadata
+        self.metadata.update({
+            'class_name': object_class.__name__,
+            'methods': [m for m in dir(object_class) 
+                       if not m.startswith('_') and callable(getattr(object_class, m))]
+        })
+    
+    async def invoke(self, context: ExecutionContext, input_data: Any) -> Any:
+        """Execute a method on the virtual object"""
+        # TODO: Implement in Phase 2 (Objects)
+        # For now, raise helpful error
+        raise NotImplementedError(
+            f"Virtual Objects coming in Phase 2. "
+            f"Component '{self.name}' is registered but not yet executable. "
+            f"Use @function decorator for now."
+        )
+
+
+class FlowComponent(Component):
+    """Flow component - multi-step workflow"""
+    
+    def __init__(self, name: str, flow_handler: Callable, **kwargs):
+        super().__init__(name, ComponentType.FLOW)
+        self.flow_handler = flow_handler
+        self.steps = kwargs.get('steps', [])
+        
+        # Add flow-specific metadata
+        self.metadata.update({
+            'handler_name': flow_handler.__name__,
+            'step_count': str(len(self.steps)) if self.steps else 'dynamic'
+        })
+    
+    async def invoke(self, context: ExecutionContext, input_data: Any) -> Any:
+        """Execute the workflow"""
+        # TODO: Implement in Phase 3 (Flows)
+        # For now, raise helpful error
+        raise NotImplementedError(
+            f"Flows/Workflows coming in Phase 3. "
+            f"Component '{self.name}' is registered but not yet executable. "
+            f"Use @function decorator for now."
+        )
+
+
+# Helper classes for future phases
+
+class StateManager:
+    """Manages state persistence for virtual objects (Phase 2)"""
+    
+    def __init__(self):
+        # Will be implemented with actual state backend
+        pass
+    
+    async def load_state(self, object_type: str, object_id: str) -> Optional[Dict[str, Any]]:
+        """Load object state from persistent storage"""
+        # TODO: Implement with NATS KV or similar
+        return None
+    
+    async def save_state(self, object_type: str, object_id: str, 
+                        state: Dict[str, Any], 
+                        mutations: List[Dict[str, Any]]) -> None:
+        """Save object state to persistent storage"""
+        # TODO: Implement with NATS KV or similar
+        pass
+
+
+class FlowExecutor:
+    """Manages workflow execution and orchestration (Phase 3)"""
+    
+    def __init__(self):
+        # Will be implemented with actual flow execution engine
+        pass
+    
+    async def execute_step(self, flow_instance_id: str, step: int, 
+                          input_data: Any) -> Any:
+        """Execute a single step in a workflow"""
+        # TODO: Implement with deterministic replay
+        pass
+    
+    async def checkpoint(self, flow_instance_id: str, 
+                        checkpoint_data: Dict[str, Any]) -> None:
+        """Save workflow checkpoint"""
+        # TODO: Implement with journal persistence
+        pass
+
+
+# Export main classes
+__all__ = [
+    'ComponentType',
+    'ExecutionContext', 
+    'Component',
+    'FunctionComponent',
+    'ObjectComponent', 
+    'FlowComponent',
+    'StateManager',
+    'FlowExecutor'
+]

agnt5/decorators.py

@@ -0,0 +1,240 @@
+"""
+Function decorators for AGNT5 workers.
+
+This module provides decorators for registering functions as handlers
+that can be invoked through the AGNT5 platform.
+"""
+
+import functools
+import inspect
+import logging
+from typing import Any, Callable, Dict, List, Optional
+
+# Set default logging level to DEBUG
+logging.getLogger().setLevel(logging.DEBUG)
+logger = logging.getLogger(__name__)
+
+# Global registry of decorated functions
+_function_registry: Dict[str, Callable] = {}
+
+
+def function(name: str = None):
+    """
+    Decorator to register a function as an AGNT5 handler.
+    
+    Args:
+        name: The name to register the function under. If None, uses the function's name.
+        
+    Usage:
+        @function("add_numbers")
+        def add_numbers(ctx, a: int, b: int) -> int:
+            return a + b
+            
+        @function()
+        def greet_user(ctx, name: str) -> str:
+            return f"Hello, {name}!"
+    """
+    def decorator(func: Callable) -> Callable:
+        handler_name = name if name is not None else func.__name__
+        
+        # Store function metadata
+        func._agnt5_handler_name = handler_name
+        func._agnt5_is_function = True
+        
+        # Register in global registry
+        _function_registry[handler_name] = func
+        
+        logger.debug(f"Registered function handler: {handler_name}")
+        
+        @functools.wraps(func)
+        def wrapper(*args, **kwargs):
+            return func(*args, **kwargs)
+        
+        # Copy metadata to wrapper
+        wrapper._agnt5_handler_name = handler_name
+        wrapper._agnt5_is_function = True
+        
+        return wrapper
+    
+    return decorator
+
+
+def get_registered_functions() -> Dict[str, Callable]:
+    """
+    Get all registered function handlers.
+    
+    Returns:
+        Dictionary mapping handler names to functions
+    """
+    return _function_registry.copy()
+
+
+def get_function_metadata(func: Callable) -> Optional[Dict[str, Any]]:
+    """
+    Extract metadata from a decorated function.
+    
+    Args:
+        func: The function to extract metadata from
+        
+    Returns:
+        Dictionary with function metadata or None if not decorated
+    """
+    if not hasattr(func, '_agnt5_is_function'):
+        return None
+        
+    signature = inspect.signature(func)
+    parameters = []
+    param_items = list(signature.parameters.items())
+    
+    for i, (param_name, param) in enumerate(param_items):
+        if i == 0 and param_name == 'ctx':  # Skip context parameter if it's the first one
+            continue
+            
+        param_info = {
+            'name': param_name,
+            'type': 'any'  # Default type, could be enhanced with type hints
+        }
+        
+        # Extract type information if available
+        if param.annotation != inspect.Parameter.empty:
+            param_info['type'] = str(param.annotation.__name__ if hasattr(param.annotation, '__name__') else param.annotation)
+            
+        if param.default != inspect.Parameter.empty:
+            param_info['default'] = param.default
+            
+        parameters.append(param_info)
+    
+    return {
+        'name': func._agnt5_handler_name,
+        'type': 'function',
+        'parameters': parameters,
+        'return_type': str(signature.return_annotation.__name__ if signature.return_annotation != inspect.Parameter.empty else 'any')
+    }
+
+
+# Alias for more intuitive usage
+handler = function
+
+
+def clear_registry():
+    """Clear the function registry. Mainly for testing."""
+    global _function_registry
+    _function_registry.clear()
+
+
+def invoke_function(handler_name: str, input_data: bytes, context: Any = None) -> bytes:
+    """
+    Invoke a registered function handler.
+    
+    Args:
+        handler_name: Name of the handler to invoke
+        input_data: Input data as bytes (will be decoded from JSON)
+        context: Execution context
+        
+    Returns:
+        Function result as bytes (JSON encoded)
+        
+    Raises:
+        ValueError: If handler is not found
+        RuntimeError: If function execution fails
+    """
+    import json
+    import traceback
+    
+    # Input validation
+    if not handler_name:
+        error_msg = "Empty handler name provided"
+        logger.error(error_msg)
+        raise ValueError(error_msg)
+    
+    if handler_name not in _function_registry:
+        error_msg = f"Handler '{handler_name}' not found in registry. Available handlers: {list(_function_registry.keys())}"
+        logger.error(error_msg)
+        raise ValueError(error_msg)
+    
+    func = _function_registry[handler_name]
+    logger.info(f"Invoking handler: {handler_name}")
+    
+    try:
+        # Decode input data
+        if input_data:
+            logger.debug(f"Processing {len(input_data)} bytes for {handler_name}")
+            
+            # Try direct JSON first
+            try:
+                raw_data = input_data.decode('utf-8')
+                input_params = json.loads(raw_data)
+                logger.info(f"Decoded JSON input for {handler_name}: {type(input_params)} with keys: {list(input_params.keys()) if isinstance(input_params, dict) else 'non-dict'}")
+                logger.debug(f"Input parameters: {input_params}")
+            except (UnicodeDecodeError, json.JSONDecodeError):
+                # Fallback to protobuf extraction
+                logger.debug(f"JSON decoding failed, trying protobuf extraction for {handler_name}")
+                start_idx = input_data.find(b'\x1a')
+                if start_idx == -1 or start_idx + 1 >= len(input_data):
+                    logger.error(f"Invalid data format for {handler_name}. Length: {len(input_data)}, Hex: {input_data.hex()}")
+                    raise RuntimeError("Invalid input data - not JSON and no protobuf marker found")
+                
+                json_length = input_data[start_idx + 1]
+                json_start = start_idx + 2
+                
+                if json_start + json_length > len(input_data):
+                    raise RuntimeError(f"Protobuf structure invalid - length {json_length} exceeds data")
+                
+                json_bytes = input_data[json_start:json_start + json_length]
+                raw_data = json_bytes.decode('utf-8')
+                input_params = json.loads(raw_data)
+                logger.info(f"Extracted from protobuf for {handler_name}: {type(input_params)} with keys: {list(input_params.keys()) if isinstance(input_params, dict) else 'non-dict'}")
+                logger.debug(f"Extracted parameters: {input_params}")
+                
+        else:
+            input_params = {}
+            logger.debug(f"No input data provided for {handler_name}")
+            
+        # Execute function
+        try:
+            sig = inspect.signature(func)
+            params = list(sig.parameters.keys())
+            
+            logger.info(f"Calling {handler_name} with signature: {sig}")
+            
+            if params and params[0] == 'ctx':
+                if isinstance(input_params, dict):
+                    logger.debug(f"Calling {handler_name}(ctx, **{input_params})")
+                    result = func(context, **input_params)
+                else:
+                    logger.debug(f"Calling {handler_name}(ctx, {input_params})")
+                    result = func(context, input_params)
+            else:
+                if isinstance(input_params, dict):
+                    logger.debug(f"Calling {handler_name}(**{input_params})")
+                    result = func(**input_params)
+                else:
+                    logger.debug(f"Calling {handler_name}({input_params})")
+                    result = func(input_params)
+                    
+        except TypeError as e:
+            logger.error(f"Signature mismatch in {handler_name}: {e}. Expected: {sig}, Got: {input_params}")
+            raise RuntimeError(f"Function signature mismatch: {e}")
+            
+        except Exception as e:
+            logger.error(f"Function {handler_name} failed: {type(e).__name__}: {e}")
+            raise RuntimeError(f"Function execution failed: {e}")
+            
+        # Encode result
+        if result is None:
+            return b""
+        
+        try:
+            result_json = json.dumps(result)
+            return result_json.encode('utf-8')
+        except (TypeError, ValueError, UnicodeEncodeError) as e:
+            logger.error(f"Cannot serialize/encode result from {handler_name}: {type(result)} - {e}")
+            raise RuntimeError(f"Result serialization/encoding error: {e}")
+        
+    except RuntimeError:
+        raise
+        
+    except Exception as e:
+        logger.error(f"Unexpected error in {handler_name}: {type(e).__name__}: {e}")
+        logger.debug(f"Stack trace: {traceback.format_exc()}")
+        raise RuntimeError(f"Unexpected error: {e}")

agnt5/logging.py

@@ -0,0 +1,140 @@
+"""
+OpenTelemetry logging integration for AGNT5 Python SDK.
+
+This module provides a logging handler that forwards Python logs to the Rust core
+for integration with OpenTelemetry. All logs are automatically correlated with 
+traces and sent to the OTLP collector.
+"""
+
+import logging
+import os
+from typing import Optional
+
+from ._compat import _rust_available
+
+if _rust_available:
+    from ._core import log_from_python
+
+
+class OpenTelemetryHandler(logging.Handler):
+    """
+    A logging handler that forwards Python logs to Rust for OpenTelemetry integration.
+    
+    This handler automatically captures all Python logs and forwards them to the
+    Rust core where they are integrated with OpenTelemetry tracing and sent to
+    the OTLP collector. Logs are automatically correlated with active traces.
+    """
+    
+    def __init__(self, level: int = logging.NOTSET):
+        super().__init__(level)
+        
+        if not _rust_available:
+            raise RuntimeError("OpenTelemetry logging handler requires Rust core")
+    
+    def emit(self, record: logging.LogRecord) -> None:
+        """
+        Forward a log record to Rust for OpenTelemetry integration.
+        
+        Args:
+            record: The Python log record to forward
+        """
+        try:
+            # Format the message
+            message = self.format(record)
+            
+            # Extract metadata for Rust
+            level = record.levelname
+            target = record.name  # Logger name (e.g., 'agnt5.worker')
+            module_path = getattr(record, 'module', record.name)
+            filename = getattr(record, 'pathname', None)
+            line = getattr(record, 'lineno', None)
+            
+            # Make filename relative if it's absolute
+            if filename and os.path.isabs(filename):
+                try:
+                    # Try to make it relative to current working directory
+                    filename = os.path.relpath(filename)
+                except ValueError:
+                    # If relpath fails (e.g., different drives on Windows), use basename
+                    filename = os.path.basename(filename)
+            
+            # Forward to Rust core - silently ignore if telemetry not ready yet
+            try:
+                log_from_python(
+                    level=level,
+                    message=message,
+                    target=target,
+                    module_path=module_path,
+                    filename=filename,
+                    line=line
+                )
+            except Exception:
+                # Silently ignore if Rust telemetry system not ready yet
+                # This handles the timing issue during startup
+                pass
+            
+        except Exception as e:
+            # Don't let logging errors crash the application
+            # Use handleError to maintain Python logging standards
+            self.handleError(record)
+
+
+def install_opentelemetry_logging(
+    logger: Optional[logging.Logger] = None,
+    level: int = logging.INFO,
+    format_string: Optional[str] = None
+) -> OpenTelemetryHandler:
+    """
+    Install OpenTelemetry logging handler on a logger.
+    
+    Args:
+        logger: Logger to install handler on. If None, uses root logger.
+        level: Minimum log level to forward to OpenTelemetry
+        format_string: Optional format string for log messages
+        
+    Returns:
+        The installed OpenTelemetryHandler instance
+        
+    Example:
+        # Install on root logger (captures all logs)
+        install_opentelemetry_logging()
+        
+        # Install on specific logger
+        logger = logging.getLogger('my_app')
+        install_opentelemetry_logging(logger, level=logging.DEBUG)
+    """
+    if logger is None:
+        logger = logging.getLogger()
+    
+    # Create handler
+    handler = OpenTelemetryHandler(level=level)
+    
+    # Set formatter if provided
+    if format_string:
+        formatter = logging.Formatter(format_string)
+        handler.setFormatter(formatter)
+    
+    # Install handler
+    logger.addHandler(handler)
+    
+    return handler
+
+
+def remove_opentelemetry_logging(logger: Optional[logging.Logger] = None) -> None:
+    """
+    Remove OpenTelemetry logging handlers from a logger.
+    
+    Args:
+        logger: Logger to remove handlers from. If None, uses root logger.
+    """
+    if logger is None:
+        logger = logging.getLogger()
+    
+    # Remove all OpenTelemetryHandler instances
+    handlers_to_remove = [
+        handler for handler in logger.handlers 
+        if isinstance(handler, OpenTelemetryHandler)
+    ]
+    
+    for handler in handlers_to_remove:
+        logger.removeHandler(handler)