tactus 0.31.2__py3-none-any.whl

tactus/primitives/log.py

@@ -0,0 +1,187 @@
+"""
+Log Primitive - Logging operations.
+
+Provides:
+- Log.debug(message, context={}) - Debug logging
+- Log.info(message, context={}) - Info logging
+- Log.warn(message, context={}) - Warning logging
+- Log.error(message, context={}) - Error logging
+"""
+
+import logging
+from typing import Any, Dict, Optional, TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from tactus.protocols.log_handler import LogHandler
+
+logger = logging.getLogger(__name__)
+
+
+class LogPrimitive:
+    """
+    Provides logging operations for procedures.
+
+    All methods log using Python's standard logging module
+    with appropriate log levels, and optionally send structured
+    events to a LogHandler for custom rendering.
+    """
+
+    def __init__(self, procedure_id: str, log_handler: Optional["LogHandler"] = None):
+        """
+        Initialize Log primitive.
+
+        Args:
+            procedure_id: ID of the running procedure (for context)
+            log_handler: Optional handler for structured log events
+        """
+        self.procedure_id = procedure_id
+        self.logger = logging.getLogger(f"procedure.{procedure_id}")
+        self.log_handler = log_handler
+
+    def _format_message(self, message: str, context: Optional[Dict[str, Any]] = None) -> str:
+        """Format log message with context."""
+        if context:
+            import json
+
+            # Convert Lua tables to Python dicts
+            context_dict = self._lua_to_python(context)
+            context_str = json.dumps(context_dict, indent=2)
+            return f"{message}\nContext: {context_str}"
+        return message
+
+    def _lua_to_python(self, obj: Any) -> Any:
+        """Convert Lua objects to Python equivalents recursively."""
+        # Check if it's a Lua table
+        if hasattr(obj, "items"):  # Lua table with dict-like interface
+            return {self._lua_to_python(k): self._lua_to_python(v) for k, v in obj.items()}
+        elif hasattr(obj, "__iter__") and not isinstance(obj, (str, bytes)):  # Lua array
+            try:
+                return [self._lua_to_python(v) for v in obj]
+            except Exception:  # noqa: E722
+                # If iteration fails, return as-is
+                return obj
+        else:
+            return obj
+
+    def debug(self, message: str, context: Optional[Dict[str, Any]] = None) -> None:
+        """
+        Log debug message.
+
+        Args:
+            message: Debug message
+            context: Optional context dict
+
+        Example (Lua):
+            Log.debug("Processing item", {index = i, item = item})
+        """
+        # Send to log handler if provided
+        if self.log_handler:
+            from tactus.protocols.models import LogEvent
+
+            context_dict = self._lua_to_python(context) if context else None
+            event = LogEvent(
+                level="DEBUG",
+                message=message,
+                context=context_dict,
+                logger_name=self.logger.name,
+                procedure_id=self.procedure_id,
+            )
+            self.log_handler.log(event)
+        else:
+            # Fall back to Python logging if no handler
+            formatted = self._format_message(message, context)
+            self.logger.debug(formatted)
+
+    def info(self, message: str, context: Optional[Dict[str, Any]] = None) -> None:
+        """
+        Log info message.
+
+        Args:
+            message: Info message
+            context: Optional context dict
+
+        Example (Lua):
+            Log.info("Phase complete", {duration = elapsed, items = count})
+        """
+        # Send to log handler if provided
+        if self.log_handler:
+            from tactus.protocols.models import LogEvent
+
+            context_dict = self._lua_to_python(context) if context else None
+            event = LogEvent(
+                level="INFO",
+                message=message,
+                context=context_dict,
+                logger_name=self.logger.name,
+                procedure_id=self.procedure_id,
+            )
+            self.log_handler.log(event)
+        else:
+            # Fall back to Python logging if no handler
+            formatted = self._format_message(message, context)
+            self.logger.info(formatted)
+
+    def warn(self, message: str, context: Optional[Dict[str, Any]] = None) -> None:
+        """
+        Log warning message.
+
+        Args:
+            message: Warning message
+            context: Optional context dict
+
+        Example (Lua):
+            Log.warn("Retry limit reached", {attempts = attempts})
+        """
+        # Send to log handler if provided
+        if self.log_handler:
+            from tactus.protocols.models import LogEvent
+
+            context_dict = self._lua_to_python(context) if context else None
+            event = LogEvent(
+                level="WARNING",
+                message=message,
+                context=context_dict,
+                logger_name=self.logger.name,
+                procedure_id=self.procedure_id,
+            )
+            self.log_handler.log(event)
+        else:
+            # Fall back to Python logging if no handler
+            formatted = self._format_message(message, context)
+            self.logger.warning(formatted)
+
+    def warning(self, message: str, context: Optional[Dict[str, Any]] = None) -> None:
+        """Alias for warn(), matching common logging APIs."""
+        self.warn(message, context)
+
+    def error(self, message: str, context: Optional[Dict[str, Any]] = None) -> None:
+        """
+        Log error message.
+
+        Args:
+            message: Error message
+            context: Optional context dict
+
+        Example (Lua):
+            Log.error("Operation failed", {error = last_error})
+        """
+        # Send to log handler if provided
+        if self.log_handler:
+            from tactus.protocols.models import LogEvent
+
+            context_dict = self._lua_to_python(context) if context else None
+            event = LogEvent(
+                level="ERROR",
+                message=message,
+                context=context_dict,
+                logger_name=self.logger.name,
+                procedure_id=self.procedure_id,
+            )
+            self.log_handler.log(event)
+        else:
+            # Fall back to Python logging if no handler
+            formatted = self._format_message(message, context)
+            self.logger.error(formatted)
+
+    def __repr__(self) -> str:
+        return f"LogPrimitive(procedure_id={self.procedure_id})"

