tactus 0.31.0__py3-none-any.whl → 0.34.1__py3-none-any.whl

tactus/cli/control.py

@@ -0,0 +1,393 @@
+"""
+Tactus Control CLI - Connect to running procedure and respond to control requests.
+
+This is a standalone CLI application that connects to the runtime's IPC socket
+and allows humans (or other controllers) to respond to control requests from
+running procedures.
+
+Usage:
+    tactus control [--socket PATH]
+"""
+
+import asyncio
+import logging
+import sys
+from datetime import datetime, timezone
+from typing import Dict, List, Optional
+
+from rich.console import Console
+from rich.panel import Panel
+from rich.prompt import Confirm, Prompt
+from rich.table import Table
+
+from tactus.broker.protocol import read_message, write_message
+
+logger = logging.getLogger(__name__)
+
+
+class ControlCLI:
+    """CLI app for responding to control requests via IPC."""
+
+    def __init__(
+        self, socket_path: str = "/tmp/tactus-control.sock", auto_respond: Optional[str] = None
+    ):
+        """
+        Initialize control CLI.
+
+        Args:
+            socket_path: Path to runtime's Unix socket
+            auto_respond: If set, automatically respond with this value (for testing)
+        """
+        self.socket_path = socket_path
+        self.auto_respond = auto_respond
+        self.console = Console()
+        self._reader: Optional[asyncio.StreamReader] = None
+        self._writer: Optional[asyncio.StreamWriter] = None
+        self._running = False
+
+    async def connect(self) -> bool:
+        """
+        Connect to runtime's IPC socket.
+
+        Returns:
+            True if connected successfully
+        """
+        try:
+            self._reader, self._writer = await asyncio.open_unix_connection(self.socket_path)
+            return True
+        except FileNotFoundError:
+            self.console.print(f"[red]✗ Socket not found: {self.socket_path}[/red]")
+            self.console.print("\n[yellow]Is the Tactus runtime running?[/yellow]")
+            return False
+        except ConnectionRefusedError:
+            self.console.print(f"[red]✗ Connection refused: {self.socket_path}[/red]")
+            return False
+        except Exception as e:
+            self.console.print(f"[red]✗ Failed to connect: {e}[/red]")
+            return False
+
+    async def disconnect(self) -> None:
+        """Close connection to runtime."""
+        if self._writer:
+            try:
+                self._writer.close()
+                await self._writer.wait_closed()
+            except Exception:
+                pass
+
+    async def watch_mode(self) -> None:
+        """
+        Interactive mode - watch for requests and respond.
+
+        This is the main entry point for the control CLI. It connects to the
+        runtime, displays pending requests, and prompts for responses.
+        """
+        # Connect to runtime
+        if not await self.connect():
+            return
+
+        self.console.print()
+        self.console.print(
+            Panel(
+                f"[green]Connected to: {self.socket_path}[/green]\n"
+                "[dim]Waiting for control requests...[/dim]",
+                title="Control Session",
+                border_style="green",
+            )
+        )
+        self.console.print()
+
+        self._running = True
+
+        try:
+            # Read messages from runtime
+            while self._running:
+                try:
+                    message = await read_message(self._reader)
+                except EOFError:
+                    self.console.print("\n[yellow]✗ Connection closed by runtime[/yellow]")
+                    break
+                except asyncio.IncompleteReadError:
+                    self.console.print("\n[yellow]✗ Connection closed by runtime[/yellow]")
+                    break
+
+                await self._handle_message(message)
+
+        except KeyboardInterrupt:
+            self.console.print("\n[dim]Disconnecting...[/dim]")
+
+        finally:
+            await self.disconnect()
+
+    async def _handle_message(self, message: Dict) -> None:
+        """
+        Handle a message from the runtime.
+
+        Args:
+            message: Parsed JSON message
+        """
+        msg_type = message.get("type")
+
+        if msg_type == "control.request":
+            await self._handle_request(message)
+
+        elif msg_type == "control.cancelled":
+            self._handle_cancellation(message)
+
+        elif msg_type == "control.list_response":
+            self._handle_list_response(message)
+
+        else:
+            logger.warning(f"Unknown message type: {msg_type}")
+
+    async def _handle_request(self, request: Dict) -> None:
+        """
+        Handle a control request from the runtime.
+
+        Args:
+            request: Control request message
+        """
+        request_id = request["request_id"]
+        procedure_name = request.get("procedure_name", "Unknown Procedure")
+        request_type = request["request_type"]
+        message = request["message"]
+        options = request.get("options", [])
+        default_value = request.get("default_value")
+        started_at = request.get("started_at")
+
+        # Calculate elapsed time
+        elapsed_str = "Unknown"
+        if started_at:
+            started = datetime.fromisoformat(started_at)
+            elapsed = (datetime.now(timezone.utc) - started).total_seconds()
+            if elapsed < 60:
+                elapsed_str = f"{int(elapsed)} seconds ago"
+            elif elapsed < 3600:
+                elapsed_str = f"{int(elapsed / 60)} minutes ago"
+            else:
+                elapsed_str = f"{int(elapsed / 3600)} hours ago"
+
+        # Display request panel
+        self.console.print()
+        self.console.print(
+            Panel(
+                f"[bold]{procedure_name}[/bold]\n" f"Started: {elapsed_str}",
+                title="Control Request",
+                border_style="blue",
+            )
+        )
+        self.console.print()
+
+        self.console.print(
+            Panel(
+                f"[bold]{message}[/bold]\n\n"
+                f"Type: {request_type}\n"
+                f"ID: [dim]{request_id}[/dim]",
+                border_style="cyan",
+            )
+        )
+        self.console.print()
+
+        # Handle based on request type
+        if request_type == "approval":
+            await self._handle_approval_request(request, options, default_value)
+
+        elif request_type == "choice":
+            await self._handle_choice_request(request, options, default_value)
+
+        elif request_type == "input":
+            await self._handle_input_request(request, default_value)
+
+        else:
+            self.console.print(f"[yellow]⚠ Unknown request type: {request_type}[/yellow]")
+
+    async def _handle_approval_request(
+        self, request: Dict, options: List[Dict], default_value: Optional[bool]
+    ) -> None:
+        """Handle an approval request."""
+        request_id = request["request_id"]
+
+        # Auto-respond mode (for testing)
+        if self.auto_respond is not None:
+            value = self.auto_respond.lower() in ("y", "yes", "true", "1")
+            await self._send_response(request_id, value)
+            return
+
+        # Interactive prompt
+        if default_value is not None:
+            prompt_str = f"Approve? [y/n] ({default_value and 'y' or 'n'}): "
+        else:
+            prompt_str = "Approve? [y/n]: "
+
+        response = Confirm.ask(
+            prompt_str, default=default_value if default_value is not None else None
+        )
+        await self._send_response(request_id, response)
+
+    async def _handle_choice_request(
+        self, request: Dict, options: List[Dict], default_value: Optional[any]
+    ) -> None:
+        """Handle a choice request."""
+        request_id = request["request_id"]
+
+        # Auto-respond mode (for testing)
+        if self.auto_respond is not None:
+            # Try to match auto_respond to an option value
+            for option in options:
+                if str(option.get("value")) == self.auto_respond:
+                    await self._send_response(request_id, option["value"])
+                    return
+            # Default to first option
+            await self._send_response(request_id, options[0]["value"] if options else None)
+            return
+
+        # Display options
+        self.console.print("Options:")
+        for i, option in enumerate(options, 1):
+            label = option.get("label", str(option.get("value")))
+            value = option.get("value")
+            if value == default_value:
+                self.console.print(f"  [{i}] {label} [dim](default)[/dim]")
+            else:
+                self.console.print(f"  [{i}] {label}")
+
+        self.console.print()
+
+        # Prompt for selection
+        while True:
+            selection = Prompt.ask(
+                "Choose an option",
+                default=(
+                    str(
+                        options.index(
+                            next(
+                                (o for o in options if o.get("value") == default_value), options[0]
+                            )
+                        )
+                        + 1
+                    )
+                    if default_value
+                    else "1"
+                ),
+            )
+            try:
+                index = int(selection) - 1
+                if 0 <= index < len(options):
+                    value = options[index]["value"]
+                    await self._send_response(request_id, value)
+                    break
+                else:
+                    self.console.print("[red]Invalid selection, please try again[/red]")
+            except ValueError:
+                self.console.print("[red]Please enter a number[/red]")
+
+    async def _handle_input_request(self, request: Dict, default_value: Optional[str]) -> None:
+        """Handle a text input request."""
+        request_id = request["request_id"]
+
+        # Auto-respond mode (for testing)
+        if self.auto_respond is not None:
+            await self._send_response(request_id, self.auto_respond)
+            return
+
+        # Interactive prompt
+        response = Prompt.ask("Enter value", default=default_value or "")
+        await self._send_response(request_id, response)
+
+    async def _send_response(self, request_id: str, value: any) -> None:
+        """
+        Send a response back to the runtime.
+
+        Args:
+            request_id: Request being responded to
+            value: Response value
+        """
+        response_message = {
+            "type": "control.response",
+            "request_id": request_id,
+            "value": value,
+            "responder_id": "control-cli",
+            "responded_at": datetime.now().isoformat(),
+        }
+
+        try:
+            await write_message(self._writer, response_message)
+            self.console.print()
+            self.console.print("[green]✓ Response sent via IPC[/green]")
+            self.console.print()
+        except Exception as e:
+            self.console.print(f"[red]✗ Failed to send response: {e}[/red]")
+
+    def _handle_cancellation(self, message: Dict) -> None:
+        """Handle a cancellation notification."""
+        request_id = message["request_id"]
+        reason = message.get("reason", "unknown")
+        self.console.print()
+        self.console.print(f"[yellow]✗ Request {request_id} was cancelled: {reason}[/yellow]")
+        self.console.print()
+
+    def _handle_list_response(self, message: Dict) -> None:
+        """Handle a list response."""
+        requests = message.get("requests", [])
+
+        if not requests:
+            self.console.print("[dim]No pending requests[/dim]")
+            return
+
+        table = Table(title="Pending Requests")
+        table.add_column("ID", style="cyan")
+        table.add_column("Procedure", style="green")
+        table.add_column("Type")
+        table.add_column("Message")
+
+        for request in requests:
+            table.add_row(
+                request["request_id"][:8],
+                request.get("procedure_name", "Unknown"),
+                request["request_type"],
+                request["message"][:50] + ("..." if len(request["message"]) > 50 else ""),
+            )
+
+        self.console.print(table)
+
+    async def list_requests(self) -> None:
+        """Request a list of pending requests from the runtime."""
+        if not await self.connect():
+            return
+
+        try:
+            # Send list request
+            list_message = {"type": "control.list"}
+            await write_message(self._writer, list_message)
+
+            # Wait for response
+            message = await read_message(self._reader)
+            if message.get("type") == "control.list_response":
+                self._handle_list_response(message)
+
+        except Exception as e:
+            self.console.print(f"[red]✗ Failed to list requests: {e}[/red]")
+
+        finally:
+            await self.disconnect()
+
+
+async def main(socket_path: str = "/tmp/tactus-control.sock", auto_respond: Optional[str] = None):
+    """
+    Main entry point for control CLI.
+
+    Args:
+        socket_path: Path to runtime's Unix socket
+        auto_respond: If set, automatically respond with this value
+    """
+    cli = ControlCLI(socket_path, auto_respond)
+    await cli.watch_mode()
+
+
+if __name__ == "__main__":
+    import sys
+
+    socket_path = sys.argv[1] if len(sys.argv) > 1 else "/tmp/tactus-control.sock"
+    auto_respond = sys.argv[2] if len(sys.argv) > 2 else None
+
+    asyncio.run(main(socket_path, auto_respond))

