agent-runtime-core 0.5.1__py3-none-any.whl → 0.6.0__py3-none-any.whl

agent_runtime_core/__init__.py

@@ -34,7 +34,7 @@ Example usage:
             return RunResult(final_output={"message": "Hello!"})
 """
 
-__version__ = "0.5.1"
+__version__ = "0.6.0"
 
 # Core interfaces
 from agent_runtime_core.interfaces import (
@@ -53,6 +53,10 @@ from agent_runtime_core.interfaces import (
     TraceSink,
 )
 
+
+# Tool Calling Agent base class
+from agent_runtime_core.tool_calling_agent import ToolCallingAgent
+
 # Configuration
 from agent_runtime_core.config import (
     RuntimeConfig,
@@ -142,6 +146,7 @@ __all__ = [
     "TraceSink",
     "EventType",
     "ErrorInfo",
+        "ToolCallingAgent",
     # Configuration
     "RuntimeConfig",
     "configure",

agent_runtime_core/interfaces.py

@@ -303,6 +303,50 @@ class ToolRegistry:
             raise KeyError(f"Tool not found: {name}")
         return await tool.handler(**arguments)
 
+    async def execute_with_events(
+        self,
+        tool_call: Any,  # ToolCall object with name, arguments, id
+        ctx: "RunContext",
+        **kwargs
+    ) -> Any:
+        """
+        Execute a tool and automatically emit events.
+        
+        This is a convenience method that wraps execute() and handles
+        event emission automatically. Use this in your agent loop to
+        reduce boilerplate.
+        
+        Args:
+            tool_call: Tool call object with name, arguments, and id
+            ctx: Run context for emitting events
+            **kwargs: Additional arguments to pass to the tool
+        
+        Returns:
+            Tool result
+        
+        Example:
+            for tool_call in response.tool_calls:
+                result = await tools.execute_with_events(tool_call, ctx)
+        """
+        # Emit tool call event
+        await ctx.emit(EventType.TOOL_CALL, {
+            "tool_name": tool_call.name,
+            "tool_args": tool_call.arguments,
+            "tool_call_id": tool_call.id,
+        })
+        
+        # Execute the tool
+        result = await self.execute(tool_call.name, tool_call.arguments, **kwargs)
+        
+        # Emit tool result event
+        await ctx.emit(EventType.TOOL_RESULT, {
+            "tool_name": tool_call.name,
+            "tool_call_id": tool_call.id,
+            "result": result,
+        })
+        
+        return result
+
 
 class LLMClient(ABC):
     """

agent_runtime_core/registry.py

@@ -3,72 +3,151 @@ Agent runtime registry.
 
 Provides a global registry for agent runtimes, allowing them to be
 looked up by key.
+
+Supports:
+- Manual registration via register_runtime()
+- Factory functions for lazy instantiation
+- Class registration (auto-instantiation)
 """
 
-from typing import Optional
+import logging
+from typing import Callable, Optional, Type, Union
 
 from agent_runtime_core.interfaces import AgentRuntime
 
+logger = logging.getLogger(__name__)
 
 # Global registry
 _runtimes: dict[str, AgentRuntime] = {}
+_runtime_factories: dict[str, Callable[[], AgentRuntime]] = {}
+
+
+def _is_agent_runtime(obj) -> bool:
+    """Check if an object is an AgentRuntime instance."""
+    return isinstance(obj, AgentRuntime)
+
 
+def _is_agent_runtime_class(cls) -> bool:
+    """Check if a class is an AgentRuntime subclass."""
+    if not isinstance(cls, type):
+        return False
+    try:
+        return issubclass(cls, AgentRuntime)
+    except TypeError:
+        return False
 
-def register_runtime(runtime: AgentRuntime) -> None:
+
+def register_runtime(
+    runtime: Union[AgentRuntime, Type[AgentRuntime], Callable[[], AgentRuntime]],
+    key: Optional[str] = None,
+) -> None:
     """
     Register an agent runtime.
-    
+
     Args:
