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

thoughtflow/__init__.py

@@ -1,7 +1,56 @@
+"""
+ThoughtFlow: A minimal, explicit, Pythonic substrate for LLM and agent systems.
 
-import numpy
-import numpy as np 
-import pandas as pd 
+Core Philosophy:
+    - Tiny surface area: Few powerful primitives over many specialized classes
+    - Explicit state: All state is visible, serializable, and replayable
+    - Portability: Works across OpenAI, Anthropic, local models, serverless
+    - Deterministic testing: Record/replay workflows, stable sessions
 
-from .jtools1 import Sorter  # Assuming you have a class named Sorter in jtools1.py
-from .jtools2 import Adder   # Assuming you have a class named Adder in jtools2.py
+Basic Usage:
+    >>> from thoughtflow import Agent
+    >>> from thoughtflow.adapters import OpenAIAdapter
+    >>>
+    >>> adapter = OpenAIAdapter(api_key="...")
+    >>> agent = Agent(adapter)
+    >>> response = agent.call([
+    ...     {"role": "user", "content": "Hello!"}
+    ... ])
+"""
+
+from __future__ import annotations
+
+# Core exports
+from thoughtflow.agent import Agent
+from thoughtflow.message import Message, MessageList
+
+# Submodule access
+from thoughtflow import adapters
+from thoughtflow import tools
+from thoughtflow import memory
+from thoughtflow import trace
+from thoughtflow import eval
+
+# Version
+try:
+    from importlib.metadata import version as _get_version
+
+    __version__ = _get_version("thoughtflow")
+except Exception:
+    __version__ = "0.0.0"
+
+# Public API
+__all__ = [
+    # Core
+    "Agent",
+    "Message",
+    "MessageList",
+    # Submodules
+    "adapters",
+    "tools",
+    "memory",
+    "trace",
+    "eval",
+    # Metadata
+    "__version__",
+]

thoughtflow/_util.py

@@ -0,0 +1,108 @@
+"""
+Internal utilities for ThoughtFlow.
+
+This module contains helper functions used internally by ThoughtFlow.
+These are NOT part of the public API and may change without notice.
+
+Note: The underscore prefix indicates this is internal/private.
+"""
+
+from __future__ import annotations
+
+import time
+from typing import Any, Callable, TypeVar
+
+T = TypeVar("T")
+
+
+def get_timestamp() -> float:
+    """Get current timestamp in seconds since epoch.
+
+    Returns:
+        Current time as a float.
+    """
+    return time.time()
+
+
+def get_timestamp_ms() -> int:
+    """Get current timestamp in milliseconds since epoch.
+
+    Returns:
+        Current time in milliseconds as an integer.
+    """
+    return int(time.time() * 1000)
+
+
+def deep_merge(base: dict[str, Any], override: dict[str, Any]) -> dict[str, Any]:
+    """Deep merge two dictionaries.
+
+    Values from `override` take precedence. Nested dicts are merged recursively.
+
+    Args:
+        base: The base dictionary.
+        override: The dictionary to merge on top.
+
+    Returns:
+        A new merged dictionary.
+    """
+    result = base.copy()
+    for key, value in override.items():
+        if key in result and isinstance(result[key], dict) and isinstance(value, dict):
+            result[key] = deep_merge(result[key], value)
+        else:
+            result[key] = value
+    return result
+
+
+def truncate_string(s: str, max_length: int = 100, suffix: str = "...") -> str:
+    """Truncate a string to a maximum length.
+
+    Args:
+        s: The string to truncate.
+        max_length: Maximum length (including suffix).
+        suffix: Suffix to add if truncated.
+
+    Returns:
+        The truncated string.
+    """
+    if len(s) <= max_length:
+        return s
+    return s[: max_length - len(suffix)] + suffix
+
+
+def retry_with_backoff(
+    func: Callable[[], T],
+    max_retries: int = 3,
+    base_delay: float = 1.0,
+    max_delay: float = 60.0,
+) -> T:
+    """Retry a function with exponential backoff.
+
+    Note: This is an EXPLICIT retry mechanism - callers must opt-in.
+    ThoughtFlow does not retry implicitly.
+
+    Args:
+        func: The function to retry.
+        max_retries: Maximum number of retry attempts.
+        base_delay: Initial delay in seconds.
+        max_delay: Maximum delay between retries.
+
+    Returns:
+        The function's return value.
+
+    Raises:
+        Exception: The last exception if all retries fail.
+    """
+    last_exception: Exception | None = None
+    delay = base_delay
+
+    for attempt in range(max_retries + 1):
+        try:
+            return func()
+        except Exception as e:
+            last_exception = e
+            if attempt < max_retries:
+                time.sleep(min(delay, max_delay))
+                delay *= 2  # Exponential backoff
+
+    raise last_exception  # type: ignore[misc]

