tactus 0.32.2__py3-none-any.whl → 0.34.0__py3-none-any.whl

tactus/stdlib/tac/tactus/classify/fuzzy.tac

@@ -0,0 +1,87 @@
+-- Fuzzy String Matching Classification
+--
+-- Provides string similarity-based classification:
+-- - Configurable similarity threshold
+-- - Case-insensitive matching
+-- - Character overlap similarity algorithm
+
+-- Load dependencies
+local base = require("tactus.classify.base")
+local BaseClassifier = base.BaseClassifier
+local class = base.class
+
+-- ============================================================================
+-- FuzzyMatchClassifier
+-- ============================================================================
+
+local FuzzyMatchClassifier = class(BaseClassifier)
+
+function FuzzyMatchClassifier:init(config)
+    BaseClassifier.init(self, config)
+
+    assert(config.expected, "FuzzyMatchClassifier requires 'expected' field")
+
+    self.expected = config.expected
+    self.threshold = config.threshold or 0.8
+    self.classes = config.classes or {"Yes", "No"}
+end
+
+function FuzzyMatchClassifier:calculate_similarity(s1, s2)
+    s1 = s1:lower()
+    s2 = s2:lower()
+
+    if s1 == s2 then
+        return 1.0
+    end
+
+    if s1:find(s2, 1, true) or s2:find(s1, 1, true) then
+        return 0.85
+    end
+
+    -- Character overlap similarity
+    local set1 = {}
+    for i = 1, #s1 do
+        set1[s1:sub(i,i)] = true
+    end
+
+    local intersection = 0
+    local set2 = {}
+    for i = 1, #s2 do
+        local char = s2:sub(i,i)
+        set2[char] = true
+        if set1[char] then
+            intersection = intersection + 1
+        end
+    end
+
+    local union = 0
+    for _ in pairs(set1) do union = union + 1 end
+    for char in pairs(set2) do
+        if not set1[char] then
+            union = union + 1
+        end
+    end
+
+    if union == 0 then
+        return 0.0
+    end
+
+    return intersection / union
+end
+
+function FuzzyMatchClassifier:classify(input_text)
+    local similarity = self:calculate_similarity(input_text, self.expected)
+    local value = similarity >= self.threshold and self.classes[1] or self.classes[2]
+
+    return {
+        value = value,
+        confidence = similarity,
+        matched_text = self.expected,  -- What it matched against
+        retry_count = 0
+    }
+end
+
+-- Export FuzzyMatchClassifier
+return {
+    FuzzyMatchClassifier = FuzzyMatchClassifier,
+}

tactus/stdlib/tac/tactus/classify/index.md

@@ -0,0 +1,77 @@
+# Classification Module
+
+The `tactus.classify` module provides a comprehensive classification system with support for both LLM-based and fuzzy string matching approaches.
+
+## Overview
+
+All classifiers extend `BaseClassifier` and share a common interface, making them interchangeable. This enables you to switch between LLM and fuzzy matching without changing your code structure.
+
+## When to Use
+
+- **LLMClassifier**: Use when you need semantic understanding and context-aware classification. Ideal for ambiguous cases where the answer isn't just string matching.
+
+- **FuzzyMatchClassifier**: Use when you're matching against known expected values with typo tolerance. Much faster than LLM calls and doesn't require API access.
+
+## Architecture
+
+The module uses a proper Lua class hierarchy:
+
+- `BaseClassifier` - Abstract base with common interface
+- `LLMClassifier` - LLM-powered classification with automatic retry logic
+- `FuzzyMatchClassifier` - String similarity matching with configurable thresholds
+
+All classifiers return a consistent result format:
+
+```lua
+{
+    value = "Yes",           -- Classification result
+    confidence = 0.85,       -- Confidence score (0.0-1.0)
+    retry_count = 0,         -- Number of retries needed
+    matched_text = "yes",    -- Original matched text (fuzzy only)
+    raw_response = "..."     -- LLM response (LLM only)
+}
+```
+
+## Loading the Module
+
+```lua
+-- Load the main module
+local classify = require("tactus.classify")
+
+-- Or load specific classifiers (dependencies auto-load)
+local LLMClassifier = require("tactus.classify.llm")
+local FuzzyMatchClassifier = require("tactus.classify.fuzzy")
+```
+
+## Performance Notes
+
+- LLM classification typically takes 1-3 seconds per call
+- Fuzzy matching is nearly instantaneous (<1ms)
+- Consider caching LLM results for repeated classifications
+- Fuzzy matching works offline and requires no API keys
+
+## Extending Classifiers
+
+You can extend `BaseClassifier` to create custom classifiers:
+
+```lua
+local base = require("tactus.classify.base")
+local class = base.class
+local BaseClassifier = base.BaseClassifier
+
+MyClassifier = class(BaseClassifier)
+
+function MyClassifier:init(config)
+    BaseClassifier.init(self, config)
+    -- Your initialization
+end
+
+function MyClassifier:classify(text)
+    -- Your classification logic
+    return {
+        value = "Yes",
+        confidence = 1.0,
+        retry_count = 0
+    }
+end
+```

