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

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,189 @@
+"""
+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")
+    provider = payload.get("provider")
+    if not model:
+        raise ValueError("client.model is required")
+
+    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")
+
+    payload["provider"] = provider
+    payload["model"] = model
+
+    biblicus = _require_biblicus_text()
+    return biblicus["LlmClientConfig"](**payload)
+
+
+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:
+    try:
+        from tactus.core.mocking import get_current_mock_manager
+    except Exception:
+        return None
+    mock_manager = get_current_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 extract(request: Dict[str, Any]) -> Dict[str, Any]:
+    payload = _prepare_request(request)
+    mock_result = _maybe_mock("biblicus.text.extract", payload)
+    if mock_result is not None:
+        return mock_result
+    biblicus = _require_biblicus_text()
+    result = biblicus["apply_text_extract"](biblicus["TextExtractRequest"](**payload))
+    return result.model_dump()
+
+
+def slice(request: Dict[str, Any]) -> Dict[str, Any]:
+    payload = _prepare_request(request)
+    mock_result = _maybe_mock("biblicus.text.slice", payload)
+    if mock_result is not None:
+        return mock_result
+    biblicus = _require_biblicus_text()
+    result = biblicus["apply_text_slice"](biblicus["TextSliceRequest"](**payload))
+    return result.model_dump()
+
+
+def annotate(request: Dict[str, Any]) -> Dict[str, Any]:
+    payload = _prepare_request(request)
+    mock_result = _maybe_mock("biblicus.text.annotate", payload)
+    if mock_result is not None:
+        return mock_result
+    biblicus = _require_biblicus_text()
+    result = biblicus["apply_text_annotate"](biblicus["TextAnnotateRequest"](**payload))
+    return result.model_dump()
+
+
+def redact(request: Dict[str, Any]) -> Dict[str, Any]:
+    payload = _prepare_request(request)
+    mock_result = _maybe_mock("biblicus.text.redact", payload)
+    if mock_result is not None:
+        return mock_result
+    biblicus = _require_biblicus_text()
+    result = biblicus["apply_text_redact"](biblicus["TextRedactRequest"](**payload))
+    return result.model_dump()
+
+
+def link(request: Dict[str, Any]) -> Dict[str, Any]:
+    payload = _prepare_request(request)
+    mock_result = _maybe_mock("biblicus.text.link", payload)
+    if mock_result is not None:
+        return mock_result
+    biblicus = _require_biblicus_text()
+    result = biblicus["apply_text_link"](biblicus["TextLinkRequest"](**payload))
+    return result.model_dump()
+
+
+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
+}

tactus/stdlib/tac/tactus/corpora/base.tac

@@ -0,0 +1,42 @@
+local function merge_defaults(defaults, config)
+  local merged = {}
+  if defaults then
+    for key, value in pairs(defaults) do
+      merged[key] = value
+    end
+  end
+  if config then
+    for key, value in pairs(config) do
+      merged[key] = value
+    end
+  end
+  return merged
+end
+
+local function normalize_corpus_config(config, defaults)
+  local merged = merge_defaults(defaults, config or {})
+  if merged.root ~= nil and merged.corpus_root == nil then
+    merged.corpus_root = merged.root
+    merged.root = nil
+  end
+  return merged
+end
+
+local function wrap_corpus(defaults)
+  local function constructor(config)
+    return _tactus_internal_corpus(normalize_corpus_config(config, defaults))
+  end
+  local cls = {}
+  function cls:new(config)
+    return constructor(config)
+  end
+  return setmetatable(cls, {
+    __call = function(_, config)
+      return constructor(config)
+    end,
+  })
+end
+
+return {
+  wrap_corpus = wrap_corpus,
+}

tactus/stdlib/tac/tactus/corpora/filesystem.tac

@@ -0,0 +1,5 @@
+local base = require("tactus.corpora.base")
+
+return {
+  Corpus = base.wrap_corpus({}),
+}

tactus/stdlib/tac/tactus/retrievers/base.tac

@@ -0,0 +1,37 @@
+local function merge_defaults(defaults, config)
+  local merged = {}
+  if defaults then
+    for key, value in pairs(defaults) do
+      merged[key] = value
+    end
+  end
+  if config then
+    for key, value in pairs(config) do
+      merged[key] = value
+    end
+  end
+  return merged
+end
+
+local corpora_base = require("tactus.corpora.base")
+
+local function wrap_retriever(defaults)
+  local function constructor(config)
+    local merged = merge_defaults(defaults, config or {})
+    return _tactus_internal_retriever(merged)
+  end
+  local cls = {}
+  function cls:new(config)
+    return constructor(config)
+  end
+  return setmetatable(cls, {
+    __call = function(_, config)
+      return constructor(config)
+    end,
+  })
+end
+
+return {
+  wrap_corpus = corpora_base.wrap_corpus,
+  wrap_retriever = wrap_retriever,
+}

tactus/stdlib/tac/tactus/retrievers/embedding_index_file.tac

@@ -0,0 +1,6 @@
+local base = require("tactus.retrievers.base")
+
+return {
+  Corpus = base.wrap_corpus({}),
+  Retriever = base.wrap_retriever({ retriever_id = "embedding-index-file" }),
+}

tactus/stdlib/tac/tactus/retrievers/embedding_index_inmemory.tac

@@ -0,0 +1,6 @@
+local base = require("tactus.retrievers.base")
+
+return {
+  Corpus = base.wrap_corpus({}),
+  Retriever = base.wrap_retriever({ retriever_id = "embedding-index-inmemory" }),
+}