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

tactus/stdlib/extract/llm.py

@@ -0,0 +1,330 @@
+"""
+LLMExtractor - Information extraction using Language Models with retry logic.
+
+This extractor uses an LLM (via agent_factory) to extract structured data from text,
+with built-in retry logic and JSON schema validation.
+"""
+
+import json
+import logging
+import re
+from typing import Any, Callable, Dict, List, Optional
+
+from ..core.base import BaseExtractor
+from ..core.models import ExtractorResult
+
+logger = logging.getLogger(__name__)
+
+
+class LLMExtractor(BaseExtractor):
+    """
+    LLM-based extractor with automatic retry and validation.
+
+    Uses conversational feedback to help the LLM self-correct when it
+    returns invalid or incomplete extractions.
+
+    Example:
+        extractor = LLMExtractor(
+            fields={"name": "string", "age": "number", "email": "string"},
+            prompt="Extract customer information from this text",
+            agent_factory=my_agent_factory,
+        )
+        result = extractor.extract("John Smith is 34 years old. Contact: john@example.com")
+        # result.fields = {"name": "John Smith", "age": 34, "email": "john@example.com"}
+    """
+
+    def __init__(
+        self,
+        fields: Dict[str, str],
+        prompt: str,
+        agent_factory: Callable[[Dict[str, Any]], Any],
+        max_retries: int = 3,
+        temperature: float = 0.3,
+        model: Optional[str] = None,
+        strict: bool = True,
+        name: Optional[str] = None,
+    ):
+        """
+        Initialize LLMExtractor.
+
+        Args:
+            fields: Dict mapping field names to their types
+                   (e.g., {"name": "string", "age": "number", "items": "list"})
+            prompt: Extraction instruction/prompt
+            agent_factory: Factory function to create Agent instances
+            max_retries: Maximum retry attempts on invalid output
+            temperature: LLM temperature for extraction
+            model: Specific model to use (optional)
+            strict: If True, all fields must be extracted; if False, missing fields are OK
+            name: Optional name for this extractor
+        """
+        self.fields = fields
+        self.name = name
+        self.prompt = prompt
+        self.agent_factory = agent_factory
+        self.max_retries = max_retries
+        self.temperature = temperature
+        self.model = model
+        self.strict = strict
+
+        # Build extraction system prompt
+        self._system_prompt = self._build_system_prompt()
+
+        # Create agent for extraction
+        self._agent = self._create_agent()
+
+        # Track statistics
+        self.total_calls = 0
+        self.total_retries = 0
+
+    def _build_system_prompt(self) -> str:
+        """Build the extraction system prompt."""
+        fields_description = "\n".join(
+            f"  - {name}: {type_}" for name, type_ in self.fields.items()
+        )
+
+        return f"""You are an information extraction assistant. Your task is to extract structured data according to the following instruction:
+
+{self.prompt}
+
+FIELDS TO EXTRACT:
+{fields_description}
+
+IMPORTANT RULES:
+1. You MUST respond with a valid JSON object containing the extracted fields.
+2. Include ONLY the specified fields in your response.
+3. Use null for fields that cannot be extracted from the input.
+4. For "number" fields, return numeric values (not strings).
+5. For "list" fields, return JSON arrays.
+6. For "boolean" fields, return true or false.
+7. Do NOT include any explanation or text outside the JSON.
+
+RESPONSE FORMAT:
+{{
+  "field1": "extracted value",
+  "field2": 123,
+  ...
+}}
+"""
+
+    def _create_agent(self) -> Any:
+        """Create the internal Agent for extraction."""
+        if self.agent_factory is None:
+            raise RuntimeError("LLMExtractor requires agent_factory")
+
+        agent_config = {
+            "system_prompt": self._system_prompt,
+            "temperature": self.temperature,
+        }
+        if self.model:
+            agent_config["model"] = self.model
+
+        return self.agent_factory(agent_config)
+
+    def extract(self, input_text: str) -> ExtractorResult:
+        """
+        Extract structured data from the input text with retry logic.
+
+        Args:
+            input_text: The text to extract from
+
+        Returns:
+            ExtractorResult with fields dict and validation info
+        """
+        self.total_calls += 1
+
+        # Reset agent conversation for fresh extraction
+        if hasattr(self._agent, "reset"):
+            self._agent.reset()
+
+        retry_count = 0
+        last_response = None
+        validation_errors = []
+
+        for attempt in range(self.max_retries + 1):
+            # Build the message for this attempt
+            if attempt == 0:
+                message = f"Please extract the following information:\n\n{input_text}"
+            else:
+                # Retry with feedback
+                retry_count += 1
+                self.total_retries += 1
+                message = self._build_retry_feedback(last_response, validation_errors)
+                logger.debug(f"Extraction retry {retry_count}: {message[:100]}...")
+
+            # Call the agent
+            try:
+                result = self._call_agent(message)
+                last_response = result.get("response") or result.get("message") or str(result)
+            except Exception as e:
+                logger.error(f"Agent call failed: {e}")
+                return ExtractorResult(
+                    fields={},
+                    error=str(e),
+                    retry_count=retry_count,
+                )
+
+            # Parse the response
+            parsed, validation_errors = self._parse_response(last_response)
+
+            # Check if extraction is valid
+            if not validation_errors:
+                return ExtractorResult(
+                    fields=parsed,
+                    retry_count=retry_count,
+                    raw_response=last_response,
+                )
+
+            logger.debug(f"Invalid extraction: {validation_errors}")
+
+        # All retries exhausted
+        logger.warning(f"Extraction failed after {self.max_retries} retries")
+        return ExtractorResult(
+            fields=parsed if "parsed" in dir() else {},
+            validation_errors=validation_errors,
+            error=f"Max retries ({self.max_retries}) exceeded. Validation errors: {validation_errors}",
+            retry_count=retry_count,
+            raw_response=last_response,
+        )
+
+    def _call_agent(self, message: str) -> Dict[str, Any]:
+        """Call the internal agent with a message."""
+        input_dict = {"message": message}
+        result = self._agent(input_dict)
+
+        # Convert result to dict
+        if hasattr(result, "to_dict"):
+            return result.to_dict()
+        if hasattr(result, "message"):
+            return {"response": result.message}
+        if hasattr(result, "response"):
+            return {"response": result.response}
+        if isinstance(result, dict):
+            return result
+
+        return {"response": str(result)}
+
+    def _build_retry_feedback(self, last_response: str, errors: List[str]) -> str:
+        """Build feedback message for retry."""
+        errors_str = "\n".join(f"  - {e}" for e in errors)
+        fields_str = ", ".join(f'"{f}"' for f in self.fields.keys())
+
+        return f"""Your previous response was not valid JSON or had validation errors.
+
+Previous response:
+{last_response[:500]}
+
+Errors:
+{errors_str}
+
+Please respond with ONLY a valid JSON object containing these fields: {fields_str}
+
+Do NOT include any explanation or text outside the JSON object."""
+
+    def _parse_response(self, response: str) -> tuple[Dict[str, Any], List[str]]:
+        """
+        Parse extraction response and validate against schema.
+
+        Returns:
+            Tuple of (extracted_fields, validation_errors)
+        """
+        if not response:
+            return {}, ["Empty response"]
+
+        # Try to extract JSON from response
+        json_match = re.search(r"\{[^{}]*\}", response, re.DOTALL)
+        if not json_match:
+            # Try to find JSON with nested braces
+            json_match = re.search(r"\{.*\}", response, re.DOTALL)
+
+        if not json_match:
+            return {}, ["No JSON object found in response"]
+
+        try:
+            parsed = json.loads(json_match.group())
+        except json.JSONDecodeError as e:
+            return {}, [f"Invalid JSON: {e}"]
+
+        # Validate fields
+        validation_errors = []
+        result = {}
+
+        for field_name, field_type in self.fields.items():
+            if field_name not in parsed:
+                if self.strict:
+                    validation_errors.append(f"Missing required field: {field_name}")
+                result[field_name] = None
+            else:
+                value = parsed[field_name]
+                validated, error = self._validate_field(field_name, value, field_type)
+                if error:
+                    validation_errors.append(error)
+                result[field_name] = validated
+
+        return result, validation_errors
+
+    def _validate_field(
+        self, field_name: str, value: Any, field_type: str
+    ) -> tuple[Any, Optional[str]]:
+        """
+        Validate a field value against its type.
+
+        Returns:
+            Tuple of (validated_value, error_message or None)
+        """
+        if value is None:
+            return None, None
+
+        type_lower = field_type.lower()
+
+        if type_lower == "string":
+            return str(value), None
+
+        elif type_lower == "number":
+            if isinstance(value, (int, float)):
+                return value, None
+            try:
+                return float(value), None
+            except (ValueError, TypeError):
+                return None, f"Field '{field_name}' must be a number, got: {type(value).__name__}"
+
+        elif type_lower == "integer":
+            if isinstance(value, int) and not isinstance(value, bool):
+                return value, None
+            try:
+                return int(float(value)), None
+            except (ValueError, TypeError):
+                return None, f"Field '{field_name}' must be an integer, got: {type(value).__name__}"
+
+        elif type_lower == "boolean":
+            if isinstance(value, bool):
+                return value, None
+            if isinstance(value, str):
+                if value.lower() in ("true", "yes", "1"):
+                    return True, None
+                if value.lower() in ("false", "no", "0"):
+                    return False, None
+            return None, f"Field '{field_name}' must be a boolean, got: {value}"
+
+        elif type_lower in ("list", "array"):
+            if isinstance(value, list):
+                return value, None
+            return None, f"Field '{field_name}' must be a list, got: {type(value).__name__}"
+
+        elif type_lower in ("dict", "object"):
+            if isinstance(value, dict):
+                return value, None
+            return None, f"Field '{field_name}' must be an object, got: {type(value).__name__}"
+
+        else:
+            # Unknown type, accept any value
+            return value, None
+
+    def reset(self) -> None:
+        """Reset the extractor state (clear agent conversation)."""
+        if hasattr(self._agent, "reset"):
+            self._agent.reset()
+
+    def __repr__(self) -> str:
+        fields_str = ", ".join(self.fields.keys())
+        return f"LLMExtractor(fields=[{fields_str}], calls={self.total_calls}, retries={self.total_retries})"

