tactus 0.37.0__py3-none-any.whl → 0.39.0__py3-none-any.whl

tactus/primitives/handles.py

@@ -222,7 +222,7 @@ class AgentHandle:
         return f"AgentHandle('{self.name}', {connected})"
 
 
-class ModelHandle:
+class ModelHandle:
     """
     Lightweight handle returned by model() DSL function.
 
@@ -303,12 +303,84 @@ class ModelHandle:
         self._primitive = primitive
         logger.debug("ModelHandle '%s' connected to primitive", self.name)
 
-    def __repr__(self) -> str:
-        connected = "connected" if self._primitive else "disconnected"
-        return f"ModelHandle('{self.name}', {connected})"
-
-
-class AgentLookup:
+    def __repr__(self) -> str:
+        connected = "connected" if self._primitive else "disconnected"
+        return f"ModelHandle('{self.name}', {connected})"
+
+
+class ContextHandle:
+    """
+    Lightweight handle returned by Context DSL declarations.
+    """
+
+    def __init__(self, name: str):
+        """
+        Initialize context handle.
+
+        Args:
+            name: Context name (string identifier)
+        """
+        self.name = name
+
+    def __repr__(self) -> str:
+        return f"ContextHandle('{self.name}')"
+
+
+class CorpusHandle:
+    """
+    Lightweight handle returned by Corpus DSL declarations.
+    """
+
+    def __init__(self, name: str):
+        """
+        Initialize corpus handle.
+
+        Args:
+            name: Corpus name (string identifier)
+        """
+        self.name = name
+
+    def __repr__(self) -> str:
+        return f"CorpusHandle('{self.name}')"
+
+
+class RetrieverHandle:
+    """
+    Lightweight handle returned by Retriever DSL declarations.
+    """
+
+    def __init__(self, name: str):
+        """
+        Initialize retriever handle.
+
+        Args:
+            name: Retriever name (string identifier)
+        """
+        self.name = name
+
+    def __repr__(self) -> str:
+        return f"RetrieverHandle('{self.name}')"
+
+
+class CompactorHandle:
+    """
+    Lightweight handle returned by Compactor DSL declarations.
+    """
+
+    def __init__(self, name: str):
+        """
+        Initialize compactor handle.
+
+        Args:
+            name: Compactor name (string identifier)
+        """
+        self.name = name
+
+    def __repr__(self) -> str:
+        return f"CompactorHandle('{self.name}')"
+
+
+class AgentLookup:
     """
     Agent lookup primitive - provides Agent("name") lookup functionality.
 

tactus/sandbox/config.py

@@ -113,7 +113,7 @@ class SandboxConfig(BaseModel):
 
     # Development mode: mount live Tactus source code
     dev_mode: bool = Field(
-        default=False,
+        default=True,
         description="Enable development mode: mount live Tactus source code instead of using baked-in version",
     )
 

tactus/sandbox/container_runner.py

@@ -358,6 +358,7 @@ class ContainerRunner:
         source_file_path: Optional[str] = None,
         working_dir: Optional[Path] = None,
         format: str = "lua",
+        task_name: Optional[str] = None,
         event_handler: Optional[Callable[[Dict[str, Any]], None]] = None,
         callback_url: Optional[str] = None,
         run_id: Optional[str] = None,
@@ -497,6 +498,7 @@ class ContainerRunner:
                 run_id=run_id,
                 source_file_path=source_file_path,
                 format=format,
+                task_name=task_name,
             )
 
             # Run container

tactus/sandbox/entrypoint.py

