tactus 0.31.2__py3-none-any.whl

tactus/primitives/toolset.py

@@ -0,0 +1,229 @@
+"""
+Toolset Primitive - Manages and composes tool collections in Tactus.
+
+Provides first-class support for Pydantic AI's composable toolset architecture.
+"""
+
+import logging
+from typing import Any, Dict, Callable
+from pydantic_ai.toolsets import AbstractToolset, CombinedToolset, FilteredToolset
+
+logger = logging.getLogger(__name__)
+
+
+class ToolsetPrimitive:
+    """
+    Toolset primitive for managing and composing tool collections.
+
+    Exposes Pydantic AI's toolset composition features to the Lua DSL.
+
+    Example Lua usage:
+        toolset("financial", {type = "plugin", paths = {"./tools/financial"}})
+
+        local ts = Toolset.get("financial")
+        local combined = Toolset.combine(ts1, ts2)
+        local filtered = Toolset.filter(ts, function(name) return name:match("^web_") end)
+    """
+
+    def __init__(self, runtime):
+        """
+        Initialize toolset primitive.
+
+        Args:
+            runtime: TactusRuntime instance for resolving toolset references
+        """
+        self.runtime = runtime
+        self.definitions = {}  # name -> toolset config (from DSL)
+        logger.debug("ToolsetPrimitive initialized")
+
+    def define(self, name: str, config: Dict[str, Any]) -> None:
+        """
+        Register a toolset definition from the DSL.
+
+        This is called when the Lua DSL uses: toolset("name", {...})
+
+        Args:
+            name: Toolset name
+            config: Configuration dict with type and type-specific params
+
+        Example config:
+            {
+                "type": "plugin",
+                "paths": ["./tools/financial"]
+            }
+            {
+                "type": "mcp",
+                "server": "plexus"
+            }
+            {
+                "type": "combined",
+                "sources": ["financial", "plexus"]
+            }
+        """
+        self.definitions[name] = config
+        logger.info(f"Defined toolset '{name}' of type '{config.get('type')}'")
+
+    def get(self, name: str) -> AbstractToolset:
+        """
+        Get a toolset by name.
+
+        Resolves the toolset from runtime's registered toolsets or creates it
+        from a DSL definition.
+
+        Args:
+            name: Toolset name
+
+        Returns:
+            AbstractToolset instance
+
+        Raises:
+            ValueError: If toolset not found
+        """
+        # Try to resolve from runtime first (config-defined toolsets)
+        toolset = self.runtime.resolve_toolset(name)
+        if toolset:
+            return toolset
+
+        # Try DSL definitions
+        if name in self.definitions:
+            return self._create_toolset_from_definition(name, self.definitions[name])
+
+        raise ValueError(f"Toolset '{name}' not found (not in config or DSL)")
+
+    def combine(self, *toolsets) -> CombinedToolset:
+        """
+        Combine multiple toolsets into one.
+
+        Args:
+            *toolsets: Variable number of AbstractToolset instances
+
+        Returns:
+            CombinedToolset containing all input toolsets
+        """
+        toolset_list = list(toolsets)
+        logger.debug(f"Combining {len(toolset_list)} toolsets")
+        return CombinedToolset(toolset_list)
+
+    def filter(self, toolset: AbstractToolset, predicate: Callable[[str], bool]) -> FilteredToolset:
+        """
+        Filter tools in a toolset based on a predicate function.
+
+        Args:
+            toolset: Toolset to filter
+            predicate: Function that takes tool name and returns bool
+
+        Returns:
+            FilteredToolset with only matching tools
+
+        Example:
+            filtered = Toolset.filter(ts, function(name)
+                return name:match("^web_")
+            end)
+        """
+
+        # Wrap Lua function for Pydantic AI's filter API
+        # Pydantic AI's filtered() expects: lambda ctx, tool: bool
+        def pydantic_filter(ctx, tool):
+            # Call Lua predicate with just the tool name
+            return predicate(tool.name)
+
+        logger.debug("Creating filtered toolset")
+        return toolset.filtered(pydantic_filter)
+
+    def _create_toolset_from_definition(self, name: str, config: Dict[str, Any]) -> AbstractToolset:
+        """
+        Create a toolset from a DSL definition.
+
+        Args:
+            name: Toolset name
+            config: Toolset configuration
+
+        Returns:
+            Created toolset instance
+
+        Raises:
+            ValueError: If toolset type is unknown
+        """
+        toolset_type = config.get("type")
+
+        if toolset_type == "plugin":
+            return self._create_plugin_toolset(name, config)
+        elif toolset_type == "mcp":
+            return self._create_mcp_toolset_reference(name, config)
+        elif toolset_type == "combined":
+            return self._create_combined_toolset(name, config)
+        elif toolset_type == "filtered":
+            return self._create_filtered_toolset(name, config)
+        else:
+            raise ValueError(f"Unknown toolset type: {toolset_type}")
+
+    def _create_plugin_toolset(self, name: str, config: Dict[str, Any]) -> AbstractToolset:
+        """Create a plugin toolset from paths."""
+        from tactus.adapters.plugins import PluginLoader
+
+        paths = config.get("paths", [])
+        if not paths:
+            raise ValueError(f"Plugin toolset '{name}' must specify 'paths'")
+
+        loader = PluginLoader(tool_primitive=self.runtime.tool_primitive)
+        toolset = loader.create_toolset(paths, name=name)
+        return toolset
+
+    def _create_mcp_toolset_reference(self, name: str, config: Dict[str, Any]) -> AbstractToolset:
+        """Get reference to an MCP toolset."""
+        server_name = config.get("server")
+        if not server_name:
+            raise ValueError(f"MCP toolset '{name}' must specify 'server' name")
+
+        # MCP toolsets are created during runtime initialization
+        # Look them up from runtime's MCP manager
+        if not hasattr(self.runtime, "mcp_manager") or not self.runtime.mcp_manager:
+            raise ValueError(f"MCP server '{server_name}' not configured")
+
+        # Get the toolset by server name
+        toolset = self.runtime.mcp_manager.get_toolset_by_name(server_name)
+        if toolset:
+            logger.info(f"Found MCP toolset for server '{server_name}'")
+            return toolset
+
+        raise ValueError(f"MCP server toolset '{server_name}' not found")
+
+    def _create_combined_toolset(self, name: str, config: Dict[str, Any]) -> CombinedToolset:
+        """Create a combined toolset from sources."""
+        sources = config.get("sources", [])
+        if not sources:
+            raise ValueError(f"Combined toolset '{name}' must specify 'sources'")
+
+        # Resolve each source toolset
+        resolved_toolsets = []
+        for source_name in sources:
+            toolset = self.get(source_name)
+            resolved_toolsets.append(toolset)
+
+        return CombinedToolset(resolved_toolsets)
+
+    def _create_filtered_toolset(self, name: str, config: Dict[str, Any]) -> FilteredToolset:
+        """Create a filtered toolset."""
+        source = config.get("source")
+        filter_pattern = config.get("filter")
+
+        if not source:
+            raise ValueError(f"Filtered toolset '{name}' must specify 'source'")
+        if not filter_pattern:
+            raise ValueError(f"Filtered toolset '{name}' must specify 'filter' pattern")
+
+        # Get source toolset
+        source_toolset = self.get(source)
+
+        # Create filter function (simple regex match for now)
+        import re
+
+        pattern = re.compile(filter_pattern)
+
+        def filter_func(ctx, tool):
+            return pattern.match(tool.name) is not None
+
+        return source_toolset.filtered(filter_func)
+
+    def __repr__(self) -> str:
+        return f"ToolsetPrimitive({len(self.definitions)} definitions)"