thoughtflow/adapters/__init__.py

@@ -0,0 +1,43 @@
+"""
+Provider adapters for ThoughtFlow.
+
+Adapters translate between ThoughtFlow's stable message schema and
+provider-specific APIs (OpenAI, Anthropic, local models, etc.).
+
+Example:
+    >>> from thoughtflow.adapters import OpenAIAdapter
+    >>> adapter = OpenAIAdapter(api_key="...")
+    >>> response = adapter.complete(messages, params)
+"""
+
+from __future__ import annotations
+
+from thoughtflow.adapters.base import Adapter, AdapterConfig
+
+# Lazy imports to avoid requiring all provider dependencies
+# Users only need to install the providers they use
+
+__all__ = [
+    "Adapter",
+    "AdapterConfig",
+    "OpenAIAdapter",
+    "AnthropicAdapter",
+    "LocalAdapter",
+]
+
+
+def __getattr__(name: str):
+    """Lazy load adapters to avoid import errors for missing dependencies."""
+    if name == "OpenAIAdapter":
+        from thoughtflow.adapters.openai import OpenAIAdapter
+
+        return OpenAIAdapter
+    elif name == "AnthropicAdapter":
+        from thoughtflow.adapters.anthropic import AnthropicAdapter
+
+        return AnthropicAdapter
+    elif name == "LocalAdapter":
+        from thoughtflow.adapters.local import LocalAdapter
+
+        return LocalAdapter
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

thoughtflow/adapters/anthropic.py