tactus/primitives/message_history.py

@@ -0,0 +1,157 @@
+"""
+MessageHistory primitive for managing conversation history.
+
+Provides Lua-accessible methods for manipulating message history,
+aligned with pydantic-ai's message_history concept.
+"""
+
+from typing import Any, Optional
+
+try:
+    from pydantic_ai.messages import ModelMessage, ModelRequest, ModelResponse, TextPart
+except ImportError:
+    # Fallback types if pydantic_ai not available
+    ModelMessage = dict
+    ModelRequest = dict
+    ModelResponse = dict
+    TextPart = dict
+
+
+class MessageHistoryPrimitive:
+    """
+    Primitive for managing conversation message history.
+
+    Aligned with pydantic-ai's message_history concept.
+
+    Provides methods to:
+    - Append messages to history
+    - Inject system messages
+    - Clear history
+    - Access full history
+    - Save/load message history state
+    """
+
+    def __init__(self, message_history_manager=None, agent_name: Optional[str] = None):
+        """
+        Initialize MessageHistory primitive.
+
+        Args:
+            message_history_manager: MessageHistoryManager instance
+            agent_name: Name of the agent this message history belongs to
+        """
+        self.message_history_manager = message_history_manager
+        self.agent_name = agent_name
+
+    def append(self, message_data: dict) -> None:
+        """
+        Append a message to the message history.
+
+        Args:
+            message_data: Dict with 'role' and 'content' keys
+                         role: 'user', 'assistant', 'system'
+                         content: message text
+
+        Example:
+            MessageHistory.append({role = "user", content = "Hello"})
+        """
+        if not self.message_history_manager or not self.agent_name:
+            return
+
+        role = message_data.get("role", "user")
+        content = message_data.get("content", "")
+
+        # Create a simple message dict
+        message = {"role": role, "content": content}
+
+        self.message_history_manager.add_message(self.agent_name, message)
+
+    def inject_system(self, text: str) -> None:
+        """
+        Inject a system message into the message history.
+
+        This is useful for providing context or instructions
+        for the next agent turn.
+
+        Args:
+            text: System message content
+
+        Example:
+            MessageHistory.inject_system("Focus on security implications")
+        """
+        self.append({"role": "system", "content": text})
+
+    def clear(self) -> None:
+        """
+        Clear the message history for this agent.
+
+        Example:
+            MessageHistory.clear()
+        """
+        if not self.message_history_manager or not self.agent_name:
+            return
+
+        self.message_history_manager.clear_agent_history(self.agent_name)
+
+    def get(self) -> list:
+        """
+        Get the full message history for this agent.
+
+        Aligned with pydantic-ai's message_history concept.
+
+        Returns:
+            List of message dicts with 'role' and 'content' keys
+
+        Example:
+            local messages = MessageHistory.get()
+            for i, msg in ipairs(messages) do
+                Log.info(msg.role .. ": " .. msg.content)
+            end
+        """
+        if not self.message_history_manager or not self.agent_name:
+            return []
+
+        messages = self.message_history_manager.histories.get(self.agent_name, [])
+
+        # Convert to Lua-friendly format
+        result = []
+        for msg in messages:
+            if isinstance(msg, dict):
+                result.append({"role": msg.get("role", ""), "content": str(msg.get("content", ""))})
+            else:
+                # Handle pydantic_ai ModelMessage objects
+                try:
+                    result.append(
+                        {
+                            "role": getattr(msg, "role", ""),
+                            "content": str(getattr(msg, "content", "")),
+                        }
+                    )
+                except Exception:
+                    # Fallback: convert to string
+                    result.append({"role": "unknown", "content": str(msg)})
+
+        return result
+
+    def load_from_node(self, node: Any) -> None:
+        """
+        Load message history from a graph node.
+
+        Not yet implemented - placeholder for future graph support.
+
+        Args:
+            node: Graph node containing saved message history
+        """
+        # TODO: Implement when graph primitives are added
+        pass
+
+    def save_to_node(self, node: Any) -> None:
+        """
+        Save message history to a graph node.
+
+        Not yet implemented - placeholder for future graph support.
+
+        Args:
+            node: Graph node to save message history to
+        """
+        # TODO: Implement when graph primitives are added
+        pass