tactus/core/config_manager.py

@@ -259,10 +259,32 @@ class ConfigManager:
             # Sandbox configuration
             "TACTUS_SANDBOX_ENABLED": ("sandbox", "enabled"),
             "TACTUS_SANDBOX_IMAGE": ("sandbox", "image"),
+            # Notification configuration
+            "TACTUS_NOTIFICATIONS_ENABLED": ("notifications", "enabled"),
+            "TACTUS_NOTIFICATIONS_CALLBACK_URL": ("notifications", "callback_base_url"),
+            "TACTUS_HITL_SIGNING_SECRET": ("notifications", "signing_secret"),
+            # Slack notification channel
+            "SLACK_BOT_TOKEN": ("notifications", "channels", "slack", "token"),
+            # Discord notification channel
+            "DISCORD_BOT_TOKEN": ("notifications", "channels", "discord", "token"),
+            # Teams notification channel
+            "TEAMS_WEBHOOK_URL": ("notifications", "channels", "teams", "webhook_url"),
+            # Control loop configuration
+            "TACTUS_CONTROL_ENABLED": ("control", "enabled"),
+            "TACTUS_CONTROL_CLI_ENABLED": ("control", "channels", "cli", "enabled"),
+            # Tactus Cloud control channel
+            "TACTUS_CLOUD_API_URL": ("control", "channels", "tactus_cloud", "api_url"),
+            "TACTUS_CLOUD_TOKEN": ("control", "channels", "tactus_cloud", "token"),
+            "TACTUS_CLOUD_WORKSPACE_ID": ("control", "channels", "tactus_cloud", "workspace_id"),
         }
 
         # Boolean env vars that need special parsing