tactus/protocols/__init__.py

@@ -0,0 +1,38 @@
+"""
+Tactus protocols and models.
+
+This module exports all Pydantic models and protocol definitions for Tactus.
+"""
+
+# Core models
+from tactus.protocols.models import (
+    CheckpointEntry,
+    ProcedureMetadata,
+    HITLRequest,
+    HITLResponse,
+    ChatMessage,
+)
+
+# Protocols
+from tactus.protocols.storage import StorageBackend
+from tactus.protocols.hitl import HITLHandler
+from tactus.protocols.chat_recorder import ChatRecorder
+
+# Configuration
+from tactus.protocols.config import TactusConfig, ProcedureConfig
+
+__all__ = [
+    # Models
+    "CheckpointEntry",
+    "ProcedureMetadata",
+    "HITLRequest",
+    "HITLResponse",
+    "ChatMessage",
+    # Protocols
+    "StorageBackend",
+    "HITLHandler",
+    "ChatRecorder",
+    # Config
+    "TactusConfig",
+    "ProcedureConfig",
+]

tactus/protocols/chat_recorder.py

@@ -0,0 +1,81 @@
+"""
+Chat recorder protocol for Tactus.
+
+Defines the interface for recording conversation history during workflow execution.
+Implementations can store chat logs anywhere (memory, files, databases, APIs, etc.).
+"""
+
+from typing import Protocol, Optional, Dict, Any
+from tactus.protocols.models import ChatMessage
+
+
+class ChatRecorder(Protocol):
+    """
+    Protocol for chat recorders.
+
+    Implementations record conversation history between agents, tools, and humans.
+    This is optional - procedures can run without chat recording.
+    """
+
+    async def start_session(
+        self, procedure_id: str, context: Optional[Dict[str, Any]] = None
+    ) -> str:
+        """
+        Start a new chat session for a procedure.
+
+        Args:
+            procedure_id: Unique procedure identifier
+            context: Optional context data for the session
+
+        Returns:
+            Session ID
+
+        Raises:
+            ChatRecorderError: If session creation fails
+        """
+        ...
+
+    async def record_message(self, message: ChatMessage) -> str:
+        """
+        Record a message in the current session.
+
+        Args:
+            message: ChatMessage to record
+
+        Returns:
+            Message ID
+
+        Raises:
+            ChatRecorderError: If recording fails
+        """
+        ...
+
+    async def end_session(self, session_id: str, status: str = "COMPLETED") -> None:
+        """
+        End a chat session.
+
+        Args:
+            session_id: Session ID to end
+            status: Final status (COMPLETED, FAILED, etc.)
+
+        Raises:
+            ChatRecorderError: If ending session fails
+        """
+        ...
+
+    async def get_session_messages(
+        self, session_id: str, limit: Optional[int] = None
+    ) -> list[ChatMessage]:
+        """
+        Get messages from a session.
+
+        Optional method for implementations that support retrieval.
+
+        Args:
+            session_id: Session ID
+            limit: Optional limit on number of messages
+
+        Returns:
+            List of ChatMessage objects
+        """
+        ...

