tactus 0.20.1__tar.gz → 0.21.1__tar.gz

{tactus-0.20.1 → tactus-0.21.1}/.github/workflows/release.yml

@@ -77,10 +77,10 @@ jobs:
           semantic-release publish
 
       - name: Publish to PyPI
-        if: success()
+        if: success() && hashFiles('dist/*') != ''
         env:
           TWINE_USERNAME: __token__
           TWINE_PASSWORD: ${{ secrets.PYPI_TOKEN }}
         run: |
           pip install twine
-          twine upload dist/*
+          twine upload --skip-existing dist/*

{tactus-0.20.1 → tactus-0.21.1}/.gitignore

@@ -37,6 +37,8 @@ yarn-error.log*
 .tactus/config.yml
 progress.output
 .tac/
+tmp/
+examples/output/
 
 *storybook.log
 storybook-static

{tactus-0.20.1 → tactus-0.21.1}/CHANGELOG.md

@@ -2,12 +2,52 @@
 
 <!-- version list -->
 
-## v0.20.1 (2026-01-10)
+## v0.21.1 (2026-01-10)
 
 ### Bug Fixes
 
-- Correct Toolset declaration syntax
-  ([`c075c97`](https://github.com/AnthusAI/Tactus/commit/c075c97841c918187d83378224687155a4c2d924))
+- **ci**: Add --skip-existing to twine upload
+  ([`7a1b369`](https://github.com/AnthusAI/Tactus/commit/7a1b369376ce68869b98f0faed877a52855b4459))
+
+
+## v0.21.0 (2026-01-10)
+
+### Bug Fixes
+
+- Add Checkpoint.exists and Checkpoint.get
+  ([`d652411`](https://github.com/AnthusAI/Tactus/commit/d6524115dea8de42559b94a1f35309f7538958e7))
+
+- Add System.alert primitive
+  ([`18ece11`](https://github.com/AnthusAI/Tactus/commit/18ece114eea760e97b07a493b7ee13eb27034516))
+
+- Clarify summarization prompts are logged
+  ([`423b912`](https://github.com/AnthusAI/Tactus/commit/423b912c590cd7e9702a0e9dbb76288f26cdfd4a))
+
+- Clarify template namespaces and rendering
+  ([`a33a383`](https://github.com/AnthusAI/Tactus/commit/a33a3831fb335b81d1e3152f5feb6d24f436bdb8))
+
+- Expose agent Result usage and history
+  ([`7f41286`](https://github.com/AnthusAI/Tactus/commit/7f412860f94c79a442fc8e86365f71ddddc9b58f))
+
+- Handle string input in agent __call__ method
+  ([`4af6ad5`](https://github.com/AnthusAI/Tactus/commit/4af6ad590cacb116885ce60ca93656c092f01435))
+
+- Remove incompatible tests and skip deprecated YAML test
+  ([`f96f084`](https://github.com/AnthusAI/Tactus/commit/f96f0842ceffa8176329b5553096c39ff1ba15d1))
+
+- Standardize on TactusResult.value and fix agent mock lookup
+  ([`a4e02c0`](https://github.com/AnthusAI/Tactus/commit/a4e02c0699a40461a2d0476e1359216d02a82616))
+
+- Support message alias for agent calls
+  ([`9a2b817`](https://github.com/AnthusAI/Tactus/commit/9a2b817478acf5848dad346fa9d0f0dd1a78eb86))
+
+- **ci**: Only run twine upload when dist files exist
+  ([`d490f55`](https://github.com/AnthusAI/Tactus/commit/d490f5527c8588666ffcafa67d13e195815c2856))
+
+### Chores
+
+- Update .gitignore to include tmp/ directory
+  ([`1294360`](https://github.com/AnthusAI/Tactus/commit/1294360a261cec1ff8c35f8063ae2b652c340373))
 
 
 ## v0.20.0 (2026-01-09)

{tactus-0.20.1 → tactus-0.21.1}/IMPLEMENTATION.md

@@ -741,9 +741,9 @@ Defines interface for HITL implementations.
 
 **Specification**: Programmatic alerts from anywhere (not just procedures).
 
-**Status**: ❌ **Not Implemented**
+**Status**: ✅ **Implemented**
 
-Only `Human.notify()` exists, which logs notifications. No `System.alert()` primitive or system-level alert infrastructure.
+Implemented as a non-blocking primitive that emits a structured `SystemAlertEvent` via the configured `LogHandler` (CLI/IDE), with a fallback to standard Python logging when no handler is present.
 
 #### Message Classification
 
@@ -1103,6 +1103,9 @@ Explicit checkpoints do **not** create suspend points. They simply persist curre
 
 - ✅ `Checkpoint.clear_all()` - Clear all checkpoints (execution log)
 - ✅ `Checkpoint.clear_after(position)` - Clear from position onwards
+- ✅ `Checkpoint.next_position()` - Get next checkpoint position
+- ✅ `Checkpoint.exists(position)` - Check whether a checkpoint exists
+- ✅ `Checkpoint.get(position)` - Get cached value (or nil)
 
 **Usage**: Testing and debugging checkpoint replay behavior. These are utility functions for test scenarios, not for production use.
 
@@ -1181,35 +1184,30 @@ main = procedure("main", {
 end)
 ```
 
-#### ResultPrimitive (`tactus/primitives/result.py`)
-
-**Status**: ✅ **Fully Implemented**
+#### Result (`tactus/protocols/result.py`)
 
-Wraps pydantic-ai's `RunResult` for Lua access.
+**Status**: ✅ **Implemented (DSPy)**
 
-**Aligned with pydantic-ai:** Direct mapping to `RunResult.data`, `RunResult.usage()`, `RunResult.new_messages()`, `RunResult.all_messages()`.
+`Agent()` returns a standard `TactusResult` wrapper (instead of raw text).
 
 **Features:**
-- ✅ `result.data` - Response data (text or structured dict)
+- ✅ `result.value` - Response value (string or structured data)
 - ✅ `result.usage` - Token usage stats (prompt_tokens, completion_tokens, total_tokens)
-- ✅ `result.new_messages()` - Messages from this turn
-- ✅ `result.all_messages()` - Full conversation history
-- ✅ `result.cost()` - Token usage (for cost calculation)
+- ✅ `result.cost()` - Cost stats (total_cost, prompt_cost, completion_cost)
+
+**Breaking change:** Access agent output via `result.value` (not `result.message` / `result.data`).
 
-**Breaking change:** `Agent()` now returns `ResultPrimitive` instead of raw data. Access response via `result.data`.
+**Implementation locations:**
+- `tactus/dspy/agent.py` (`DSPyAgentHandle.__call__`)
+- `tactus/protocols/result.py` (`TactusResult`)
+- `tactus/protocols/cost.py` (`UsageStats`, `CostStats`)
 
 **Example:**
 ```lua
 local result = Agent()
-
--- Access response
-Log.info(result.data)
-
--- Access usage
+Log.info(result.value)
 Log.info("Tokens", {total = result.usage.total_tokens})
-
--- Access messages
-local msgs = result.new_messages()
+Log.info("Cost", {total = result.cost().total_cost})
 ```
 
 #### Structured Output (output_type)
@@ -1234,7 +1232,7 @@ agent("extractor", {
 
 -- Agent automatically validates output against schema
 local result = Extractor()
-Log.info(result.data.city)  -- Type-safe access
+Log.info(result.value.city)
 ```
 
 #### State Primitives
@@ -1756,9 +1754,9 @@ tactus evaluate procedure.tac --runs 10
    - Only local context exists
    - No AWS Lambda integration
 
-4. **System.alert()** ❌
-   - No system-level alerts
-   - Only `Human.notify()` exists
+4. **System.alert()** ✅
+   - Non-blocking alerts via `System.alert()`
+   - Emits structured `system_alert` events to log handlers (CLI/IDE)
 
 5. **Async Procedure Spawning** ❌
    - No `Procedure.spawn()` for async invocation
@@ -1825,7 +1823,6 @@ tactus/
 │   ├── retry.py                # RetryPrimitive
 │   ├── file.py                 # FilePrimitive
 │   ├── message_history.py      # MessageHistoryPrimitive
-│   ├── result.py               # ResultPrimitive
 │   └── deps_generator.py       # Dynamic AgentDeps generation [NEW]
 │
 ├── backends/
@@ -1902,7 +1899,7 @@ To align the implementation with the specification:
 ### Medium Priority
 4. **Inline Procedures** - Parse and support `procedures:` section in YAML
 5. **Agent `prepare` hook** - Enable `prepared` template namespace
-6. **System.alert()** - System-level alert infrastructure
+6. **System.alert() integrations** - Route alerts to external monitoring
 7. **Template variables** - Add `context`, `env`, `output` support
 8. **More Model Backends** - BERT, scikit-learn, ONNX, SageMaker
 

{tactus-0.20.1 → tactus-0.21.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tactus
-Version: 0.20.1
+Version: 0.21.1
 Summary: Tactus: Lua-based DSL for agentic workflows
 Project-URL: Homepage, https://github.com/AnthusAI/Tactus
 Project-URL: Documentation, https://github.com/AnthusAI/Tactus/tree/main/docs

{tactus-0.20.1 → tactus-0.21.1}/SPECIFICATION.md

@@ -356,13 +356,11 @@ This ensures type-safe, structured outputs from agents.
 **Aligned with pydantic-ai:** The Result object wraps pydantic-ai's `RunResult` and provides Lua-accessible properties.
 
 **Properties:**
-- `result.message` - The response message (text string or structured data dict)
+- `result.value` - The response value (string or structured data)
 - `result.usage` - Token usage stats (prompt_tokens, completion_tokens, total_tokens)
 
 **Methods:**
-- `result.new_messages()` - Messages from this turn only
-- `result.all_messages()` - Full conversation history
-- `result.cost()` - Token usage (same as .usage, for cost calculation)
+- `result.cost()` - Cost statistics (total_cost, prompt_cost, completion_cost)
 
 **Example:**
 
@@ -377,8 +375,8 @@ Procedure {
     function(input)
         local result = worker()
 
-        -- Access response message
-        Log.info("Response", {message = result.message})
+        -- Access response value
+        Log.info("Response", {value = result.value})
 
         -- Access token usage
         Log.info("Tokens used", {
@@ -387,11 +385,6 @@ Procedure {
             total = result.usage.total_tokens
         })
 
-        -- Access messages
-        local messages = result.new_messages()
-        for i, msg in ipairs(messages) do
-            Log.info("Message", {role = msg.role, content = msg.content})
-        end
     end
 }
 ```
@@ -414,8 +407,8 @@ Procedure {
 
         -- Access structured data fields
         Log.info("Extracted", {
-            city = result.message.city,
-            country = result.message.country
+            city = result.value.city,
+            country = result.value.country
         })
     end
 }
@@ -1883,12 +1876,12 @@ local web_search = Tool.get("web_search")  -- From MCP server
 local result = web_search({query = "weather"})
 ```
 
-### Toolset with type="lua"
+### toolset() with type="lua"
 
 Group multiple related tools into a named toolset:
 
 ```lua
-Toolset "math_tools" {
+toolset("math_tools", {
     type = "lua",
     tools = {
         {
@@ -2197,6 +2190,8 @@ For testing and debugging:
 Checkpoint.clear_all()              -- Clear all checkpoints
 Checkpoint.clear_after(position)    -- Clear checkpoint at position and all after (position is a number)
 Checkpoint.next_position()          -- Get the next checkpoint position number
+Checkpoint.exists(position)         -- Check if a checkpoint exists at a position
+Checkpoint.get(position)            -- Get cached value at a position (or nil)
 ```
 
 ### Human Interaction Primitives
@@ -2477,9 +2472,9 @@ local error_matcher = contains("error")
 
 -- Use in conditional logic
 local result = worker()
-if result.message:find("success") then
+if tostring(result.value):find("success") then
     -- Contains success
-elseif result.message:find("error") then
+elseif tostring(result.value):find("error") then
     -- Contains error
 end
 ```

{tactus-0.20.1 → tactus-0.21.1}/TECHNICAL_DEBT.md

@@ -77,37 +77,32 @@ These are minor features documented in the spec that could be implemented with s
 
 ### Checkpoint Inspection Methods
 
-The spec documents methods to inspect checkpoint state that don't exist:
-
-```lua
-Checkpoint.exists(name)  -- Check if a checkpoint exists
-Checkpoint.get(name)     -- Get the cached value from a checkpoint
-```
-
-**What exists:** `clear_all()`, `clear_after(position)`, `next_position()`
-
-**Why it matters:** These would be useful for testing and debugging checkpoint behavior.
-
-**Implementation location:** `tactus/primitives/step.py` CheckpointPrimitive class
+Implemented in `tactus/primitives/step.py` (`Checkpoint.exists(position)`, `Checkpoint.get(position)`).
 
 ---
 
 ### Result Object with Usage Statistics
 
-The spec documents a rich Result object with token usage and message history:
+We want a standard Result object with response data + token usage + cost:
 
 ```lua
-result.usage          -- {prompt_tokens, completion_tokens, total_tokens}
-result.new_messages() -- Messages from this turn only
-result.all_messages() -- Full conversation history
-result.cost()         -- Cost calculation
+result.value   -- string or structured data
+result.usage   -- {prompt_tokens, completion_tokens, total_tokens}
+result.cost()  -- {total_cost, prompt_cost, completion_cost}
 ```
 
-**What exists:** `TactusPrediction` with `.text` only
+**What exists now:** `TactusResult` returned by `Agent()` (breaking change: use `result.value`)
+
+**Intentionally not implemented (YAGNI for now):**
+- `result.new_messages()`
+- `result.all_messages()`
 
 **Why it matters:** Users can't track token usage or costs per-call, which is important for optimization and budgeting.
 
-**Implementation location:** `tactus/dspy/prediction.py`
+**Implementation locations:**
+- `tactus/dspy/agent.py`
+- `tactus/protocols/result.py`
+- `tactus/protocols/cost.py`
 
 ---
 

{tactus-0.20.1 → tactus-0.21.1}/docs/CONFIGURATION.md

@@ -93,6 +93,138 @@ default_model: "gpt-4o-mini"
 
 **Security**: Sidecar files can contain file paths and command execution. Only use trusted sidecar files.
 
+## Sandbox Configuration
+
+Tactus runs procedures in Docker containers by default for security isolation. You can configure sandbox behavior at any configuration level (user, project, or sidecar).
+
+### Basic Sandbox Settings
+
+```yaml
+# ~/.tactus/config.yml or .tactus/config.yml
+sandbox:
+  enabled: true                    # Default: true (if Docker available)
+  image: "tactus-sandbox:local"    # Docker image name (auto-built on first use)
+  timeout: 3600                    # Max execution time in seconds (default: 1 hour)
+  mcp_servers_path: "~/.tactus/mcp-servers"  # Path to MCP servers
+```
+
+**Note**: If Docker is unavailable and `enabled: true`, execution will fail with an error. Use `--no-sandbox` flag or `enabled: false` to explicitly run without isolation.
+
+### Resource Limits
+
+Control memory and CPU usage per container:
+
+```yaml
+sandbox:
+  limits:
+    memory: "2g"     # Per-container memory limit (default: 2GB)
+    cpus: "2"        # Per-container CPU cores (default: 2)
+```
+
+**Error handling**:
+- Out of memory: Container killed with exit code 137
+- Timeout exceeded: Container killed with exit code 124
+
+### Network Configuration
+
+Control network access for procedures:
+
+```yaml
+sandbox:
+  network: "bridge"  # Network mode (default: bridge)
+
+  # Options:
+  # - "bridge": Default Docker bridge (allows outbound connections)
+  # - "none": No network access (most secure, but can't call LLM APIs)
+  # - "host": Use host network (not recommended for security)
+  # - "custom-network": Use a custom Docker network
+```
+
+**Security consideration**: Default `bridge` mode allows outbound connections (needed for LLM API calls), but agents could potentially exfiltrate data. See [Sandboxing Guide: Threat Model](./SANDBOXING.md#threat-model) for details.
+
+### Volume Mounts
+
+Mount host directories into the container:
+
+```yaml
+sandbox:
+  volumes:
+    - "/host/data:/data:ro"           # Read-only mount
+    - "/host/outputs:/outputs:rw"     # Read-write mount
+    - "/shared/config:/config:ro"
+```
+
+**Default mounts** (always included):
+- Workspace: Temporary directory at `/workspace` (ephemeral, destroyed after run)
+- MCP Servers: `~/.tactus/mcp-servers` at `/mcp-servers` (read-only)
+
+### Environment Variables
+
+Pass environment variables to the container:
+
+```yaml
+sandbox:
+  env:
+    CUSTOM_VAR: "value"
+    DEBUG: "true"
+    LOG_LEVEL: "info"
+```
+
+**Automatically passed through** (no configuration needed):
+- `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, `GOOGLE_API_KEY`
+- `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, `AWS_DEFAULT_REGION`, `AWS_SESSION_TOKEN`
+- `AZURE_OPENAI_API_KEY`, `AZURE_OPENAI_ENDPOINT`
+
+### Per-Procedure Sandbox Configuration
+
+Use sidecar files to customize sandbox settings per procedure:
+
+**Example**: `financial_analysis.tac.yml`
+```yaml
+# Procedure-specific sandbox configuration
+sandbox:
+  enabled: true
+
+  limits:
+    memory: "4g"      # More memory for data-heavy processing
+    cpus: "4"         # More CPU cores
+
+  timeout: 1800       # 30 minute timeout
+
+  network: "none"     # No network access for sensitive data
+
+  volumes:
+    - "/data/financial:/data:ro"      # Read-only financial data
+    - "/output/reports:/reports:rw"   # Write reports here
+
+  env:
+    DATA_PATH: "/data"
+    OUTPUT_PATH: "/reports"
+```
+
+**Use cases for per-procedure sandbox configs**:
+- Higher resource limits for data-intensive procedures
+- Network isolation for procedures handling sensitive data
+- Custom volume mounts for specific data sources
+- Procedure-specific environment variables
+
+### Disabling the Sandbox
+
+To run without Docker isolation:
+
+**Via CLI**:
+```bash
+tactus run procedure.tac --no-sandbox
+```
+
+**Via configuration**:
+```yaml
+sandbox:
+  enabled: false
+```
+
+**Security warning**: Running without sandbox removes OS-level isolation. Only disable for trusted procedures or development. See [Sandboxing Guide](./SANDBOXING.md) for security implications.
+
 ### Directory-Level Configuration
 
 You can place `.tactus/config.yml` files in any directory to configure settings for procedures in that directory and subdirectories.
@@ -322,6 +454,7 @@ api_key = config.get("openai_api_key")
 
 ## See Also
 
+- [Sandboxing & Security](SANDBOXING.md) - Security concepts and threat models
 - [Tool Roadmap](TOOL_ROADMAP.md) - Information about tool loading
 - [README](../README.md) - General Tactus documentation
 - [Examples](../examples/) - Example procedures with sidecar configs

{tactus-0.20.1 → tactus-0.21.1}/docs/DURABILITY.md

@@ -1097,7 +1097,7 @@ class AgentPrimitive:
         )
         return {
             "output": result.output,
-            "messages": self.messages + result.new_messages()
+            "messages": self.messages
         }
 ```
 
@@ -1390,4 +1390,4 @@ result = await runtime.execute(
 
 4. **Observability**: Integration with Logfire/OpenTelemetry for tracing?
 
-5. **Error recovery**: Retry policies, dead letter queues, manual intervention?
+5. **Error recovery**: Retry policies, dead letter queues, manual intervention?