@@ -0,0 +1,119 @@
+"""
+Anthropic adapter for ThoughtFlow.
+
+Provides integration with Anthropic's API (Claude models).
+
+Requires: pip install thoughtflow[anthropic]
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from thoughtflow.adapters.base import Adapter, AdapterConfig, AdapterResponse
+
+if TYPE_CHECKING:
+    from thoughtflow.message import MessageList
+
+
+class AnthropicAdapter(Adapter):
+    """Adapter for Anthropic's API.
+
+    Supports Claude 3, Claude 2, and other Anthropic models.
+
+    Example:
+        >>> adapter = AnthropicAdapter(api_key="sk-ant-...")
+        >>> response = adapter.complete([
+        ...     {"role": "user", "content": "Hello!"}
+        ... ])
+        >>> print(response.content)
+
+    Attributes:
+        config: Adapter configuration.
+        client: Anthropic client instance (created lazily).
+    """
+
+    DEFAULT_MODEL = "claude-sonnet-4-20250514"
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        config: AdapterConfig | None = None,
+        **kwargs: Any,
+    ) -> None:
+        """Initialize the Anthropic adapter.
+
+        Args:
+            api_key: Anthropic API key. Can also be set via ANTHROPIC_API_KEY env var.
+            config: Full adapter configuration.
+            **kwargs: Additional config options.
+        """
+        if config is None:
+            config = AdapterConfig(api_key=api_key, **kwargs)
+        super().__init__(config)
+        self._client = None
+
+    @property
+    def client(self) -> Any:
+        """Lazy-load the Anthropic client.
+
+        Returns:
+            Anthropic client instance.
+
+        Raises:
+            ImportError: If anthropic package is not installed.
+        """
+        if self._client is None:
+            try:
+                from anthropic import Anthropic
+            except ImportError as e:
+                raise ImportError(
+                    "Anthropic package not installed. "
+                    "Install with: pip install thoughtflow[anthropic]"
+                ) from e
+
+            self._client = Anthropic(
+                api_key=self.config.api_key,
+                base_url=self.config.base_url,
+                timeout=self.config.timeout,
+                max_retries=self.config.max_retries,
+            )
+        return self._client
+
+    def complete(
+        self,
+        messages: MessageList,
+        params: dict[str, Any] | None = None,
+    ) -> AdapterResponse:
+        """Generate a completion using Anthropic's API.
+
+        Args:
+            messages: List of message dicts.
+            params: Optional parameters (model, temperature, max_tokens, etc.)
+
+        Returns:
+            AdapterResponse with the generated content.
+
+        Raises:
+            NotImplementedError: This is a placeholder implementation.
+        """
+        # TODO: Implement actual Anthropic API call
+        # Note: Anthropic uses a different message format (system as separate param)
+        raise NotImplementedError(
+            "AnthropicAdapter.complete() is not yet implemented. "
+            "This is a placeholder for the ThoughtFlow alpha release."
+        )
+
+    def get_capabilities(self) -> dict[str, Any]:
+        """Get Anthropic adapter capabilities.
+
+        Returns:
+            Dict of supported features.
+        """
+        return {
+            "streaming": True,
+            "tool_calling": True,
+            "vision": True,
+            "json_mode": False,  # Anthropic doesn't have native JSON mode
+            "seed": False,
+        }

thoughtflow/adapters/base.py

@@ -0,0 +1,140 @@
+"""
+Base adapter interface for ThoughtFlow.
+
+All provider adapters implement this interface, ensuring a stable
+contract across different LLM providers.
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from thoughtflow.message import MessageList
+
+
+@dataclass
+class AdapterConfig:
+    """Configuration for an adapter.
+
+    Attributes:
+        api_key: API key for the provider (if required).
+        base_url: Optional custom base URL for the API.
+        timeout: Request timeout in seconds.
+        max_retries: Maximum number of retries for failed requests.
+        default_model: Default model to use if not specified in params.
+        extra: Additional provider-specific configuration.
+    """
+
+    api_key: str | None = None
+    base_url: str | None = None
+    timeout: float = 60.0
+    max_retries: int = 3
+    default_model: str | None = None
+    extra: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class AdapterResponse:
+    """Response from an adapter completion call.
+
+    Attributes:
+        content: The generated text content.
+        model: The model that generated the response.
+        usage: Token usage information (prompt, completion, total).
+        finish_reason: Why the model stopped (stop, length, tool_calls, etc.).
+        raw: The raw response from the provider (for debugging).
+    """
+
+    content: str
+    model: str | None = None
+    usage: dict[str, int] | None = None
+    finish_reason: str | None = None
+    raw: Any = None
+
+
+class Adapter(ABC):
+    """Abstract base class for provider adapters.
+
+    Adapters are responsible for:
+    - Translating ThoughtFlow's message format to provider-specific format
+    - Making API calls to the provider
+    - Translating responses back to ThoughtFlow's format
+    - Handling provider-specific errors and retries
+
+    Subclasses must implement:
+    - `complete()`: Synchronous completion
+    - `complete_async()`: Asynchronous completion (optional)
+    - `get_capabilities()`: Report adapter capabilities
+    """
+
+    def __init__(self, config: AdapterConfig | None = None, **kwargs: Any) -> None:
+        """Initialize the adapter.
+
+        Args:
+            config: Adapter configuration object.
+            **kwargs: Shorthand for config fields (api_key, base_url, etc.)
+        """
+        if config is None:
+            config = AdapterConfig(**kwargs)
+        self.config = config
+
+    @abstractmethod
+    def complete(
+        self,
+        messages: MessageList,
+        params: dict[str, Any] | None = None,
+    ) -> AdapterResponse:
+        """Generate a completion for the given messages.
+
+        Args:
+            messages: List of message dicts.
+            params: Optional parameters (model, temperature, max_tokens, etc.)
+
+        Returns:
+            AdapterResponse with the generated content.
+
+        Raises:
+            NotImplementedError: Subclasses must implement this method.
+        """
+        raise NotImplementedError
+
+    async def complete_async(
+        self,
+        messages: MessageList,
+        params: dict[str, Any] | None = None,
+    ) -> AdapterResponse:
+        """Async version of complete().
+
+        Default implementation calls the sync version.
+        Override for true async support.
+
+        Args:
+            messages: List of message dicts.
+            params: Optional parameters.
+
+        Returns:
+            AdapterResponse with the generated content.
+        """
+        # Default: fall back to sync
+        return self.complete(messages, params)
+
+    def get_capabilities(self) -> dict[str, Any]:
+        """Get the capabilities of this adapter.
+
+        Returns:
+            Dict describing what this adapter supports:
+            - streaming: bool
+            - tool_calling: bool
+            - vision: bool
+            - json_mode: bool
+            - etc.
+        """
+        return {
+            "streaming": False,
+            "tool_calling": False,
+            "vision": False,
+            "json_mode": False,
+        }

