tactus 0.15.0__tar.gz → 0.22.0__tar.gz

{tactus-0.15.0 → tactus-0.22.0}/.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.15.0 → tactus-0.22.0}/.gitignore

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

{tactus-0.15.0 → tactus-0.22.0}/AGENTS.md

@@ -98,6 +98,17 @@ Agent "bedrock_agent" {
 - **Do NOT delete or truncate `CHANGELOG.md`**.
 - Ensure your commit messages follow the [Angular Commit Message Convention](https://github.com/angular/angular/blob/master/CONTRIBUTING.md#commit) (e.g., `feat: ...`, `fix: ...`, `docs: ...`) so that Semantic Release can correctly generate the changelog.
 
+## Commit Message Guidelines
+
+When writing commit messages:
+
+- **Do NOT use code blocks** (backticks or triple backticks) in commit messages
+- Use plain text with proper formatting (bullet points, indentation)
+- Keep commit subject lines concise (50-72 characters)
+- Use the imperative mood ("fix bug" not "fixed bug")
+- Include detailed explanations in the commit body when necessary
+- Follow the Angular Commit Message Convention for the subject line
+
 ## Parser Generation Requirements
 
 **IMPORTANT**: Tactus uses ANTLR4 to generate parsers from the Lua grammar for both Python and TypeScript.
@@ -138,7 +149,7 @@ The IDE uses a two-layer validation approach for optimal performance and user ex
 
 **Layer 1: TypeScript Parser (Client-Side)**
 - Location: `tactus-ide/frontend/src/validation/`
-- ANTLR-generated from same `Lua.g4` grammar as Python parser
+- ANTLR-generated from same `LuaLexer.g4` and `LuaParser.g4` grammars as Python parser
 - Purpose: Instant syntax validation (< 10ms)
 - Runs in browser, no backend needed
 - Provides immediate feedback as user types

{tactus-0.15.0 → tactus-0.22.0}/CHANGELOG.md

@@ -2,6 +2,128 @@
 
 <!-- version list -->
 
+## v0.22.0 (2026-01-10)
+
+### Features
+
+- **agent**: Add configurable `module` parameter for DSPy module selection (#21)
+  ([#21](https://github.com/AnthusAI/Tactus/pull/21),
+  [`0c93af0`](https://github.com/AnthusAI/Tactus/commit/0c93af0575d191be58ed0635ed236e359d8b35af))
+
+
+## v0.21.1 (2026-01-10)
+
+### Bug Fixes
+
+- **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)
+
+
+## v0.19.0 (2026-01-09)
+
+
+## v0.18.0 (2026-01-09)
+
+
+## v0.17.0 (2026-01-08)
+
+### Bug Fixes
+
+- Pass registry and mock_manager to DSPy agent creation
+  ([`e86a069`](https://github.com/AnthusAI/Tactus/commit/e86a0690cba607507f4745106f8a609aab38c8f3))
+
+- Remove unused Path import in test_script_mode.py
+  ([`1c28430`](https://github.com/AnthusAI/Tactus/commit/1c28430502ac2f1c0b08f6456ec7374e9fc4252a))
+
+### Code Style
+
+- Format code with black
+  ([`2fc1a07`](https://github.com/AnthusAI/Tactus/commit/2fc1a0734f639c3d502f4e96b0eb44703a3522c8))
+
+### Testing
+
+- Skip agent mock test in CI until mocking fully implemented
+  ([`f46f183`](https://github.com/AnthusAI/Tactus/commit/f46f1834a616a8dfde31b9ee6cdb928264489b93))
+
+- Skip DSPy agent mock test - assignment name interception not working
+  ([`b7971d3`](https://github.com/AnthusAI/Tactus/commit/b7971d3d87dd07f43c98fcab524a5cad5848db5d))
+
+
+## v0.16.0 (2026-01-07)
+
+### Bug Fixes
+
+- **tests**: Resolve ruff linting errors
+  ([`892f73e`](https://github.com/AnthusAI/Tactus/commit/892f73eed13602cb6cb6328c363b1caa938db850))
+
+### Code Style
+
+- Format code with black
+  ([`bdec5b8`](https://github.com/AnthusAI/Tactus/commit/bdec5b8836d7d95bd6531ede2c4f000e24e79764))
+
+### Features
+
+- **dspy**: Add comprehensive behavior specifications for DSPy integration
+  ([`531167e`](https://github.com/AnthusAI/Tactus/commit/531167e2c423c605792f1e5ab3602f7eb05ab6d8))
+
+- **dspy**: Add model_type parameter support for reasoning models
+  ([`bf8cef3`](https://github.com/AnthusAI/Tactus/commit/bf8cef38e0e0674ccf1ebfac75a92c54e80b6d0c))
+
+- **dspy**: Add model_type parameter support for reasoning models
+  ([`0043293`](https://github.com/AnthusAI/Tactus/commit/00432937a11adc01a846909fe1ae9520cc927eab))
+
+### Refactoring
+
+- **examples**: Simplify agent example and add gpt-5-mini support
+  ([`7e7934e`](https://github.com/AnthusAI/Tactus/commit/7e7934eb89508d100dbce5ebd497ddcefda7778d))
+
+
+## v0.15.1 (2026-01-07)
+
+
 ## v0.15.0 (2026-01-07)
 
 ### Code Style

{tactus-0.15.0 → tactus-0.22.0}/IMPLEMENTATION.md

@@ -176,7 +176,7 @@ input {
 }
 
 -- Top-level code acts as main procedure
-Worker.turn({inject = input.task})
+Worker({message = input.task})
 return {result = "done"}
 ```
 
@@ -249,7 +249,7 @@ output {
 }
 
 -- Top-level code returns output
-Worker.turn()
+Worker()
 return {result = "done"}
 ```
 
@@ -277,87 +277,94 @@ return {result = "done"}
 
 ### Script Mode (Phase 6)
 
-**Status**: ✅ **Fully Implemented**
+**Status**: ✅ **Fully Implemented** (Zero-Wrapper with Source Transformation)
+
+Script mode allows simple procedures to be written without explicit `Procedure {}` wrappers. Top-level code becomes the entry point, making Tactus feel more like a script than a framework.
 
-Script mode allows simple procedures to be written without explicit `procedure()` wrappers. Top-level code becomes the entry point, making Tactus feel more like a script than a framework.
+#### Zero-Wrapper Syntax
 
-#### Three Approaches
+Write procedures without any wrapper - just top-level `input {}`, `output {}`, and executable code:
 
-**1. Simplest (no schemas):**
+**Basic Example:**
 
 ```lua
--- No input/output declarations needed
-Worker = agent "worker" {
-    model = "claude-sonnet-4-20250514",
-    system_prompt = "You are a helpful assistant."
+-- No Procedure wrapper needed
+input {
+    name = field.string{required = true}
 }
 
-Worker.turn({inject = input.text})
-return {result = Worker.output}
+output {
+    greeting = field.string{required = true}
+}
+
+local message = "Hello, " .. input.name .. "!"
+return {greeting = message}
 ```
 
-**2. With Schema Declarations:**
+**With Agents:**
 
 ```lua
 input {
-    text = {type = "string", required = true},
-    language = {type = "string", default = "en"}
+    task = field.string{required = true}
 }
 
 output {
-    result = {type = "string", required = true}
+    result = field.string{required = true}
 }
 
-Worker = agent "worker" {
-    model = "claude-sonnet-4-20250514"
+done = tactus.done
+
+worker = Agent {
+    provider = "openai",
+    model = "gpt-4o",
+    system_prompt = "Complete tasks efficiently",
+    tools = {done}
 }
 
-Worker.turn({inject = input.text})
-return {result = Worker.output}
+worker({message = input.task})
+
+if done.called() then
+    return {result = "Success: " .. done.last_call().args.reason}
+else
+    return {result = "Agent did not complete"}
+end
 ```
 
-**3. Hybrid (sub-procedures + top-level main):**
+**With State:**
 
 ```lua
-input {document = {type = "string"}}
-output {result = {type = "string"}}
-
--- Helper sub-procedure
-summarize_chunk = procedure "summarize_chunk" {
-    input = {chunk = {type = "string"}},
-    output = {summary = {type = "string"}},
-    run = function()
-        Summarizer = agent "summarizer" {
-            model = "claude-sonnet-4-20250514"
-        }
-        Summarizer.turn({inject = input.chunk})
-        return {summary = Summarizer.output}
-    end
+input {
+    value = field.number{required = true}
 }
 
--- Top-level code acts as main procedure
-chunks = split_text(input.document, 1000)
-state.summaries = {}
+output {
+    doubled = field.number{required = true}
+}
 
-for i, chunk in ipairs(chunks) do
-    result = summarize_chunk({chunk = chunk})
-    state.summaries[i] = result.summary
-end
+state.original = input.value
+state.result = state.original * 2
 
-return {result = join_summaries(state.summaries)}
+return {doubled = state.result}
 ```
 
 #### How It Works
 
-1. Runtime detects top-level `input {}` and `output {}` declarations
-2. If no explicit `main` procedure exists, top-level code is wrapped in implicit main
-3. Top-level code can:
-   - Access `input` table (from runtime context)
-   - Define agents and models
-   - Call sub-procedures
-   - Mutate `state` table
-   - Return output table
-4. All durability features work identically (checkpointing, replay, HITL)
+**Source Transformation Approach:**
+
+1. **Detection**: Runtime detects script mode when file has top-level `input {}` or `output {}` without explicit `Procedure {}`
+2. **Splitting**: Source is split into:
+   - **Declarations**: `input {}`, `output {}`, `Mocks {}`, Agent/Tool/Model definitions, comments
+   - **Executable code**: Local variables, agent calls, state assignments, control flow, returns
+3. **Transformation**: Executable code is wrapped in implicit `Procedure { function(input) ... end }`
+4. **Schema merging**: Top-level schemas are merged into the implicit main procedure
+5. **Normal execution**: The transformed code executes through standard procedure flow
+
+**Why transformation?** During parsing, Lua code executes but agents aren't connected to LLMs yet. The `Procedure { function() ... end }` pattern stores the function during parsing and calls it later. Script mode uses source transformation to wrap executable code before parsing, preventing premature execution.
+
+**Pattern Detection:**
+- **Declarations**: Tracked via brace depth - entire multi-line blocks (Agent {}, Mocks {}) stay together
+- **Executable code**: Everything else that doesn't match declaration patterns
+- **Special handling**: Comments, empty lines, and `tactus.*` references treated as declarations
 
 #### When to Use
 
@@ -387,7 +394,7 @@ Script mode files can be gradually converted to explicit procedures without brea
 ```lua
 -- Before (script mode)
 input {text = {type = "string"}}
-Worker.turn({inject = input.text})
+Worker({message = input.text})
 return {result = Worker.output}
 
 -- After (explicit procedure)
@@ -396,7 +403,7 @@ main = procedure "main" {
     output = {result = {type = "string"}},
     run = function()
         Worker = agent "worker" {...}
-        Worker.turn({inject = input.text})
+        Worker({message = input.text})
         return {result = Worker.output}
     end
 }
@@ -500,7 +507,7 @@ main = procedure("main", {
     output = {...}
 }, function()
     -- Dependencies available to agents via AgentDeps
-    Worker.turn()
+    Worker()
     return {...}
 end)
 ```
@@ -647,7 +654,7 @@ main = procedure("main", {
         tools = {weather_lookup_tool}  -- Tool uses weather_api from deps
     })
 
-    Worker.turn({inject = "Get weather for " .. input.location})
+    Worker({message = "Get weather for " .. input.location})
     return {
         temperature = state.temp,
         condition = state.condition
@@ -734,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
 
@@ -781,7 +788,7 @@ Inline procedures are not parsed by `ProcedureYAMLParser` and cannot be invoked.
 - ❌ `filter` - Not implemented (no ComposedFilter, TokenBudget, etc.)
 - ❌ `response.retries` / `response.retry_delay` - Not implemented
 
-**Usage in Lua**: `Worker.turn()` (capitalized agent name)
+**Usage in Lua**: `Worker()` (capitalized agent name, callable syntax)
 
 ### Model Primitive (Phase 3: ML Inference)
 
@@ -864,9 +871,9 @@ state.intent = IntentClassifier.predict(input.message)
 
 -- Use result
 if state.intent == "billing" then
-    BillingAgent.turn()
+    BillingAgent()
 elseif state.intent == "technical" then
-    TechAgent.turn()
+    TechAgent()
 end
 ```
 
@@ -928,7 +935,7 @@ summarize_chunk = procedure "summarize_chunk" {
         Summarizer = agent "summarizer" {
             model = "claude-sonnet-4-20250514"
         }
-        Summarizer.turn({inject = input.chunk})
+        Summarizer({message = input.chunk})
         return {summary = Summarizer.output}
     end
 }
@@ -1051,7 +1058,7 @@ All procedure invocation primitives are missing.
    state.clusters = cluster_embeddings(state.embeddings)
    checkpoint()  -- Save before proceeding
 
-   Worker.turn({inject = state.clusters})
+   Worker({message = state.clusters})
    ```
 
 2. **Before risky operations:**
@@ -1096,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.
 
@@ -1107,10 +1117,10 @@ Explicit checkpoints do **not** create suspend points. They simply persist curre
 
 **Status**: ✅ **Fully Implemented**
 
-- ✅ `AgentName.turn()` - Execute agent turn
-- ✅ `AgentName.turn({inject = "..."})` - Turn with injected message
-- ✅ `AgentName.turn({tools = {...}})` - Turn with specific tools
-- ✅ `AgentName.turn({tools = {}})` - Turn with no tools
+- ✅ `AgentName()` - Execute agent turn
+- ✅ `AgentName({message = "..."})` - Call with a message
+- ✅ `AgentName({tools = {...}})` - Call with specific tools
+- ✅ `AgentName({tools = {}})` - Call with no tools
 - ✅ Per-turn model parameter overrides (temperature, max_tokens, top_p, etc.)
 
 **Per-Turn Overrides:**
@@ -1123,15 +1133,15 @@ The `turn()` method now accepts an optional table to override behavior for a sin
 **Common pattern - Tool result summarization:**
 ```lua
 repeat
-    Researcher.turn()  -- Agent has all tools
-    
-    if Tool.called("search") then
-        Researcher.turn({
-            inject = "Summarize the search results",
+    Researcher()  -- Agent has all tools
+
+    if search.called() then
+        Researcher({
+            message = "Summarize the search results",
             tools = {}  -- No tools for summarization
         })
     end
-until Tool.called("done")
+until done.called()
 ```
 
 **Response Access:**
@@ -1174,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:** `Agent.turn()` now returns `ResultPrimitive` instead of raw data. Access response via `result.data`.
+**Breaking change:** Access agent output via `result.value` (not `result.message` / `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.turn()
-
--- Access response
-Log.info(result.data)
-
--- Access usage
+local result = Agent()
+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)
@@ -1226,8 +1231,8 @@ agent("extractor", {
 })
 
 -- Agent automatically validates output against schema
-local result = Extractor.turn()
-Log.info(result.data.city)  -- Type-safe access
+local result = Extractor()
+Log.info(result.value.city)
 ```
 
 #### State Primitives
@@ -1309,7 +1314,7 @@ procedure "order_fulfillment" {
 - ✅ `Iterations.exceeded(max)` - Check if exceeded limit
 
 **Implementation:**
-- Incremented by `AgentPrimitive.turn()` automatically
+- Incremented by agent calls automatically
 - Can be checked in procedure code for safety limits
 
 #### StopPrimitive (`tactus/primitives/control.py`)
@@ -1486,7 +1491,7 @@ No graph/tree structure primitives. Procedures are linear sequences, not graphs.
 
 | Type | Description | Created By |
 |------|-------------|------------|
-| `agent_turn` | LLM conversation turn | `AgentPrimitive.turn()` |
+| `agent_turn` | LLM conversation turn | `Agent()` (callable syntax) |
 | `model_predict` | ML inference | `ModelPrimitive.predict()` |
 | `procedure_call` | Sub-procedure invocation | Procedure callable |
 | `hitl_approval` | Human approval request | `Human.approve()` |
@@ -1542,9 +1547,9 @@ checkpoint()
 
 -- ❌ Unsafe: Random value used across checkpoints
 local x = math.random(100)  -- WARNING!
-Worker.turn()  -- Checkpoint
+Worker()  -- Checkpoint
 if x > 50 then  -- Diverges on replay
-    Publisher.turn()
+    Publisher()
 end
 ```
 
@@ -1749,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
@@ -1818,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/
@@ -1895,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