tactus/protocols/config.py

@@ -0,0 +1,97 @@
+"""
+Configuration models for Tactus runtime.
+
+Defines Pydantic models for runtime configuration and procedure definitions.
+"""
+
+from typing import Optional, Dict, Any, List
+from pydantic import BaseModel, Field
+
+
+class TactusConfig(BaseModel):
+    """
+    Runtime configuration for Tactus.
+
+    This model defines all runtime settings for a Tactus instance,
+    including storage backend, HITL handler, and LLM settings.
+    """
+
+    # Storage backend
+    storage_backend: str = Field(
+        default="memory", description="Storage backend type: 'memory', 'file', or 'custom'"
+    )
+    storage_options: Dict[str, Any] = Field(
+        default_factory=dict, description="Options passed to storage backend constructor"
+    )
+
+    # HITL handler
+    hitl_handler: str = Field(
+        default="cli", description="HITL handler type: 'cli', 'none', or 'custom'"
+    )
+    hitl_options: Dict[str, Any] = Field(
+        default_factory=dict, description="Options passed to HITL handler constructor"
+    )
+
+    # Chat recorder
+    chat_recorder: Optional[str] = Field(
+        default=None, description="Chat recorder type: None, 'memory', 'file', or 'custom'"
+    )
+    chat_recorder_options: Dict[str, Any] = Field(
+        default_factory=dict, description="Options passed to chat recorder constructor"
+    )
+
+    # LLM settings
+    openai_api_key: Optional[str] = Field(default=None, description="OpenAI API key for LLM calls")
+    default_model: str = Field(default="gpt-4o", description="Default LLM model to use")
+    llm_temperature: float = Field(default=0.7, description="Temperature for LLM calls")
+
+    # Execution settings
+    max_iterations: int = Field(default=100, description="Maximum iterations before stopping")
+    enable_checkpoints: bool = Field(
+        default=True, description="Whether to enable checkpoint/resume"
+    )
+
+    # MCP server
+    mcp_server_url: Optional[str] = Field(
+        default=None, description="MCP server URL for tool loading"
+    )
+    mcp_tools: List[str] = Field(default_factory=list, description="List of MCP tools to load")
+
+
+class ProcedureConfig(BaseModel):
+    """
+    Parsed procedure configuration from YAML.
+
+    This model represents a validated procedure definition,
+    ready for execution by the Tactus runtime.
+    """
+
+    name: str = Field(..., description="Procedure name")
+    version: str = Field(..., description="Procedure version")
+    description: Optional[str] = Field(None, description="Optional description")
+
+    # Parameters (inputs)
+    params: Dict[str, Any] = Field(
+        default_factory=dict, description="Parameter definitions with types and defaults"
+    )
+
+    # Outputs (schema)
+    outputs: Dict[str, Any] = Field(
+        default_factory=dict, description="Output schema definitions with types and validation"
+    )
+
+    # Agents
+    agents: Dict[str, Any] = Field(..., description="Agent definitions with prompts and tools")
+
+    # Procedure
+    procedure: str = Field(..., description="Lua procedure code")
+
+    # HITL declarations
+    hitl: Dict[str, Any] = Field(default_factory=dict, description="Pre-defined HITL interactions")
+
+    # Sub-procedures (future)
+    procedures: Dict[str, Any] = Field(
+        default_factory=dict, description="Inline sub-procedure definitions (future feature)"
+    )
+
+    model_config = {"arbitrary_types_allowed": True}

