thoughtflow 0.0.1__py3-none-any.whl → 0.0.3__py3-none-any.whl

thoughtflow/action.py

@@ -0,0 +1,357 @@
+"""
+ACTION class for ThoughtFlow.
+
+The ACTION class encapsulates an external or internal operation that can be invoked 
+within a Thoughtflow agent workflow.
+"""
+
+from __future__ import annotations
+
+import json
+
+from thoughtflow._util import event_stamp
+
+
+class ACTION:
+    """
+    The ACTION class encapsulates an external or internal operation that can be invoked within a Thoughtflow agent.
+    It is designed to represent a single, named action (such as a tool call, API request, or function) whose result
+    is stored in the agent's state for later inspection, branching, or retry.
+    
+    An ACTION represents a discrete, named operation (function, API call, tool invocation) that can be defined once
+    and executed multiple times with different parameters. When executed, the ACTION handles logging, error management,
+    and result storage in a consistent way.
+    
+    Attributes:
+        name (str): Identifier for this action, used for logging and storing results.
+        id (str): Unique identifier for this action instance (event_stamp).
+        fn (callable): The function to execute when this action is called.
+        config (dict): Default configuration parameters that will be passed to the function.
+        result_key (str): Key where results are stored in memory (defaults to "{name}_result").
+        description (str): Human-readable description of what this action does.
+        last_result (Any): The most recent result from executing this action.
+        last_error (Exception): The most recent error from executing this action, if any.
+        execution_count (int): Number of times this action has been executed.
+        execution_history (list): Full execution history with timing and success/error tracking.
+    
+    Methods:
+        __init__(name, fn, config=None, result_key=None, description=None):
+            Initializes an ACTION with a name, function, and optional configuration.
+            
+        __call__(memory, **kwargs):
+            Executes the action function with the memory object and any override parameters.
+            The function receives (memory, **merged_kwargs) where merged_kwargs combines
+            self.config with any call-specific kwargs.
+            
+            Returns the memory object with results stored via set_var.
+            Logs execution details with JSON-formatted event data.
+            Tracks execution timing and history.
+            
+            Handles exceptions during execution by logging them rather than raising them,
+            allowing the workflow to continue and decide how to handle failures.
+            
+        get_last_result():
+            Returns the most recent result from executing this action.
+            
+        was_successful():
+            Returns True if the last execution was successful, False otherwise.
+            
+        reset_stats():
+            Resets execution statistics (count, last_result, last_error, execution_history).
+            
+        copy():
+            Returns a copy of this ACTION with a new ID and reset statistics.
+            
+        to_dict():
+            Returns a serializable dictionary representation of this action.
+            
+        from_dict(cls, data, fn_registry):
+            Class method to reconstruct an ACTION from a dictionary representation.
+    
+    Example Usage:
+        # Define a web search action
+        def search_web(memory, query, max_results=3):
+            # Implementation of web search
+            results = web_api.search(query, limit=max_results)
+            return {"status": "success", "hits": results}
+            
+        search_action = ACTION(
+            name="web_search",
+            fn=search_web,
+            config={"max_results": 5},
+            description="Searches the web for information"
+        )
+        
+        # Execute the action
+        memory = MEMORY()
+        memory = search_action(memory, query="thoughtflow framework")
+        
+        # Access results
+        result = memory.get_var("web_search_result")
+        
+        # Check execution history
+        print(search_action.execution_history[-1]['duration_ms'])  # Execution time
+        print(search_action.execution_history[-1]['success'])      # True/False
+    
+    Design Principles:
+        1. Explicit and inspectable operations with consistent logging
+        2. Predictable result storage via memory.set_var
+        3. Error handling that doesn't interrupt workflow execution
+        4. Composability with other Thoughtflow components (MEMORY, THOUGHT)
+        5. Serialization support for reproducibility
+        6. Full execution history with timing for debugging and optimization
+    """
+    
+    def __init__(self, name, fn, config=None, result_key=None, description=None):
+        """
+        Initialize an ACTION with a name, function, and optional configuration.
+        
+        Args:
+            name (str): Identifier for this action, used for logging and result storage.
+            fn (callable): The function to execute when this action is called.
+            config (dict, optional): Default configuration parameters passed to the function.
+            result_key (str, optional): Key where results are stored in memory (defaults to "{name}_result").
+            description (str, optional): Human-readable description of what this action does.
+        """
+        self.name = name
+        self.id = event_stamp()  # Unique identifier for this action instance
+        self.fn = fn
+        self.config = config or {}
+        self.result_key = result_key or "{}_result".format(name)
+        self.description = description or "Action: {}".format(name)
+        self.last_result = None
+        self.last_error = None
+        self.execution_count = 0
+        self.execution_history = []  # Full execution tracking with timing
+    
+    def __call__(self, memory, **kwargs):
+        """
+        Execute the action function with the memory object and any override parameters.
+        
+        Args:
+            memory (MEMORY): The memory object to update with results.
+            **kwargs: Parameters that override the default config for this execution.
+            
+        Returns:
+            MEMORY: The updated memory object with results stored in memory.vars[result_key].
+            
+        Note:
+            The function receives (memory, **merged_kwargs) where merged_kwargs combines
+            self.config with any call-specific kwargs.
+            
+            Exceptions during execution are logged rather than raised, allowing the
+            workflow to continue and decide how to handle failures.
+        """
+        import time as time_module
+        
+        start_time = time_module.time()
+        
+        # Merge default config with call-specific kwargs
+        merged_kwargs = {**self.config, **kwargs}
+        self.execution_count += 1
+        
+        try:
+            # Execute the function
+            result = self.fn(memory, **merged_kwargs)
+            self.last_result = result
+            self.last_error = None
+            
+            # Calculate execution duration
+            duration_ms = (time_module.time() - start_time) * 1000
+            
+            # Store result in memory using set_var (correct API)
+            if hasattr(memory, "set_var") and callable(getattr(memory, "set_var", None)):
+                memory.set_var(self.result_key, result, desc="Result of action: {}".format(self.name))
+            
+            # Build execution event for logging (JSON format like THOUGHT)
+            execution_event = {
+                'action_name': self.name,
+                'action_id': self.id,
+                'status': 'success',
+                'duration_ms': round(duration_ms, 2),
+                'result_key': self.result_key
+            }
+            
+            # Log successful execution (single message with JSON, no invalid details param)
+            if hasattr(memory, "add_log") and callable(getattr(memory, "add_log", None)):
+                memory.add_log("Action execution complete: " + json.dumps(execution_event))
+            
+            # Track execution history
+            self.execution_history.append({
+                'stamp': event_stamp(),
+                'memory_id': getattr(memory, 'id', None),
+                'duration_ms': duration_ms,
+                'success': True,
+                'error': None
+            })
+                
+        except Exception as e:
+            # Handle and log exceptions
+            self.last_error = e
+            
+            # Calculate execution duration
+            duration_ms = (time_module.time() - start_time) * 1000
+            
+            # Build error event for logging
+            error_event = {
+                'action_name': self.name,
+                'action_id': self.id,
+                'status': 'error',
+                'error': str(e),
+                'duration_ms': round(duration_ms, 2),
+                'result_key': self.result_key
+            }
+            
+            # Log failed execution (single message with JSON)
+            if hasattr(memory, "add_log") and callable(getattr(memory, "add_log", None)):
+                memory.add_log("Action execution failed: " + json.dumps(error_event))
+            
+            # Store error info in memory using set_var
+            if hasattr(memory, "set_var") and callable(getattr(memory, "set_var", None)):
+                memory.set_var(self.result_key, error_event, desc="Error in action: {}".format(self.name))
+            
+            # Track execution history
+            self.execution_history.append({
+                'stamp': event_stamp(),
+                'memory_id': getattr(memory, 'id', None),
+                'duration_ms': duration_ms,
+                'success': False,
+                'error': str(e)
+            })
+        
+        return memory
+    
+    def get_last_result(self):
+        """
+        Returns the most recent result from executing this action.
+        
+        Returns:
+            Any: The last result or None if the action hasn't been executed.
+        """
+        return self.last_result
+    
+    def was_successful(self):
+        """
+        Returns True if the last execution was successful, False otherwise.
+        
+        Returns:
+            bool: True if the last execution completed without errors, False otherwise.
+        """
+        return self.last_error is None and self.execution_count > 0
+    
+    def reset_stats(self):
+        """
+        Resets execution statistics (count, last_result, last_error, execution_history).
+        
+        Returns:
+            ACTION: Self for method chaining.
+        """
+        self.execution_count = 0
+        self.last_result = None
+        self.last_error = None
+        self.execution_history = []
+        return self
+    
+    def copy(self):
+        """
+        Return a copy of this ACTION with a new ID.
+        
+        The function reference is shared (same callable), but config is copied.
+        Execution statistics are reset in the copy.
+        
+        Returns:
+            ACTION: A new ACTION instance with copied attributes and new ID.
+        """
+        new_action = ACTION(
+            name=self.name,
+            fn=self.fn,  # Same function reference
+            config=self.config.copy() if self.config else None,
+            result_key=self.result_key,
+            description=self.description
+        )
+        # New ID is already assigned in __init__, no need to set it
+        return new_action
+    
+    def to_dict(self):
+        """
+        Returns a serializable dictionary representation of this action.
+        
+        Note: The function itself cannot be serialized, so it's represented by name.
+        When deserializing, a function registry must be provided.
+        
+        Returns:
+            dict: Serializable representation of this action.
+        """
+        return {
+            "name": self.name,
+            "id": self.id,
+            "fn_name": self.fn.__name__,
+            "config": self.config,
+            "result_key": self.result_key,
+            "description": self.description,
+            "execution_count": self.execution_count,
+            "execution_history": self.execution_history
+        }
+    
+    @classmethod
+    def from_dict(cls, data, fn_registry):
+        """
+        Reconstruct an ACTION from a dictionary representation.
+        
+        Args:
+            data (dict): Dictionary representation of an ACTION.
+            fn_registry (dict): Dictionary mapping function names to function objects.
+            
+        Returns:
+            ACTION: Reconstructed ACTION object.
+            
+        Raises:
+            KeyError: If the function name is not found in the registry.
+        """
+        if data["fn_name"] not in fn_registry:
+            raise KeyError("Function '{}' not found in registry".format(data['fn_name']))
+            
+        action = cls(
+            name=data["name"],
+            fn=fn_registry[data["fn_name"]],
+            config=data["config"],
+            result_key=data["result_key"],
+            description=data["description"]
+        )
+        # Restore ID if provided, otherwise keep the new one from __init__
+        if data.get("id"):
+            action.id = data["id"]
+        action.execution_count = data.get("execution_count", 0)
+        action.execution_history = data.get("execution_history", [])
+        return action
+    
+    def __str__(self):
+        """
+        Returns a string representation of this action.
+        
+        Returns:
+            str: String representation.
+        """
+        return "ACTION({}, desc='{}', executions={})".format(self.name, self.description, self.execution_count)
+    
+    def __repr__(self):
+        """
+        Returns a detailed string representation of this action.
+        
+        Returns:
+            str: Detailed string representation.
+        """
+        return ("ACTION(name='{}', fn={}, "
+                "config={}, result_key='{}', "
+                "description='{}', execution_count={})".format(
+                    self.name, self.fn.__name__, self.config, 
+                    self.result_key, self.description, self.execution_count))
+
+
+### ACTION CLASS TESTS
+
+ActionClassTests = """
+# --- ACTION Class Tests ---
+
+
+"""

