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

thoughtflow/trace/session.py

@@ -0,0 +1,141 @@
+"""
+Session object for ThoughtFlow.
+
+A Session captures the complete state of an agent run, enabling
+debugging, evaluation, reproducibility, and replay.
+"""
+
+from __future__ import annotations
+
+import json
+import uuid
+from dataclasses import dataclass, field
+from datetime import datetime
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from thoughtflow.trace.events import Event
+
+
+@dataclass
+class Session:
+    """A session capturing the complete trace of an agent run.
+
+    Sessions are the foundation for:
+    - Debugging: See exactly what happened
+    - Evaluation: Measure quality and performance
+    - Reproducibility: Replay runs with same inputs
+    - Regression testing: Diff across versions/models
+
+    Attributes:
+        session_id: Unique identifier for this session.
+        created_at: When the session was created.
+        events: List of events that occurred during the run.
+        metadata: Additional session metadata.
+
+    Example:
+        >>> session = Session()
+        >>> session.add_event(Event(type="call_start", data={...}))
+        >>> session.add_event(Event(type="call_end", data={...}))
+        >>>
+        >>> # Get summary
+        >>> print(session.summary())
+        >>>
+        >>> # Save for later
+        >>> session.save("trace.json")
+        >>>
+        >>> # Load and replay
+        >>> loaded = Session.load("trace.json")
+    """
+
+    session_id: str = field(default_factory=lambda: str(uuid.uuid4()))
+    created_at: datetime = field(default_factory=datetime.now)
+    events: list[Event] = field(default_factory=list)
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+    # Aggregated metrics (updated as events are added)
+    _total_tokens: int = field(default=0, repr=False)
+    _total_cost: float = field(default=0.0, repr=False)
+    _total_duration_ms: int = field(default=0, repr=False)
+
+    def add_event(self, event: Event) -> None:
+        """Add an event to the session.
+
+        Args:
+            event: The event to add.
+        """
+        self.events.append(event)
+        # TODO: Update aggregated metrics based on event type
+
+    @property
+    def total_tokens(self) -> int:
+        """Total tokens used across all model calls."""
+        return self._total_tokens
+
+    @property
+    def total_cost(self) -> float:
+        """Total cost in USD across all model calls."""
+        return self._total_cost
+
+    @property
+    def duration_ms(self) -> int:
+        """Total duration in milliseconds."""
+        return self._total_duration_ms
+
+    def summary(self) -> dict[str, Any]:
+        """Get a summary of the session.
+
+        Returns:
+            Dict with key metrics and counts.
+        """
+        return {
+            "session_id": self.session_id,
+            "created_at": self.created_at.isoformat(),
+            "event_count": len(self.events),
+            "total_tokens": self.total_tokens,
+            "total_cost": self.total_cost,
+            "duration_ms": self.duration_ms,
+        }
+
+    def to_dict(self) -> dict[str, Any]:
+        """Convert to a serializable dict.
+
+        Returns:
+            Complete session data as a dict.
+        """
+        return {
+            "session_id": self.session_id,
+            "created_at": self.created_at.isoformat(),
+            "events": [e.to_dict() for e in self.events],
+            "metadata": self.metadata,
+            "summary": self.summary(),
+        }
+
+    def save(self, path: str | Path) -> None:
+        """Save the session to a JSON file.
+
+        Args:
+            path: Path to save to.
+        """
+        path = Path(path)
+        path.write_text(json.dumps(self.to_dict(), indent=2))
+
+    @classmethod
+    def load(cls, path: str | Path) -> Session:
+        """Load a session from a JSON file.
+
+        Args:
+            path: Path to load from.
+
+        Returns:
+            Loaded Session instance.
+
+        Raises:
+            NotImplementedError: This is a placeholder implementation.
+        """
+        # TODO: Implement session loading with event deserialization
+        raise NotImplementedError(
+            "Session.load() is not yet implemented. "
+            "This is a placeholder for the ThoughtFlow alpha release."
+        )

thoughtflow-0.0.3.dist-info/METADATA

