tactus 0.31.0__py3-none-any.whl → 0.34.1__py3-none-any.whl

tactus/stdlib/tac/tactus/generate/index.md

@@ -0,0 +1,195 @@
+# Generate Module
+
+The `tactus.generate` module provides flexible text generation built on DSPy's modular architecture.
+
+## Overview
+
+All generators extend `BaseGenerator` and share a common interface. The module supports multiple output formats and optional chain-of-thought reasoning via DSPy's native modules.
+
+## DSPy Module Integration
+
+The generator uses DSPy's module system under the hood:
+
+| Mode | DSPy Module | Behavior |
+|------|------------|----------|
+| **Default** | `Raw` | No prompt modifications - passes your system prompt and user message directly to the LLM without any DSPy formatting |
+| **`reasoning = true`** | `ChainOfThought` | Uses DSPy's native reasoning module - automatically adds step-by-step thinking |
+
+### Why Raw Mode by Default?
+
+Even DSPy's basic `Predict` module adds formatting delimiters (like `[[ ## response ## ]]`) to prompts. The `Raw` module bypasses all DSPy prompt modifications, giving you:
+
+- **Clean prompts**: Your system prompt goes to the LLM exactly as written
+- **Predictable output**: No unexpected formatting in responses
+- **Full control**: You decide what goes in the prompt
+
+### When to Use ChainOfThought
+
+Enable `reasoning = true` when you want the model to:
+- Show its work on math problems
+- Explain multi-step reasoning
+- Provide transparent decision-making
+
+The reasoning is captured separately from the final answer, so you can access both.
+
+## Output Formats
+
+| Format | Description |
+|--------|-------------|
+| `text` | Plain text output (default) |
+| `json` | JSON-formatted response with validation |
+| `markdown` | Markdown-formatted response |
+
+## Architecture
+
+The module uses a proper Lua class hierarchy:
+
+- `BaseGenerator` - Abstract base with common interface
+- `LLMGenerator` - LLM-powered generation with all options
+
+All generators return a consistent result format:
+
+```lua
+{
+    output = "The generated text...",    -- Main output (final answer)
+    reasoning = "Step-by-step...",       -- Reasoning steps (only if reasoning=true)
+    format = "text",                     -- Format used
+    retry_count = 0,                     -- Number of retries needed
+    raw_response = "...",                -- Raw LLM response
+    error = nil                          -- Error message if failed
+}
+```
+
+## Loading the Module
+
+```lua
+-- Load the main module
+local generate = require("tactus.generate")
+
+-- Or load specific generators (dependencies auto-load)
+local LLMGenerator = require("tactus.generate.llm")
+```
+
+## Examples
+
+### Basic Text Generation (Raw Mode)
+
+By default, your prompt goes directly to the LLM without modification:
+
+```lua
+local generator = LLMGenerator:new {
+    model = "openai/gpt-4o-mini"
+}
+local result = generator:generate("Write a haiku about programming")
+print(result.output)
+```
+
+### Chain-of-Thought Reasoning
+
+Enable `reasoning = true` to use DSPy's `ChainOfThought` module. The reasoning is captured in a separate field:
+
+```lua
+local generator = LLMGenerator:new {
+    model = "openai/gpt-4o-mini",
+    reasoning = true
+}
+local result = generator:generate("What is 15% of 240?")
+
+-- Access both the reasoning and the final answer
+print("Reasoning:", result.reasoning)  -- "15% means 15/100 = 0.15. So 0.15 × 240 = 36"
+print("Answer:", result.output)        -- "36"
+```
+
+### JSON Output Format
+
+```lua
+local generator = LLMGenerator:new {
+    model = "openai/gpt-4o-mini",
+    output_format = "json"
+}
+local result = generator:generate("Return a JSON object with name, age, and city for a fictional person")
+-- result.output will be valid JSON like: {"name": "Alice", "age": 28, "city": "Portland"}
+```
+
+### Custom System Prompt
+
+Your system prompt is passed directly to the LLM (no DSPy modifications):
+
+```lua
+local generator = LLMGenerator:new {
+    model = "openai/gpt-4o-mini",
+    system_prompt = "You are a helpful coding assistant specializing in Lua.",
+    temperature = 0.3
+}
+local result = generator:generate("How do I iterate over a table in Lua?")
+```
+
+### With Constraints
+
+```lua
+local generator = LLMGenerator:new {
+    model = "openai/gpt-4o-mini",
+    constraints = {"Keep response under 50 words", "Use simple language"}
+}
+local result = generator:generate("Explain quantum computing")
+```
+
+## Parameters Reference
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `model` | `string` | required | Model identifier (e.g., "openai/gpt-4o-mini") |
+| `temperature` | `number` | 0.7 | Generation randomness (0.0-1.0) |
+| `max_tokens` | `number` | nil | Maximum output tokens |
+| `reasoning` | `boolean` | false | Enable ChainOfThought mode (captures reasoning separately) |
+| `output_format` | `string` | "text" | Output format: "text", "json", "markdown" |
+| `system_prompt` | `string` | nil | Custom system prompt (passed directly, no modifications) |
+| `instructions` | `string` | nil | Additional generation instructions |
+| `constraints` | `string|table` | nil | Output constraints |
+| `max_retries` | `number` | 2 | Maximum retry attempts |
+
+## Result Fields
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `output` | `string` | The main generated output (final answer) |
+| `reasoning` | `string?` | Step-by-step reasoning (only when `reasoning = true`) |
+| `format` | `string` | The output format used |
+| `retry_count` | `number` | Number of retries that were needed |
+| `raw_response` | `string` | The raw response from the LLM |
+| `error` | `string?` | Error message if generation failed |
+
+## Future Enhancements
+
+Planned DSPy-inspired features:
+
+- **Few-shot examples**: Pass examples for in-context learning
+- **Optimizers**: Automatic prompt optimization with training data
+- **Assertions**: Output validation with automatic retry
+- **Parallel generation**: Multiple completions with selection
+
+## Extending Generators
+
+You can extend `BaseGenerator` to create custom generators:
+
+```lua
+local base = require("tactus.generate.base")
+local class = base.class
+local BaseGenerator = base.BaseGenerator
+
+MyGenerator = class(BaseGenerator)
+
+function MyGenerator:init(config)
+    BaseGenerator.init(self, config)
+    -- Your initialization
+end
+
+function MyGenerator:generate(prompt)
+    -- Your generation logic
+    return {
+        output = "...",
+        format = self.output_format,
+        retry_count = 0
+    }
+end
+```