tactus/stdlib/extract/primitive.py

@@ -0,0 +1,256 @@
+"""
+ExtractPrimitive - Smart information extraction with built-in retry and validation.
+
+This primitive wraps the extraction infrastructure to provide:
+- Automatic retry with conversational feedback
+- JSON schema validation
+- Type coercion for extracted fields
+- Structured result format
+"""
+
+import logging
+from typing import Any, Dict
+
+from ..core.base import BaseExtractor, ExtractorFactory
+from ..core.models import ExtractorResult
+from .llm import LLMExtractor
+
+logger = logging.getLogger(__name__)
+
+__all__ = ["ExtractPrimitive", "ExtractHandle", "ExtractorResult"]
+
+# Register the LLM extractor as the default method
+ExtractorFactory.register("llm", LLMExtractor)
+
+
+class ExtractHandle:
+    """
+    A reusable extractor handle for Lua interop.
+
+    This is a wrapper around a BaseExtractor that handles
+    Lua table conversion.
+
+    Created by Extract { ... } and can be called multiple times.
+    """
+
+    def __init__(
+        self,
+        extractor: BaseExtractor,
+        lua_table_from: Any = None,
+    ):
+        """
+        Initialize ExtractHandle.
+
+        Args:
+            extractor: The underlying BaseExtractor instance
+            lua_table_from: Function to convert Python dicts to Lua tables
+        """
+        self._extractor = extractor
+        self.lua_table_from = lua_table_from
+
+        # Expose extractor attributes
+        self.fields = extractor.fields
+
+        # For test access
+        self._agent = getattr(extractor, "_agent", None)
+
+    def __call__(self, input_value: Any) -> ExtractorResult:
+        """
+        Extract from the input.
+
+        Args:
+            input_value: Input text or dict with 'text' field
+
+        Returns:
+            ExtractorResult with fields dict and validation info
+        """
+        # Extract text from input
+        if isinstance(input_value, dict):
+            text = input_value.get("text") or input_value.get("input") or str(input_value)
+        else:
+            text = str(input_value)
+
+        return self._extractor.extract(text)
+
+    def reset(self):
+        """Reset the extractor state."""
+        self._extractor.reset()
+
+    @property
+    def total_calls(self) -> int:
+        """Get total number of calls made."""
+        return getattr(self._extractor, "total_calls", 0)
+
+    @property
+    def total_retries(self) -> int:
+        """Get total number of retries."""
+        return getattr(self._extractor, "total_retries", 0)
+
+    def __repr__(self) -> str:
+        return f"ExtractHandle(extractor={self._extractor})"
+
+
+class ExtractPrimitive:
+    """
+    Smart extraction primitive with retry logic.
+
+    Follows the Agent pattern - can be configured once and called multiple times,
+    or used as a one-shot extractor.
+
+    Example usage in Lua:
+        -- One-shot extraction
+        data = Extract {
+            fields = {name = "string", age = "number", email = "string"},
+            prompt = "Extract customer information",
+            input = transcript
+        }
+        -- data.name = "John Smith"
+        -- data.age = 34
+        -- data.email = "john@example.com"
+
+        -- Reusable extractor
+        customer_extractor = Extract {
+            fields = {name = "string", age = "number"},
+            prompt = "Extract customer information"
+        }
+        data1 = customer_extractor(text1)
+        data2 = customer_extractor(text2)
+    """
+
+    def __init__(
+        self,
+        agent_factory: Any,
+        lua_table_from: Any = None,
+        registry: Any = None,
+        mock_manager: Any = None,
+    ):
+        """
+        Initialize ExtractPrimitive.
+
+        Args:
+            agent_factory: Factory function to create Agent instances
+            lua_table_from: Function to convert Python dicts to Lua tables
+            registry: Optional registry for accessing mocks
+            mock_manager: Optional mock manager for testing
+        """
+        self.agent_factory = agent_factory
+        self.lua_table_from = lua_table_from
+        self.registry = registry
+        self.mock_manager = mock_manager
+
+    def __call__(self, config: Dict[str, Any]) -> Any:
+        """
+        Create an extractor from configuration.
+
+        This is called when Lua does: Extract { ... }
+
+        Args:
+            config: Extraction configuration
+                - fields: Dict mapping field names to types (required)
+                - prompt: Extraction instruction (required)
+                - input: Optional input for one-shot extraction
+                - method: Extraction method ("llm", default: "llm")
+                - max_retries: Maximum retry attempts (default: 3)
+                - temperature: Model temperature (default: 0.3)
+                - model: Model to use (optional)
+                - strict: Whether all fields are required (default: True)
+
+        Returns:
+            ExtractHandle if no input provided (reusable)
+            dict if input provided (one-shot result)
+        """
+        # Convert Lua table to Python dict
+        config = self._lua_to_python(config)
+
+        # Validate required fields
+        fields = config.get("fields")
+        if not fields:
+            raise ValueError("Extract requires 'fields' field")
+
+        prompt = config.get("prompt")
+        if not prompt:
+            raise ValueError("Extract requires 'prompt' field")
+
+        # Create the extractor using the factory
+        extractor = self._create_extractor(config)
+
+        # Wrap in handle for Lua interop
+        handle = ExtractHandle(
+            extractor=extractor,
+            lua_table_from=self.lua_table_from,
+        )
+
+        # If input is provided, do one-shot extraction
+        input_text = config.get("input")
+        if input_text is not None:
+            result = handle(input_text)
+            # Return extracted fields as a flat dict for Lua convenience
+            return self._to_lua_table(result.to_lua_dict())
+
+        return handle
+
+    def _create_extractor(self, config: Dict[str, Any]) -> BaseExtractor:
+        """
+        Create an extractor based on configuration.
+
+        Args:
+            config: Configuration dict
+
+        Returns:
+            BaseExtractor instance
+        """
+        method = config.get("method", "llm")
+
+        if method == "llm":
+            return LLMExtractor(
+                fields=config["fields"],
+                prompt=config["prompt"],
+                agent_factory=self.agent_factory,
+                max_retries=config.get("max_retries", 3),
+                temperature=config.get("temperature", 0.3),
+                model=config.get("model"),
+                strict=config.get("strict", True),
+                name=config.get("name"),
+            )
+        else:
+            # Use the factory for other methods
+            factory_config = {**config, "agent_factory": self.agent_factory}
+            return ExtractorFactory.create(factory_config)
+
+    def _lua_to_python(self, value: Any) -> Any:
+        """Convert Lua table to Python dict recursively."""
+        if value is None:
+            return None
+
+        try:
+            from lupa import lua_type
+
+            if lua_type(value) == "table":
+                # Check if it's an array (1-indexed sequential keys)
+                result = {}
+                max_int_key = 0
+                has_string_keys = False
+
+                for k, v in value.items():
+                    if isinstance(k, int):
+                        max_int_key = max(max_int_key, k)
+                    else:
+                        has_string_keys = True
+                    result[k] = self._lua_to_python(v)
+
+                # If all keys are sequential integers 1..n, convert to list
+                if not has_string_keys and max_int_key == len(result):
+                    return [result[i] for i in range(1, max_int_key + 1)]
+
+                return result
+            return value
+        except ImportError:
+            return value
+
+    def _to_lua_table(self, value: Any) -> Any:
+        """Convert Python value to Lua table."""
+        if self.lua_table_from is None:
+            return value
+        if isinstance(value, dict):
+            return self.lua_table_from(value)
+        return value

tactus/stdlib/tac/tactus/classify/base.tac

@@ -0,0 +1,51 @@
+-- Base Classification Class
+--
+-- This module provides the foundation for all classifiers:
+-- - class() helper for Lua OOP with inheritance
+-- - BaseClassifier abstract base class
+
+-- 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)
+-- ============================================================================
+
+local 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
+
+-- Export classes and helpers
+return {
+    class = class,
+    BaseClassifier = BaseClassifier,
+}