tactus 0.31.0__py3-none-any.whl

tactus/primitives/handles.py

@@ -0,0 +1,378 @@
+"""
+DSL Handles - Lightweight placeholders returned by DSL declarations.
+
+These handles are created during DSL parsing (before actual primitives exist)
+and get connected to their real implementations at runtime via _enhance_handles().
+
+Usage:
+    # During parsing:
+    Greeter = agent "greeter" { config }  # Returns AgentHandle("greeter")
+
+    # During execution (callable syntax - preferred):
+    Greeter()                             # Direct call
+    Greeter({message = "Hello"})          # Call with options
+
+    # Lookup syntax also works:
+    Agent("greeter")()                    # Lookup + call
+"""
+
+import logging
+from typing import Any, Optional, Dict, TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from tactus.dspy.agent import DSPyAgentHandle
+    from tactus.primitives.model import ModelPrimitive
+
+logger = logging.getLogger(__name__)
+
+
+def _convert_lua_table(lua_table):
+    """
+    Convert a lupa Lua table to a Python dict or list.
+
+    Used to convert opts passed from Lua to Python methods.
+    """
+    if lua_table is None:
+        return None
+
+    # Check if it's a lupa table by checking for the items method
+    if not hasattr(lua_table, "items"):
+        # It's a primitive value (string, number, bool), return as-is
+        return lua_table
+
+    try:
+        # Get all keys
+        keys = list(lua_table.keys())
+
+        # Empty table - return empty dict for opts (different from dsl_stubs which returns [])
+        if not keys:
+            return {}
+
+        # Check if it's an array (all keys are consecutive integers starting from 1)
+        if all(isinstance(k, int) for k in keys):
+            sorted_keys = sorted(keys)
+            if sorted_keys == list(range(1, len(keys) + 1)):
+                # It's an array
+                return [_convert_lua_table(lua_table[k]) for k in sorted_keys]
+
+        # It's a dictionary
+        result = {}
+        for key, value in lua_table.items():
+            # Recursively convert nested tables
+            result[key] = _convert_lua_table(value)
+        return result
+
+    except (AttributeError, TypeError):
+        # Fallback: return as-is
+        return lua_table
+
+
+class AgentHandle:
+    """
+    Lightweight handle returned by agent() DSL function.
+
+    Created during DSL parsing, enhanced at runtime with actual AgentPrimitive.
+    Supports callable syntax: agent() or agent({message = "..."})
+    """
+
+    def __init__(self, name: str):
+        """
+        Initialize agent handle.
+
+        Args:
+            name: Agent name (string identifier)
+        """
+        self.name = name
+        self._primitive: Optional["DSPyAgentHandle"] = None
+        self._execution_context: Optional[Any] = None
+        logger.debug(f"AgentHandle created for '{name}'")
+
+    def __call__(self, inputs=None):
+        """
+        Execute an agent turn using the callable interface.
+
+        This is the unified callable interface that allows:
+            result = worker({message = "Hello"})
+
+        Args:
+            inputs: Input dict with fields matching input_schema.
+                   Default field 'message' is used as the user message.
+
+        Returns:
+            Result object with response and other fields
+
+        Raises:
+            RuntimeError: If handle not connected to primitive
+
+        Example (Lua):
+            result = worker({message = "Process this task"})
+            print(result.response)
+        """
+        logger.debug(
+            f"[CHECKPOINT] AgentHandle '{self.name}'.__call__ invoked, _primitive={self._primitive is not None}, _execution_context={self._execution_context is not None}"
+        )
+        if self._primitive is None:
+            raise RuntimeError(
+                f"Agent '{self.name}' initialization failed.\n"
+                f"This should not happen with immediate agent creation.\n"
+                f"Please report this as a bug with a minimal reproduction example."
+            )
+        # Convert Lua table to Python dict if needed
+        converted_inputs = _convert_lua_table(inputs) if inputs is not None else None
+
+        # Convenience: allow shorthand string calls in Lua:
+        #   World("Hello") == World({message = "Hello"})
+        if isinstance(converted_inputs, str):
+            converted_inputs = {"message": converted_inputs}
+
+        # If we have an execution context, checkpoint the agent call
+        logger.debug(
+            f"[CHECKPOINT] AgentHandle '{self.name}' called, has_execution_context={self._execution_context is not None}"
+        )
+        if self._execution_context is not None:
+
+            def agent_call():
+                return self._primitive(converted_inputs)
+
+            # Capture source location from Lua if available
+            source_info = None
+            if (
+                hasattr(self._execution_context, "lua_sandbox")
+                and self._execution_context.lua_sandbox
+            ):
+                try:
+                    lua = self._execution_context.lua_sandbox.lua
+                    info = lua.eval("debug.getinfo(2, 'Sl')")
+                    if info:
+                        source_info = {
+                            "file": info.get("source", "unknown"),
+                            "line": info.get("currentline", 0),
+                        }
+                except Exception as e:
+                    logger.debug(f"Could not capture source location: {e}")
+
+            logger.debug(
+                f"[CHECKPOINT] Creating checkpoint for agent '{self.name}', type=agent_turn, source_info={source_info}"
+            )
+            result = self._execution_context.checkpoint(
+                agent_call, checkpoint_type="agent_turn", source_info=source_info
+            )
+        else:
+            # No execution context - call directly without checkpointing
+            result = self._primitive(converted_inputs)
+
+        # Convenience: expose the last agent output on the handle as `.output`
+        # for Lua patterns like `agent(); return agent.output`.
+        output_text = None
+        if result is not None:
+            for attr in ("response", "message"):
+                try:
+                    value = getattr(result, attr, None)
+                except Exception:
+                    value = None
+                if isinstance(value, str):
+                    output_text = value
+                    break
+
+            if output_text is None and isinstance(result, dict):
+                for key in ("response", "message"):
+                    value = result.get(key)
+                    if isinstance(value, str):
+                        output_text = value
+                        break
+
+            if output_text is None:
+                output_text = str(result)
+
+        self.output = output_text
+        return result
+
+    def _set_primitive(
+        self, primitive: "DSPyAgentHandle", execution_context: Optional[Any] = None
+    ) -> None:
+        """
+        Connect this handle to its actual primitive and execution context.
+
+        Called by runtime._enhance_handles() after primitives are created.
+
+        Args:
+            primitive: The DSPyAgentHandle to delegate to
+            execution_context: Optional execution context for checkpointing
+        """
+        self._primitive = primitive
+        self._execution_context = execution_context
+        logger.debug(
+            f"[CHECKPOINT] AgentHandle '{self.name}' connected to primitive (checkpointing={'enabled' if execution_context else 'disabled'}, execution_context={execution_context})"
+        )
+
+    def __repr__(self) -> str:
+        connected = "connected" if self._primitive else "disconnected"
+        return f"AgentHandle('{self.name}', {connected})"
+
+
+class ModelHandle:
+    """
+    Lightweight handle returned by model() DSL function.
+
+    Created during DSL parsing, enhanced at runtime with actual ModelPrimitive.
+    Delegates .predict() calls to the real primitive.
+    """
+
+    def __init__(self, name: str):
+        """
+        Initialize model handle.
+
+        Args:
+            name: Model name (string identifier)
+        """
+        self.name = name
+        self._primitive: Optional["ModelPrimitive"] = None
+        logger.debug(f"ModelHandle created for '{name}'")
+
+    def predict(self, data: Any) -> Any:
+        """
+        Run model prediction (delegates to ModelPrimitive.predict()).
+
+        Args:
+            data: Input data for prediction
+
+        Returns:
+            Prediction result
+
+        Raises:
+            RuntimeError: If handle not connected to primitive
+        """
+        if self._primitive is None:
+            raise RuntimeError(
+                f"Model '{self.name}' initialization failed.\n"
+                f"This should not happen - please report this as a bug."
+            )
+        converted_data = _convert_lua_table(data) if data is not None else None
+        return self._primitive.predict(converted_data)
+
+    def __call__(self, data: Any = None) -> Any:
+        """
+        Execute model prediction using the callable interface.
+
+        This is the unified callable interface that allows:
+            result = classifier({text = "Hello"})
+
+        Args:
+            data: Input data for prediction (format depends on model type)
+
+        Returns:
+            Model prediction result
+
+        Raises:
+            RuntimeError: If handle not connected to primitive
+
+        Example (Lua):
+            result = classifier({text = "This is great!"})
+            print(result.label)       -- "positive"
+        """
+        if self._primitive is None:
+            raise RuntimeError(
+                f"Model '{self.name}' initialization failed.\n"
+                f"This should not happen - please report this as a bug."
+            )
+        # Convert Lua table to Python dict if needed
+        converted_data = _convert_lua_table(data) if data is not None else None
+        return self._primitive(converted_data)
+
+    def _set_primitive(self, primitive: "ModelPrimitive") -> None:
+        """
+        Connect this handle to its actual primitive.
+
+        Called by runtime._enhance_handles() after primitives are created.
+
+        Args:
+            primitive: The ModelPrimitive to delegate to
+        """
+        self._primitive = primitive
+        logger.debug(f"ModelHandle '{self.name}' connected to primitive")
+
+    def __repr__(self) -> str:
+        connected = "connected" if self._primitive else "disconnected"
+        return f"ModelHandle('{self.name}', {connected})"
+
+
+class AgentLookup:
+    """
+    Agent lookup primitive - provides Agent("name") lookup functionality.
+
+    Injected into Lua as 'Agent'. Callable to look up agents by name.
+    """
+
+    def __init__(self, registry: Dict[str, AgentHandle]):
+        """
+        Initialize with reference to the agent registry.
+
+        Args:
+            registry: Dict mapping agent names to AgentHandle instances
+        """
+        self._registry = registry
+
+    def __call__(self, name: str) -> AgentHandle:
+        """
+        Look up an agent by name.
+
+        Args:
+            name: Agent name to look up
+
+        Returns:
+            AgentHandle for the named agent
+
+        Raises:
+            ValueError: If agent not found
+
+        Example (Lua):
+            Agent("greeter")()  -- or Agent("greeter")({message = "Hello"})
+        """
+        if name not in self._registry:
+            available = list(self._registry.keys())
+            raise ValueError(f"Agent '{name}' not defined. Available agents: {available}")
+        return self._registry[name]
+
+    def __repr__(self) -> str:
+        return f"AgentLookup({len(self._registry)} agents)"
+
+
+class ModelLookup:
+    """
+    Model lookup primitive - provides Model("name") lookup functionality.
+
+    Injected into Lua as 'Model'. Callable to look up models by name.
+    """
+
+    def __init__(self, registry: Dict[str, ModelHandle]):
+        """
+        Initialize with reference to the model registry.
+
+        Args:
+            registry: Dict mapping model names to ModelHandle instances
+        """
+        self._registry = registry
+
+    def __call__(self, name: str) -> ModelHandle:
+        """
+        Look up a model by name.
+
+        Args:
+            name: Model name to look up
+
+        Returns:
+            ModelHandle for the named model
+
+        Raises:
+            ValueError: If model not found
+
+        Example (Lua):
+            Model("classifier").predict(data)
+        """
+        if name not in self._registry:
+            available = list(self._registry.keys())
+            raise ValueError(f"Model '{name}' not defined. Available models: {available}")
+        return self._registry[name]
+
+    def __repr__(self) -> str:
+        return f"ModelLookup({len(self._registry)} models)"