thoughtflow/agent.py

@@ -0,0 +1,66 @@
+"""
+DEPRECATED: Use THOUGHT class instead.
+
+The Agent class has been replaced by the THOUGHT class which provides
+a more powerful and flexible interface for LLM interactions.
+
+Example migration:
+    # Old (deprecated):
+    agent = Agent(adapter)
+    response = agent.call(messages)
+    
+    # New:
+    from thoughtflow import THOUGHT, MEMORY, LLM
+    
+    llm = LLM("openai:gpt-4o", key="your-api-key")
+    thought = THOUGHT(name="my_thought", llm=llm, prompt="...")
+    memory = MEMORY()
+    memory = thought(memory)
+    result = memory.get_var("my_thought_result")
+"""
+
+from __future__ import annotations
+
+import warnings
+
+
+class Agent:
+    """
+    DEPRECATED: Use THOUGHT class instead.
+    
+    The Agent class has been deprecated in favor of the THOUGHT class,
+    which provides a more powerful and flexible interface for LLM interactions.
+    """
+    
+    def __init__(self, *args, **kwargs):
+        warnings.warn(
+            "Agent is deprecated. Use THOUGHT instead. "
+            "See the migration guide in the module docstring.",
+            DeprecationWarning,
+            stacklevel=2
+        )
+        raise NotImplementedError(
+            "Agent is deprecated. Use THOUGHT instead. "
+            "Example: thought = THOUGHT(name='my_thought', llm=llm, prompt='...')"
+        )
+
+
+class TracedAgent:
+    """
+    DEPRECATED: Use THOUGHT class instead.
+    
+    The TracedAgent class has been deprecated. THOUGHT provides built-in
+    execution history tracking and tracing capabilities.
+    """
+    
+    def __init__(self, *args, **kwargs):
+        warnings.warn(
+            "TracedAgent is deprecated. Use THOUGHT instead. "
+            "THOUGHT provides built-in execution history tracking.",
+            DeprecationWarning,
+            stacklevel=2
+        )
+        raise NotImplementedError(
+            "TracedAgent is deprecated. Use THOUGHT instead. "
+            "THOUGHT provides built-in execution history tracking via execution_history."
+        )

