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

thoughtflow/tools/__init__.py

@@ -0,0 +1,27 @@
+"""
+Tool interfaces for ThoughtFlow.
+
+Tools are functions with contracts that agents can invoke.
+ThoughtFlow makes tool use explicit, testable, and auditable.
+
+Example:
+    >>> from thoughtflow.tools import Tool
+    >>>
+    >>> class Calculator(Tool):
+    ...     name = "calculator"
+    ...     description = "Perform arithmetic operations"
+    ...
+    ...     def call(self, payload):
+    ...         return eval(payload["expression"])
+"""
+
+from __future__ import annotations
+
+from thoughtflow.tools.base import Tool, ToolResult
+from thoughtflow.tools.registry import ToolRegistry
+
+__all__ = [
+    "Tool",
+    "ToolResult",
+    "ToolRegistry",
+]

thoughtflow/tools/base.py

@@ -0,0 +1,145 @@
+"""
+Base tool interface for ThoughtFlow.
+
+Tools are functions with contracts. Tool invocation is an explicit step,
+tool results are recorded in the trace, and tools can be simulated/stubbed
+for deterministic tests.
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass
+class ToolResult:
+    """Result of a tool invocation.
+
+    Attributes:
+        success: Whether the tool call succeeded.
+        output: The tool's output (if successful).
+        error: Error message (if failed).
+        metadata: Additional metadata about the call.
+    """
+
+    success: bool
+    output: Any = None
+    error: str | None = None
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+    @classmethod
+    def ok(cls, output: Any, **metadata: Any) -> ToolResult:
+        """Create a successful result.
+
+        Args:
+            output: The tool's output.
+            **metadata: Additional metadata.
+
+        Returns:
+            A successful ToolResult.
+        """
+        return cls(success=True, output=output, metadata=metadata)
+
+    @classmethod
+    def fail(cls, error: str, **metadata: Any) -> ToolResult:
+        """Create a failed result.
+
+        Args:
+            error: Error message.
+            **metadata: Additional metadata.
+
+        Returns:
+            A failed ToolResult.
+        """
+        return cls(success=False, error=error, metadata=metadata)
+
+
+class Tool(ABC):
+    """Abstract base class for tools.
+
+    Tools are the mechanism for agents to interact with the outside world.
+    Each tool has:
+    - A unique name
+    - A description (for the LLM to understand when to use it)
+    - A schema (JSON Schema for the expected input)
+    - A call method that executes the tool
+
+    Example:
+        >>> class WebSearch(Tool):
+        ...     name = "web_search"
+        ...     description = "Search the web for information"
+        ...
+        ...     def get_schema(self):
+        ...         return {
+        ...             "type": "object",
+        ...             "properties": {
+        ...                 "query": {"type": "string"}
+        ...             },
+        ...             "required": ["query"]
+        ...         }
+        ...
+        ...     def call(self, payload, params=None):
+        ...         query = payload["query"]
+        ...         # ... perform search ...
+        ...         return ToolResult.ok(results)
+    """
+
+    # Subclasses should override these
+    name: str = "unnamed_tool"
+    description: str = "No description provided"
+
+    @abstractmethod
+    def call(
+        self,
+        payload: dict[str, Any],
+        params: dict[str, Any] | None = None,
+    ) -> ToolResult:
+        """Execute the tool with the given payload.
+
+        Args:
+            payload: The input data for the tool.
+            params: Optional execution parameters.
+
+        Returns:
+            ToolResult indicating success/failure and output.
+        """
+        raise NotImplementedError
+
+    def get_schema(self) -> dict[str, Any]:
+        """Get the JSON Schema for the tool's input.
+
+        Override this to provide a schema for the LLM.
+
+        Returns:
+            JSON Schema dict describing expected input.
+        """
+        return {"type": "object", "properties": {}}
+
+    def to_openai_tool(self) -> dict[str, Any]:
+        """Convert to OpenAI tool format.
+
+        Returns:
+            Dict in OpenAI's tool specification format.
+        """
+        return {
+            "type": "function",
+            "function": {
+                "name": self.name,
+                "description": self.description,
+                "parameters": self.get_schema(),
+            },
+        }
+
+    def to_anthropic_tool(self) -> dict[str, Any]:
+        """Convert to Anthropic tool format.
+
+        Returns:
+            Dict in Anthropic's tool specification format.
+        """
+        return {
+            "name": self.name,
+            "description": self.description,
+            "input_schema": self.get_schema(),
+        }

thoughtflow/tools/registry.py

@@ -0,0 +1,122 @@
+"""
+Tool registry for ThoughtFlow.
+
+Provides an explicit registry for tools. This is optional - you can
+also pass tools directly to agents. The registry is useful for
+organizing and discovering available tools.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from thoughtflow.tools.base import Tool
+
+
+class ToolRegistry:
+    """Registry for managing available tools.
+
+    The registry provides a central place to register and lookup tools.
+    This is completely optional - ThoughtFlow doesn't require using a registry.
+
+    Example:
+        >>> registry = ToolRegistry()
+        >>> registry.register(calculator_tool)
+        >>> registry.register(web_search_tool)
+        >>>
+        >>> # Get a tool by name
+        >>> calc = registry.get("calculator")
+        >>>
+        >>> # Get all tools
+        >>> all_tools = registry.list()
+    """
+
+    def __init__(self) -> None:
+        """Initialize an empty registry."""
+        self._tools: dict[str, Tool] = {}
+
+    def register(self, tool: Tool) -> None:
+        """Register a tool.
+
+        Args:
+            tool: The tool to register.
+
+        Raises:
+            ValueError: If a tool with the same name already exists.
+        """
+        if tool.name in self._tools:
+            raise ValueError(
+                f"Tool '{tool.name}' is already registered. "
+                "Use replace=True to override."
+            )
+        self._tools[tool.name] = tool
+
+    def unregister(self, name: str) -> None:
+        """Unregister a tool by name.
+
+        Args:
+            name: Name of the tool to unregister.
+
+        Raises:
+            KeyError: If no tool with that name exists.
+        """
+        if name not in self._tools:
+            raise KeyError(f"Tool '{name}' not found in registry")
+        del self._tools[name]
+
+    def get(self, name: str) -> Tool:
+        """Get a tool by name.
+
+        Args:
+            name: Name of the tool.
+
+        Returns:
+            The registered Tool.
+
+        Raises:
+            KeyError: If no tool with that name exists.
+        """
+        if name not in self._tools:
+            raise KeyError(f"Tool '{name}' not found in registry")
+        return self._tools[name]
+
+    def list(self) -> list[Tool]:
+        """List all registered tools.
+
+        Returns:
+            List of all registered tools.
+        """
+        return list(self._tools.values())
+
+    def names(self) -> list[str]:
+        """List all registered tool names.
+
+        Returns:
+            List of tool names.
+        """
+        return list(self._tools.keys())
+
+    def to_openai_tools(self) -> list[dict]:
+        """Convert all tools to OpenAI format.
+
+        Returns:
+            List of tool dicts in OpenAI format.
+        """
+        return [tool.to_openai_tool() for tool in self._tools.values()]
+
+    def to_anthropic_tools(self) -> list[dict]:
+        """Convert all tools to Anthropic format.
+
+        Returns:
+            List of tool dicts in Anthropic format.
+        """
+        return [tool.to_anthropic_tool() for tool in self._tools.values()]
+
+    def __len__(self) -> int:
+        """Return number of registered tools."""
+        return len(self._tools)
+
+    def __contains__(self, name: str) -> bool:
+        """Check if a tool is registered."""
+        return name in self._tools

