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

tactus/stdlib/classify/classify.spec.tac

@@ -0,0 +1,195 @@
+--[[
+REFERENCE SPEC - Tests Python implementation
+
+The primary Tactus (.tac) implementation and spec is now at:
+  tactus/stdlib/tac/tactus/classify.spec.tac
+
+This spec remains for:
+- Testing Python fallback implementation
+- Documentation reference
+- Backwards compatibility verification
+]]
+
+--[[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.stdlib.classify")
+local LLMClassifier = classify.LLMClassifier
+local FuzzyMatchClassifier = classify.FuzzyMatchClassifier
+
+-- 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.
+]]
+
+-- 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/classify/classify.tac

@@ -0,0 +1,257 @@
+-- Classification Classes with Proper Inheritance
+--
+-- This implements a proper Lua class hierarchy for classifiers:
+-- - BaseClassifier (abstract base)
+-- - LLMClassifier (LLM-based classification)
+-- - FuzzyMatchClassifier (string similarity)
+
+-- Simple class system for Lua
+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
+
+-- ============================================================================
+-- BaseClassifier (Abstract Base Class)
+-- ============================================================================
+
+BaseClassifier = class()
+
+function BaseClassifier:init(config)
+    self.config = config or {}
+end
+
+function BaseClassifier:classify(text)
+    error("BaseClassifier.classify() must be implemented by subclass")
+end
+
+function BaseClassifier:__call(text)
+    return self:classify(text)
+end
+
+-- ============================================================================
+-- LLMClassifier
+-- ============================================================================
+
+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:turn({input = input_text})
+        last_response = agent_result.message or agent_result.content 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:turn({input = 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
+
+-- ============================================================================
+-- FuzzyMatchClassifier
+-- ============================================================================
+
+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 classes
+return {
+    BaseClassifier = BaseClassifier,
+    LLMClassifier = LLMClassifier,
+    FuzzyMatchClassifier = FuzzyMatchClassifier,
+}