-        boolean_env_keys = {"TACTUS_SANDBOX_ENABLED"}
+        boolean_env_keys = {
+            "TACTUS_SANDBOX_ENABLED",
+            "TACTUS_NOTIFICATIONS_ENABLED",
+            "TACTUS_CONTROL_ENABLED",
+            "TACTUS_CONTROL_CLI_ENABLED",
+        }
 
         for env_key, config_key in env_mappings.items():
             value = os.environ.get(env_key)
@@ -272,12 +294,17 @@ class ConfigManager:
                     value = value.lower() in ("true", "1", "yes", "on")
 
                 if isinstance(config_key, tuple):
-                    # Nested key (e.g., aws.access_key_id, sandbox.enabled)
-                    if config_key[0] not in config:
-                        config[config_key[0]] = {}
-                    config[config_key[0]][config_key[1]] = value
+                    # Nested key - handle arbitrary depth
+                    # e.g., ("aws", "access_key_id") -> config["aws"]["access_key_id"]
+                    # e.g., ("notifications", "channels", "slack", "token")
+                    current = config
+                    for i, key in enumerate(config_key[:-1]):
+                        if key not in current:
+                            current[key] = {}
+                        current = current[key]
+                    current[config_key[-1]] = value
                     # Track env var name for this nested key