thoughtflow/trace/__init__.py

@@ -0,0 +1,34 @@
+"""
+Tracing and session management for ThoughtFlow.
+
+Traces capture complete run state: inputs, outputs, tool calls, model calls,
+timing, token usage, and costs. This enables debugging, evaluation,
+reproducibility, regression testing, and replay/diff across versions.
+
+Example:
+    >>> from thoughtflow.trace import Session
+    >>>
+    >>> session = Session()
+    >>> response = agent.call(messages, session=session)
+    >>>
+    >>> # Inspect the trace
+    >>> print(session.events)
+    >>> print(session.total_tokens)
+    >>> print(session.total_cost)
+    >>>
+    >>> # Save for replay
+    >>> session.save("trace.json")
+"""
+
+from __future__ import annotations
+
+from thoughtflow.trace.session import Session
+from thoughtflow.trace.events import Event, EventType
+from thoughtflow.trace.schema import TraceSchema
+
+__all__ = [
+    "Session",
+    "Event",
+    "EventType",
+    "TraceSchema",
+]

thoughtflow/trace/events.py

@@ -0,0 +1,183 @@
+"""
+Event types for ThoughtFlow tracing.
+
+Events represent discrete occurrences during an agent run:
+- Model calls (start, end, error)
+- Tool invocations
+- Memory operations
+- Custom user events
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import datetime
+from enum import Enum
+from typing import Any
+
+
+class EventType(str, Enum):
+    """Types of events that can occur during a session."""
+
+    # Agent lifecycle
+    CALL_START = "call_start"
+    CALL_END = "call_end"
+    CALL_ERROR = "call_error"
+
+    # Model interactions
+    MODEL_REQUEST = "model_request"
+    MODEL_RESPONSE = "model_response"
+    MODEL_ERROR = "model_error"
+
+    # Tool interactions
+    TOOL_CALL = "tool_call"
+    TOOL_RESULT = "tool_result"
+    TOOL_ERROR = "tool_error"
+
+    # Memory interactions
+    MEMORY_RETRIEVE = "memory_retrieve"
+    MEMORY_STORE = "memory_store"
+
+    # Custom
+    CUSTOM = "custom"
+
+
+@dataclass
+class Event:
+    """A single event in a session trace.
+
+    Events capture everything that happens during an agent run,
+    enabling complete visibility and replay capability.
+
+    Attributes:
+        event_type: The type of event.
+        timestamp: When the event occurred.
+        data: Event-specific data.
+        duration_ms: Duration in milliseconds (for end events).
+        metadata: Additional metadata.
+
+    Example:
+        >>> event = Event(
+        ...     event_type=EventType.MODEL_REQUEST,
+        ...     data={
+        ...         "messages": [...],
+        ...         "params": {"model": "gpt-4", "temperature": 0.7}
+        ...     }
+        ... )
+    """
+
+    event_type: EventType | str
+    timestamp: datetime = field(default_factory=datetime.now)
+    data: dict[str, Any] = field(default_factory=dict)
+    duration_ms: int | None = None
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+    def to_dict(self) -> dict[str, Any]:
+        """Convert to a serializable dict.
+
+        Returns:
+            Dict representation of the event.
+        """
+        return {
+            "event_type": (
+                self.event_type.value
+                if isinstance(self.event_type, EventType)
+                else self.event_type
+            ),
+            "timestamp": self.timestamp.isoformat(),
+            "data": self.data,
+            "duration_ms": self.duration_ms,
+            "metadata": self.metadata,
+        }
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> Event:
+        """Create an Event from a dict.
+
+        Args:
+            data: Dict with event data.
+
+        Returns:
+            Event instance.
+        """
+        event_type_str = data["event_type"]
+        try:
+            event_type = EventType(event_type_str)
+        except ValueError:
+            event_type = event_type_str
+
+        return cls(
+            event_type=event_type,
+            timestamp=datetime.fromisoformat(data["timestamp"]),
+            data=data.get("data", {}),
+            duration_ms=data.get("duration_ms"),
+            metadata=data.get("metadata", {}),
+        )
+
+
+# Convenience functions for creating common events
+
+
+def call_start(messages: list[dict], params: dict | None = None) -> Event:
+    """Create a CALL_START event.
+
+    Args:
+        messages: The input messages.
+        params: Call parameters.
+
+    Returns:
+        Event instance.
+    """
+    return Event(
+        event_type=EventType.CALL_START,
+        data={"messages": messages, "params": params or {}},
+    )
+
+
+def call_end(response: str, tokens: dict | None = None) -> Event:
+    """Create a CALL_END event.
+
+    Args:
+        response: The agent's response.
+        tokens: Token usage information.
+
+    Returns:
+        Event instance.
+    """
+    return Event(
+        event_type=EventType.CALL_END,
+        data={"response": response, "tokens": tokens or {}},
+    )
+
+
+def tool_call(tool_name: str, payload: dict) -> Event:
+    """Create a TOOL_CALL event.
+
+    Args:
+        tool_name: Name of the tool being called.
+        payload: The tool's input payload.
+
+    Returns:
+        Event instance.
+    """
+    return Event(
+        event_type=EventType.TOOL_CALL,
+        data={"tool_name": tool_name, "payload": payload},
+    )
+
+
+def tool_result(tool_name: str, result: Any, success: bool = True) -> Event:
+    """Create a TOOL_RESULT event.
+
+    Args:
+        tool_name: Name of the tool.
+        result: The tool's output.
+        success: Whether the tool call succeeded.
+
+    Returns:
+        Event instance.
+    """
+    return Event(
+        event_type=EventType.TOOL_RESULT,
+        data={"tool_name": tool_name, "result": result, "success": success},
+    )

thoughtflow/trace/schema.py

@@ -0,0 +1,111 @@
+"""
+Trace schema versioning for ThoughtFlow.
+
+Once trace schemas are in use, downstream systems depend on them.
+This module provides schema versioning to maintain backward compatibility.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+
+# Current schema version
+SCHEMA_VERSION = "1.0.0"
+
+
+@dataclass
+class TraceSchema:
+    """Schema metadata for trace files.
+
+    Enables forward/backward compatibility as the trace format evolves.
+
+    Attributes:
+        version: Schema version string.
+        thoughtflow_version: ThoughtFlow version that created the trace.
+        features: List of optional features used in this trace.
+    """
+
+    version: str = SCHEMA_VERSION
+    thoughtflow_version: str | None = None
+    features: list[str] | None = None
+
+    def to_dict(self) -> dict[str, Any]:
+        """Convert to a dict for embedding in trace files.
+
+        Returns:
+            Dict with schema information.
+        """
+        return {
+            "schema_version": self.version,
+            "thoughtflow_version": self.thoughtflow_version,
+            "features": self.features or [],
+        }
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> TraceSchema:
+        """Create from a dict.
+
+        Args:
+            data: Dict with schema information.
+
+        Returns:
+            TraceSchema instance.
+        """
+        return cls(
+            version=data.get("schema_version", "1.0.0"),
+            thoughtflow_version=data.get("thoughtflow_version"),
+            features=data.get("features"),
+        )
+
+    def is_compatible(self, other_version: str) -> bool:
+        """Check if this schema is compatible with another version.
+
+        Compatibility rules:
+        - Same major version = compatible
+        - Different major version = incompatible
+
+        Args:
+            other_version: Version string to check against.
+
+        Returns:
+            True if compatible, False otherwise.
+        """
+        this_major = self.version.split(".")[0]
+        other_major = other_version.split(".")[0]
+        return this_major == other_major
+
+
+def validate_trace(trace_data: dict[str, Any]) -> list[str]:
+    """Validate a trace against the current schema.
+
+    Args:
+        trace_data: The trace data to validate.
+
+    Returns:
+        List of validation errors (empty if valid).
+    """
+    errors: list[str] = []
+
+    # Check required fields
+    if "session_id" not in trace_data:
+        errors.append("Missing required field: session_id")
+
+    if "events" not in trace_data:
+        errors.append("Missing required field: events")
+    elif not isinstance(trace_data["events"], list):
+        errors.append("Field 'events' must be a list")
+
+    # Check schema version compatibility
+    schema_info = trace_data.get("schema", {})
+    if schema_info:
+        trace_version = schema_info.get("schema_version", "1.0.0")
+        current_schema = TraceSchema()
+        if not current_schema.is_compatible(trace_version):
+            errors.append(
+                f"Schema version mismatch: trace is v{trace_version}, "
+                f"current is v{SCHEMA_VERSION}"
+            )
+
+    return errors