tactus/primitives/host.py

@@ -0,0 +1,94 @@
+"""
+Host Primitive - brokered host capabilities for the runtime container.
+
+This primitive is intended to be used inside the sandboxed runtime container.
+It delegates allowlisted operations to the trusted host-side broker via the
+`TACTUS_BROKER_SOCKET` transport.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from typing import Any, Dict, Optional
+
+from tactus.broker.client import BrokerClient
+
+
+class HostPrimitive:
+    """Provides access to allowlisted host-side tools via the broker."""
+
+    def __init__(self, client: Optional[BrokerClient] = None):
+        self._client = client or BrokerClient.from_environment()
+        self._registry = None
+        if self._client is None:
+            # Allow Host.call() to work in non-sandboxed runs (and in deterministic tests)
+            # without requiring a broker transport, while still staying deny-by-default.
+            from tactus.broker.server import HostToolRegistry
+
+            self._registry = HostToolRegistry.default()
+
+    def _run_coro(self, coro):
+        """
+        Run an async coroutine from Lua's synchronous context.
+
+        Mirrors the approach used by `ToolHandle` for async tool handlers.
+        """
+        try:
+            asyncio.get_running_loop()
+
+            import threading
+
+            result_container = {"value": None, "exception": None}
+
+            def run_in_thread():
+                try:
+                    result_container["value"] = asyncio.run(coro)
+                except Exception as e:
+                    result_container["exception"] = e
+
+            thread = threading.Thread(target=run_in_thread)
+            thread.start()
+            thread.join()
+
+            if result_container["exception"]:
+                raise result_container["exception"]
+            return result_container["value"]
+
+        except RuntimeError:
+            return asyncio.run(coro)
+
+    def _lua_to_python(self, obj: Any) -> Any:
+        if obj is None:
+            return None
+        if hasattr(obj, "items") and not isinstance(obj, dict):
+            return {k: self._lua_to_python(v) for k, v in obj.items()}
+        if isinstance(obj, dict):
+            return {k: self._lua_to_python(v) for k, v in obj.items()}
+        if isinstance(obj, (list, tuple)):
+            return [self._lua_to_python(v) for v in obj]
+        return obj
+
+    def call(self, name: str, args: Optional[Dict[str, Any]] = None) -> Any:
+        """
+        Call an allowlisted host tool via the broker.
+
+        Example (Lua):
+            local result = Host.call("host.ping", {value = 1})
+        """
+        if not isinstance(name, str) or not name:
+            raise ValueError("Host.call requires a non-empty tool name string")
+
+        args_dict = self._lua_to_python(args) or {}
+        if not isinstance(args_dict, dict):
+            raise ValueError("Host.call args must be an object/table")
+
+        if self._client is not None:
+            return self._run_coro(self._client.call_tool(name=name, args=args_dict))
+
+        if self._registry is not None:
+            try:
+                return self._registry.call(name, args_dict)
+            except KeyError as e:
+                raise RuntimeError(f"Tool not allowlisted: {name}") from e
+
+        raise RuntimeError("Host.call requires TACTUS_BROKER_SOCKET to be set")