thoughtflow/eval/__init__.py

@@ -0,0 +1,34 @@
+"""
+Evaluation utilities for ThoughtFlow.
+
+Deterministic evaluation is a first-class constraint in ThoughtFlow.
+This module provides utilities for:
+- Record/replay workflows
+- Golden tests (expected response shape/constraints)
+- Prompt/version pinning
+- Stable metrics extraction from traces
+
+Example:
+    >>> from thoughtflow.eval import Replay, Harness
+    >>>
+    >>> # Record a session
+    >>> session = agent.call(messages, record=True)
+    >>> session.save("golden.json")
+    >>>
+    >>> # Replay and compare
+    >>> replay = Replay.load("golden.json")
+    >>> results = replay.run(agent)
+    >>> assert results.matches_expected()
+"""
+
+from __future__ import annotations
+
+from thoughtflow.eval.replay import Replay
+from thoughtflow.eval.harness import Harness, TestCase, TestResult
+
+__all__ = [
+    "Replay",
+    "Harness",
+    "TestCase",
+    "TestResult",
+]

thoughtflow/eval/harness.py

@@ -0,0 +1,200 @@
+"""
+Test harness for ThoughtFlow evaluations.
+
+Provides structured test cases and evaluation harnesses for
+systematic agent testing.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING, Any, Callable
+
+if TYPE_CHECKING:
+    from thoughtflow.agent import Agent
+    from thoughtflow.message import MessageList
+
+
+@dataclass
+class TestCase:
+    """A single test case for agent evaluation.
+
+    Attributes:
+        name: Human-readable name for the test.
+        messages: Input messages for the test.
+        params: Optional call parameters.
+        expected: Expected response (exact match or callable validator).
+        tags: Tags for filtering/grouping tests.
+        metadata: Additional test metadata.
+    """
+
+    name: str
+    messages: MessageList
+    params: dict[str, Any] | None = None
+    expected: str | Callable[[str], bool] | None = None
+    tags: list[str] = field(default_factory=list)
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+    def validate(self, response: str) -> bool:
+        """Validate a response against expectations.
+
+        Args:
+            response: The agent's response.
+
+        Returns:
+            True if valid, False otherwise.
+        """
+        if self.expected is None:
+            return True
+        if callable(self.expected):
+            return self.expected(response)
+        return response == self.expected
+
+
+@dataclass
+class TestResult:
+    """Result of running a test case.
+
+    Attributes:
+        test_case: The test case that was run.
+        passed: Whether the test passed.
+        response: The agent's response.
+        error: Error message if the test failed.
+        duration_ms: How long the test took.
+        metadata: Additional result metadata.
+    """
+
+    test_case: TestCase
+    passed: bool
+    response: str | None = None
+    error: str | None = None
+    duration_ms: int | None = None
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+
+class Harness:
+    """Test harness for running evaluation suites.
+
+    The Harness provides a structured way to:
+    - Define test cases
+    - Run them against agents
+    - Collect and analyze results
+
+    Example:
+        >>> harness = Harness()
+        >>>
+        >>> # Add test cases
+        >>> harness.add(TestCase(
+        ...     name="greeting",
+        ...     messages=[{"role": "user", "content": "Hello!"}],
+        ...     expected=lambda r: "hello" in r.lower()
+        ... ))
+        >>>
+        >>> # Run all tests
+        >>> results = harness.run(agent)
+        >>>
+        >>> # Check results
+        >>> print(f"Passed: {results.passed_count}/{results.total_count}")
+    """
+
+    def __init__(self) -> None:
+        """Initialize an empty harness."""
+        self.test_cases: list[TestCase] = []
+
+    def add(self, test_case: TestCase) -> None:
+        """Add a test case to the harness.
+
+        Args:
+            test_case: The test case to add.
+        """
+        self.test_cases.append(test_case)
+
+    def add_many(self, test_cases: list[TestCase]) -> None:
+        """Add multiple test cases.
+
+        Args:
+            test_cases: List of test cases to add.
+        """
+        self.test_cases.extend(test_cases)
+
+    def filter_by_tags(self, tags: list[str]) -> list[TestCase]:
+        """Filter test cases by tags.
+
+        Args:
+            tags: Tags to filter by.
+
+        Returns:
+            Test cases matching any of the specified tags.
+        """
+        return [tc for tc in self.test_cases if any(t in tc.tags for t in tags)]
+
+    def run(
+        self,
+        agent: Agent,
+        filter_tags: list[str] | None = None,
+    ) -> HarnessResults:
+        """Run all test cases against an agent.
+
+        Args:
+            agent: The agent to test.
+            filter_tags: Optional tags to filter which tests to run.
+
+        Returns:
+            HarnessResults with all test results.
+
+        Raises:
+            NotImplementedError: This is a placeholder implementation.
+        """
+        # TODO: Implement test execution
+        raise NotImplementedError(
+            "Harness.run() is not yet implemented. "
+            "This is a placeholder for the ThoughtFlow alpha release."
+        )
+
+
+@dataclass
+class HarnessResults:
+    """Results from running a test harness.
+
+    Attributes:
+        results: Individual test results.
+        metadata: Harness-level metadata.
+    """
+
+    results: list[TestResult] = field(default_factory=list)
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+    @property
+    def total_count(self) -> int:
+        """Total number of tests run."""
+        return len(self.results)
+
+    @property
+    def passed_count(self) -> int:
+        """Number of tests that passed."""
+        return sum(1 for r in self.results if r.passed)
+
+    @property
+    def failed_count(self) -> int:
+        """Number of tests that failed."""
+        return self.total_count - self.passed_count
+
+    @property
+    def pass_rate(self) -> float:
+        """Percentage of tests that passed."""
+        if self.total_count == 0:
+            return 0.0
+        return self.passed_count / self.total_count
+
+    def summary(self) -> dict[str, Any]:
+        """Get a summary of the results.
+
+        Returns:
+            Dict with summary statistics.
+        """
+        return {
+            "total": self.total_count,
+            "passed": self.passed_count,
+            "failed": self.failed_count,
+            "pass_rate": self.pass_rate,
+        }