-                    path = f"{config_key[0]}.{config_key[1]}"
+                    path = ".".join(config_key)
                     self.env_var_mapping[path] = env_key
                 elif config_key == "tool_paths":
                     # Parse JSON list

tactus/core/dsl_stubs.py

@@ -35,6 +35,7 @@ from typing import Any, Callable, Dict
 
 from .registry import RegistryBuilder
 from tactus.primitives.handles import AgentHandle, ModelHandle, AgentLookup, ModelLookup
+from tactus.stdlib.classify import ClassifyPrimitive
 
 
 # NEW Builder pattern for field types - moved outside function for import
@@ -473,17 +474,26 @@ def create_dsl_stubs(
         """Register BDD specs.
 
         Supported forms:
-          - Specification([[ Gherkin text ]])  (alias for Specifications)
-          - Specification("name", { ... })     (structured form; legacy)
+          - Specification([[ Gherkin text ]])    (inline Gherkin)
+          - Specification("name", { ... })       (structured form; legacy)
+          - Specification { from = "path" }      (external file reference)
         """
         if len(args) == 1:
-            builder.register_specifications(args[0])
+            arg = args[0]
+            # Check if it's a table with 'from' parameter
+            if isinstance(arg, dict) or (hasattr(arg, "keys") and callable(arg.keys)):
+                config = lua_table_to_dict(arg) if not isinstance(arg, dict) else arg
+                if "from" in config:
+                    builder.register_specs_from(config["from"])
+                    return
+            # Otherwise treat as inline Gherkin text
+            builder.register_specifications(arg)
             return
         if len(args) >= 2:
             spec_name, scenarios = args[0], args[1]
             builder.register_specification(spec_name, lua_table_to_dict(scenarios))
             return
-        raise TypeError("Specification expects either (gherkin_text) or (name, scenarios)")
+        raise TypeError("Specification expects gherkin_text, {from='path'}, or (name, scenarios)")
 
     def _specifications(gherkin_text: str) -> None:
         """Register Gherkin BDD specifications."""
@@ -947,6 +957,18 @@ def create_dsl_stubs(
             if not isinstance(mock_config, dict):
                 continue
 
+            # Agent mocks can be message-only, tool_calls-only, or both.
+            if any(k in mock_config for k in ("tool_calls", "message", "data", "usage")):
+                agent_config = {
+                    "tool_calls": mock_config.get("tool_calls", []),
+                    "message": mock_config.get("message", ""),
+                    "data": mock_config.get("data", {}),
+                    "usage": mock_config.get("usage", {}),
+                    "temporal": mock_config.get("temporal", []),
+                }
+                builder.register_agent_mock(name, agent_config)
+                continue
+
             # Tool mocks use explicit keys.
             tool_mock_keys = {"returns", "temporal", "conditional", "error"}
             if any(k in mock_config for k in tool_mock_keys):
@@ -978,17 +1000,6 @@ def create_dsl_stubs(
                 builder.register_mock(name, processed_config)
                 continue
 
-            # Agent mocks can be message-only, tool_calls-only, or both.
-            if any(k in mock_config for k in ("tool_calls", "message", "data")):
-                agent_config = {
-                    "tool_calls": mock_config.get("tool_calls", []),
-                    "message": mock_config.get("message", ""),
-                    "data": mock_config.get("data", {}),
-                    "usage": mock_config.get("usage", {}),
-                }
-                builder.register_agent_mock(name, agent_config)
-                continue
-
             # Otherwise, ignore unknown mock config.
             continue
 
@@ -1949,6 +1960,80 @@ def create_dsl_stubs(
 
         return handle
 
+    def _new_classify(config=None):
+        """
+        Classify factory for smart classification with retry logic.
+
+        Syntax:
+            -- One-shot classification
+            result = Classify {
+                classes = {"Yes", "No"},
+                prompt = "Did the agent greet the customer?",
+                input = transcript
+            }
+
+            -- Reusable classifier
+            classifier = Classify {
+                classes = {"positive", "negative", "neutral"},
+                prompt = "What is the sentiment?"
+            }
+            result = classifier(text)
+
+        Config options:
+            - classes: List of valid classification values (required)
+            - prompt: Classification instruction (required)
+            - input: Optional input for one-shot classification
+            - max_retries: Maximum retry attempts (default: 3)
+            - temperature: Model temperature (default: 0.3)
+            - model: Model to use (optional)
+            - confidence_mode: "heuristic" or "none" (default: "heuristic")
+
+        Returns:
+            ClassifyHandle if no input (reusable)
+            ClassifyResult dict if input provided (one-shot)
+        """
+        if config is None:
+            raise TypeError("Classify requires a configuration table")
+
+        # Create a wrapper function that creates agents using _new_agent.
+        #
+        # Important: Classify creates internal agents that are not assigned to a Lua global,
+        # so they normally keep a random _temp_agent_* name. If the stdlib passes a stable
+        # `name` in the agent config, we rename the handle here so it can be mocked via
+        # `Mocks { <name> = { ... } }` in BDD specs.
+        def agent_factory(agent_config):
+            """Factory function to create Agent instances for Classify."""
+            desired_name = None
+            if isinstance(agent_config, dict):
+                desired_name = agent_config.get("name")
+
+            # Use _new_agent to create an agent handle
+            handle = _new_agent(agent_config)
+
+            # Apply stable naming for internal agents when requested.
+            if desired_name:
+                try:
+                    binding_callback(desired_name, handle)
+                except Exception:
+                    # Best-effort: naming is for mocking/traceability; do not break runtime
+                    pass
+            return handle
+
+        # Create the classify primitive with the agent factory
+        classify_primitive = ClassifyPrimitive(
+            agent_factory=agent_factory,
+            lua_table_from=None,  # Will be handled by result conversion
+            registry=builder.registry if hasattr(builder, "registry") else None,
+            mock_manager=mock_manager,
+        )
+
+        # Call the primitive with the config
+        return classify_primitive(lua_table_to_dict(config))
+
+    binding_callback = _make_binding_callback(
+        builder, _tool_registry, _agent_registry, _runtime_context
+    )
+
     return {
         # NEW SYNTAX (Phase B+)
         # Note: stdlib tools are accessed via require("tactus.tools.done") etc.
@@ -1960,6 +2045,7 @@ def create_dsl_stubs(
         "Prompt": _prompt,
         "Toolset": _toolset,
         "Tool": _new_tool,  # NEW syntax - assignment based
+        "Classify": _new_classify,  # NEW stdlib: smart classification with retry
         "Hitl": _hitl,
         "Specification": _specification,
         # BDD Testing
@@ -2012,9 +2098,7 @@ def create_dsl_stubs(
             "model": _model_registry,
         },
         # Assignment interception callback
-        "_tactus_register_binding": _make_binding_callback(
-            builder, _tool_registry, _agent_registry, _runtime_context
-        ),
+        "_tactus_register_binding": binding_callback,
     }