agnt5 0.2.0__cp39-abi3-manylinux_2_34_aarch64.whl → 0.2.1__cp39-abi3-manylinux_2_34_aarch64.whl

agnt5/__init__.py

@@ -6,9 +6,19 @@ with built-in durability guarantees and state management.
 """
 
 from ._compat import _import_error, _rust_available
-from .agent import Agent, AgentResult
+from .agent import Agent, AgentRegistry, AgentResult, agent
+from .client import Client, RunError
 from .context import Context
-from .entity import EntityInstance, EntityType, entity
+from .entity import (
+    DurableEntity,
+    SessionEntity,
+    MemoryEntity,
+    WorkflowEntity,
+    EntityInstance,
+    EntityRegistry,
+    EntityType,
+    entity,
+)
 from .exceptions import (
     AGNT5Error,
     CheckpointError,
@@ -24,6 +34,9 @@ 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__ = [
@@ -31,19 +44,27 @@ __all__ = [
     "__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",
-    "Worker",
     # Types
     "RetryPolicy",
     "BackoffPolicy",
@@ -57,4 +78,7 @@ __all__ = [
     "RetryError",
     "StateError",
     "CheckpointError",
+    "RunError",
+    # Language Model (Simplified API)
+    "lm",
 ]

agnt5/_telemetry.py

@@ -0,0 +1,141 @@
+"""
+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
+
+        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

agnt5/agent.py

@@ -6,15 +6,49 @@ Phase 2: Platform-backed agents with durable execution and multi-agent coordinat
 
 from __future__ import annotations
 
+import functools
 import json
 import logging
-from typing import Any, Dict, List, Optional
+from typing import Any, Callable, Dict, List, Optional
 
 from .context import Context
-from .lm import GenerateRequest, GenerateResponse, LanguageModel, Message, ToolDefinition
+from . import lm
+from .lm import GenerateRequest, GenerateResponse, Message, ModelConfig, ToolDefinition
 from .tool import Tool, ToolRegistry
+from ._telemetry import setup_module_logger
 
-logger = logging.getLogger(__name__)
+logger = setup_module_logger(__name__)
+
+# Global agent registry
+_AGENT_REGISTRY: Dict[str, "Agent"] = {}
+
+
+class AgentRegistry:
+    """Registry for agents."""
+
+    @staticmethod
+    def register(agent: "Agent") -> None:
+        """Register an agent."""
+        if agent.name in _AGENT_REGISTRY:
+            logger.warning(f"Overwriting existing agent '{agent.name}'")
+        _AGENT_REGISTRY[agent.name] = agent
+        logger.debug(f"Registered agent '{agent.name}'")
+
+    @staticmethod
+    def get(name: str) -> Optional["Agent"]:
+        """Get agent by name."""
+        return _AGENT_REGISTRY.get(name)
+
+    @staticmethod
+    def all() -> Dict[str, "Agent"]:
+        """Get all registered agents."""
+        return _AGENT_REGISTRY.copy()
+
+    @staticmethod
+    def clear() -> None:
+        """Clear all registered agents."""
+        _AGENT_REGISTRY.clear()
+        logger.debug("Cleared agent registry")
 
 
 class AgentResult:
@@ -43,20 +77,20 @@ class Agent:
 
     Example:
         ```python
-        from agnt5 import Agent, tool
-        from agnt5.lm import OpenAILanguageModel
+        from agnt5 import Agent, tool, Context
 
         @tool(auto_schema=True)
         async def search_web(ctx: Context, query: str) -> List[Dict]:
             # Search implementation
             return [{"title": "Result", "url": "..."}]
 
-        lm = OpenAILanguageModel()
+        # Simple usage with model string
         agent = Agent(
             name="researcher",
-            model=lm,
+            model="openai/gpt-4o-mini",
             instructions="You are a research assistant.",
-            tools=[search_web]
+            tools=[search_web],
+            temperature=0.7
         )
 
         result = await agent.run("What are the latest AI trends?")
@@ -67,29 +101,35 @@ class Agent:
     def __init__(
         self,
         name: str,
-        model: LanguageModel,
+        model: str,
         instructions: str,
         tools: Optional[List[Any]] = None,
-        model_name: str = "gpt-4o-mini",
         temperature: float = 0.7,
+        max_tokens: Optional[int] = None,
+        top_p: Optional[float] = None,
+        model_config: Optional[ModelConfig] = None,
         max_iterations: int = 10,
     ):
         """Initialize agent.
 
         Args:
             name: Agent name/identifier
-            model: Language model instance
+            model: Model string with provider prefix (e.g., "openai/gpt-4o-mini")
             instructions: System instructions for the agent
             tools: List of tools available to the agent (functions with @tool decorator)
-            model_name: Model name to use (e.g., "gpt-4", "claude-3-opus")
             temperature: LLM temperature (0.0 to 1.0)
+            max_tokens: Maximum tokens to generate
+            top_p: Nucleus sampling parameter
+            model_config: Optional advanced configuration (custom endpoints, headers, etc.)
             max_iterations: Maximum reasoning iterations
         """
         self.name = name
         self.model = model
         self.instructions = instructions
-        self.model_name = model_name
         self.temperature = temperature
+        self.max_tokens = max_tokens
+        self.top_p = top_p
+        self.model_config = model_config
         self.max_iterations = max_iterations
 
         # Build tool registry
@@ -116,6 +156,33 @@ class Agent:
 
         self.logger = logging.getLogger(f"agnt5.agent.{name}")
 
+        # Define schemas based on the run method signature
+        # Input: user_message (string)
+        self.input_schema = {
+            "type": "object",
+            "properties": {
+                "user_message": {"type": "string"}
+            },
+            "required": ["user_message"]
+        }
+        # Output: AgentResult with output and tool_calls
+        self.output_schema = {
+            "type": "object",
+            "properties": {
+                "output": {"type": "string"},
+                "tool_calls": {
+                    "type": "array",
+                    "items": {"type": "object"}
+                }
+            }
+        }
+
+        # Store metadata
+        self.metadata = {
+            "description": instructions,
+            "model": model_name
+        }
+
     async def run(
         self,
         user_message: str,
@@ -163,17 +230,34 @@ class Agent:
                 for tool in self.tools.values()
             ]
 
-            # Create LLM request
+            # Convert messages to dict format for lm.generate()
+            messages_dict = []
+            for msg in messages:
+                messages_dict.append({
+                    "role": msg.role.value,
+                    "content": msg.content
+                })
+
+            # Call LLM using simplified API
+            # TODO: Support tools in lm.generate() - for now using GenerateRequest internally
             request = GenerateRequest(
-                model=self.model_name,
+                model=self.model,
                 system_prompt=self.instructions,
                 messages=messages,
                 tools=tool_defs if tool_defs else [],
             )
             request.config.temperature = self.temperature
-
-            # Call LLM
-            response = await self.model.generate(request)
+            if self.max_tokens:
+                request.config.max_tokens = self.max_tokens
+            if self.top_p:
+                request.config.top_p = self.top_p
+
+            # Create internal LM instance for generation
+            # TODO: Use model_config when provided
+            from .lm import _LanguageModel
+            provider, model_name = self.model.split('/', 1)
+            internal_lm = _LanguageModel(provider=provider.lower(), default_model=None)
+            response = await internal_lm.generate(request)
 
             # Add assistant response to messages
             messages.append(Message.assistant(response.text))
@@ -288,16 +372,124 @@ class Agent:
 
         # Build request (no tools for simple chat)
         request = GenerateRequest(
-            model=self.model_name,
+            model=self.model,
             system_prompt=self.instructions,
             messages=conversation,
         )
         request.config.temperature = self.temperature
+        if self.max_tokens:
+            request.config.max_tokens = self.max_tokens
+        if self.top_p:
+            request.config.top_p = self.top_p
 
-        # Call LLM
-        response = await self.model.generate(request)
+        # Create internal LM instance for generation
+        from .lm import _LanguageModel
+        provider, model_name = self.model.split('/', 1)
+        internal_lm = _LanguageModel(provider=provider.lower(), default_model=None)
+        response = await internal_lm.generate(request)
 
         # Add assistant response
         conversation.append(Message.assistant(response.text))
 
         return response.text, conversation
+
+
+def agent(
+    _func: Optional[Callable] = None,
+    *,
+    name: Optional[str] = None,
+    model: Optional[LanguageModel] = None,
+    instructions: Optional[str] = None,
+    tools: Optional[List[Any]] = None,
+    model_name: str = "gpt-4o-mini",
+    temperature: float = 0.7,
+    max_iterations: int = 10,
+) -> Callable:
+    """
+    Decorator to register a function as an agent and automatically register it.
+
+    This decorator allows you to define agents as functions that create and return Agent instances.
+    The agent will be automatically registered in the AgentRegistry for discovery by the worker.
+
+    Args:
+        name: Agent name (defaults to function name)
+        model: Language model instance (required if not provided in function)
+        instructions: System instructions (required if not provided in function)
+        tools: List of tools available to the agent
+        model_name: Model name to use
+        temperature: LLM temperature
+        max_iterations: Maximum reasoning iterations
+
+    Returns:
+        Decorated function that returns an Agent instance
+
+    Example:
+        ```python
+        from agnt5 import agent, tool
+        from agnt5.lm import OpenAILanguageModel
+
+        @agent(
+            name="research_agent",
+            model=OpenAILanguageModel(),
+            instructions="You are a research assistant.",
+            tools=[search_web, analyze_data]
+        )
+        def create_researcher():
+            # Agent is created and registered automatically
+            pass
+
+        # Or create agent directly
+        @agent
+        def my_agent():
+            from agnt5.lm import OpenAILanguageModel
+            return Agent(
+                name="my_agent",
+                model=OpenAILanguageModel(),
+                instructions="You are a helpful assistant."
+            )
+        ```
+    """
+
+    def decorator(func: Callable) -> Callable:
+        # Determine agent name
+        agent_name = name or func.__name__
+
+        # Create the agent
+        @functools.wraps(func)
+        def wrapper(*args, **kwargs) -> Agent:
+            # Check if function returns an Agent
+            result = func(*args, **kwargs)
+            if isinstance(result, Agent):
+                # Function creates its own agent
+                agent_instance = result
+            elif model is not None and instructions is not None:
+                # Create agent from decorator parameters
+                agent_instance = Agent(
+                    name=agent_name,
+                    model=model,
+                    instructions=instructions,
+                    tools=tools,
+                    model_name=model_name,
+                    temperature=temperature,
+                    max_iterations=max_iterations,
+                )
+            else:
+                raise ValueError(
+                    f"Agent decorator for '{agent_name}' requires either "
+                    "the decorated function to return an Agent instance, "
+                    "or 'model' and 'instructions' parameters to be provided"
+                )
+
+            # Register agent
+            AgentRegistry.register(agent_instance)
+            return agent_instance
+
+        # Create agent immediately and store reference
+        agent_instance = wrapper()
+
+        # Return the agent instance itself (so it can be used directly)
+        return agent_instance
+
+    if _func is None:
+        return decorator
+    return decorator(_func)