-        runtime: The runtime to register
-        
+        runtime: Runtime instance, class, or factory function
+        key: Optional key override (uses runtime.key if not provided)
+
+    Examples:
+        # Register an instance
+        register_runtime(MyRuntime())
+
+        # Register a class (will be instantiated)
+        register_runtime(MyRuntime)
+
+        # Register with custom key
+        register_runtime(MyRuntime(), key="custom-key")
+
+        # Register a factory
+        register_runtime(lambda: MyRuntime(config=get_config()), key="my-runtime")
+
     Raises:
-        ValueError: If a runtime with the same key is already registered
+        ValueError: If key is required but not provided
+        TypeError: If runtime is not a valid type
     """
-    key = runtime.key
-    if key in _runtimes:
-        raise ValueError(f"Runtime already registered: {key}")
-    _runtimes[key] = runtime
+    if _is_agent_runtime(runtime):
+        # Instance provided
+        runtime_key = key or runtime.key
+        _runtimes[runtime_key] = runtime
+        logger.info(f"Registered agent runtime: {runtime_key}")
+
+    elif _is_agent_runtime_class(runtime):
+        # Class provided - instantiate it
+        instance = runtime()
+        runtime_key = key or instance.key
+        _runtimes[runtime_key] = instance
+        logger.info(f"Registered agent runtime: {runtime_key}")
 
+    elif callable(runtime):
+        # Factory function provided
+        if not key:
+            raise ValueError("key is required when registering a factory function")
+        _runtime_factories[key] = runtime
+        logger.info(f"Registered agent runtime factory: {key}")
 
-def get_runtime(key: str) -> Optional[AgentRuntime]:
+    else:
+        raise TypeError(
+            f"runtime must be AgentRuntime instance, class, or callable, got {type(runtime)}"
+        )
+
+
+def get_runtime(key: str) -> AgentRuntime:
     """
     Get a registered runtime by key.
-    
+
     Args:
         key: The runtime key
-        
+
     Returns:
-        The runtime, or None if not found
+        The runtime instance
+
+    Raises:
+        KeyError: If runtime not found
     """
-    return _runtimes.get(key)
+    # Check instances first
+    if key in _runtimes:
+        return _runtimes[key]
+
+    # Check factories
+    if key in _runtime_factories:
+        instance = _runtime_factories[key]()
+        _runtimes[key] = instance
+        return instance
+
+    raise KeyError(f"Agent runtime not found: {key}. Available: {list_runtimes()}")
 
 
 def list_runtimes() -> list[str]:
     """
     List all registered runtime keys.
-    
+
     Returns:
         List of runtime keys
     """
-    return list(_runtimes.keys())
+    return list(set(_runtimes.keys()) | set(_runtime_factories.keys()))
 
 
 def unregister_runtime(key: str) -> bool:
     """
     Unregister a runtime.
-    
+
     Args:
         key: The runtime key