thoughtflow/adapters/local.py

@@ -0,0 +1,133 @@
+"""
+Local model adapter for ThoughtFlow.
+
+Provides integration with locally-running models via Ollama, LM Studio,
+or other local inference servers.
+
+Requires: pip install thoughtflow[local]
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from thoughtflow.adapters.base import Adapter, AdapterConfig, AdapterResponse
+
+if TYPE_CHECKING:
+    from thoughtflow.message import MessageList
+
+
+class LocalAdapter(Adapter):
+    """Adapter for locally-running models.
+
+    Supports Ollama, LM Studio, and other OpenAI-compatible local servers.
+
+    Example:
+        >>> # Using Ollama
+        >>> adapter = LocalAdapter(base_url="http://localhost:11434/v1")
+        >>> response = adapter.complete([
+        ...     {"role": "user", "content": "Hello!"}
+        ... ], params={"model": "llama3"})
+
+        >>> # Using LM Studio
+        >>> adapter = LocalAdapter(base_url="http://localhost:1234/v1")
+
+    Attributes:
+        config: Adapter configuration.
+        client: HTTP client for making requests.
+    """
+
+    DEFAULT_BASE_URL = "http://localhost:11434/v1"
+    DEFAULT_MODEL = "llama3"
+
+    def __init__(
+        self,
+        base_url: str | None = None,
+        config: AdapterConfig | None = None,
+        **kwargs: Any,
+    ) -> None:
+        """Initialize the local adapter.
+
+        Args:
+            base_url: URL of the local inference server.
+            config: Full adapter configuration.
+            **kwargs: Additional config options.
+        """
+        if config is None:
+            config = AdapterConfig(
+                base_url=base_url or self.DEFAULT_BASE_URL,
+                **kwargs,
+            )
+        super().__init__(config)
+        self._client = None
+
+    @property
+    def client(self) -> Any:
+        """Lazy-load the HTTP client.
+
+        Returns:
+            Ollama client or httpx client instance.
+
+        Raises:
+            ImportError: If required packages are not installed.
+        """
+        if self._client is None:
+            # Try Ollama first, fall back to generic OpenAI-compatible client
+            try:
+                from ollama import Client
+
+                self._client = Client(host=self.config.base_url)
+            except ImportError:
+                # Fall back to using OpenAI client with custom base_url
+                try:
+                    from openai import OpenAI
+
+                    self._client = OpenAI(
+                        base_url=self.config.base_url,
+                        api_key="not-needed",  # Local servers often don't need keys
+                    )
+                except ImportError as e:
+                    raise ImportError(
+                        "No local model client available. "
+                        "Install with: pip install thoughtflow[local] or thoughtflow[openai]"
+                    ) from e
+        return self._client
+
+    def complete(
+        self,
+        messages: MessageList,
+        params: dict[str, Any] | None = None,
+    ) -> AdapterResponse:
+        """Generate a completion using a local model.
+
+        Args:
+            messages: List of message dicts.
+            params: Optional parameters (model, temperature, etc.)
+
+        Returns:
+            AdapterResponse with the generated content.
+
+        Raises:
+            NotImplementedError: This is a placeholder implementation.
+        """
+        # TODO: Implement actual local model call
+        raise NotImplementedError(
+            "LocalAdapter.complete() is not yet implemented. "
+            "This is a placeholder for the ThoughtFlow alpha release."
+        )
+
+    def get_capabilities(self) -> dict[str, Any]:
+        """Get local adapter capabilities.
+
+        Note: Capabilities depend on the specific model being used.
+
+        Returns:
+            Dict of supported features.
+        """
+        return {
+            "streaming": True,
+            "tool_calling": False,  # Depends on model
+            "vision": False,  # Depends on model
+            "json_mode": False,
+            "seed": True,
+        }