tactus/stdlib/tac/tactus/generate/init.tac

@@ -0,0 +1,28 @@
+-- Tactus Generate Module
+--
+-- Provides flexible text generation with DSPy-inspired features:
+-- - LLM-based generation (tactus.generate.llm)
+-- - Optional chain-of-thought reasoning
+-- - Output format control (text, JSON, markdown)
+-- - Extensible base class (tactus.generate.base)
+--
+-- Usage:
+--   local generate = require("tactus.generate")
+--   local generator = generate.LLMGenerator:new{...}
+--
+-- Or load specific generators:
+--   local LLMGenerator = require("tactus.generate.llm")
+
+-- Load all submodules
+local base = require("tactus.generate.base")
+local llm = require("tactus.generate.llm")
+
+-- Re-export all classes
+return {
+    -- Core classes
+    BaseGenerator = base.BaseGenerator,
+    LLMGenerator = llm.LLMGenerator,
+
+    -- Helper for users who want to extend
+    class = base.class,
+}

tactus/stdlib/tac/tactus/generate/llm.tac

@@ -0,0 +1,169 @@
+-- LLM-Based Text Generation
+--
+-- Provides flexible text generation with DSPy-inspired features:
+-- - Configurable prompts and system instructions
+-- - Optional chain-of-thought reasoning
+-- - Output format control (text, JSON, markdown)
+-- - Retry logic for invalid responses
+-- - Few-shot examples support (future optimization)
+
+-- Load dependencies
+local base = require("tactus.generate.base")
+local BaseGenerator = base.BaseGenerator
+local class = base.class
+
+-- ============================================================================
+-- LLMGenerator
+-- ============================================================================
+
+local LLMGenerator = class(BaseGenerator)
+
+function LLMGenerator:init(config)
+    BaseGenerator.init(self, config)
+
+    -- Build system prompt (without reasoning - ChainOfThought handles that)
+    local full_system_prompt = self:build_system_prompt()
+
+    -- Create agent configuration
+    -- Default: "Raw" module (no prompt modifications)
+    -- With reasoning: "ChainOfThought" module (DSPy's reasoning)
+    local agent_config = {
+        system_prompt = full_system_prompt,
+        temperature = self.temperature,
+    }
+
+    -- Use ChainOfThought module when reasoning is enabled
+    -- Otherwise, Agent defaults to "Raw" (no prompt modifications)
+    if self.reasoning then
+        agent_config.module = "ChainOfThought"
+    end
+
+    -- Parse model string (e.g., "openai/gpt-4o-mini")
+    if self.model then
+        local provider, model_id = self.model:match("([^/]+)/(.+)")
+        if provider and model_id then
+            agent_config.provider = provider
+            agent_config.model = model_id
+        end
+    end
+
+    -- Add max_tokens if specified
+    if self.max_tokens then
+        agent_config.max_tokens = self.max_tokens
+    end
+
+    if self.name then
+        self.agent = Agent(self.name)(agent_config)
+    else
+        self.agent = Agent(agent_config)
+    end
+end
+
+function LLMGenerator:generate(prompt)
+    local retry_count = 0
+    local last_response = nil
+    local last_error = nil
+
+    for attempt = 1, self.max_retries + 1 do
+        -- Call agent
+        local ok, agent_result = pcall(function()
+            return self.agent({message = prompt})
+        end)
+
+        if not ok then
+            last_error = agent_result
+            retry_count = retry_count + 1
+        else
+            local output = agent_result.output
+            local response_text = nil
+            local reasoning_text = nil
+
+            -- Handle different output formats from DSPy modules
+            if type(output) == "table" then
+                -- ChainOfThought returns {reasoning: ..., response: ...}
+                response_text = tostring(output.response or "")
+                reasoning_text = output.reasoning and tostring(output.reasoning) or nil
+                last_response = response_text
+            else
+                -- Raw module returns plain text
+                response_text = tostring(output or "")
+                last_response = response_text
+
+                -- For raw mode with reasoning enabled, try to parse structured output
+                -- (This handles edge cases where manual reasoning format was used)
+                if self.reasoning and type(response_text) == "string" then
+                    local parsed = self:parse_reasoning_response(response_text)
+                    response_text = parsed.response
+                    reasoning_text = parsed.reasoning
+                end
+            end
+
+            -- Validate response based on format
+            local valid = self:validate_response(response_text)
+
+            if valid then
+                return {
+                    output = response_text,
+                    reasoning = reasoning_text,
+                    format = self.output_format,
+                    retry_count = retry_count,
+                    raw_response = last_response
+                }
+            end
+
+            retry_count = retry_count + 1
+        end
+    end
+
+    -- All retries exhausted
+    return {
+        output = last_response or "",
+        reasoning = nil,
+        format = self.output_format,
+        retry_count = retry_count,
+        error = last_error or "Failed to generate valid response after " .. self.max_retries .. " retries",
+        raw_response = last_response
+    }
+end
+
+function LLMGenerator:validate_response(response)
+    -- Ensure response is a string
+    if response == nil then
+        return false
+    end
+
+    -- Convert to string if needed (handles Python objects)
+    local response_str = tostring(response)
+
+    -- Basic validation - ensure we got something
+    if #response_str == 0 then
+        return false
+    end
+
+    -- JSON format validation
+    if self.output_format == "json" then
+        -- Try to detect valid JSON (basic check)
+        local trimmed = response_str:gsub("^%s+", ""):gsub("%s+$", "")
+
+        -- Should start with { or [
+        if not (trimmed:match("^%{") or trimmed:match("^%[")) then
+            return false
+        end
+
+        -- Should end with } or ]
+        if not (trimmed:match("%}$") or trimmed:match("%]$")) then
+            return false
+        end
+    end
+
+    return true
+end
+
+function LLMGenerator:__call(prompt)
+    return self:generate(prompt)
+end
+
+-- Export LLMGenerator
+return {
+    LLMGenerator = LLMGenerator,
+}

tactus/stdlib/tac/tactus/generate.spec.tac

@@ -0,0 +1,210 @@
+--[[doc
+# Generate Classes
+
+Flexible text generation with DSPy-inspired features:
+
+- **BaseGenerator**: Abstract base class for custom generators
+- **LLMGenerator**: LLM-based generation with configurable options
+
+## Usage
+
+```lua
+-- Import generate classes
+local generate = require("tactus.generate")
+local LLMGenerator = generate.LLMGenerator
+
+-- Or load directly:
+local LLMGenerator = require("tactus.generate.llm")
+
+-- Basic generation
+local generator = LLMGenerator:new {
+    model = "openai/gpt-4o-mini"
+}
+local result = generator:generate("Write a haiku about coding")
+
+-- With chain-of-thought reasoning (DSPy-inspired)
+local reasoning_generator = LLMGenerator:new {
+    model = "openai/gpt-4o-mini",
+    reasoning = true
+}
+local result = reasoning_generator:generate("Solve: What is 15% of 80?")
+-- result.reasoning contains step-by-step thinking
+-- result.output contains final answer
+
+-- JSON output format
+local json_generator = LLMGenerator:new {
+    model = "openai/gpt-4o-mini",
+    output_format = "json"
+}
+```
+
+## LLMGenerator Parameters
+
+- `model`: Model identifier (e.g., "openai/gpt-4o-mini")
+- `temperature`: Generation randomness (default: 0.7)
+- `max_tokens`: Maximum output tokens (optional)
+- `reasoning`: Enable chain-of-thought mode (default: false)
+- `output_format`: Output format - "text" (default), "json", "markdown"
+- `system_prompt`: Custom system prompt (optional)
+- `instructions`: Additional instructions (optional)
+- `constraints`: Output constraints (optional)
+- `max_retries`: Maximum retry attempts (default: 2)
+]]
+
+-- Load generate classes
+local generate = require("tactus.generate")
+local LLMGenerator = generate.LLMGenerator
+
+-- Local state for test context
+local test_state = {}
+
+-- Custom step definitions
+Step("an LLM generator", function(ctx)
+    test_state.generator_config = {
+        name = "stdlib_generate_llm",
+        model = "openai/gpt-4o-mini"
+    }
+end)
+
+Step("an LLM generator with reasoning enabled", function(ctx)
+    test_state.generator_config = {
+        name = "stdlib_generate_llm",
+        model = "openai/gpt-4o-mini",
+        reasoning = true
+    }
+end)
+
+Step("an LLM generator with JSON output format", function(ctx)
+    test_state.generator_config = {
+        name = "stdlib_generate_llm",
+        model = "openai/gpt-4o-mini",
+        output_format = "json"
+    }
+end)
+
+Step("an LLM generator with markdown output format", function(ctx)
+    test_state.generator_config = {
+        name = "stdlib_generate_llm",
+        model = "openai/gpt-4o-mini",
+        output_format = "markdown"
+    }
+end)
+
+Step("temperature of (.+)", function(ctx, temp)
+    test_state.generator_config.temperature = tonumber(temp)
+end)
+
+Step("system prompt \"(.+)\"", function(ctx, prompt)
+    test_state.generator_config.system_prompt = prompt
+end)
+
+Step("I generate text for prompt \"(.+)\"", function(ctx, prompt)
+    if not test_state.generator then
+        test_state.generator = LLMGenerator:new(test_state.generator_config)
+    end
+    test_state.result = test_state.generator:generate(prompt)
+end)
+
+Step("the generation should succeed", function(ctx)
+    assert(test_state.result, "No generation result found")
+    assert(not test_state.result.error,
+        "Generation failed with error: " .. tostring(test_state.result.error))
+end)
+
+Step("the output should not be empty", function(ctx)
+    assert(test_state.result, "No generation result found")
+    assert(test_state.result.output, "No output in result")
+    assert(#test_state.result.output > 0, "Output is empty")
+end)
+
+Step("the result format should be \"(.+)\"", function(ctx, expected_format)
+    assert(test_state.result, "No generation result found")
+    assert(test_state.result.format == expected_format,
+        "Expected format '" .. expected_format .. "' but got '" .. tostring(test_state.result.format) .. "'")
+end)
+
+Step("the result should include reasoning", function(ctx)
+    assert(test_state.result, "No generation result found")
+    -- Note: reasoning may or may not be parsed depending on LLM response format
+    -- We check that the result structure supports reasoning
+    assert(test_state.result.output ~= nil, "Output should be present")
+end)
+
+Step("the output should look like JSON", function(ctx)
+    assert(test_state.result, "No generation result found")
+    local output = test_state.result.output or ""
+    local trimmed = output:gsub("^%s+", ""):gsub("%s+$", "")
+    assert(trimmed:match("^%{") or trimmed:match("^%["),
+        "Output does not appear to be JSON: " .. output:sub(1, 100))
+end)
+
+Mocks {
+    stdlib_generate_llm = {
+        message = "Mocked response",
+        temporal = {
+            {
+                when_message = "Write a one-sentence description of the color blue.",
+                message = "Blue is a calm, cool color that often symbolizes clarity and depth."
+            },
+            {
+                when_message = "Generate a creative name for a coffee shop.",
+                message = "Amber Bean Cafe"
+            },
+            {
+                when_message = "What is 25% of 120? Explain your calculation.",
+                message = "REASONING: 25% is one quarter. 120 divided by 4 is 30. RESPONSE: 30"
+            },
+            {
+                when_message = "Return a JSON object with keys 'name' and 'age' for a fictional person.",
+                message = [[{"name":"Ava","age":28}]]
+            }
+        }
+    }
+}
+
+-- BDD Specifications
+Specification([[
+Feature: Generate Class Hierarchy
+  As a Tactus developer
+  I want to generate text with various options
+  So that I can create content flexibly
+
+  Scenario: Basic text generation
+    Given an LLM generator
+    When I generate text for prompt "Write a one-sentence description of the color blue."
+    Then the generation should succeed
+    And the output should not be empty
+    And the result format should be "text"
+
+  Scenario: Generation with custom temperature
+    Given an LLM generator
+    And temperature of 0.9
+    When I generate text for prompt "Generate a creative name for a coffee shop."
+    Then the generation should succeed
+    And the output should not be empty
+
+  Scenario: Generation with reasoning mode
+    Given an LLM generator with reasoning enabled
+    When I generate text for prompt "What is 25% of 120? Explain your calculation."
+    Then the generation should succeed
+    And the output should not be empty
+    And the result should include reasoning
+
+  Scenario: JSON output format
+    Given an LLM generator with JSON output format
+    When I generate text for prompt "Return a JSON object with keys 'name' and 'age' for a fictional person."
+    Then the generation should succeed
+    And the output should not be empty
+    And the result format should be "json"
+    And the output should look like JSON
+]])
+
+-- Minimal procedure
+Procedure {
+    output = {
+        result = field.string{required = true}
+    },
+    function(input)
+        return {result = "Generate class hierarchy specs executed"}
+    end
+}