tactus/stdlib/tac/tactus/classify/init.tac

@@ -0,0 +1,29 @@
+-- Tactus Classification Module
+--
+-- Provides a comprehensive classification system with:
+-- - LLM-based classification (tactus.classify.llm)
+-- - Fuzzy string matching (tactus.classify.fuzzy)
+-- - Extensible base class (tactus.classify.base)
+--
+-- Usage:
+--   local classify = require("tactus.classify")
+--   local classifier = classify.LLMClassifier:new{...}
+--
+-- Or load specific classifiers:
+--   local LLMClassifier = require("tactus.classify.llm")
+
+-- Load all submodules
+local base = require("tactus.classify.base")
+local llm = require("tactus.classify.llm")
+local fuzzy = require("tactus.classify.fuzzy")
+
+-- Re-export all classes
+return {
+    -- Core classes
+    BaseClassifier = base.BaseClassifier,
+    LLMClassifier = llm.LLMClassifier,
+    FuzzyMatchClassifier = fuzzy.FuzzyMatchClassifier,
+
+    -- Helper for users who want to extend
+    class = base.class,
+}

tactus/stdlib/tac/tactus/classify/llm.tac

@@ -0,0 +1,150 @@
+-- LLM-Based Classification
+--
+-- Provides LLM-powered text classification with:
+-- - Retry logic for invalid responses
+-- - Multiple class support
+-- - Configurable confidence modes
+-- - Response parsing with fallbacks
+
+-- Load dependencies
+local base = require("tactus.classify.base")
+local BaseClassifier = base.BaseClassifier
+local class = base.class
+
+-- ============================================================================
+-- LLMClassifier
+-- ============================================================================
+
+local LLMClassifier = class(BaseClassifier)
+
+function LLMClassifier:init(config)
+    BaseClassifier.init(self, config)
+
+    -- Validate required fields
+    assert(config.classes, "LLMClassifier requires 'classes' field")
+    assert(config.prompt, "LLMClassifier requires 'prompt' field")
+
+    self.classes = config.classes
+    self.prompt = config.prompt
+    self.max_retries = config.max_retries or 3
+    self.temperature = config.temperature or 0.3
+    self.model = config.model
+    self.confidence_mode = config.confidence_mode or "heuristic"
+
+    -- Build classification prompt
+    local classes_str = table.concat(self.classes, ", ")
+    self.system_prompt = string.format([[%s
+
+You MUST respond with ONLY one of these values: %s
+
+Response format:
+- Start your response with the classification value on its own line
+- You may optionally explain your reasoning afterward
+
+Valid values: %s]], self.prompt, classes_str, classes_str)
+
+    -- Create agent
+    local agent_config = {
+        system_prompt = self.system_prompt,
+        temperature = self.temperature,
+    }
+
+    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
+
+    self.agent = Agent(agent_config)
+end
+
+function LLMClassifier:parse_response(response)
+    if not response or response == "" then
+        return nil
+    end
+
+    -- Get first line
+    local first_line = response:match("^([^\n]+)")
+    if not first_line then
+        first_line = response
+    end
+
+    -- Clean up formatting
+    first_line = first_line:gsub("[%*\"'`:%.]", ""):gsub("^%s+", ""):gsub("%s+$", "")
+    local first_line_lower = first_line:lower()
+
+    -- Create case-insensitive lookup
+    local value_map = {}
+    for _, v in ipairs(self.classes) do
+        value_map[v:lower()] = v
+    end
+
+    -- Exact match (case-insensitive)
+    if value_map[first_line_lower] then
+        return value_map[first_line_lower]
+    end
+
+    -- Prefix match
+    for v_lower, v_original in pairs(value_map) do
+        if first_line_lower:find("^" .. v_lower) then
+            return v_original
+        end
+    end
+
+    return nil
+end
+
+function LLMClassifier:classify(input_text)
+    local retry_count = 0
+    local last_response = nil
+
+    for attempt = 1, self.max_retries + 1 do
+        -- Call agent
+        local agent_result = self.agent({message = input_text})
+        last_response = agent_result.output or ""
+
+        -- Parse classification
+        local value = self:parse_response(last_response)
+
+        if value then
+            local result = {
+                value = value,
+                retry_count = retry_count,
+                raw_response = last_response
+            }
+
+            if self.confidence_mode == "heuristic" then
+                result.confidence = 0.8
+            end
+
+            return result
+        end
+
+        -- Retry
+        retry_count = retry_count + 1
+
+        if attempt <= self.max_retries then
+            local feedback = string.format(
+                "Your response '%s' is not valid. Please respond with ONLY one of: %s",
+                last_response,
+                table.concat(self.classes, ", ")
+            )
+            self.agent({message = feedback})
+        end
+    end
+
+    -- All retries exhausted
+    return {
+        value = "ERROR",
+        error = "Failed to get valid classification after " .. self.max_retries .. " retries",
+        retry_count = retry_count,
+        raw_response = last_response
+    }
+end
+
+-- Export LLMClassifier
+return {
+    LLMClassifier = LLMClassifier,
+}

