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

thoughtflow/memory/base.py

@@ -0,0 +1,142 @@
+"""
+Base memory interface for ThoughtFlow.
+
+Memory hooks provide a clean pattern for memory integration:
+- Memory retrieval produces context items
+- Those items are explicitly inserted into the message list
+- Memory writes are explicit events emitted by the agent run
+
+This avoids:
+- Hidden memory mutation
+- "Where did this context come from?"
+- Irreproducible behavior across runs
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+from datetime import datetime
+from typing import Any
+
+
+@dataclass
+class MemoryEvent:
+    """An event representing a memory operation.
+
+    Captured in traces to maintain full visibility into memory interactions.
+
+    Attributes:
+        event_type: Type of event (retrieve, store, delete).
+        timestamp: When the event occurred.
+        query: The retrieval query (for retrieve events).
+        content: The content being stored (for store events).
+        results: Retrieved memories (for retrieve events).
+        metadata: Additional event metadata.
+    """
+
+    event_type: str  # "retrieve", "store", "delete"
+    timestamp: datetime = field(default_factory=datetime.now)
+    query: str | None = None
+    content: str | None = None
+    results: list[dict[str, Any]] = field(default_factory=list)
+    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,
+            "timestamp": self.timestamp.isoformat(),
+            "query": self.query,
+            "content": self.content,
+            "results": self.results,
+            "metadata": self.metadata,
+        }
+
+
+class MemoryHook(ABC):
+    """Abstract base class for memory integrations.
+
+    Memory hooks allow agents to:
+    - Retrieve relevant context from long-term memory
+    - Store new information for future retrieval
+    - Maintain conversation history beyond context window
+
+    Implementations might include:
+    - Vector database (Pinecone, Weaviate, ChromaDB)
+    - Key-value store
+    - SQL database
+    - File-based storage
+
+    Example:
+        >>> class SimpleMemory(MemoryHook):
+        ...     def __init__(self):
+        ...         self.memories = []
+        ...
+        ...     def retrieve(self, query, k=5):
+        ...         # Simple keyword matching (real impl would use embeddings)
+        ...         matches = [m for m in self.memories if query.lower() in m["content"].lower()]
+        ...         return matches[:k]
+        ...
+        ...     def store(self, content, metadata=None):
+        ...         self.memories.append({"content": content, "metadata": metadata or {}})
+    """
+
+    @abstractmethod
+    def retrieve(
+        self,
+        query: str,
+        k: int = 5,
+        filters: dict[str, Any] | None = None,
+    ) -> list[dict[str, Any]]:
+        """Retrieve relevant memories for a query.
+
+        Args:
+            query: The search query.
+            k: Maximum number of results to return.
+            filters: Optional filters to apply.
+
+        Returns:
+            List of memory dicts, each containing at least "content".
+        """
+        raise NotImplementedError
+
+    @abstractmethod
+    def store(
+        self,
+        content: str,
+        metadata: dict[str, Any] | None = None,
+    ) -> str:
+        """Store a new memory.
+
+        Args:
+            content: The content to store.
+            metadata: Optional metadata to associate with the memory.
+
+        Returns:
+            ID of the stored memory.
+        """
+        raise NotImplementedError
+
+    def delete(self, memory_id: str) -> bool:
+        """Delete a memory by ID.
+
+        Args:
+            memory_id: ID of the memory to delete.
+
+        Returns:
+            True if deleted, False if not found.
+        """
+        raise NotImplementedError("delete() not implemented for this memory hook")
+
+    def clear(self) -> int:
+        """Clear all memories.
+
+        Returns:
+            Number of memories deleted.
+        """
+        raise NotImplementedError("clear() not implemented for this memory hook")

thoughtflow/message.py

@@ -0,0 +1,140 @@
+"""
+Message schema for ThoughtFlow.
+
+Messages are the universal currency across providers. ThoughtFlow keeps
+messages provider-agnostic, minimal, and stable.
+
+Typical structure:
+    msg_list = [
+        {"role": "system", "content": "You are a helpful assistant."},
+        {"role": "user", "content": "Hello!"},
+    ]
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Literal, TypeAlias
+
+
+# Type aliases for clarity
+Role: TypeAlias = Literal["system", "user", "assistant", "tool"]
+MessageDict: TypeAlias = dict[str, Any]
+MessageList: TypeAlias = list[MessageDict]
+
+
+@dataclass
+class Message:
+    """A single message in a conversation.
+
+    This is an optional structured representation. You can also use
+    plain dicts - ThoughtFlow accepts both.
+
+    Attributes:
+        role: The role of the message sender (system, user, assistant, tool).
+        content: The text content of the message.
+        name: Optional name for the sender (useful for multi-agent scenarios).
+        tool_call_id: Optional ID linking to a tool call (for tool responses).
+        metadata: Optional metadata dict for extensions.
+
+    Example:
+        >>> msg = Message(role="user", content="Hello!")
+        >>> msg.to_dict()
+        {'role': 'user', 'content': 'Hello!'}
+    """
+
+    role: Role
+    content: str
+    name: str | None = None
+    tool_call_id: str | None = None
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+    def to_dict(self) -> MessageDict:
+        """Convert to a provider-compatible dict.
+
+        Returns:
+            Dict with role, content, and optional fields.
+        """
+        result: MessageDict = {
+            "role": self.role,
+            "content": self.content,
+        }
+        if self.name:
+            result["name"] = self.name
+        if self.tool_call_id:
+            result["tool_call_id"] = self.tool_call_id
+        return result
+
+    @classmethod
+    def from_dict(cls, data: MessageDict) -> Message:
+        """Create a Message from a dict.
+
+        Args:
+            data: Dict with at least 'role' and 'content' keys.
+
+        Returns:
+            A Message instance.
+        """
+        return cls(
+            role=data["role"],
+            content=data["content"],
+            name=data.get("name"),
+            tool_call_id=data.get("tool_call_id"),
+            metadata=data.get("metadata", {}),
+        )
+
+    @classmethod
+    def system(cls, content: str) -> Message:
+        """Create a system message.
+
+        Args:
+            content: The system prompt content.
+
+        Returns:
+            A Message with role='system'.
+        """
+        return cls(role="system", content=content)
+
+    @classmethod
+    def user(cls, content: str) -> Message:
+        """Create a user message.
+
+        Args:
+            content: The user's message content.
+
+        Returns:
+            A Message with role='user'.
+        """
+        return cls(role="user", content=content)
+
+    @classmethod
+    def assistant(cls, content: str) -> Message:
+        """Create an assistant message.
+
+        Args:
+            content: The assistant's response content.
+
+        Returns:
+            A Message with role='assistant'.
+        """
+        return cls(role="assistant", content=content)
+
+
+def normalize_messages(messages: list[Message | MessageDict]) -> MessageList:
+    """Normalize a list of messages to dicts.
+
+    Accepts both Message objects and dicts, returning a uniform list of dicts.
+
+    Args:
+        messages: List of Message objects or dicts.
+
+    Returns:
+        List of message dicts.
+    """
+    result: MessageList = []
+    for msg in messages:
+        if isinstance(msg, Message):
+            result.append(msg.to_dict())
+        else:
+            result.append(msg)
+    return result

thoughtflow/py.typed

@@ -0,0 +1,2 @@
+# PEP 561 marker file
+# This file indicates that the package supports type checking

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",
+]