agnt5 0.1.1__cp39-abi3-manylinux_2_34_aarch64.whl → 0.1.3__cp39-abi3-manylinux_2_34_aarch64.whl

agnt5/__init__.py

@@ -7,21 +7,17 @@ Rust core.
 """
 
 from .version import _get_version
-# Import compatibility checks
 from ._compat import _rust_available, _import_error
-
-# Import decorators
 from .decorators import function
-
-# Import high-level Worker
-from .worker_manager import Worker
+from .worker import Worker
+from .logging import install_opentelemetry_logging, remove_opentelemetry_logging
 
 __version__ = _get_version()
 
-
-# Import the Rust core if available
-if _rust_available:
-    from ._core import (
-        PyWorker
-    )
-
+__all__ = [
+    'function',
+    'Worker',
+    'install_opentelemetry_logging',
+    'remove_opentelemetry_logging',
+    '__version__',
+]

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

@@ -10,6 +10,8 @@ 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
@@ -82,9 +84,10 @@ def get_function_metadata(func: Callable) -> Optional[Dict[str, Any]]:
         
     signature = inspect.signature(func)
     parameters = []
+    param_items = list(signature.parameters.items())
     
-    for param_name, param in signature.parameters.items():
-        if param_name == 'ctx':  # Skip context parameter
+    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 = {
@@ -109,6 +112,10 @@ def get_function_metadata(func: Callable) -> Optional[Dict[str, Any]]:
     }
 
 
+# Alias for more intuitive usage
+handler = function
+
+
 def clear_registry():
     """Clear the function registry. Mainly for testing."""
     global _function_registry
@@ -132,67 +139,102 @@ def invoke_function(handler_name: str, input_data: bytes, context: Any = None) -
         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:
-        raise ValueError(f"Handler '{handler_name}' not found")
+        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:
-            print(f"📨 Received function invocation: {handler_name}")
+            logger.debug(f"Processing {len(input_data)} bytes for {handler_name}")
             
-            # Check if this is protobuf data by looking for the pattern
+            # 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):
-                # This is protobuf data - extract the JSON payload
-                # The JSON is embedded after the \x1a<length> pattern
+                # 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 and start_idx + 1 < len(input_data):
-                    # The byte after \x1a indicates the length of the JSON data
-                    json_length = input_data[start_idx + 1]
-                    json_start = start_idx + 2
-                    
-                    if json_start + json_length <= len(input_data):
-                        json_bytes = input_data[json_start:json_start + json_length]
-                        raw_data = json_bytes.decode('utf-8')
-                        print(f"📋 Extracted JSON from protobuf: {raw_data}")
-                        input_params = json.loads(raw_data)
-                    else:
-                        raise ValueError("Invalid protobuf structure - JSON length exceeds available data")
-                else:
-                    raise ValueError("Could not find JSON data in protobuf message")
+                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}")
             
-        logger.debug(f"Invoking function {handler_name} with params: {input_params}")
-        
-        # Call function with context as first parameter
-        if isinstance(input_params, dict):
-            result = func(context, **input_params)
-        else:
-            # Handle case where input is not a dict (e.g., single value)
-            result = func(context, input_params)
+        # 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:
-            result_data = b""
-        else:
+            return b""
+        
+        try:
             result_json = json.dumps(result)
-            result_data = result_json.encode('utf-8')
-            
-        logger.debug(f"Function {handler_name} completed successfully")
-        return result_data
+            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 json.JSONDecodeError as e:
-        print(f"❌ JSON parsing failed: {e}")
-        print(f"📋 Failed to parse: {repr(raw_data if 'raw_data' in locals() else 'No raw_data available')}")
-        logger.error(f"JSON decode error for {handler_name}: {e}")
-        raise RuntimeError(f"Invalid JSON input: {e}")
     except Exception as e:
-        print(f"❌ Function '{handler_name}' failed: {type(e).__name__}: {e}")
-        logger.error(f"Function {handler_name} failed: {e}")
-        raise RuntimeError(f"Function execution failed: {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)

agnt5/runtimes/__init__.py

@@ -0,0 +1,13 @@
+"""
+Runtime adapters for different execution environments.
+"""
+
+from .base import RuntimeAdapter
+from .worker import WorkerRuntime
+from .asgi import ASGIRuntime
+
+__all__ = [
+    'RuntimeAdapter',
+    'WorkerRuntime', 
+    'ASGIRuntime',
+]