tactus/stdlib/tac/tactus/classify.spec.tac

@@ -0,0 +1,191 @@
+--[[doc
+# Classification Classes
+
+Proper Lua class hierarchy for text classification:
+
+- **BaseClassifier**: Abstract base class
+- **LLMClassifier**: LLM-based classification with retry logic
+- **FuzzyMatchClassifier**: String similarity matching
+
+## Usage
+
+```lua
+-- Import classification classes
+local classify = require("tactus.classify")
+local LLMClassifier = classify.LLMClassifier
+local FuzzyMatchClassifier = classify.FuzzyMatchClassifier
+
+-- Or load specific classifiers (dependencies auto-load):
+local LLMClassifier = require("tactus.classify.llm")
+
+-- LLM Classification
+local classifier = LLMClassifier:new {
+    classes = {"Yes", "No"},
+    prompt = "Is this a question?",
+    model = "openai/gpt-4o-mini"
+}
+local result = classifier:classify("How are you?")
+
+-- Fuzzy Matching
+local fuzzy = FuzzyMatchClassifier:new {
+    expected = "hello",
+    threshold = 0.8
+}
+local result = fuzzy:classify("helo")
+```
+
+## LLMClassifier Parameters
+
+- `classes` (required): List of valid classification values
+- `prompt` (required): Classification instruction
+- `model`: Model identifier (e.g., "openai/gpt-4o-mini")
+- `temperature`: LLM temperature (default: 0.3)
+- `max_retries`: Maximum retry attempts (default: 3)
+- `confidence_mode`: "heuristic" or "none" (default: "heuristic")
+
+## FuzzyMatchClassifier Parameters
+
+- `expected` (required): Expected string to match against
+- `threshold`: Similarity threshold 0.0-1.0 (default: 0.8)
+- `classes`: Output values (default: ["Yes", "No"])
+
+## Confidence Warning
+
+LLM self-assessed confidence is generally unreliable unless calibrated
+for your specific use case. Consider using fuzzy matching or human
+review for high-stakes decisions.
+]]
+
+-- Load classification classes
+local classify = require("tactus.classify")
+local LLMClassifier = classify.LLMClassifier
+local FuzzyMatchClassifier = classify.FuzzyMatchClassifier
+
+-- Local state for test context
+local test_state = {}
+
+-- Custom step definitions
+Step("an LLM classifier with classes (.+)", function(ctx, classes_str)
+    local classes = {}
+    for class in string.gmatch(classes_str, '"([^"]+)"') do
+        table.insert(classes, class)
+    end
+    test_state.classifier_config = {
+        classes = classes,
+        model = "openai/gpt-4o-mini"
+    }
+    test_state.classifier_type = "llm"
+end)
+
+Step("prompt \"(.+)\"", function(ctx, prompt)
+    test_state.classifier_config.prompt = prompt
+end)
+
+Step("a fuzzy classifier expecting \"(.+)\"", function(ctx, expected)
+    test_state.classifier_config = {
+        expected = expected
+    }
+    test_state.classifier_type = "fuzzy"
+end)
+
+Step("I create the classifier", function(ctx)
+    if test_state.classifier_type == "llm" then
+        test_state.classifier = LLMClassifier:new(test_state.classifier_config)
+    elseif test_state.classifier_type == "fuzzy" then
+        test_state.classifier = FuzzyMatchClassifier:new(test_state.classifier_config)
+    else
+        error("Unknown classifier type: " .. tostring(test_state.classifier_type))
+    end
+end)
+
+Step("I classify \"(.+)\"", function(ctx, text)
+    if not test_state.classifier then
+        if test_state.classifier_type == "llm" then
+            test_state.classifier = LLMClassifier:new(test_state.classifier_config)
+        else
+            test_state.classifier = FuzzyMatchClassifier:new(test_state.classifier_config)
+        end
+    end
+    test_state.result = test_state.classifier:classify(text)
+end)
+
+Step("the result value should be \"(.+)\"", function(ctx, expected)
+    assert(test_state.result, "No classification result found")
+    assert(test_state.result.value == expected,
+        "Expected '" .. expected .. "' but got '" .. tostring(test_state.result.value) .. "'")
+end)
+
+Step("the result should have a confidence score", function(ctx)
+    assert(test_state.result, "No classification result found")
+    assert(test_state.result.confidence ~= nil,
+        "Expected confidence score but got nil")
+    assert(type(test_state.result.confidence) == "number",
+        "Confidence should be a number, got " .. type(test_state.result.confidence))
+    assert(test_state.result.confidence >= 0.0 and test_state.result.confidence <= 1.0,
+        "Confidence should be between 0 and 1, got " .. tostring(test_state.result.confidence))
+end)
+
+Step("the matched_text should be \"(.+)\"", function(ctx, expected)
+    assert(test_state.result, "No classification result found")
+    assert(test_state.result.matched_text == expected,
+        "Expected matched_text '" .. expected .. "' but got '" .. tostring(test_state.result.matched_text) .. "'")
+end)
+
+-- BDD Specifications
+Specification([[
+Feature: Classification Class Hierarchy
+  As a Tactus developer
+  I want to use proper OOP classifiers
+  So that I can extend and compose classification behavior
+
+  Scenario: LLM binary classification
+    Given an LLM classifier with classes "Yes" and "No"
+    And prompt "Is this a question?"
+    When I classify "How are you?"
+    Then the result value should be "Yes"
+    And the result should have a confidence score
+
+  Scenario: LLM multi-class classification
+    Given an LLM classifier with classes "positive", "negative", and "neutral"
+    And prompt "What is the sentiment?"
+    When I classify "I love this product!"
+    Then the result value should be "positive"
+
+  Scenario: LLM negative sentiment
+    Given an LLM classifier with classes "positive", "negative", and "neutral"
+    And prompt "What is the sentiment?"
+    When I classify "This is terrible"
+    Then the result value should be "negative"
+
+  Scenario: LLM neutral sentiment
+    Given an LLM classifier with classes "positive", "negative", and "neutral"
+    And prompt "What is the sentiment?"
+    When I classify "The sky is blue"
+    Then the result value should be "neutral"
+
+  Scenario: Fuzzy match with typo
+    Given a fuzzy classifier expecting "hello"
+    When I classify "helo"
+    Then the result value should be "Yes"
+    And the matched_text should be "hello"
+
+  Scenario: Fuzzy match exact
+    Given a fuzzy classifier expecting "hello"
+    When I classify "hello"
+    Then the result value should be "Yes"
+
+  Scenario: Fuzzy match failure
+    Given a fuzzy classifier expecting "hello"
+    When I classify "goodbye"
+    Then the result value should be "No"
+]])
+
+-- Minimal procedure
+Procedure {
+    output = {
+        result = field.string{required = true}
+    },
+    function(input)
+        return {result = "Classification class hierarchy specs executed"}
+    end
+}

