tactus 0.33.0__py3-none-any.whl → 0.34.0__py3-none-any.whl

tactus/sandbox/container_runner.py

@@ -20,7 +20,11 @@ from pathlib import Path
 from typing import Any, Callable, Dict, List, Optional
 
 from .config import SandboxConfig
-from .docker_manager import DockerManager, calculate_source_hash
+from .docker_manager import (
+    DockerManager,
+    calculate_source_hash,
+    resolve_dockerfile_path,
+)
 from .protocol import (
     ExecutionRequest,
     ExecutionResult,
@@ -146,14 +150,16 @@ class ContainerRunner:
         # container_runner.py is in tactus/sandbox/, so root is 2 levels up
         tactus_root = Path(__file__).parent.parent.parent
 
-        current_hash = calculate_source_hash(tactus_root)
+        dockerfile_path, build_mode = resolve_dockerfile_path(tactus_root)
+        current_hash = None
+        if build_mode == "source":
+            current_hash = calculate_source_hash(tactus_root)
+        else:
+            logger.info("[SANDBOX] No source tree detected, using PyPI-based sandbox image build")
 
         # Check if rebuild is needed
         if self.docker_manager.needs_rebuild(__version__, current_hash):
-            logger.info("Code changes detected, rebuilding sandbox...")
-
-            # Get paths
-            dockerfile_path = tactus_root / "tactus" / "docker" / "Dockerfile"
+            logger.info("Sandbox image missing or outdated, rebuilding...")
 
             # Build with source hash
             success, msg = self.docker_manager.build_image(
@@ -253,8 +259,8 @@ class ContainerRunner:
         if self.config.limits.cpus:
             cmd.extend(["--cpus", self.config.limits.cpus])
 
-        # Mount working directory
-        cmd.extend(["-v", f"{working_dir}:/workspace:rw"])
+        # Working directory mount is handled by SandboxConfig.add_default_volumes()
+        # which adds ".:/workspace:rw" to config.volumes (unless mount_current_dir=False)
 
         # Mount MCP servers if available
         if mcp_servers_path and mcp_servers_path.exists():
@@ -321,7 +327,7 @@ class ContainerRunner:
         container = parts[1]
         mode = parts[2] if len(parts) > 2 else None
 
-        host_is_path = host.startswith(("/", "./", "../", "~"))
+        host_is_path = host.startswith(("/", "./", "../", "~")) or host == "." or host == ".."
         if not host_is_path:
             # Named volume (or other special form) - leave unchanged
             return volume
@@ -344,6 +350,9 @@ class ContainerRunner:
         format: str = "lua",
         event_handler: Optional[Callable[[Dict[str, Any]], None]] = None,
         callback_url: Optional[str] = None,
+        run_id: Optional[str] = None,
+        control_handler: Optional[Callable[[dict], Any]] = None,
+        llm_backend_config: Optional[Dict[str, Any]] = None,
     ) -> ExecutionResult:
         """
         Execute a procedure in a sandboxed container.
@@ -355,6 +364,10 @@ class ContainerRunner:
             working_dir: Working directory to use (default: temp directory)
             format: Source format ("lua" for .tac files, "yaml" for legacy)
             event_handler: Optional host callback for streaming events from the container
+            callback_url: Optional HTTP callback URL for streaming events
+            run_id: Optional run ID for checkpoint isolation across executions
+            control_handler: Optional callback for handling container HITL requests
+            llm_backend_config: Optional config for broker's LLM backend (provider-agnostic)
 
         Returns:
             ExecutionResult with status, result/error, and metadata.
@@ -427,12 +440,18 @@ class ContainerRunner:
                         keyfile=self.config.broker_tls_key_file,
                     )
 
+                # Extract OpenAI-specific config if provided
+                openai_key = None
+                if llm_backend_config:
+                    openai_key = llm_backend_config.get("openai_api_key")
+
                 broker_server = TcpBrokerServer(
                     host=self.config.broker_bind_host,
                     port=self.config.broker_port,
                     ssl_context=ssl_context,
-                    openai_backend=OpenAIChatBackend(),
+                    openai_backend=OpenAIChatBackend(api_key=openai_key),
                     event_handler=event_handler,
+                    control_handler=control_handler,
                 )
                 await broker_server.start()
                 if broker_server.bound_port is None:
@@ -463,6 +482,7 @@ class ContainerRunner:
                 working_dir="/workspace",
                 params=params or {},
                 execution_id=execution_id,
+                run_id=run_id,
                 source_file_path=source_file_path,
                 format=format,
             )
@@ -487,6 +507,8 @@ class ContainerRunner:
                         request,
                         timeout=self.config.timeout,
                         event_handler=event_handler,
+                        control_handler=control_handler,
+                        llm_backend_config=llm_backend_config,
                     )
                 finally:
                     # Cancel broker task when container finishes
@@ -501,6 +523,8 @@ class ContainerRunner:
                     request,
                     timeout=self.config.timeout,
                     event_handler=event_handler,
+                    control_handler=control_handler,
+                    llm_backend_config=llm_backend_config,
                 )
 
             result.duration_seconds = time.time() - start_time
@@ -537,6 +561,8 @@ class ContainerRunner:
         request: ExecutionRequest,
         timeout: int,
         event_handler: Optional[Callable[[Dict[str, Any]], None]] = None,
+        control_handler: Optional[Callable[[dict], Any]] = None,
+        llm_backend_config: Optional[Dict[str, Any]] = None,
     ) -> ExecutionResult:
         """
         Run the container and communicate via stdio.
@@ -558,7 +584,13 @@ class ContainerRunner:
             from tactus.broker.stdio import STDIO_REQUEST_PREFIX
 
             stdio_request_prefix = STDIO_REQUEST_PREFIX
-            openai_backend = OpenAIChatBackend()
+
+            # Extract OpenAI-specific config if provided
+            openai_key = None
+            if llm_backend_config:
+                openai_key = llm_backend_config.get("openai_api_key")
+
+            openai_backend = OpenAIChatBackend(api_key=openai_key)
             tool_registry = HostToolRegistry.default()
 
             async def send_event(writer: asyncio.StreamWriter, event: dict[str, Any]) -> None:
@@ -602,6 +634,42 @@ class ContainerRunner:
                     await send_event(writer, {"id": req_id, "event": "done", "data": {"ok": True}})
                     return
 
+                if method == "control.request":
+                    request_data = params.get("request") if isinstance(params, dict) else None
+                    if control_handler is not None:
+                        try:
+                            # Send delivered event
+                            await send_event(writer, {"id": req_id, "event": "delivered"})
+
+                            # Call control handler and await response
+                            response_data = await control_handler(request_data)
+
+                            # Send response event
+                            await send_event(
+                                writer, {"id": req_id, "event": "response", "data": response_data}
+                            )
+                        except asyncio.TimeoutError:
+                            await send_event(
+                                writer,
+                                {"id": req_id, "event": "timeout", "data": {"timed_out": True}},
+                            )
+                        except Exception as e:
+                            logger.debug("[BROKER] control.request handler raised", exc_info=True)
+                            await send_event(
+                                writer,
+                                {"id": req_id, "event": "error", "error": {"message": str(e)}},
+                            )
+                    else:
+                        await send_event(
+                            writer,
+                            {
+                                "id": req_id,
+                                "event": "error",
+                                "error": {"message": "No control handler configured"},
+                            },
+                        )
+                    return
+
                 if method == "tool.call":
                     name = params.get("name") if isinstance(params, dict) else None
                     args = params.get("args") if isinstance(params, dict) else None

tactus/sandbox/docker_manager.py

@@ -18,6 +18,26 @@ DEFAULT_IMAGE_NAME = "tactus-sandbox"
 DEFAULT_IMAGE_TAG = "local"
 
 
+def resolve_dockerfile_path(tactus_root: Path) -> Tuple[Path, str]:
+    """
+    Choose the appropriate Dockerfile for the sandbox build.
+
+    Returns:
+        Tuple of (dockerfile_path, build_mode) where build_mode is "source" or "pypi".
+    """
+    docker_dir = tactus_root / "tactus" / "docker"
+    source_dockerfile = docker_dir / "Dockerfile"
+    pypi_dockerfile = docker_dir / "Dockerfile.pypi"
+    has_source_tree = (tactus_root / "pyproject.toml").exists() and (
+        tactus_root / "README.md"
+    ).exists()
+
+    if has_source_tree or not pypi_dockerfile.exists():
+        return source_dockerfile, "source"
+
+    return pypi_dockerfile, "pypi"
+
+
 def calculate_source_hash(tactus_root: Path) -> str:
     """
     Calculate hash of Tactus source files for change detection.
@@ -35,6 +55,7 @@ def calculate_source_hash(tactus_root: Path) -> str:
     paths_to_hash = [
         tactus_root / "tactus" / "dspy",
         tactus_root / "tactus" / "adapters",
+        tactus_root / "tactus" / "broker",  # Broker client used by sandbox
         tactus_root / "tactus" / "core",
         tactus_root / "tactus" / "primitives",
         tactus_root / "tactus" / "sandbox",
@@ -283,6 +304,8 @@ class DockerManager:
             self.full_image_name,
             "-f",
             str(dockerfile_path),
+            "--build-arg",
+            f"TACTUS_VERSION={version}",
             "--label",
             f"tactus.version={version}",
         ]

tactus/sandbox/entrypoint.py

@@ -85,6 +85,7 @@ async def execute_procedure(
     params: Dict[str, Any],
     source_file_path: Optional[str] = None,
     format: str = "lua",
+    run_id: Optional[str] = None,
 ) -> Any:
     """
     Execute a procedure using TactusRuntime.
@@ -96,6 +97,7 @@ async def execute_procedure(
         mcp_servers: MCP server configurations
         source_file_path: Original source file path
         format: Source format ("lua" or "yaml")
+        run_id: Run ID for checkpoint isolation
 
     Returns:
         Procedure execution result
@@ -105,6 +107,7 @@ async def execute_procedure(
     from tactus.adapters.broker_log import BrokerLogHandler
     from tactus.adapters.http_callback_log import HTTPCallbackLogHandler
     from tactus.adapters.cost_collector_log import CostCollectorLogHandler
+    from tactus.adapters.channels.broker import BrokerControlChannel
 
     # Create a unique procedure ID
     import uuid
@@ -129,6 +132,18 @@ async def execute_procedure(
             log_handler = CostCollectorLogHandler()
             logger.info("[SANDBOX] No callback configured; using CostCollectorLogHandler")
 
+    # Set up HITL control channel (broker-based in container mode)
+    broker_channel = BrokerControlChannel.from_environment()
+    hitl_handler = None
+    if broker_channel:
+        from tactus.adapters.control_loop import ControlLoopHandler, ControlLoopHITLAdapter
+
+        control_handler = ControlLoopHandler(channels=[broker_channel])
+        hitl_handler = ControlLoopHITLAdapter(control_handler)
+        logger.info("[SANDBOX] Using broker control channel for HITL")
+    else:
+        logger.debug("[SANDBOX] No broker control channel available, HITL disabled")
+
     # Create runtime with log handler for event streaming
     runtime = TactusRuntime(
         procedure_id=procedure_id,
@@ -137,6 +152,8 @@ async def execute_procedure(
         external_config={},
         source_file_path=source_file_path,
         log_handler=log_handler,  # Enable event streaming to IDE
+        hitl_handler=hitl_handler,  # Enable HITL control channel
+        run_id=run_id,  # Pass run_id for checkpoint isolation
     )
 
     # Execute procedure
@@ -146,6 +163,14 @@ async def execute_procedure(
         format=format,
     )
 
+    # CRITICAL: Flush pending log events before returning
+    # This ensures all streaming events reach the broker before container exits.
+    # Without this, fire-and-forget async tasks may be discarded.
+    if hasattr(log_handler, "flush"):
+        logger.info("[SANDBOX] Flushing pending log events...")
+        await log_handler.flush()
+        logger.info("[SANDBOX] Log events flushed")
+
     return result
 
 
@@ -179,6 +204,7 @@ async def main_async() -> int:
             params=request.params,
             source_file_path=request.source_file_path,
             format=request.format,
+            run_id=request.run_id,
         )
 
         # Create success result

tactus/sandbox/protocol.py

@@ -51,6 +51,9 @@ class ExecutionRequest:
     # Unique execution ID for tracking
     execution_id: Optional[str] = None
 
+    # Run ID for checkpoint isolation across multiple executions
+    run_id: Optional[str] = None
+
     # Source file path (for error messages)
     source_file_path: Optional[str] = None
 

tactus/stdlib/README.md

@@ -0,0 +1,77 @@
+# Tactus Standard Library
+
+The Tactus standard library provides reusable primitives for building AI agents and classification workflows.
+
+## Architecture
+
+The stdlib follows the **Dogfooding with BDD Specs as Contract** principle:
+
+1. **BDD specs define behavior** - Each primitive has comprehensive `.spec.tac` files
+2. **Implementation is secondary** - Python, Tactus, or mix - doesn't matter if specs pass
+3. **Specs serve triple duty** - Tests, documentation, and contract
+
+## Structure
+
+```
+tactus/stdlib/
+├── classify/
+│   ├── classify.tac          # Tactus implementation (reference)
+│   ├── classify.spec.tac     # BDD specifications (THE CONTRACT)
+│   ├── primitive.py           # Current Python implementation
+│   ├── llm.py                 # LLM-based classifier
+│   └── fuzzy.py               # Fuzzy string matching
+```
+
+## Testing
+
+Run all stdlib specs:
+```bash
+tactus stdlib test
+```
+
+Run specific primitive specs:
+```bash
+tactus test tactus/stdlib/classify/classify.spec.tac
+```
+
+## Documentation
+
+Each `.spec.tac` file contains:
+- `--[[doc]]` blocks with usage documentation
+- `--[[doc:parameter name]]` blocks with parameter documentation
+- BDD scenarios showing expected behavior
+- Custom step definitions for the tests
+
+## Example: Classify
+
+The Classify primitive demonstrates the stdlib pattern:
+
+**Specifications** ([classify.spec.tac](classify/classify.spec.tac)):
+- 7 BDD scenarios covering LLM and fuzzy matching
+- Documentation blocks explaining usage and parameters
+- Custom steps for testing classification behavior
+
+**Current Status**:
+- ✅ Specs pass with Python implementation
+- ✅ Tactus reference implementation exists
+- 🔜 Module loading system needed to use Tactus impl
+
+## Adding New Primitives
+
+1. Create `primitive-name/` directory
+2. Write `primitive-name.spec.tac` with:
+   - `--[[doc]]` documentation blocks
+   - Custom step definitions
+   - Comprehensive BDD scenarios
+3. Implement in Python (for now) or Tactus (when module loading ready)
+4. Ensure `tactus test` passes
+
+## CI Integration
+
+```yaml
+# .github/workflows/stdlib.yml
+- name: Test Standard Library
+  run: tactus stdlib test --verbose
+```
+
+All stdlib specs must pass before merge.

tactus/stdlib/__init__.py

@@ -1,6 +1,27 @@
 """Tactus Standard Library.
 
-The standard library consists of .tac files in the tac/ subdirectory.
+The standard library provides high-level primitives for common AI tasks:
+
+## Primitives (injected into Lua)
+
+### Classify - Smart classification with retry logic
+    result = Classify {
+        classes = {"Yes", "No"},
+        prompt = "Did the agent greet the customer?",
+        input = transcript
+    }
+    -- result.value = "Yes"
+    -- result.confidence = 0.92
+    -- result.explanation = "The agent said 'Hello'..."
+
+### Coming Soon
+- Extract: Schema-based information extraction with validation
+- Match: Fuzzy matching verification
+- Generate: Constrained generation with validation
+
+## Utility Modules (via require)
+
+The standard library also includes .tac files in the tac/ subdirectory.
 These are loaded via Lua's require() function:
 
     local done = require("tactus.tools.done")
@@ -8,3 +29,8 @@ These are loaded via Lua's require() function:
 
 See tactus/stdlib/tac/ for available modules.
 """
+
+from .classify import ClassifyPrimitive
+from .extract import ExtractPrimitive
+
+__all__ = ["ClassifyPrimitive", "ExtractPrimitive"]

tactus/stdlib/classify/__init__.py

@@ -0,0 +1,165 @@
+"""
+Tactus Standard Library - Classify Primitive
+
+Provides smart classification with built-in retry logic, validation,
+and confidence extraction.
+
+## Quick Start
+
+    -- Simple binary classification
+    result = Classify {
+        classes = {"Yes", "No"},
+        prompt = "Did the agent greet the customer?",
+        input = transcript
+    }
+    -- result.value = "Yes"
+    -- result.confidence = 0.92
+    -- result.explanation = "The agent said 'Hello'..."
+
+## Reusable Classifier
+
+Create a classifier once and use it multiple times:
+
+    sentiment = Classify {
+        classes = {"positive", "negative", "neutral"},
+        prompt = "What is the sentiment of this text?"
+    }
+    result1 = sentiment(text1)
+    result2 = sentiment(text2)
+
+## Configuration Options
+
+| Option          | Type     | Default    | Description                          |
+|-----------------|----------|------------|--------------------------------------|
+| classes         | table    | (required) | Valid classification values          |
+| prompt          | string   | (required) | Classification instruction           |
+| input           | string   | nil        | Input for one-shot classification    |
+| max_retries     | number   | 3          | Max retry attempts on invalid output |
+| temperature     | number   | 0.3        | LLM temperature for classification   |
+| model           | string   | nil        | Override default model               |
+| confidence_mode | string   | "heuristic"| "heuristic" or "none"               |
+
+## Return Value
+
+The Classify primitive returns a result with:
+
+| Field       | Type    | Description                              |
+|-------------|---------|------------------------------------------|
+| value       | string  | The classification (e.g., "Yes", "No")   |
+| confidence  | number  | Confidence score (0.0 - 1.0) or nil      |
+| explanation | string  | LLM's reasoning for the classification   |
+| retry_count | number  | Number of retries needed                 |
+| error       | string  | Error message if classification failed   |
+
+## Retry Logic
+
+When the LLM returns an invalid classification (not in the `classes` list),
+Classify automatically retries with conversational feedback:
+
+1. First attempt: Send classification request
+2. If invalid: Send feedback message with valid options
+3. Repeat until valid classification or max_retries exceeded
+
+This mimics the LangGraphScore retry pattern where the LLM sees its
+previous mistake and can self-correct.
+
+## Confidence Extraction
+
+In "heuristic" mode (default), confidence is extracted from response text:
+
+- High (0.95): "definitely", "certainly", "clearly", "absolutely"
+- Medium-high (0.80): "likely", "probably", "appears to be"
+- Low (0.50): "possibly", "might be", "uncertain"
+- Default (0.75): When no indicators found
+
+Set `confidence_mode = "none"` to disable confidence extraction.
+
+## Examples
+
+### Binary Classification with NA
+
+    result = Classify {
+        classes = {"Yes", "No", "NA"},
+        prompt = "Did the agent provide the required information?",
+        input = transcript
+    }
+
+### Multi-class with Custom Temperature
+
+    urgency = Classify {
+        classes = {"critical", "high", "medium", "low"},
+        prompt = "What is the urgency level of this support ticket?",
+        temperature = 0.1,  -- More deterministic
+        max_retries = 5     -- More attempts for complex classification
+    }
+    result = urgency(ticket_text)
+
+### Sentiment Analysis
+
+    sentiment = Classify {
+        classes = {"positive", "negative", "neutral", "mixed"},
+        prompt = [[
+            Analyze the overall sentiment of the customer feedback.
+            Consider both explicit statements and implicit tone.
+        ]],
+    }
+
+    for _, review in ipairs(reviews) do
+        local result = sentiment(review.text)
+        Log.info("Review sentiment: " .. result.value)
+    end
+
+### Fuzzy String Matching
+
+For string similarity matching (finding the best match from a list):
+
+    -- Match school names with variations
+    local FuzzyClassifier = require("tactus.stdlib.classify.fuzzy")
+
+    local school_matcher = FuzzyClassifier {
+        classes = {
+            "United Education Institute",
+            "Abilene Christian University",
+            "Arizona School of Integrative Studies"
+        },
+        threshold = 0.75,
+        algorithm = "token_set_ratio"  -- Handles reordered tokens
+    }
+
+    local result = school_matcher("Institute Education United Dallas")
+    -- result.value = "United Education Institute"
+    -- result.matched_text = "United Education Institute"
+    -- result.confidence = 0.82
+
+Available algorithms:
+- `ratio`: Character-level similarity (default, best for exact matches)
+- `token_set_ratio`: Tokenizes and compares unique words (handles reordering)
+- `token_sort_ratio`: Sorts tokens before comparing (handles reordering)
+- `partial_ratio`: Best substring match (good for partial text)
+
+Binary mode (Yes/No matching):
+
+    local matcher = FuzzyClassifier {
+        expected = "Customer Service",
+        threshold = 0.8,
+        algorithm = "token_set_ratio"
+    }
+
+    local result = matcher("Service for Customers")
+    -- result.value = "Yes" (matched)
+    -- result.matched_text = "Customer Service" (what it matched against)
+"""
+
+from .primitive import ClassifyPrimitive, ClassifyHandle
+from .llm import LLMClassifier
+from .fuzzy import FuzzyMatchClassifier, FuzzyClassifier
+from ..core.models import ClassifierResult
+
+__all__ = [
+    "ClassifyPrimitive",
+    "ClassifyHandle",
+    "ClassifierResult",
+    "LLMClassifier",
+    "FuzzyMatchClassifier",
+    "FuzzyClassifier",
+]