@@ -86,6 +86,7 @@ async def execute_procedure(
     source_file_path: Optional[str] = None,
     format: str = "lua",
     run_id: Optional[str] = None,
+    task_name: Optional[str] = None,
 ) -> Any:
     """
     Execute a procedure using TactusRuntime.
@@ -163,6 +164,7 @@ async def execute_procedure(
         source=source,
         context=params,
         format=format,
+        task_name=task_name,
     )
 
     # CRITICAL: Flush pending log events before returning
@@ -181,6 +183,7 @@ async def main_async() -> int:
     from tactus.sandbox.protocol import (
         ExecutionRequest,
         ExecutionResult,
+        ExecutionStatus,
     )
 
     start_time = time.time()
@@ -200,14 +203,54 @@ async def main_async() -> int:
         request = ExecutionRequest(**request_data)
         logger.info("Executing procedure (id=%s)", request.execution_id)
 
-        # Execute procedure
-        proc_result = await execute_procedure(
-            source=request.source,
-            params=request.params,
-            source_file_path=request.source_file_path,
-            format=request.format,
-            run_id=request.run_id,
-        )
+        try:
+            # Execute procedure
+            proc_result = await execute_procedure(
+                source=request.source,
+                params=request.params,
+                source_file_path=request.source_file_path,
+                format=request.format,
+                run_id=request.run_id,
+                task_name=request.task_name,
+            )
+        except Exception as exc:
+            # Provide structured results for common control-flow exceptions.
+            from tactus.core.exceptions import ProcedureWaitingForHuman, TaskSelectionRequired
+
+            duration = time.time() - start_time
+
+            if isinstance(exc, TaskSelectionRequired):
+                result = ExecutionResult.failure(
+                    error=str(exc),
+                    error_type=type(exc).__name__,
+                    traceback=None,
+                    duration_seconds=duration,
+                    exit_code=2,
+                    metadata={"tasks": list(exc.tasks)},
+                )
+                write_result_to_stdout(result)
+                return 2
+
+            if isinstance(exc, ProcedureWaitingForHuman):
+                result = ExecutionResult(
+                    status=ExecutionStatus.CANCELLED,
+                    result=None,
+                    error=str(exc),
+                    error_type=type(exc).__name__,
+                    traceback=None,
+                    duration_seconds=duration,
+                    exit_code=0,
+                    logs=[],
+                    metadata={
+                        "waiting_for_human": True,
+                        "procedure_id": exc.procedure_id,
+                        "pending_message_id": exc.pending_message_id,
+                    },
+                )
+                write_result_to_stdout(result)
+                return 0
+
+            raise
 
         # Create success result
         duration = time.time() - start_time

tactus/sandbox/protocol.py

@@ -60,6 +60,9 @@ class ExecutionRequest:
     # Source format: "lua" for .tac files, "yaml" for legacy YAML format
     format: str = "lua"
 
+    # Optional task name to execute
+    task_name: Optional[str] = None
+
     def to_json(self) -> str:
         """Serialize to JSON string."""
         return json.dumps(asdict(self), indent=None, separators=(",", ":"))
@@ -148,6 +151,7 @@ class ExecutionResult:
         duration_seconds: float = 0.0,
         exit_code: int = 1,
         logs: Optional[list[dict[str, Any]]] = None,
+        metadata: Optional[dict[str, Any]] = None,
     ) -> "ExecutionResult":
         """Create a failed result."""
         return cls(
@@ -158,6 +162,7 @@ class ExecutionResult:
             duration_seconds=duration_seconds,
             exit_code=exit_code,
             logs=logs or [],
+            metadata=metadata or {},
         )
 
     @classmethod

tactus/stdlib/README.md

@@ -22,6 +22,15 @@ tactus/stdlib/
 │   └── fuzzy.py               # Fuzzy string matching
 ```
 
+## Available Modules
+
+- `tactus.classify` - LLM and fuzzy classification
+- `tactus.extract` - Structured extraction utilities
+- `tactus.generate` - LLM-based generation helpers
+- `tactus.io.*` - File I/O helpers (json, csv, tsv, file)
+- `biblicus.text` - Biblicus-backed text utilities
+- `tactus.retrievers.*` - Biblicus-backed retrievers
+
 ## Testing
 
 Run all stdlib specs:
@@ -54,7 +63,7 @@ The Classify primitive demonstrates the stdlib pattern:
 **Current Status**:
 - ✅ Specs pass with Python implementation
 - ✅ Tactus reference implementation exists
-- 🔜 Module loading system needed to use Tactus impl
+- Next: Module loading system needed to use Tactus impl
 
 ## Adding New Primitives
 

tactus/stdlib/biblicus/__init__.py

@@ -0,0 +1,3 @@
+"""
+Biblicus-backed standard library modules.
+"""

tactus/stdlib/biblicus/text.py

@@ -0,0 +1,208 @@
+"""
+tactus.biblicus.text - Biblicus text utilities for Tactus.
+
+This module exposes Biblicus text helpers to Lua via the stdlib loader.
+"""
+
+from __future__ import annotations
+
+import os
+from typing import Any, Dict, List
+
+
+def _require_biblicus_text() -> Dict[str, Any]:
+    try:
+        from biblicus.ai.models import LlmClientConfig
+        from biblicus.text import (
+            apply_text_annotate,
+            apply_text_extract,
+            apply_text_link,
+            apply_text_redact,
+            apply_text_slice,
+        )
+        from biblicus.text.markup import (
+            parse_span_markup,
+            strip_span_tags,
+            summarize_span_context,
+        )
+        from biblicus.text.models import (
+            TextAnnotateRequest,
+            TextExtractRequest,
+            TextLinkRequest,
+            TextRedactRequest,
+            TextSliceRequest,
+        )
+    except ModuleNotFoundError as exc:
+        raise ValueError(
+            "Biblicus text utilities are unavailable. Install a Biblicus build "
+            "that includes biblicus.text to use the text stdlib."
+        ) from exc
+
+    return {
+        "LlmClientConfig": LlmClientConfig,
+        "apply_text_annotate": apply_text_annotate,
+        "apply_text_extract": apply_text_extract,
+        "apply_text_link": apply_text_link,
+        "apply_text_redact": apply_text_redact,
+        "apply_text_slice": apply_text_slice,
+        "parse_span_markup": parse_span_markup,
+        "strip_span_tags": strip_span_tags,
+        "summarize_span_context": summarize_span_context,
+        "TextAnnotateRequest": TextAnnotateRequest,
+        "TextExtractRequest": TextExtractRequest,
+        "TextLinkRequest": TextLinkRequest,
+        "TextRedactRequest": TextRedactRequest,
+        "TextSliceRequest": TextSliceRequest,
+    }
+
+
+def _normalize_client_config(client: Any) -> Any:
+    if not isinstance(client, dict):
+        raise ValueError("client must be a table with provider and model")
+
+    payload = dict(client)
+    model = payload.get("model")
+    if not model:
+        raise ValueError("client.model is required")
+
+    provider, model = _resolve_provider_and_model(payload.get("provider"), model)
+    payload["provider"] = provider
+    payload["model"] = model
+
+    biblicus = _require_biblicus_text()
+    return biblicus["LlmClientConfig"](**payload)
+
+
+def _resolve_provider_and_model(provider: str | None, model: Any) -> tuple[str, Any]:
+    if provider is None and isinstance(model, str) and "/" in model:
+        provider, model = model.split("/", 1)
+    elif provider is not None and isinstance(model, str) and model.startswith(f"{provider}/"):
+        model = model.split("/", 1)[1]
+
+    if provider is None:
+        raise ValueError("client.provider is required when model lacks a provider prefix")
+
+    return provider, model
+
+
+def _prepare_request(request: Dict[str, Any]) -> Dict[str, Any]:
+    if not isinstance(request, dict):
+        raise ValueError("request must be a table")
+
+    payload = dict(request)
+    mock_mode = os.environ.get("TACTUS_MOCK_MODE")
+    if mock_mode == "0":
+        payload.pop("mock_marked_up_text", None)
+    client = payload.get("client")
+    if client is None:
+        raise ValueError("client is required")
+    payload["client"] = _normalize_client_config(client)
+    return payload
+
+
+def _maybe_mock(tool_name: str, payload: Dict[str, Any]) -> Dict[str, Any] | None:
+    mock_manager = _get_mock_manager()
+    if mock_manager is None:
+        return None
+    mock_result = mock_manager.get_mock_response(tool_name, payload)
+    if mock_result is None:
+        return None
+    mock_manager.record_call(tool_name, payload, mock_result)
+    return mock_result
+
+
+def _get_mock_manager() -> Any | None:
+    try:
+        from tactus.core.mocking import get_current_mock_manager
+    except Exception:
+        return None
+    return get_current_mock_manager()
+
+
+def _run_text_tool(
+    request: Dict[str, Any],
+    *,
+    tool_name: str,
+    request_model_key: str,
+    apply_key: str,
+) -> Dict[str, Any]:
+    payload = _prepare_request(request)
+    mock_result = _maybe_mock(tool_name, payload)
+    if mock_result is not None:
+        return mock_result
+    biblicus = _require_biblicus_text()
+    result = biblicus[apply_key](biblicus[request_model_key](**payload))
+    return result.model_dump()
+
+
+def extract(request: Dict[str, Any]) -> Dict[str, Any]:
+    return _run_text_tool(
+        request,
+        tool_name="biblicus.text.extract",
+        request_model_key="TextExtractRequest",
+        apply_key="apply_text_extract",
+    )
+
+
+def slice(request: Dict[str, Any]) -> Dict[str, Any]:
+    return _run_text_tool(
+        request,
+        tool_name="biblicus.text.slice",
+        request_model_key="TextSliceRequest",
+        apply_key="apply_text_slice",
+    )
+
+
+def annotate(request: Dict[str, Any]) -> Dict[str, Any]:
+    return _run_text_tool(
+        request,
+        tool_name="biblicus.text.annotate",
+        request_model_key="TextAnnotateRequest",
+        apply_key="apply_text_annotate",
+    )
+
+
+def redact(request: Dict[str, Any]) -> Dict[str, Any]:
+    return _run_text_tool(
+        request,
+        tool_name="biblicus.text.redact",
+        request_model_key="TextRedactRequest",
+        apply_key="apply_text_redact",
+    )
+
+
+def link(request: Dict[str, Any]) -> Dict[str, Any]:
+    return _run_text_tool(
+        request,
+        tool_name="biblicus.text.link",
+        request_model_key="TextLinkRequest",
+        apply_key="apply_text_link",
+    )
+
+
+def strip_span_tags(marked_up_text: str) -> str:
+    biblicus = _require_biblicus_text()
+    return biblicus["strip_span_tags"](marked_up_text)
+
+
+def parse_span_markup(marked_up_text: str) -> List[Dict[str, Any]]:
+    biblicus = _require_biblicus_text()
+    spans = biblicus["parse_span_markup"](marked_up_text)
+    return [span.model_dump() for span in spans]
+
+
+def summarize_span_context(marked_up_text: str, span_indices: List[int]) -> List[str]:
+    biblicus = _require_biblicus_text()
+    return biblicus["summarize_span_context"](marked_up_text, span_indices)
+
+
+__tactus_exports__ = [
+    "extract",
+    "slice",
+    "annotate",
+    "redact",
+    "link",
+    "strip_span_tags",
+    "parse_span_markup",
+    "summarize_span_context",
+]

tactus/stdlib/tac/biblicus/text.tac

@@ -0,0 +1,32 @@
+--[[doc
+# biblicus.text
+
+Biblicus-powered text utilities for Tactus.
+
+This module exposes Biblicus text helpers through the Tactus stdlib. It mirrors
+the Biblicus request/response shapes while keeping configuration in Tactus.
+
+## Usage
+
+```lua
+local text = require("biblicus.text")
+
+local result = text.extract({
+    text = "Alice met Bob in Paris.",
+    client = {
+        provider = "openai",
+        model = "gpt-4o-mini"
+    },
+    prompt_template = "Extract the person names in the text.",
+})
+```
+
+## Testing hook
+
+For deterministic tests, use Tactus `Mocks {}` to return stable Biblicus
+results without touching the model.
+]]
+
+local text = require("tactus.biblicus.text")
+
+return text

tactus/stdlib/tac/tactus/biblicus.spec.tac

@@ -0,0 +1,179 @@
+--[[doc
+# Biblicus Text Utilities
+
+This specification covers the Biblicus-backed `biblicus.text` stdlib module.
+It exercises the deterministic mock path plus markup helper functions.
+]]
+
+local text = require("biblicus.text")
+
+local test_state = {}
+local function build_request(text_value)
+    local client = {
+        provider = "openai",
+        model = "gpt-4o-mini"
+    }
+    return {
+        text = text_value,
+        client = client,
+        prompt_template = "Return only the updated markup."
+    }
+end
+
+Step("a biblicus request for \"(.+)\"", function(ctx, raw_text)
+    test_state.request = build_request(raw_text)
+end)
+
+Step("I apply mock extraction markup \"(.+)\"", function(ctx, markup)
+    local request = test_state.request
+    request.mock_marked_up_text = markup
+    local ok, result = pcall(text.extract, request)
+    assert(ok, "text.extract failed: " .. tostring(result))
+    test_state.result = result
+end)
+
+Step("the extracted span should be \"(.+)\"", function(ctx, expected)
+    local spans = test_state.result.spans or {}
+    assert(#spans == 1, "Expected one span")
+    assert(spans[1].text == expected,
+        "Expected span text '" .. expected .. "' but got '" .. tostring(spans[1].text) .. "'")
+end)
+
+Step("I apply mock annotation markup \"(.+)\"", function(ctx, markup)
+    local request = test_state.request
+    request.mock_marked_up_text = markup
+    local ok, result = pcall(text.annotate, request)
+    assert(ok, "text.annotate failed: " .. tostring(result))
+    test_state.result = result
+end)
+
+Step("the annotation span label should be \"(.+)\"", function(ctx, expected)
+    local spans = test_state.result.spans or {}
+    assert(#spans == 1, "Expected one span")
+    assert(spans[1].attributes.label == expected,
+        "Expected label '" .. expected .. "' but got '" .. tostring(spans[1].attributes.label) .. "'")
+end)
+
+Step("I apply mock link markup \"(.+)\"", function(ctx, markup)
+    local request = test_state.request
+    request.mock_marked_up_text = markup
+    request.id_prefix = "link_"
+    local ok, result = pcall(text.link, request)
+    assert(ok, "text.link failed: " .. tostring(result))
+    test_state.result = result
+end)
+
+Step("the link spans should include ids", function(ctx)
+    local spans = test_state.result.spans or {}
+    assert(#spans == 2, "Expected two spans")
+    assert(spans[1].attributes.id == "link_1", "Expected first span id link_1")
+    assert(spans[2].attributes.ref == "link_1", "Expected second span ref link_1")
+end)
+
+Step("I apply mock redaction markup \"(.+)\"", function(ctx, markup)
+    local request = test_state.request
+    request.mock_marked_up_text = markup
+    local ok, result = pcall(text.redact, request)
+    assert(ok, "text.redact failed: " .. tostring(result))
+    test_state.result = result
+end)
+
+Step("the redaction should return one span", function(ctx)
+    local spans = test_state.result.spans or {}
+    assert(#spans == 1, "Expected one redaction span")
+end)
+
+Step("I apply mock slice markup \"(.+)\"", function(ctx, markup)
+    local request = test_state.request
+    request.mock_marked_up_text = markup
+    local ok, result = pcall(text.slice, request)
+    assert(ok, "text.slice failed: " .. tostring(result))
+    test_state.result = result
+end)
+
+Step("the slices should be \"(.+)\" and \"(.+)\"", function(ctx, first, second)
+    local slices = test_state.result.slices or {}
+    assert(#slices == 2, "Expected two slices")
+    assert(slices[1].text == first, "Expected first slice '" .. first .. "'")
+    assert(slices[2].text == second, "Expected second slice '" .. second .. "'")
+end)
+
+Step("I strip span tags from \"(.+)\"", function(ctx, markup)
+    test_state.cleaned = text.strip_span_tags(markup)
+end)
+
+Step("the stripped text should be \"(.+)\"", function(ctx, expected)
+    assert(test_state.cleaned == expected,
+        "Expected stripped text '" .. expected .. "' but got '" .. tostring(test_state.cleaned) .. "'")
+end)
+
+Step("I parse spans from \"(.+)\"", function(ctx, markup)
+    test_state.parsed_spans = text.parse_span_markup(markup)
+end)
+
+Step("the parsed span text should be \"(.+)\"", function(ctx, expected)
+    local spans = test_state.parsed_spans or {}
+    assert(#spans == 1, "Expected one parsed span")
+    assert(spans[1].text == expected,
+        "Expected span text '" .. expected .. "' but got '" .. tostring(spans[1].text) .. "'")
+end)
+
+Step("I summarize span 1 from \"(.+)\"", function(ctx, markup)
+    local summaries = text.summarize_span_context(markup, {1})
+    test_state.summary = summaries[1]
+end)
+
+Step("the summary should be \"(.+)\"", function(ctx, expected)
+    assert(test_state.summary == expected,
+        "Expected summary '" .. expected .. "' but got '" .. tostring(test_state.summary) .. "'")
+end)
+
+Specification([[
+Feature: Biblicus Text Utilities
+  As a Tactus developer
+  I want to access Biblicus text utilities from the stdlib
+  So that I can reuse Biblicus text processing in workflows
+
+  Scenario: Extract spans from mock markup
+    Given a biblicus request for "Alice met Bob."
+    When I apply mock extraction markup "Alice met <span>Bob</span>."
+    Then the extracted span should be "Bob"
+
+  Scenario: Annotate spans with attributes
+    Given a biblicus request for "Ada wrote code."
+    When I apply mock annotation markup "Ada wrote <span label=\"artifact\">code</span>."
+    Then the annotation span label should be "artifact"
+
+  Scenario: Link repeated spans
+    Given a biblicus request for "Alice met Bob and Bob waved."
+    When I apply mock link markup "Alice met <span id=\"link_1\">Bob</span> and <span ref=\"link_1\">Bob</span> waved."
+    Then the link spans should include ids
+
+  Scenario: Redact spans without types
+    Given a biblicus request for "The secret is safe."
+    When I apply mock redaction markup "The <span>secret</span> is safe."
+    Then the redaction should return one span
+
+  Scenario: Slice text into segments
+    Given a biblicus request for "First sentence. Second sentence."
+    When I apply mock slice markup "First sentence.<slice/> Second sentence."
+    Then the slices should be "First sentence." and " Second sentence."
+
+  Scenario: Use markup helpers
+    Given a biblicus request for "Ignored."
+    When I strip span tags from "Hello <span>world</span>."
+    Then the stripped text should be "Hello world."
+    When I parse spans from "Hello <span>world</span>."
+    Then the parsed span text should be "world"
+    When I summarize span 1 from "Hello <span>world</span>."
+    Then the summary should be "Span 1: world"
+]])
+
+Procedure {
+    output = {
+        result = field.string{required = true}
+    },
+    function(input)
+        return {result = "Biblicus text stdlib specs executed"}
+    end
+}