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

thoughtflow/eval/replay.py

@@ -0,0 +1,137 @@
+"""
+Record/replay functionality for ThoughtFlow.
+
+Replay enables deterministic testing by recording agent runs and
+replaying them with mocked responses.
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from thoughtflow.agent import Agent
+    from thoughtflow.trace.session import Session
+
+
+@dataclass
+class ReplayResult:
+    """Result of a replay run.
+
+    Attributes:
+        success: Whether the replay succeeded.
+        original_response: The recorded response.
+        replayed_response: The response from the replay.
+        differences: List of differences found.
+        metadata: Additional result metadata.
+    """
+
+    success: bool
+    original_response: str | None = None
+    replayed_response: str | None = None
+    differences: list[str] = field(default_factory=list)
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+
+class Replay:
+    """Replay recorded sessions for testing.
+
+    Replay allows you to:
+    - Record agent runs to files
+    - Replay them with mocked model responses
+    - Compare outputs for regression testing
+    - Test without hitting live APIs
+
+    Example:
+        >>> # Save a session for replay
+        >>> session = Session()
+        >>> response = agent.call(messages, session=session)
+        >>> Replay.save(session, "test_case.json")
+        >>>
+        >>> # Later: replay the session
+        >>> replay = Replay.load("test_case.json")
+        >>> result = replay.run(agent)
+        >>>
+        >>> assert result.success
+        >>> assert result.replayed_response == result.original_response
+    """
+
+    def __init__(self, session_data: dict[str, Any]) -> None:
+        """Initialize a Replay from session data.
+
+        Args:
+            session_data: Recorded session data.
+        """
+        self.session_data = session_data
+        self._inputs = self._extract_inputs()
+        self._expected_outputs = self._extract_outputs()
+
+    def _extract_inputs(self) -> list[dict[str, Any]]:
+        """Extract input messages from session data.
+
+        Returns:
+            List of input message dicts.
+        """
+        inputs = []
+        for event in self.session_data.get("events", []):
+            if event.get("event_type") == "call_start":
+                inputs.append(event.get("data", {}).get("messages", []))
+        return inputs
+
+    def _extract_outputs(self) -> list[str]:
+        """Extract expected outputs from session data.
+
+        Returns:
+            List of expected response strings.
+        """
+        outputs = []
+        for event in self.session_data.get("events", []):
+            if event.get("event_type") == "call_end":
+                outputs.append(event.get("data", {}).get("response", ""))
+        return outputs
+
+    def run(self, agent: Agent) -> ReplayResult:
+        """Run the replay against an agent.
+
+        Args:
+            agent: The agent to test.
+
+        Returns:
+            ReplayResult with comparison data.
+
+        Raises:
+            NotImplementedError: This is a placeholder implementation.
+        """
+        # TODO: Implement replay with mocked adapter responses
+        raise NotImplementedError(
+            "Replay.run() is not yet implemented. "
+            "This is a placeholder for the ThoughtFlow alpha release."
+        )
+
+    @classmethod
+    def load(cls, path: str | Path) -> Replay:
+        """Load a replay from a JSON file.
+
+        Args:
+            path: Path to the replay file.
+
+        Returns:
+            Replay instance.
+        """
+        path = Path(path)
+        data = json.loads(path.read_text())
+        return cls(data)
+
+    @staticmethod
+    def save(session: Session, path: str | Path) -> None:
+        """Save a session for replay.
+
+        Args:
+            session: The session to save.
+            path: Path to save to.
+        """
+        path = Path(path)
+        path.write_text(json.dumps(session.to_dict(), indent=2))

thoughtflow/llm.py

@@ -0,0 +1,250 @@
+"""
+LLM class for ThoughtFlow.
+
+A unified interface for calling various language model services.
+"""
+
+from __future__ import annotations
+
+import json
+import urllib.request
+import urllib.error
+
+
+class LLM:
+    """
+    The LLM class is designed to interface with various language model services.
+    
+    Attributes:
+        service (str): The name of the service provider (e.g., 'openai', 'groq', 'anthropic').
+        model (str): The specific model to be used within the service.
+        api_key (str): The API key for authenticating requests.
+        api_secret (str): The API secret for additional authentication.
+        last_params (dict): Stores the parameters used in the last API call.
+
+    Methods:
+        __init__(model_id, key, secret):
+            Initializes the LLM instance with a model ID, API key, and secret.
+        
+        call(msg_list, params):
+            Calls the appropriate API based on the service with the given message list and parameters.
+        
+        _call_openai(msg_list, params):
+            Sends a request to the OpenAI API with the specified messages and parameters.
+        
+        _call_groq(msg_list, params):
+            Sends a request to the Groq API with the specified messages and parameters.
+        
+        _call_anthropic(msg_list, params):
+            Sends a request to the Anthropic API with the specified messages and parameters.
+        
+        _send_request(url, data, headers):
+            Helper function to send HTTP requests to the specified URL with data and headers.
+    """
+    def __init__(self, model_id='', key='API_KEY', secret='API_SECRET'):
+        # Parse model ID and initialize service and model name
+        if ':' not in model_id: model_id = 'openai:gpt-4-turbo'
+        
+        splitted = model_id.split(':') 
+        self.service = splitted[0]
+        self.model = ''.join(splitted[1:]) 
+        self.api_key = key
+        self.api_secret = secret
+        self.last_params = {} 
+        # Make the object directly callable
+        self.__call__ = self.call
+
+    def _normalize_messages(self, msg_list):
+        """
+        Accepts either:
+        - list[str] -> converts to [{'role':'user','content': str}, ...]
+        - list[dict] with 'role' and 'content' -> passes through unchanged
+        - list[dict] with only 'content' -> assumes role='user'
+        Returns: list[{'role': str, 'content': str or list[...]}]
+        """
+        norm = []
+        for m in msg_list:
+            if isinstance(m, dict):
+                role = m.get("role", "user")
+                content = m.get("content", "")
+                norm.append({"role": role, "content": content})
+            else:
+                # treat as plain user text
+                norm.append({"role": "user", "content": str(m)})
+        return norm
+
+    def call(self, msg_list, params={}):
+        self.last_params = dict(params)
+        # General function to call the appropriate API with msg_list and optional parameters
+        if self.service == 'openai':
+            return self._call_openai(msg_list, params)
+        elif self.service == 'groq':
+            return self._call_groq(msg_list, params)
+        elif self.service == 'anthropic':
+            return self._call_anthropic(msg_list, params)
+        elif self.service == 'ollama':
+            return self._call_ollama(msg_list, params)
+        elif self.service == 'gemini':
+            return self._call_gemini(msg_list, params)
+        elif self.service == 'openrouter':
+            return self._call_openrouter(msg_list, params)
+        else:
+            raise ValueError("Unsupported service '{}'.".format(self.service))
+
+    def _call_openai(self, msg_list, params):
+        url = "https://api.openai.com/v1/chat/completions"
+        data = json.dumps({
+            "model": self.model,
+            "messages": self._normalize_messages(msg_list),
+            **params
+        }).encode("utf-8")
+        headers = {
+            "Authorization": "Bearer " + self.api_key,
+            "Content-Type": "application/json",
+        }
+        res = self._send_request(url, data, headers)
+        choices = [a["message"]["content"] for a in res.get("choices", [])]
+        return choices
+
+    def _call_groq(self, msg_list, params):
+        url = "https://api.groq.com/openai/v1/chat/completions"
+        data = json.dumps({
+            "model": self.model,
+            "messages": self._normalize_messages(msg_list),
+            **params
+        }).encode("utf-8")
+        headers = {
+            "Authorization": "Bearer " + self.api_key,
+            "Content-Type": "application/json",
+            "User-Agent": "Groq/Python 0.9.0",
+        }
+        res = self._send_request(url, data, headers)
+        choices = [a["message"]["content"] for a in res.get("choices", [])]
+        return choices
+
+    def _call_anthropic(self, msg_list, params):
+        url = "https://api.anthropic.com/v1/messages"
+        data = json.dumps({
+            "model": self.model,
+            "max_tokens": params.get("max_tokens", 1024),
+            "messages": self._normalize_messages(msg_list),
+        }).encode("utf-8")
+        headers = {
+            "x-api-key": self.api_key,
+            "anthropic-version": "2023-06-01",
+            "Content-Type": "application/json",
+        }
+        res = self._send_request(url, data, headers)
+        # Anthropic returns {"content":[{"type":"text","text":"..."}], ...}
+        choices = [c.get("text", "") for c in res.get("content", [])]
+        return choices
+
+    def _call_gemini(self, msg_list, params):
+        """
+        Calls Google Gemini/SVertexAI chat-supported models via REST API.
+        Requires self.api_key to be set.
+        """
+        url = "https://generativelanguage.googleapis.com/v1beta/models/{}:generateContent?key={}".format(self.model, self.api_key)
+        # Gemini expects a list of "contents" alternating user/assistant
+        # We collapse the messages into a sequence of dicts as required by Gemini
+        # Gemini wants [{"role": "user/assistant", "parts": [{"text": ...}]}]
+        gemini_msgs = []
+        for m in self._normalize_messages(msg_list):
+            # Google's role scheme: "user" or "model"
+            g_role = {"user": "user", "assistant": "model", "system": "user"}.get(m["role"], "user")
+            gemini_msgs.append({
+                "role": g_role,
+                "parts": [{"text": str(m["content"])}] if isinstance(m["content"], str) else m["content"]
+            })
+        payload = {
+            "contents": gemini_msgs,
+            **{k: v for k, v in params.items() if k != "model"}
+        }
+        data = json.dumps(payload).encode("utf-8")
+        headers = {
+            "Content-Type": "application/json",
+        }
+        res = self._send_request(url, data, headers)
+        # Gemini returns { "candidates": [ { "content": { "parts": [ { "text": ... } ] } } ] }
+        choices = []
+        for cand in res.get("candidates", []):
+            parts = cand.get("content", {}).get("parts", [])
+            text = "".join([p.get("text", "") for p in parts])
+            choices.append(text)
+        return choices
+
+    def _call_openrouter(self, msg_list, params):
+        """
+        Calls an LLM via the OpenRouter API. Requires self.api_key.
+        API docs: https://openrouter.ai/docs
+        Model list: https://openrouter.ai/docs#models
+        """
+        url = "https://openrouter.ai/api/v1/chat/completions"
+        data = json.dumps({
+            "model": self.model,
+            "messages": self._normalize_messages(msg_list),
+            **params
+        }).encode("utf-8")
+        headers = {
+            "Authorization": "Bearer " + self.api_key,
+            "Content-Type": "application/json",
+            "HTTP-Referer": params.get("referer", "https://your-app.com"),
+            "X-Title": params.get("title", "Thoughtflow"),
+        }
+        res = self._send_request(url, data, headers)
+        choices = [a["message"]["content"] for a in res.get("choices", [])]
+        return choices
+
+    def _call_ollama(self, msg_list, params):
+        """
+        Calls a local model served via Ollama (http://localhost:11434 by default).
+        Expects no authentication. Ollama messages format is like OpenAI's.
+        """
+        base_url = params.get("ollama_url", "http://localhost:11434")
+        url = base_url.rstrip('/') + "/api/chat"
+        payload = {
+            "model": self.model,
+            "messages": self._normalize_messages(msg_list),
+            "stream": False,  # Disable streaming to get a single JSON response
+            **{k: v for k, v in params.items() if k not in ("ollama_url", "model")}
+        }
+        data = json.dumps(payload).encode("utf-8")
+        headers = {
+            "Content-Type": "application/json",
+        }
+        res = self._send_request(url, data, headers)
+        # Ollama returns {"message": {...}, ...} or {"choices": [{...}]}
+        # Prefer OpenAI-style extraction if available, else fallback
+        if "choices" in res:
+            choices = [a["message"]["content"] for a in res.get("choices", [])]
+        elif "message" in res:
+            # single result
+            msg = res["message"]
+            choices = [msg.get("content", "")]
+        elif "response" in res:
+            # streaming/fallback
+            choices = [res["response"]]
+        else:
+            choices = []
+        return choices
+
+    def _send_request(self, url, data, headers):
+        # Sends the actual HTTP request and handles the response
+        try:
+            req = urllib.request.Request(url, data=data, headers=headers)
+            with urllib.request.urlopen(req) as response:
+                response_data = response.read().decode("utf-8")  
+                # Attempt to parse JSON response; handle plain-text responses
+                try:
+                    return json.loads(response_data)  # Parse JSON response
+                except json.JSONDecodeError:
+                    # If response is not JSON, return it as-is in a structured format
+                    return {"error": "Non-JSON response", "response_data": response_data}
+                
+        except urllib.error.HTTPError as e:
+            # Return the error details in case of an HTTP error
+            error_msg = e.read().decode("utf-8")
+            print("HTTP Error:", error_msg)  # Log HTTP error for debugging
+            return {"error": json.loads(error_msg) if error_msg else "Unknown HTTP error"}
+        except Exception as e:
+            return {"error": str(e)}  

thoughtflow/memory/__init__.py

@@ -0,0 +1,32 @@
+"""
+Memory module for ThoughtFlow.
+
+The MEMORY class is the event-sourced state container for managing events,
+logs, messages, reflections, and variables in ThoughtFlow workflows.
+
+Example:
+    >>> from thoughtflow.memory import MEMORY
+    >>>
+    >>> memory = MEMORY()
+    >>> memory.add_msg('user', 'Hello!', channel='webapp')
+    >>> memory.add_msg('assistant', 'Hi there!', channel='webapp')
+    >>> memory.set_var('session_id', 'abc123', desc='Current session')
+    >>>
+    >>> # Get messages
+    >>> memory.get_msgs(include=['user'])
+    >>>
+    >>> # Prepare context for LLM
+    >>> context = memory.prepare_context(format='openai')
+    >>>
+    >>> # Save/load state
+    >>> memory.save('memory.pkl')
+    >>> memory.to_json('memory.json')
+"""
+
+from __future__ import annotations
+
+from thoughtflow.memory.base import MEMORY
+
+__all__ = [
+    "MEMORY",
+]