tactus/stdlib/tac/tactus/extract/base.tac

@@ -0,0 +1,138 @@
+-- Base Extraction Class
+--
+-- This module provides the foundation for all extractors:
+-- - class() helper for Lua OOP with inheritance
+-- - BaseExtractor abstract base class
+
+-- Simple class system for Lua (shared with classify module pattern)
+local function class(base)
+    local c = {}
+    if base then
+        for k, v in pairs(base) do
+            c[k] = v
+        end
+        c._base = base
+    end
+    c.__index = c
+
+    function c:new(config)
+        local instance = setmetatable({}, self)
+        if instance.init then
+            instance:init(config)
+        end
+        return instance
+    end
+
+    return c
+end
+
+-- ============================================================================
+-- BaseExtractor (Abstract Base Class)
+-- ============================================================================
+
+local BaseExtractor = class()
+
+function BaseExtractor:init(config)
+    self.config = config or {}
+    self.fields = config.fields or {}
+    self.prompt = config.prompt or ""
+    self.strict = config.strict ~= false  -- Default to strict mode
+    self.max_retries = config.max_retries or 3
+end
+
+function BaseExtractor:extract(text)
+    error("BaseExtractor.extract() must be implemented by subclass")
+end
+
+function BaseExtractor:__call(text)
+    return self:extract(text)
+end
+
+-- Helper to validate extracted fields against schema
+function BaseExtractor:validate_fields(extracted, schema)
+    local errors = {}
+    local result = {}
+
+    for field_name, field_type in pairs(schema) do
+        local value = extracted[field_name]
+
+        if value == nil then
+            if self.strict then
+                table.insert(errors, "Missing required field: " .. field_name)
+            end
+            result[field_name] = nil
+        else
+            local validated, err = self:validate_field(field_name, value, field_type)
+            if err then
+                table.insert(errors, err)
+            end
+            result[field_name] = validated
+        end
+    end
+
+    return result, errors
+end
+
+-- Validate a single field value against its type
+function BaseExtractor:validate_field(field_name, value, field_type)
+    if value == nil then
+        return nil, nil
+    end
+
+    local type_lower = string.lower(field_type)
+
+    if type_lower == "string" then
+        return tostring(value), nil
+
+    elseif type_lower == "number" then
+        local num = tonumber(value)
+        if num then
+            return num, nil
+        end
+        return nil, "Field '" .. field_name .. "' must be a number"
+
+    elseif type_lower == "integer" then
+        local num = tonumber(value)
+        if num then
+            return math.floor(num), nil
+        end
+        return nil, "Field '" .. field_name .. "' must be an integer"
+
+    elseif type_lower == "boolean" then
+        if type(value) == "boolean" then
+            return value, nil
+        end
+        if type(value) == "string" then
+            local lower = string.lower(value)
+            if lower == "true" or lower == "yes" or lower == "1" then
+                return true, nil
+            end
+            if lower == "false" or lower == "no" or lower == "0" then
+                return false, nil
+            end
+        end
+        return nil, "Field '" .. field_name .. "' must be a boolean"
+
+    elseif type_lower == "list" or type_lower == "array" then
+        if type(value) == "table" then
+            return value, nil
+        end
+        return nil, "Field '" .. field_name .. "' must be a list"
+
+    elseif type_lower == "object" or type_lower == "dict" then
+        if type(value) == "table" then
+            return value, nil
+        end
+        return nil, "Field '" .. field_name .. "' must be an object"
+
+    else
+        -- Unknown type, accept any value
+        return value, nil
+    end
+end
+
+-- Export classes and helpers
+return {
+    class = class,
+    BaseExtractor = BaseExtractor,
+}