-        
+
     Returns:
         True if unregistered, False if not found
     """
+    removed = False
     if key in _runtimes:
         del _runtimes[key]
-        return True
-    return False
+        removed = True
+    if key in _runtime_factories:
+        del _runtime_factories[key]
+        removed = True
+    return removed
 
 
 def clear_registry() -> None:
     """Clear all registered runtimes. Useful for testing."""
     _runtimes.clear()
+    _runtime_factories.clear()

agent_runtime_core/tool_calling_agent.py

@@ -0,0 +1,256 @@
+"""
+ToolCallingAgent - A base class for agents that use tool calling.
+
+This eliminates the boilerplate of implementing the tool-calling loop
+in every agent. Just define your system prompt and tools, and the base
+class handles the rest.
+"""
+
+import json
+import logging
+from abc import abstractmethod
+from typing import Optional
+
+from agent_runtime_core.interfaces import (
+    AgentRuntime,
+    RunContext,
+    RunResult,
+    EventType,
+    ToolRegistry,
+    LLMClient,
+)
+
+logger = logging.getLogger(__name__)
+
+
+class ToolCallingAgent(AgentRuntime):
+    """
+    Base class for agents that use tool calling.
+    
+    Handles the standard tool-calling loop so you don't have to implement it
+    in every agent. Just override the abstract properties and you're done.
+    
+    Example:
+        class MyAgent(ToolCallingAgent):
+            @property
+            def key(self) -> str:
+                return "my-agent"
+            
+            @property
+            def system_prompt(self) -> str:
+                return "You are a helpful assistant..."
+            
+            @property
+            def tools(self) -> ToolRegistry:
+                return create_my_tools()
+    """
+    
+    @property
+    @abstractmethod
+    def system_prompt(self) -> str:
+        """
+        System prompt for the agent.
+        
+        This is prepended to the conversation messages.
+        """
+        ...
+    
+    @property
+    @abstractmethod
+    def tools(self) -> ToolRegistry:
+        """
+        Tools available to the agent.
+        
+        Return a ToolRegistry with all tools registered.
+        """
+        ...
+    
+    @property
+    def max_iterations(self) -> int:
+        """
+        Maximum number of tool-calling iterations.
+        
+        Override to change the default limit.
+        """
+        return 10
+    
+    @property
+    def model(self) -> Optional[str]:
+        """
+        Model to use for this agent.
+        
+        If None, uses the default model from configuration.
+        Override to use a specific model.
+        """
+        return None
+    
+    @property
+    def temperature(self) -> Optional[float]:
+        """
+        Temperature for LLM generation.
+        
+        If None, uses the LLM client's default.
+        Override to set a specific temperature.
+        """
+        return None
+    
+    def get_llm_client(self) -> LLMClient:
+        """
+        Get the LLM client to use.
+        
+        Override to customize LLM client selection.
+        Default uses the configured client.
+        """
+        from agent_runtime_core.llm import get_llm_client
+        return get_llm_client()
+    
+    async def before_run(self, ctx: RunContext) -> None:
+        """
+        Hook called before the agent run starts.
+        
+        Override to add custom initialization logic.
+        """
+        pass
+    
+    async def after_run(self, ctx: RunContext, result: RunResult) -> RunResult:
+        """
+        Hook called after the agent run completes.
+        
+        Override to add custom finalization logic.
+        Can modify the result before returning.
+        """
+        return result
+    
+    async def on_tool_call(self, ctx: RunContext, tool_name: str, tool_args: dict) -> None:
+        """
+        Hook called before each tool execution.
+        
+        Override to add custom logic (logging, validation, etc.).
+        """
+        pass
+    
+    async def on_tool_result(self, ctx: RunContext, tool_name: str, result: any) -> any:
+        """
+        Hook called after each tool execution.
+        
+        Override to transform or validate tool results.
+        Can return a modified result.
+        """
+        return result
+    
+    async def run(self, ctx: RunContext) -> RunResult:
+        """
+        Execute the agent with tool calling support.
+        
+        This implements the standard tool-calling loop:
+        1. Build messages with system prompt
+        2. Call LLM with tools
+        3. If tool calls, execute them and loop
+        4. If no tool calls, return final response
+        """
+        logger.info(f"[{self.key}] Starting run, input messages: {len(ctx.input_messages)}")
+        
+        # Call before_run hook
+        await self.before_run(ctx)
+        
+        # Get LLM client
+        llm = self.get_llm_client()
+        
+        # Build messages with system prompt
+        messages = [
+            {"role": "system", "content": self.system_prompt}
+        ] + ctx.input_messages
+        
+        logger.info(f"[{self.key}] Built {len(messages)} messages (including system prompt)")
+        
+        # Run the agent loop (tool calling)
+        iteration = 0
+        final_response = None
+        
+        while iteration < self.max_iterations:
+            iteration += 1
+            logger.info(f"[{self.key}] Iteration {iteration}/{self.max_iterations}")
+            
+            # Generate response with tools
+            logger.info(f"[{self.key}] Calling LLM...")
+            response = await llm.generate(
+                messages=messages,
+                tools=self.tools.to_openai_format(),
+                model=self.model,
+                temperature=self.temperature,
+            )
+            logger.info(f"[{self.key}] LLM response received, tool_calls: {bool(response.message.get('tool_calls'))}")
+            
+            # Check if the model wants to call tools
+            if response.message.get('tool_calls'):
+                # Add the assistant message with tool calls
+                messages.append(response.message)
+                
+                # Execute the tools
+                tool_results = []
+                for tool_call in response.message.get('tool_calls'):
+                    # Emit tool call event
+                    await ctx.emit(EventType.TOOL_CALL, {
+                        "tool_name": tool_call["function"]["name"],
+                        "tool_args": json.loads(tool_call["function"]["arguments"]),
+                        "tool_call_id": tool_call["id"],
+                    })
+                    
+                    # Call before_tool_call hook
+                    await self.on_tool_call(ctx, tool_call["function"]["name"], json.loads(tool_call["function"]["arguments"]))
+                    
+                    # Execute the tool
+                    result = await self.tools.execute(
+                        tool_call["function"]["name"],
+                        json.loads(tool_call["function"]["arguments"]),
+                    )
+                    
+                    # Call after_tool_result hook
+                    result = await self.on_tool_result(ctx, tool_call["function"]["name"], result)
+                    
+                    tool_results.append({
+                        "tool_call_id": tool_call["id"],
+                        "result": result,
+                    })
+                    
+                    # Emit tool result event
+                    await ctx.emit(EventType.TOOL_RESULT, {
+                        "tool_name": tool_call["function"]["name"],
+                        "tool_call_id": tool_call["id"],
+                        "result": result,
+                    })
+                
+                # Add tool results to messages
+                for tr in tool_results:
+                    messages.append({
+                        "role": "tool",
+                        "tool_call_id": tr["tool_call_id"],
+                        "content": str(tr["result"]),
+                    })
+            else:
+                # No tool calls - we have the final response
+                final_response = response.message["content"]
+                logger.info(f"[{self.key}] Final response received: {final_response[:100] if final_response else 'None'}...")
+                break
+        
+        # Emit the final assistant message
+        if final_response:
+            logger.info(f"[{self.key}] Emitting ASSISTANT_MESSAGE event")
+            await ctx.emit(EventType.ASSISTANT_MESSAGE, {
+                "content": final_response,
+            })
+            logger.info(f"[{self.key}] Event emitted successfully")
+        else:
+            logger.warning(f"[{self.key}] No final response to emit!")
+        
+        logger.info(f"[{self.key}] Returning RunResult")
+        result = RunResult(
+            final_output={"response": final_response},
+            final_messages=messages,
+            usage=response.usage if response else {},
+        )
+        
+        # Call after_run hook
+        result = await self.after_run(ctx, result)
+        
+        return result

{agent_runtime_core-0.5.1.dist-info → agent_runtime_core-0.6.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agent-runtime-core
-Version: 0.5.1
+Version: 0.6.0
 Summary: Framework-agnostic Python library for executing AI agents with consistent patterns
 Project-URL: Homepage, https://github.com/makemore/agent-runtime-core
 Project-URL: Repository, https://github.com/makemore/agent-runtime-core
@@ -49,8 +49,16 @@ Description-Content-Type: text/markdown
 
 A lightweight, framework-agnostic Python library for building AI agent systems. Provides the core abstractions and implementations needed to build production-ready AI agents without tying you to any specific framework.
 
-## Features
+## Recent Updates
+
+| Version | Date | Changes |
+|---------|------|---------|
+| **0.6.0** | 2025-01-23 | Enhanced registry with factory functions and class registration |
+| **0.5.2** | 2025-01-14 | Add ToolCallingAgent base class, execute_with_events helper |
+| **0.5.1** | 2025-01-13 | Bug fixes and improvements |
+| **0.5.0** | 2025-01-12 | Initial stable release |
 
+## Features
 - 🔌 **Framework Agnostic** - Works with LangGraph, CrewAI, OpenAI Agents, or your own custom loops
 - 🤖 **Model Agnostic** - OpenAI, Anthropic, or any provider via LiteLLM
 - 📦 **Zero Required Dependencies** - Core library has no dependencies; add only what you need

{agent_runtime_core-0.5.1.dist-info → agent_runtime_core-0.6.0.dist-info}/RECORD

@@ -1,10 +1,11 @@
-agent_runtime_core/__init__.py,sha256=9Aen5YoHmemdCHBhGIsKINMalFr-_QkkeGs6bXlWSKU,4010
+agent_runtime_core/__init__.py,sha256=qPJb-oJ424TMygK4OxUpLqoOu8e4I68MWok1ufxOAzQ,4139
 agent_runtime_core/config.py,sha256=e3_uB5brAuQcWU36sOhWF9R6RoJrngtCS-xEB3n2fas,4986
-agent_runtime_core/interfaces.py,sha256=V3CAt8otNMF4Wdo5xJ9DyScL0iYcmQ90U0weadMQsw0,10777
-agent_runtime_core/registry.py,sha256=hrbEdNNdqEz7-uN-82qofsXFTZBRDxZ2Ht9qwmp1qkw,1476
+agent_runtime_core/interfaces.py,sha256=T74pgS229tvarQD-_o25oflylUR7jq_jbgUjnvVs6IA,12191
+agent_runtime_core/registry.py,sha256=QmazCAcHTsPt236Z_xEBJjdppm6jUuufE-gfvcGMUCk,3959
 agent_runtime_core/runner.py,sha256=M3It72UhfmLt17jVnSvObiSfQ1_RN4JVUIJsjnRd2Ps,12771
 agent_runtime_core/steps.py,sha256=XpVFK7P-ZOpr7NwaP7XFygduIpjrKld-OIig7dHNMKE,11994
 agent_runtime_core/testing.py,sha256=ordECGprBappLBMWxlETvuf2AoIPNomJFeSedXaY30E,11131
+agent_runtime_core/tool_calling_agent.py,sha256=LY0lSI9GZbWoIKd-7NXFSvByAhvK6L625eOp01VbTrw,8525
 agent_runtime_core/events/__init__.py,sha256=Gg7cMQHWfLTQ4Xik09KSg7cWbQDmW_MuF5_jl-yZkHU,1575
 agent_runtime_core/events/base.py,sha256=NfHYyoczxr40Er5emROi_aY_07m5hDrKsn31pdWY2DY,1950
 agent_runtime_core/events/memory.py,sha256=9z4tY8XB8xDg3ybHsIwilOcRo7HY-vB-8vxiz6O54BE,2491
@@ -31,7 +32,7 @@ agent_runtime_core/state/sqlite.py,sha256=HKZwDiC_7F1W8Z_Pz8roEs91XhQ9rUHfGpuQ7W
 agent_runtime_core/tracing/__init__.py,sha256=u1QicGc39e30gWyQD4cQWxGGjITnkwoOPUhNrG6aNyI,1266
 agent_runtime_core/tracing/langfuse.py,sha256=Rj2sUlatk5sFro0y68tw5X6fQcSwWxcBOSOjB0F7JTU,3660
 agent_runtime_core/tracing/noop.py,sha256=SpsbpsUcNG6C3xZG3uyiNPUHY8etloISx3w56Q8D3KE,751
-agent_runtime_core-0.5.1.dist-info/METADATA,sha256=Y-ZOcumIFWdrqBWlV4QIvx5xyPaJGFnhUXtLtnqHjc4,23491
-agent_runtime_core-0.5.1.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
-agent_runtime_core-0.5.1.dist-info/licenses/LICENSE,sha256=fDlWep3_mUrj8KHV_jk275tHVEW7_9sJRhkNuGCZ_TA,1068
-agent_runtime_core-0.5.1.dist-info/RECORD,,
+agent_runtime_core-0.6.0.dist-info/METADATA,sha256=Q9egtbhBSMcgmeA9TM4gy_8P5pUcN0WFMCNaAOii12w,23858
+agent_runtime_core-0.6.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+agent_runtime_core-0.6.0.dist-info/licenses/LICENSE,sha256=fDlWep3_mUrj8KHV_jk275tHVEW7_9sJRhkNuGCZ_TA,1068
+agent_runtime_core-0.6.0.dist-info/RECORD,,