tactus/protocols/cost.py

@@ -0,0 +1,31 @@
+"""
+Cost and usage models shared across Tactus.
+
+These models are intentionally small and stable so they can be reused anywhere
+that may incur cost (agents, results, future primitives).
+"""
+
+from __future__ import annotations
+
+from typing import Optional
+
+from pydantic import BaseModel, Field
+
+
+class UsageStats(BaseModel):
+    """Token usage for a single call or an aggregate."""
+
+    prompt_tokens: int = Field(default=0, ge=0)
+    completion_tokens: int = Field(default=0, ge=0)
+    total_tokens: int = Field(default=0, ge=0)
+
+
+class CostStats(BaseModel):
+    """Cost for a single call or an aggregate."""
+
+    total_cost: float = Field(default=0.0, ge=0.0, description="Total cost in USD")
+    prompt_cost: float = Field(default=0.0, ge=0.0)
+    completion_cost: float = Field(default=0.0, ge=0.0)
+
+    model: Optional[str] = Field(default=None, description="Model identifier, if known")
+    provider: Optional[str] = Field(default=None, description="Provider identifier, if known")

tactus/protocols/hitl.py

@@ -0,0 +1,71 @@
+"""
+HITL (Human-in-the-Loop) handler protocol for Tactus.
+
+Defines the interface for managing human interactions during workflow execution.
+Implementations can use any UI (web, CLI, API, etc.).
+"""
+
+from typing import Protocol, Optional
+from tactus.protocols.models import HITLRequest, HITLResponse
+
+
+class HITLHandler(Protocol):
+    """
+    Protocol for HITL handlers.
+
+    Implementations manage human interactions (approval, input, review, escalation).
+    This allows Tactus to work with any UI or interaction system.
+    """
+
+    def request_interaction(self, procedure_id: str, request: HITLRequest) -> HITLResponse:
+        """
+        Request human interaction (blocking).
+
+        This method should:
+        1. Present the request to a human (via UI, CLI, API, etc.)
+        2. Wait for response (with timeout handling)
+        3. Return HITLResponse with the human's answer
+
+        For exit-and-resume patterns, this may raise
+        ProcedureWaitingForHuman to signal workflow suspension.
+
+        Args:
+            procedure_id: Unique procedure identifier
+            request: HITLRequest with interaction details
+
+        Returns:
+            HITLResponse with human's answer
+
+        Raises:
+            ProcedureWaitingForHuman: (Optional) To trigger exit-and-resume
+            HITLError: If interaction fails
+        """
+        ...
+
+    def check_pending_response(self, procedure_id: str, message_id: str) -> Optional[HITLResponse]:
+        """
+        Check if there's a response to a pending HITL request.
+
+        Used during resume flow to check if human has responded while
+        procedure was suspended.
+
+        Args:
+            procedure_id: Unique procedure identifier
+            message_id: Message/request ID to check
+
+        Returns:
+            HITLResponse if response exists, None otherwise
+        """
+        ...
+
+    def cancel_pending_request(self, procedure_id: str, message_id: str) -> None:
+        """
+        Cancel a pending HITL request.
+
+        Optional method for implementations that support cancellation.
+
+        Args:
+            procedure_id: Unique procedure identifier
+            message_id: Message/request ID to cancel
+        """
+        ...

tactus/protocols/log_handler.py

@@ -0,0 +1,27 @@
+"""
+Log handler protocol for Tactus.
+
+Defines the interface for handling log events during workflow execution.
+Implementations can render logs differently (CLI with Rich, IDE with React, etc.).
+"""
+
+from typing import Protocol, Union
+from tactus.protocols.models import LogEvent, ExecutionSummaryEvent
+
+
+class LogHandler(Protocol):
+    """
+    Protocol for log handlers.
+
+    Implementations handle log events from procedures, rendering them
+    appropriately for different environments (CLI, IDE, API, etc.).
+    """
+
+    def log(self, event: Union[LogEvent, ExecutionSummaryEvent]) -> None:
+        """
+        Handle a log or summary event.
+
+        Args:
+            event: Structured event (LogEvent or ExecutionSummaryEvent)
+        """
+        ...