tactus/primitives/model.py

@@ -0,0 +1,163 @@
+"""
+Model primitive for ML inference with automatic checkpointing.
+"""
+
+import logging
+from typing import Any, Optional
+
+from tactus.core.execution_context import ExecutionContext
+
+logger = logging.getLogger(__name__)
+
+
+class ModelPrimitive:
+    """
+    Model primitive for ML inference operations.
+
+    Unlike agents (conversational LLMs), models handle:
+    - Classification (sentiment, intent, NER)
+    - Extraction (quotes, entities, facts)
+    - Embeddings (semantic search, clustering)
+    - Custom ML inference (any trained model)
+
+    Each .predict() call is automatically checkpointed for durability.
+    """
+
+    def __init__(
+        self,
+        model_name: str,
+        config: dict,
+        context: ExecutionContext | None = None,
+        mock_manager: Optional[Any] = None,
+    ):
+        """
+        Initialize model primitive.
+
+        Args:
+            model_name: Name of the model (for checkpointing)
+            config: Model configuration dict with:
+                - type: Backend type (http, pytorch, bert, sklearn, etc.)
+                - input: Optional input schema
+                - output: Optional output schema
+                - Backend-specific config (endpoint, path, etc.)
+            context: Execution context for checkpointing
+        """
+        self.model_name = model_name
+        self.config = config
+        self.context = context
+        self.mock_manager = mock_manager
+
+        # Extract optional input/output schemas
+        self.input_schema = config.get("input", {})
+        self.output_schema = config.get("output", {})
+
+        self.backend = self._create_backend(config)
+
+    def _create_backend(self, config: dict):
+        """
+        Create appropriate backend based on model type.
+
+        Args:
+            config: Model configuration
+
+        Returns:
+            Backend instance
+        """
+        model_type = config.get("type")
+
+        if model_type == "http":
+            from tactus.backends.http_backend import HTTPModelBackend
+
+            return HTTPModelBackend(
+                endpoint=config["endpoint"],
+                timeout=config.get("timeout", 30.0),
+                headers=config.get("headers"),
+            )
+
+        elif model_type == "pytorch":
+            from tactus.backends.pytorch_backend import PyTorchModelBackend
+
+            return PyTorchModelBackend(
+                path=config["path"],
+                device=config.get("device", "cpu"),
+                labels=config.get("labels"),
+            )
+
+        else:
+            raise ValueError(f"Unknown model type: {model_type}. Supported types: http, pytorch")
+
+    def predict(self, input_data: Any) -> Any:
+        """
+        Run model inference with automatic checkpointing.
+
+        Args:
+            input_data: Input to the model (format depends on backend)
+
+        Returns:
+            Model prediction result
+        """
+        if self.context is None:
+            # No context - run directly without checkpointing
+            return self.backend.predict_sync(input_data)
+
+        # With context - checkpoint the operation
+        # Capture source location
+        import inspect
+
+        frame = inspect.currentframe()
+        if frame and frame.f_back:
+            caller_frame = frame.f_back
+            source_info = {
+                "file": caller_frame.f_code.co_filename,
+                "line": caller_frame.f_lineno,
+                "function": caller_frame.f_code.co_name,
+            }
+        else:
+            source_info = None
+
+        return self.context.checkpoint(
+            fn=lambda: self._execute_predict(input_data),
+            checkpoint_type="model_predict",
+            source_info=source_info,
+        )
+
+    def _execute_predict(self, input_data: Any) -> Any:
+        """
+        Execute the actual prediction.
+
+        Args:
+            input_data: Input to the model
+
+        Returns:
+            Model prediction result
+        """
+        if self.mock_manager is not None:
+            args = input_data if isinstance(input_data, dict) else {"input": input_data}
+            mock_result = self.mock_manager.get_mock_response(self.model_name, args)
+            if mock_result is not None:
+                # Ensure temporal mocks advance and calls are available for assertions.
+                try:
+                    self.mock_manager.record_call(self.model_name, args, mock_result)
+                except Exception:
+                    pass
+                return mock_result
+
+        return self.backend.predict_sync(input_data)
+
+    def __call__(self, input_data: Any) -> Any:
+        """
+        Execute model inference using the callable interface.
+
+        This is an alias for predict() that enables the unified callable syntax:
+            result = classifier({text = "Hello"})
+
+        Args:
+            input_data: Input to the model (format depends on backend)
+
+        Returns:
+            Model prediction result
+        """
+        return self.predict(input_data)
+
+    def __repr__(self) -> str:
+        return f"ModelPrimitive({self.model_name}, type={self.config.get('type')})"