@@ -0,0 +1,215 @@
+Metadata-Version: 2.4
+Name: thoughtflow
+Version: 0.0.3
+Summary: A minimal, explicit, Pythonic substrate for building reproducible, portable, testable LLM and agent systems.
+Project-URL: Homepage, https://github.com/jrolf/thoughtflow
+Project-URL: Documentation, https://thoughtflow.dev
+Project-URL: Repository, https://github.com/jrolf/thoughtflow
+Project-URL: Issues, https://github.com/jrolf/thoughtflow/issues
+Project-URL: Changelog, https://github.com/jrolf/thoughtflow/blob/main/CHANGELOG.md
+Author-email: "James A. Rolfsen" <james@think.dev>
+Maintainer-email: "James A. Rolfsen" <james@think.dev>
+License: MIT License
+        
+        Copyright (c) 2025 James A. Rolfsen
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Keywords: agents,ai,anthropic,langchain-alternative,llm,machine-learning,openai,orchestration
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Provides-Extra: all
+Requires-Dist: anthropic>=0.18; extra == 'all'
+Requires-Dist: mkdocs-material>=9.0; extra == 'all'
+Requires-Dist: mkdocs>=1.5; extra == 'all'
+Requires-Dist: mkdocstrings[python]>=0.24; extra == 'all'
+Requires-Dist: mypy>=1.0; extra == 'all'
+Requires-Dist: ollama>=0.1; extra == 'all'
+Requires-Dist: openai>=1.0; extra == 'all'
+Requires-Dist: pre-commit>=3.0; extra == 'all'
+Requires-Dist: pytest-asyncio>=0.21; extra == 'all'
+Requires-Dist: pytest-cov>=4.0; extra == 'all'
+Requires-Dist: pytest>=7.0; extra == 'all'
+Requires-Dist: ruff>=0.1; extra == 'all'
+Provides-Extra: all-providers
+Requires-Dist: anthropic>=0.18; extra == 'all-providers'
+Requires-Dist: ollama>=0.1; extra == 'all-providers'
+Requires-Dist: openai>=1.0; extra == 'all-providers'
+Provides-Extra: anthropic
+Requires-Dist: anthropic>=0.18; extra == 'anthropic'
+Provides-Extra: dev
+Requires-Dist: mypy>=1.0; extra == 'dev'
+Requires-Dist: pre-commit>=3.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.21; extra == 'dev'
+Requires-Dist: pytest-cov>=4.0; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: ruff>=0.1; extra == 'dev'
+Provides-Extra: docs
+Requires-Dist: mkdocs-material>=9.0; extra == 'docs'
+Requires-Dist: mkdocs>=1.5; extra == 'docs'
+Requires-Dist: mkdocstrings[python]>=0.24; extra == 'docs'
+Provides-Extra: local
+Requires-Dist: ollama>=0.1; extra == 'local'
+Provides-Extra: openai
+Requires-Dist: openai>=1.0; extra == 'openai'
+Description-Content-Type: text/markdown
+
+# ThoughtFlow
+
+[![PyPI version](https://badge.fury.io/py/thoughtflow.svg)](https://badge.fury.io/py/thoughtflow)
+[![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![CI](https://github.com/jrolf/thoughtflow/actions/workflows/ci.yml/badge.svg)](https://github.com/jrolf/thoughtflow/actions/workflows/ci.yml)
+
+**A minimal, explicit, Pythonic substrate for building reproducible, portable, testable LLM and agent systems.**
+
+> *Tiny surface area. Explicit state. Portable execution. Deterministic testing.*
+
+---
+
+## Why ThoughtFlow?
+
+The modern LLM/agent ecosystem often evolves into abstraction swamps—hidden state, magical callbacks, and frameworks that are hard to understand, test, and deploy.
+
+**ThoughtFlow takes a different path:**
+
+- ✅ **No hidden agent runtime** you can't reason about
+- ✅ **No graph DSL** you must adopt to do anything serious
+- ✅ **No implicit global memory** or callback chains
+- ✅ **No abstraction layers** whose main job is wrapping other abstractions
+
+Instead, ThoughtFlow makes orchestration logic **plain Python**: explicit inputs, explicit outputs, explicit state transitions, replayable sessions, deterministic evaluation paths.
+
+---
+
+## Installation
+
+```bash
+# Core library (zero dependencies)
+pip install thoughtflow
+
+# With OpenAI support
+pip install thoughtflow[openai]
+
+# With Anthropic support
+pip install thoughtflow[anthropic]
+
+# With all providers
+pip install thoughtflow[all-providers]
+```
+
+---
+
+## Quick Start
+
+```python
+from thoughtflow import Agent
+from thoughtflow.adapters import OpenAIAdapter
+
+# Create an adapter for your provider
+adapter = OpenAIAdapter(api_key="your-api-key")
+
+# Create an agent
+agent = Agent(adapter)
+
+# Call with a message list (the universal currency)
+response = agent.call([
+    {"role": "system", "content": "You are a helpful assistant."},
+    {"role": "user", "content": "What is ThoughtFlow?"}
+])
+
+print(response)
+```
+
+---
+
+## Core Concepts
+
+### The Agent Contract
+
+An Agent is something that can be called with messages and parameters:
+
+```python
+class Agent:
+    def call(self, msg_list, params=None):
+        raise NotImplementedError
+```
+
+That's it. Everything else is composition.
+
+### Messages: Stable Schema, Minimal Assumptions
+
+```python
+msg_list = [
+    {"role": "system", "content": "You are a helpful assistant."},
+    {"role": "user", "content": "Draft 3 names for a company."},
+]
+```
+
+### Explicit Tracing
+
+```python
+from thoughtflow.trace import Session
+
+session = Session()
+response = agent.call(msg_list, session=session)
+
+# Session captures everything: inputs, outputs, timing, tokens, costs
+print(session.to_dict())
+```
+
+---
+
+## Design Principles
+
+1. **Tiny Surface Area**: Few powerful primitives over many specialized classes
+2. **Explicit State**: All state is visible, serializable, and replayable
+3. **Portability**: Works across OpenAI, Anthropic, local models, serverless
+4. **Deterministic Testing**: Record/replay workflows, stable sessions, predictable behavior
+
+---
+
+## Project Status
+
+🚧 **Alpha** - ThoughtFlow is under active development. The API may change.
+
+See the [CHANGELOG](CHANGELOG.md) for version history.
+
+---
+
+## Contributing
+
+We welcome contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
+
+---
+
+## License
+
+[MIT](LICENSE) © James A. Rolfsen

thoughtflow-0.0.3.dist-info/RECORD

@@ -0,0 +1,25 @@
+thoughtflow/__init__.py,sha256=oeMPn51oJCvIB1m4hOj7yemq_2Ng9sTAlQ3zb0nNXnU,2541
+thoughtflow/_util.py,sha256=c0pMAdFXCGUFf9yhK3xwnqAD3SrlijD0eJVh0EekjMA,25260
+thoughtflow/action.py,sha256=ZCKC95luZwZPEUkHIf8V0ZYxRXZ_msFLtb85Zs_cETg,14246
+thoughtflow/agent.py,sha256=nSwUwUjjkcE2_dF81waSqRFmQ8xW3nQgwzX1VlEOJMo,1977
+thoughtflow/llm.py,sha256=_aZiTHzlavabeKNgdYd-uM45_R10JvvgEgSavNx_k0M,10528
+thoughtflow/message.py,sha256=5hR2Zs3tDRYLtYuuArqmJ4CgBDTUhjHj_RQhCN7tRrg,3800
+thoughtflow/py.typed,sha256=Y3QpSe9qtWcL1vKplcWdRY0cn5071TLJQWBO0QbxTm8,84
+thoughtflow/thought.py,sha256=i5Ca0IxaVGE688AhCpYFlk2vnJzotWZTX2IsW3cuLLU,43229
+thoughtflow/thoughtflow6.py,sha256=GMKlqxFyNvvMD7yIU7NEYAtuDZplapeFeK1pGf20u5o,162824
+thoughtflow/eval/__init__.py,sha256=WiXk5IarMdgQV-mCpWVq_ZwCq6iC6pAKwl9wbZsmmNA,866
+thoughtflow/eval/harness.py,sha256=DH8EGajfxIGsb9HLk7g-hnQM0t1C90VAk7bOPLK9OBQ,5505
+thoughtflow/eval/replay.py,sha256=-osU4BbjVdThLeM1bygCss7sqqHHvg9I43XEvVZkNd8,4011
+thoughtflow/memory/__init__.py,sha256=3DAxZ4NlvJbvyP-8p86WlwoU1BUF24V97a4Z0c0ZC0w,859
+thoughtflow/memory/base.py,sha256=TQn0JJd_t_k4FW73MWEbYNudwe0GEaaDqRyZIe9irvo,64870
+thoughtflow/tools/__init__.py,sha256=1bDivRtNS2rGDForiLMOGKjStBeZAWFH8wylAN3Ihjk,648
+thoughtflow/tools/base.py,sha256=VYRFDhzG912HFUR6W82kykm_FU-r4xg4aEzHBDN_b8M,4069
+thoughtflow/tools/registry.py,sha256=ERKStxvh_UkfLg7GebVFaifSuudFYAfYXbnxr7lC5o0,3335
+thoughtflow/trace/__init__.py,sha256=fQSpJJyYdtaI_L_QAD4NqvYA6yXS5xCJXxS5-rVUpoM,891
+thoughtflow/trace/events.py,sha256=jJtVzs2xSLb43CAW6_CqgBVGgM0gBJ1x-_xmQjwUGkw,4647
+thoughtflow/trace/schema.py,sha256=teyUJ3gV80ZgsU8oCYJmku_f-SDULKtvqqLjvp1eQ_E,3180
+thoughtflow/trace/session.py,sha256=ZYKMGe3t98A7LujG-nSuRQo83BvzqhZGKFXHZZU0amw,4225
+thoughtflow-0.0.3.dist-info/METADATA,sha256=4QewTCLBg1f8bGIsJiqUf6HPrZCMlk27t80eLiFGmkc,7548
+thoughtflow-0.0.3.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+thoughtflow-0.0.3.dist-info/licenses/LICENSE,sha256=Z__Z0xyty_n2lxI7UNvfqkgemXIP0_UliF5sZN8GsPw,1073
+thoughtflow-0.0.3.dist-info/RECORD,,

{thoughtflow-0.0.1.dist-info → thoughtflow-0.0.3.dist-info}/WHEEL

@@ -1,5 +1,4 @@
 Wheel-Version: 1.0
-Generator: bdist_wheel (0.41.2)
+Generator: hatchling 1.28.0
 Root-Is-Purelib: true
 Tag: py3-none-any
-

{thoughtflow-0.0.1.dist-info → thoughtflow-0.0.3.dist-info/licenses}/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2024 James A. Rolfsen
+Copyright (c) 2025 James A. Rolfsen
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

thoughtflow/jtools1.py

@@ -1,25 +0,0 @@
-
-import numpy as np 
-
-class Sorter:
-	def __init__(self):
-		self.x = np.array([])  
-	def sort_things(self,things):
-		idx = np.argsort(things) 
-		return np.array(things)[idx] 
-
-
-Notes = '''
-
-S = Sorter()
-things1 = [5,1,4,2,3]
-things2 = S.sort_things(things1)
-
-
-'''
-
-
-
-
-
-

thoughtflow/jtools2.py

@@ -1,27 +0,0 @@
-
-import numpy as np 
-
-class Adder:
-	def __init__(self):
-		self.x = np.array([])  
-	def add_things(self,things1,things2):
-		a = np.array(things1)
-		b = np.array(things2)
-		return a+b
-
-
-Notes = '''
-
-things1 = [5,1,4,2,3]
-things2 = [1,2,3,4,5] 
-
-A = Adder()
-things3 = A.add_things(things1)
-
-'''
-
-
-
-
-
-

thoughtflow-0.0.1.dist-info/METADATA

@@ -1,17 +0,0 @@
-Metadata-Version: 2.1
-Name: thoughtflow
-Version: 0.0.1
-Summary: Short Description
-Home-page: https://github.com/jrolf/rolfdog
-Author: James A. Rolfsen
-Author-email: james@think.dev
-Classifier: Programming Language :: Python :: 3.12
-Classifier: License :: OSI Approved :: MIT License
-Classifier: Operating System :: OS Independent
-Classifier: Natural Language :: English
-Classifier: Topic :: Software Development :: Libraries :: Python Modules
-License-File: LICENSE
-Requires-Dist: numpy >=1.1.1
-Requires-Dist: pandas >=0.1.1
-
-Long Description

thoughtflow-0.0.1.dist-info/RECORD

@@ -1,8 +0,0 @@
-thoughtflow/__init__.py,sha256=1k9Fv27FmuVKKsy5O4mwLU9VCcSuRprW_P50yCN0qYg,223
-thoughtflow/jtools1.py,sha256=blvqa6ipN4aprYVfsw2sPoyJqJswk1Riw74PC_t_Yzk,269
-thoughtflow/jtools2.py,sha256=vqxDivVtzhwDz_-qwg5c8RsNZurEbK9r1WaFLSDiQNk,298
-thoughtflow-0.0.1.dist-info/LICENSE,sha256=a5AbP99aMpQEW-PKXUuR7qNHxvXnSC-R3M02LBusp6g,1073
-thoughtflow-0.0.1.dist-info/METADATA,sha256=d-pYfPPzWbyvqY4AQHkv_AJOwoxFZYadKlsZAim5g8U,542
-thoughtflow-0.0.1.dist-info/WHEEL,sha256=yQN5g4mg4AybRjkgi-9yy4iQEFibGQmlz78Pik5Or-A,92
-thoughtflow-0.0.1.dist-info/top_level.txt,sha256=vuLVkcDNHCDfhFcrdwBW62c9gOII2XuyWax3-cWVHCE,12
-thoughtflow-0.0.1.dist-info/RECORD,,

thoughtflow-0.0.1.dist-info/top_level.txt

@@ -1 +0,0 @@
-thoughtflow