thoughtflow 0.0.1__py3-none-any.whl → 0.0.2__py3-none-any.whl
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- thoughtflow/__init__.py +54 -5
- thoughtflow/_util.py +108 -0
- thoughtflow/adapters/__init__.py +43 -0
- thoughtflow/adapters/anthropic.py +119 -0
- thoughtflow/adapters/base.py +140 -0
- thoughtflow/adapters/local.py +133 -0
- thoughtflow/adapters/openai.py +118 -0
- thoughtflow/agent.py +147 -0
- thoughtflow/eval/__init__.py +34 -0
- thoughtflow/eval/harness.py +200 -0
- thoughtflow/eval/replay.py +137 -0
- thoughtflow/memory/__init__.py +27 -0
- thoughtflow/memory/base.py +142 -0
- thoughtflow/message.py +140 -0
- thoughtflow/py.typed +2 -0
- thoughtflow/tools/__init__.py +27 -0
- thoughtflow/tools/base.py +145 -0
- thoughtflow/tools/registry.py +122 -0
- thoughtflow/trace/__init__.py +34 -0
- thoughtflow/trace/events.py +183 -0
- thoughtflow/trace/schema.py +111 -0
- thoughtflow/trace/session.py +141 -0
- thoughtflow-0.0.2.dist-info/METADATA +215 -0
- thoughtflow-0.0.2.dist-info/RECORD +26 -0
- {thoughtflow-0.0.1.dist-info → thoughtflow-0.0.2.dist-info}/WHEEL +1 -2
- {thoughtflow-0.0.1.dist-info → thoughtflow-0.0.2.dist-info/licenses}/LICENSE +1 -1
- thoughtflow/jtools1.py +0 -25
- thoughtflow/jtools2.py +0 -27
- thoughtflow-0.0.1.dist-info/METADATA +0 -17
- thoughtflow-0.0.1.dist-info/RECORD +0 -8
- thoughtflow-0.0.1.dist-info/top_level.txt +0 -1
|
@@ -0,0 +1,183 @@
|
|
|
1
|
+
"""
|
|
2
|
+
Event types for ThoughtFlow tracing.
|
|
3
|
+
|
|
4
|
+
Events represent discrete occurrences during an agent run:
|
|
5
|
+
- Model calls (start, end, error)
|
|
6
|
+
- Tool invocations
|
|
7
|
+
- Memory operations
|
|
8
|
+
- Custom user events
|
|
9
|
+
"""
|
|
10
|
+
|
|
11
|
+
from __future__ import annotations
|
|
12
|
+
|
|
13
|
+
from dataclasses import dataclass, field
|
|
14
|
+
from datetime import datetime
|
|
15
|
+
from enum import Enum
|
|
16
|
+
from typing import Any
|
|
17
|
+
|
|
18
|
+
|
|
19
|
+
class EventType(str, Enum):
|
|
20
|
+
"""Types of events that can occur during a session."""
|
|
21
|
+
|
|
22
|
+
# Agent lifecycle
|
|
23
|
+
CALL_START = "call_start"
|
|
24
|
+
CALL_END = "call_end"
|
|
25
|
+
CALL_ERROR = "call_error"
|
|
26
|
+
|
|
27
|
+
# Model interactions
|
|
28
|
+
MODEL_REQUEST = "model_request"
|
|
29
|
+
MODEL_RESPONSE = "model_response"
|
|
30
|
+
MODEL_ERROR = "model_error"
|
|
31
|
+
|
|
32
|
+
# Tool interactions
|
|
33
|
+
TOOL_CALL = "tool_call"
|
|
34
|
+
TOOL_RESULT = "tool_result"
|
|
35
|
+
TOOL_ERROR = "tool_error"
|
|
36
|
+
|
|
37
|
+
# Memory interactions
|
|
38
|
+
MEMORY_RETRIEVE = "memory_retrieve"
|
|
39
|
+
MEMORY_STORE = "memory_store"
|
|
40
|
+
|
|
41
|
+
# Custom
|
|
42
|
+
CUSTOM = "custom"
|
|
43
|
+
|
|
44
|
+
|
|
45
|
+
@dataclass
|
|
46
|
+
class Event:
|
|
47
|
+
"""A single event in a session trace.
|
|
48
|
+
|
|
49
|
+
Events capture everything that happens during an agent run,
|
|
50
|
+
enabling complete visibility and replay capability.
|
|
51
|
+
|
|
52
|
+
Attributes:
|
|
53
|
+
event_type: The type of event.
|
|
54
|
+
timestamp: When the event occurred.
|
|
55
|
+
data: Event-specific data.
|
|
56
|
+
duration_ms: Duration in milliseconds (for end events).
|
|
57
|
+
metadata: Additional metadata.
|
|
58
|
+
|
|
59
|
+
Example:
|
|
60
|
+
>>> event = Event(
|
|
61
|
+
... event_type=EventType.MODEL_REQUEST,
|
|
62
|
+
... data={
|
|
63
|
+
... "messages": [...],
|
|
64
|
+
... "params": {"model": "gpt-4", "temperature": 0.7}
|
|
65
|
+
... }
|
|
66
|
+
... )
|
|
67
|
+
"""
|
|
68
|
+
|
|
69
|
+
event_type: EventType | str
|
|
70
|
+
timestamp: datetime = field(default_factory=datetime.now)
|
|
71
|
+
data: dict[str, Any] = field(default_factory=dict)
|
|
72
|
+
duration_ms: int | None = None
|
|
73
|
+
metadata: dict[str, Any] = field(default_factory=dict)
|
|
74
|
+
|
|
75
|
+
def to_dict(self) -> dict[str, Any]:
|
|
76
|
+
"""Convert to a serializable dict.
|
|
77
|
+
|
|
78
|
+
Returns:
|
|
79
|
+
Dict representation of the event.
|
|
80
|
+
"""
|
|
81
|
+
return {
|
|
82
|
+
"event_type": (
|
|
83
|
+
self.event_type.value
|
|
84
|
+
if isinstance(self.event_type, EventType)
|
|
85
|
+
else self.event_type
|
|
86
|
+
),
|
|
87
|
+
"timestamp": self.timestamp.isoformat(),
|
|
88
|
+
"data": self.data,
|
|
89
|
+
"duration_ms": self.duration_ms,
|
|
90
|
+
"metadata": self.metadata,
|
|
91
|
+
}
|
|
92
|
+
|
|
93
|
+
@classmethod
|
|
94
|
+
def from_dict(cls, data: dict[str, Any]) -> Event:
|
|
95
|
+
"""Create an Event from a dict.
|
|
96
|
+
|
|
97
|
+
Args:
|
|
98
|
+
data: Dict with event data.
|
|
99
|
+
|
|
100
|
+
Returns:
|
|
101
|
+
Event instance.
|
|
102
|
+
"""
|
|
103
|
+
event_type_str = data["event_type"]
|
|
104
|
+
try:
|
|
105
|
+
event_type = EventType(event_type_str)
|
|
106
|
+
except ValueError:
|
|
107
|
+
event_type = event_type_str
|
|
108
|
+
|
|
109
|
+
return cls(
|
|
110
|
+
event_type=event_type,
|
|
111
|
+
timestamp=datetime.fromisoformat(data["timestamp"]),
|
|
112
|
+
data=data.get("data", {}),
|
|
113
|
+
duration_ms=data.get("duration_ms"),
|
|
114
|
+
metadata=data.get("metadata", {}),
|
|
115
|
+
)
|
|
116
|
+
|
|
117
|
+
|
|
118
|
+
# Convenience functions for creating common events
|
|
119
|
+
|
|
120
|
+
|
|
121
|
+
def call_start(messages: list[dict], params: dict | None = None) -> Event:
|
|
122
|
+
"""Create a CALL_START event.
|
|
123
|
+
|
|
124
|
+
Args:
|
|
125
|
+
messages: The input messages.
|
|
126
|
+
params: Call parameters.
|
|
127
|
+
|
|
128
|
+
Returns:
|
|
129
|
+
Event instance.
|
|
130
|
+
"""
|
|
131
|
+
return Event(
|
|
132
|
+
event_type=EventType.CALL_START,
|
|
133
|
+
data={"messages": messages, "params": params or {}},
|
|
134
|
+
)
|
|
135
|
+
|
|
136
|
+
|
|
137
|
+
def call_end(response: str, tokens: dict | None = None) -> Event:
|
|
138
|
+
"""Create a CALL_END event.
|
|
139
|
+
|
|
140
|
+
Args:
|
|
141
|
+
response: The agent's response.
|
|
142
|
+
tokens: Token usage information.
|
|
143
|
+
|
|
144
|
+
Returns:
|
|
145
|
+
Event instance.
|
|
146
|
+
"""
|
|
147
|
+
return Event(
|
|
148
|
+
event_type=EventType.CALL_END,
|
|
149
|
+
data={"response": response, "tokens": tokens or {}},
|
|
150
|
+
)
|
|
151
|
+
|
|
152
|
+
|
|
153
|
+
def tool_call(tool_name: str, payload: dict) -> Event:
|
|
154
|
+
"""Create a TOOL_CALL event.
|
|
155
|
+
|
|
156
|
+
Args:
|
|
157
|
+
tool_name: Name of the tool being called.
|
|
158
|
+
payload: The tool's input payload.
|
|
159
|
+
|
|
160
|
+
Returns:
|
|
161
|
+
Event instance.
|
|
162
|
+
"""
|
|
163
|
+
return Event(
|
|
164
|
+
event_type=EventType.TOOL_CALL,
|
|
165
|
+
data={"tool_name": tool_name, "payload": payload},
|
|
166
|
+
)
|
|
167
|
+
|
|
168
|
+
|
|
169
|
+
def tool_result(tool_name: str, result: Any, success: bool = True) -> Event:
|
|
170
|
+
"""Create a TOOL_RESULT event.
|
|
171
|
+
|
|
172
|
+
Args:
|
|
173
|
+
tool_name: Name of the tool.
|
|
174
|
+
result: The tool's output.
|
|
175
|
+
success: Whether the tool call succeeded.
|
|
176
|
+
|
|
177
|
+
Returns:
|
|
178
|
+
Event instance.
|
|
179
|
+
"""
|
|
180
|
+
return Event(
|
|
181
|
+
event_type=EventType.TOOL_RESULT,
|
|
182
|
+
data={"tool_name": tool_name, "result": result, "success": success},
|
|
183
|
+
)
|
|
@@ -0,0 +1,111 @@
|
|
|
1
|
+
"""
|
|
2
|
+
Trace schema versioning for ThoughtFlow.
|
|
3
|
+
|
|
4
|
+
Once trace schemas are in use, downstream systems depend on them.
|
|
5
|
+
This module provides schema versioning to maintain backward compatibility.
|
|
6
|
+
"""
|
|
7
|
+
|
|
8
|
+
from __future__ import annotations
|
|
9
|
+
|
|
10
|
+
from dataclasses import dataclass
|
|
11
|
+
from typing import Any
|
|
12
|
+
|
|
13
|
+
|
|
14
|
+
# Current schema version
|
|
15
|
+
SCHEMA_VERSION = "1.0.0"
|
|
16
|
+
|
|
17
|
+
|
|
18
|
+
@dataclass
|
|
19
|
+
class TraceSchema:
|
|
20
|
+
"""Schema metadata for trace files.
|
|
21
|
+
|
|
22
|
+
Enables forward/backward compatibility as the trace format evolves.
|
|
23
|
+
|
|
24
|
+
Attributes:
|
|
25
|
+
version: Schema version string.
|
|
26
|
+
thoughtflow_version: ThoughtFlow version that created the trace.
|
|
27
|
+
features: List of optional features used in this trace.
|
|
28
|
+
"""
|
|
29
|
+
|
|
30
|
+
version: str = SCHEMA_VERSION
|
|
31
|
+
thoughtflow_version: str | None = None
|
|
32
|
+
features: list[str] | None = None
|
|
33
|
+
|
|
34
|
+
def to_dict(self) -> dict[str, Any]:
|
|
35
|
+
"""Convert to a dict for embedding in trace files.
|
|
36
|
+
|
|
37
|
+
Returns:
|
|
38
|
+
Dict with schema information.
|
|
39
|
+
"""
|
|
40
|
+
return {
|
|
41
|
+
"schema_version": self.version,
|
|
42
|
+
"thoughtflow_version": self.thoughtflow_version,
|
|
43
|
+
"features": self.features or [],
|
|
44
|
+
}
|
|
45
|
+
|
|
46
|
+
@classmethod
|
|
47
|
+
def from_dict(cls, data: dict[str, Any]) -> TraceSchema:
|
|
48
|
+
"""Create from a dict.
|
|
49
|
+
|
|
50
|
+
Args:
|
|
51
|
+
data: Dict with schema information.
|
|
52
|
+
|
|
53
|
+
Returns:
|
|
54
|
+
TraceSchema instance.
|
|
55
|
+
"""
|
|
56
|
+
return cls(
|
|
57
|
+
version=data.get("schema_version", "1.0.0"),
|
|
58
|
+
thoughtflow_version=data.get("thoughtflow_version"),
|
|
59
|
+
features=data.get("features"),
|
|
60
|
+
)
|
|
61
|
+
|
|
62
|
+
def is_compatible(self, other_version: str) -> bool:
|
|
63
|
+
"""Check if this schema is compatible with another version.
|
|
64
|
+
|
|
65
|
+
Compatibility rules:
|
|
66
|
+
- Same major version = compatible
|
|
67
|
+
- Different major version = incompatible
|
|
68
|
+
|
|
69
|
+
Args:
|
|
70
|
+
other_version: Version string to check against.
|
|
71
|
+
|
|
72
|
+
Returns:
|
|
73
|
+
True if compatible, False otherwise.
|
|
74
|
+
"""
|
|
75
|
+
this_major = self.version.split(".")[0]
|
|
76
|
+
other_major = other_version.split(".")[0]
|
|
77
|
+
return this_major == other_major
|
|
78
|
+
|
|
79
|
+
|
|
80
|
+
def validate_trace(trace_data: dict[str, Any]) -> list[str]:
|
|
81
|
+
"""Validate a trace against the current schema.
|
|
82
|
+
|
|
83
|
+
Args:
|
|
84
|
+
trace_data: The trace data to validate.
|
|
85
|
+
|
|
86
|
+
Returns:
|
|
87
|
+
List of validation errors (empty if valid).
|
|
88
|
+
"""
|
|
89
|
+
errors: list[str] = []
|
|
90
|
+
|
|
91
|
+
# Check required fields
|
|
92
|
+
if "session_id" not in trace_data:
|
|
93
|
+
errors.append("Missing required field: session_id")
|
|
94
|
+
|
|
95
|
+
if "events" not in trace_data:
|
|
96
|
+
errors.append("Missing required field: events")
|
|
97
|
+
elif not isinstance(trace_data["events"], list):
|
|
98
|
+
errors.append("Field 'events' must be a list")
|
|
99
|
+
|
|
100
|
+
# Check schema version compatibility
|
|
101
|
+
schema_info = trace_data.get("schema", {})
|
|
102
|
+
if schema_info:
|
|
103
|
+
trace_version = schema_info.get("schema_version", "1.0.0")
|
|
104
|
+
current_schema = TraceSchema()
|
|
105
|
+
if not current_schema.is_compatible(trace_version):
|
|
106
|
+
errors.append(
|
|
107
|
+
f"Schema version mismatch: trace is v{trace_version}, "
|
|
108
|
+
f"current is v{SCHEMA_VERSION}"
|
|
109
|
+
)
|
|
110
|
+
|
|
111
|
+
return errors
|
|
@@ -0,0 +1,141 @@
|
|
|
1
|
+
"""
|
|
2
|
+
Session object for ThoughtFlow.
|
|
3
|
+
|
|
4
|
+
A Session captures the complete state of an agent run, enabling
|
|
5
|
+
debugging, evaluation, reproducibility, and replay.
|
|
6
|
+
"""
|
|
7
|
+
|
|
8
|
+
from __future__ import annotations
|
|
9
|
+
|
|
10
|
+
import json
|
|
11
|
+
import uuid
|
|
12
|
+
from dataclasses import dataclass, field
|
|
13
|
+
from datetime import datetime
|
|
14
|
+
from pathlib import Path
|
|
15
|
+
from typing import TYPE_CHECKING, Any
|
|
16
|
+
|
|
17
|
+
if TYPE_CHECKING:
|
|
18
|
+
from thoughtflow.trace.events import Event
|
|
19
|
+
|
|
20
|
+
|
|
21
|
+
@dataclass
|
|
22
|
+
class Session:
|
|
23
|
+
"""A session capturing the complete trace of an agent run.
|
|
24
|
+
|
|
25
|
+
Sessions are the foundation for:
|
|
26
|
+
- Debugging: See exactly what happened
|
|
27
|
+
- Evaluation: Measure quality and performance
|
|
28
|
+
- Reproducibility: Replay runs with same inputs
|
|
29
|
+
- Regression testing: Diff across versions/models
|
|
30
|
+
|
|
31
|
+
Attributes:
|
|
32
|
+
session_id: Unique identifier for this session.
|
|
33
|
+
created_at: When the session was created.
|
|
34
|
+
events: List of events that occurred during the run.
|
|
35
|
+
metadata: Additional session metadata.
|
|
36
|
+
|
|
37
|
+
Example:
|
|
38
|
+
>>> session = Session()
|
|
39
|
+
>>> session.add_event(Event(type="call_start", data={...}))
|
|
40
|
+
>>> session.add_event(Event(type="call_end", data={...}))
|
|
41
|
+
>>>
|
|
42
|
+
>>> # Get summary
|
|
43
|
+
>>> print(session.summary())
|
|
44
|
+
>>>
|
|
45
|
+
>>> # Save for later
|
|
46
|
+
>>> session.save("trace.json")
|
|
47
|
+
>>>
|
|
48
|
+
>>> # Load and replay
|
|
49
|
+
>>> loaded = Session.load("trace.json")
|
|
50
|
+
"""
|
|
51
|
+
|
|
52
|
+
session_id: str = field(default_factory=lambda: str(uuid.uuid4()))
|
|
53
|
+
created_at: datetime = field(default_factory=datetime.now)
|
|
54
|
+
events: list[Event] = field(default_factory=list)
|
|
55
|
+
metadata: dict[str, Any] = field(default_factory=dict)
|
|
56
|
+
|
|
57
|
+
# Aggregated metrics (updated as events are added)
|
|
58
|
+
_total_tokens: int = field(default=0, repr=False)
|
|
59
|
+
_total_cost: float = field(default=0.0, repr=False)
|
|
60
|
+
_total_duration_ms: int = field(default=0, repr=False)
|
|
61
|
+
|
|
62
|
+
def add_event(self, event: Event) -> None:
|
|
63
|
+
"""Add an event to the session.
|
|
64
|
+
|
|
65
|
+
Args:
|
|
66
|
+
event: The event to add.
|
|
67
|
+
"""
|
|
68
|
+
self.events.append(event)
|
|
69
|
+
# TODO: Update aggregated metrics based on event type
|
|
70
|
+
|
|
71
|
+
@property
|
|
72
|
+
def total_tokens(self) -> int:
|
|
73
|
+
"""Total tokens used across all model calls."""
|
|
74
|
+
return self._total_tokens
|
|
75
|
+
|
|
76
|
+
@property
|
|
77
|
+
def total_cost(self) -> float:
|
|
78
|
+
"""Total cost in USD across all model calls."""
|
|
79
|
+
return self._total_cost
|
|
80
|
+
|
|
81
|
+
@property
|
|
82
|
+
def duration_ms(self) -> int:
|
|
83
|
+
"""Total duration in milliseconds."""
|
|
84
|
+
return self._total_duration_ms
|
|
85
|
+
|
|
86
|
+
def summary(self) -> dict[str, Any]:
|
|
87
|
+
"""Get a summary of the session.
|
|
88
|
+
|
|
89
|
+
Returns:
|
|
90
|
+
Dict with key metrics and counts.
|
|
91
|
+
"""
|
|
92
|
+
return {
|
|
93
|
+
"session_id": self.session_id,
|
|
94
|
+
"created_at": self.created_at.isoformat(),
|
|
95
|
+
"event_count": len(self.events),
|
|
96
|
+
"total_tokens": self.total_tokens,
|
|
97
|
+
"total_cost": self.total_cost,
|
|
98
|
+
"duration_ms": self.duration_ms,
|
|
99
|
+
}
|
|
100
|
+
|
|
101
|
+
def to_dict(self) -> dict[str, Any]:
|
|
102
|
+
"""Convert to a serializable dict.
|
|
103
|
+
|
|
104
|
+
Returns:
|
|
105
|
+
Complete session data as a dict.
|
|
106
|
+
"""
|
|
107
|
+
return {
|
|
108
|
+
"session_id": self.session_id,
|
|
109
|
+
"created_at": self.created_at.isoformat(),
|
|
110
|
+
"events": [e.to_dict() for e in self.events],
|
|
111
|
+
"metadata": self.metadata,
|
|
112
|
+
"summary": self.summary(),
|
|
113
|
+
}
|
|
114
|
+
|
|
115
|
+
def save(self, path: str | Path) -> None:
|
|
116
|
+
"""Save the session to a JSON file.
|
|
117
|
+
|
|
118
|
+
Args:
|
|
119
|
+
path: Path to save to.
|
|
120
|
+
"""
|
|
121
|
+
path = Path(path)
|
|
122
|
+
path.write_text(json.dumps(self.to_dict(), indent=2))
|
|
123
|
+
|
|
124
|
+
@classmethod
|
|
125
|
+
def load(cls, path: str | Path) -> Session:
|
|
126
|
+
"""Load a session from a JSON file.
|
|
127
|
+
|
|
128
|
+
Args:
|
|
129
|
+
path: Path to load from.
|
|
130
|
+
|
|
131
|
+
Returns:
|
|
132
|
+
Loaded Session instance.
|
|
133
|
+
|
|
134
|
+
Raises:
|
|
135
|
+
NotImplementedError: This is a placeholder implementation.
|
|
136
|
+
"""
|
|
137
|
+
# TODO: Implement session loading with event deserialization
|
|
138
|
+
raise NotImplementedError(
|
|
139
|
+
"Session.load() is not yet implemented. "
|
|
140
|
+
"This is a placeholder for the ThoughtFlow alpha release."
|
|
141
|
+
)
|
|
@@ -0,0 +1,215 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: thoughtflow
|
|
3
|
+
Version: 0.0.2
|
|
4
|
+
Summary: A minimal, explicit, Pythonic substrate for building reproducible, portable, testable LLM and agent systems.
|
|
5
|
+
Project-URL: Homepage, https://github.com/jrolf/thoughtflow
|
|
6
|
+
Project-URL: Documentation, https://thoughtflow.dev
|
|
7
|
+
Project-URL: Repository, https://github.com/jrolf/thoughtflow
|
|
8
|
+
Project-URL: Issues, https://github.com/jrolf/thoughtflow/issues
|
|
9
|
+
Project-URL: Changelog, https://github.com/jrolf/thoughtflow/blob/main/CHANGELOG.md
|
|
10
|
+
Author-email: "James A. Rolfsen" <james@think.dev>
|
|
11
|
+
Maintainer-email: "James A. Rolfsen" <james@think.dev>
|
|
12
|
+
License: MIT License
|
|
13
|
+
|
|
14
|
+
Copyright (c) 2025 James A. Rolfsen
|
|
15
|
+
|
|
16
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
17
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
18
|
+
in the Software without restriction, including without limitation the rights
|
|
19
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
20
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
21
|
+
furnished to do so, subject to the following conditions:
|
|
22
|
+
|
|
23
|
+
The above copyright notice and this permission notice shall be included in all
|
|
24
|
+
copies or substantial portions of the Software.
|
|
25
|
+
|
|
26
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
27
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
28
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
29
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
30
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
31
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
32
|
+
SOFTWARE.
|
|
33
|
+
License-File: LICENSE
|
|
34
|
+
Keywords: agents,ai,anthropic,langchain-alternative,llm,machine-learning,openai,orchestration
|
|
35
|
+
Classifier: Development Status :: 3 - Alpha
|
|
36
|
+
Classifier: Intended Audience :: Developers
|
|
37
|
+
Classifier: License :: OSI Approved :: MIT License
|
|
38
|
+
Classifier: Operating System :: OS Independent
|
|
39
|
+
Classifier: Programming Language :: Python :: 3
|
|
40
|
+
Classifier: Programming Language :: Python :: 3.9
|
|
41
|
+
Classifier: Programming Language :: Python :: 3.10
|
|
42
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
43
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
44
|
+
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
|
|
45
|
+
Classifier: Topic :: Software Development :: Libraries :: Python Modules
|
|
46
|
+
Classifier: Typing :: Typed
|
|
47
|
+
Requires-Python: >=3.9
|
|
48
|
+
Provides-Extra: all
|
|
49
|
+
Requires-Dist: anthropic>=0.18; extra == 'all'
|
|
50
|
+
Requires-Dist: mkdocs-material>=9.0; extra == 'all'
|
|
51
|
+
Requires-Dist: mkdocs>=1.5; extra == 'all'
|
|
52
|
+
Requires-Dist: mkdocstrings[python]>=0.24; extra == 'all'
|
|
53
|
+
Requires-Dist: mypy>=1.0; extra == 'all'
|
|
54
|
+
Requires-Dist: ollama>=0.1; extra == 'all'
|
|
55
|
+
Requires-Dist: openai>=1.0; extra == 'all'
|
|
56
|
+
Requires-Dist: pre-commit>=3.0; extra == 'all'
|
|
57
|
+
Requires-Dist: pytest-asyncio>=0.21; extra == 'all'
|
|
58
|
+
Requires-Dist: pytest-cov>=4.0; extra == 'all'
|
|
59
|
+
Requires-Dist: pytest>=7.0; extra == 'all'
|
|
60
|
+
Requires-Dist: ruff>=0.1; extra == 'all'
|
|
61
|
+
Provides-Extra: all-providers
|
|
62
|
+
Requires-Dist: anthropic>=0.18; extra == 'all-providers'
|
|
63
|
+
Requires-Dist: ollama>=0.1; extra == 'all-providers'
|
|
64
|
+
Requires-Dist: openai>=1.0; extra == 'all-providers'
|
|
65
|
+
Provides-Extra: anthropic
|
|
66
|
+
Requires-Dist: anthropic>=0.18; extra == 'anthropic'
|
|
67
|
+
Provides-Extra: dev
|
|
68
|
+
Requires-Dist: mypy>=1.0; extra == 'dev'
|
|
69
|
+
Requires-Dist: pre-commit>=3.0; extra == 'dev'
|
|
70
|
+
Requires-Dist: pytest-asyncio>=0.21; extra == 'dev'
|
|
71
|
+
Requires-Dist: pytest-cov>=4.0; extra == 'dev'
|
|
72
|
+
Requires-Dist: pytest>=7.0; extra == 'dev'
|
|
73
|
+
Requires-Dist: ruff>=0.1; extra == 'dev'
|
|
74
|
+
Provides-Extra: docs
|
|
75
|
+
Requires-Dist: mkdocs-material>=9.0; extra == 'docs'
|
|
76
|
+
Requires-Dist: mkdocs>=1.5; extra == 'docs'
|
|
77
|
+
Requires-Dist: mkdocstrings[python]>=0.24; extra == 'docs'
|
|
78
|
+
Provides-Extra: local
|
|
79
|
+
Requires-Dist: ollama>=0.1; extra == 'local'
|
|
80
|
+
Provides-Extra: openai
|
|
81
|
+
Requires-Dist: openai>=1.0; extra == 'openai'
|
|
82
|
+
Description-Content-Type: text/markdown
|
|
83
|
+
|
|
84
|
+
# ThoughtFlow
|
|
85
|
+
|
|
86
|
+
[](https://badge.fury.io/py/thoughtflow)
|
|
87
|
+
[](https://www.python.org/downloads/)
|
|
88
|
+
[](https://opensource.org/licenses/MIT)
|
|
89
|
+
[](https://github.com/jrolf/thoughtflow/actions/workflows/ci.yml)
|
|
90
|
+
|
|
91
|
+
**A minimal, explicit, Pythonic substrate for building reproducible, portable, testable LLM and agent systems.**
|
|
92
|
+
|
|
93
|
+
> *Tiny surface area. Explicit state. Portable execution. Deterministic testing.*
|
|
94
|
+
|
|
95
|
+
---
|
|
96
|
+
|
|
97
|
+
## Why ThoughtFlow?
|
|
98
|
+
|
|
99
|
+
The modern LLM/agent ecosystem often evolves into abstraction swamps—hidden state, magical callbacks, and frameworks that are hard to understand, test, and deploy.
|
|
100
|
+
|
|
101
|
+
**ThoughtFlow takes a different path:**
|
|
102
|
+
|
|
103
|
+
- ✅ **No hidden agent runtime** you can't reason about
|
|
104
|
+
- ✅ **No graph DSL** you must adopt to do anything serious
|
|
105
|
+
- ✅ **No implicit global memory** or callback chains
|
|
106
|
+
- ✅ **No abstraction layers** whose main job is wrapping other abstractions
|
|
107
|
+
|
|
108
|
+
Instead, ThoughtFlow makes orchestration logic **plain Python**: explicit inputs, explicit outputs, explicit state transitions, replayable sessions, deterministic evaluation paths.
|
|
109
|
+
|
|
110
|
+
---
|
|
111
|
+
|
|
112
|
+
## Installation
|
|
113
|
+
|
|
114
|
+
```bash
|
|
115
|
+
# Core library (zero dependencies)
|
|
116
|
+
pip install thoughtflow
|
|
117
|
+
|
|
118
|
+
# With OpenAI support
|
|
119
|
+
pip install thoughtflow[openai]
|
|
120
|
+
|
|
121
|
+
# With Anthropic support
|
|
122
|
+
pip install thoughtflow[anthropic]
|
|
123
|
+
|
|
124
|
+
# With all providers
|
|
125
|
+
pip install thoughtflow[all-providers]
|
|
126
|
+
```
|
|
127
|
+
|
|
128
|
+
---
|
|
129
|
+
|
|
130
|
+
## Quick Start
|
|
131
|
+
|
|
132
|
+
```python
|
|
133
|
+
from thoughtflow import Agent
|
|
134
|
+
from thoughtflow.adapters import OpenAIAdapter
|
|
135
|
+
|
|
136
|
+
# Create an adapter for your provider
|
|
137
|
+
adapter = OpenAIAdapter(api_key="your-api-key")
|
|
138
|
+
|
|
139
|
+
# Create an agent
|
|
140
|
+
agent = Agent(adapter)
|
|
141
|
+
|
|
142
|
+
# Call with a message list (the universal currency)
|
|
143
|
+
response = agent.call([
|
|
144
|
+
{"role": "system", "content": "You are a helpful assistant."},
|
|
145
|
+
{"role": "user", "content": "What is ThoughtFlow?"}
|
|
146
|
+
])
|
|
147
|
+
|
|
148
|
+
print(response)
|
|
149
|
+
```
|
|
150
|
+
|
|
151
|
+
---
|
|
152
|
+
|
|
153
|
+
## Core Concepts
|
|
154
|
+
|
|
155
|
+
### The Agent Contract
|
|
156
|
+
|
|
157
|
+
An Agent is something that can be called with messages and parameters:
|
|
158
|
+
|
|
159
|
+
```python
|
|
160
|
+
class Agent:
|
|
161
|
+
def call(self, msg_list, params=None):
|
|
162
|
+
raise NotImplementedError
|
|
163
|
+
```
|
|
164
|
+
|
|
165
|
+
That's it. Everything else is composition.
|
|
166
|
+
|
|
167
|
+
### Messages: Stable Schema, Minimal Assumptions
|
|
168
|
+
|
|
169
|
+
```python
|
|
170
|
+
msg_list = [
|
|
171
|
+
{"role": "system", "content": "You are a helpful assistant."},
|
|
172
|
+
{"role": "user", "content": "Draft 3 names for a company."},
|
|
173
|
+
]
|
|
174
|
+
```
|
|
175
|
+
|
|
176
|
+
### Explicit Tracing
|
|
177
|
+
|
|
178
|
+
```python
|
|
179
|
+
from thoughtflow.trace import Session
|
|
180
|
+
|
|
181
|
+
session = Session()
|
|
182
|
+
response = agent.call(msg_list, session=session)
|
|
183
|
+
|
|
184
|
+
# Session captures everything: inputs, outputs, timing, tokens, costs
|
|
185
|
+
print(session.to_dict())
|
|
186
|
+
```
|
|
187
|
+
|
|
188
|
+
---
|
|
189
|
+
|
|
190
|
+
## Design Principles
|
|
191
|
+
|
|
192
|
+
1. **Tiny Surface Area**: Few powerful primitives over many specialized classes
|
|
193
|
+
2. **Explicit State**: All state is visible, serializable, and replayable
|
|
194
|
+
3. **Portability**: Works across OpenAI, Anthropic, local models, serverless
|
|
195
|
+
4. **Deterministic Testing**: Record/replay workflows, stable sessions, predictable behavior
|
|
196
|
+
|
|
197
|
+
---
|
|
198
|
+
|
|
199
|
+
## Project Status
|
|
200
|
+
|
|
201
|
+
🚧 **Alpha** - ThoughtFlow is under active development. The API may change.
|
|
202
|
+
|
|
203
|
+
See the [CHANGELOG](CHANGELOG.md) for version history.
|
|
204
|
+
|
|
205
|
+
---
|
|
206
|
+
|
|
207
|
+
## Contributing
|
|
208
|
+
|
|
209
|
+
We welcome contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
|
|
210
|
+
|
|
211
|
+
---
|
|
212
|
+
|
|
213
|
+
## License
|
|
214
|
+
|
|
215
|
+
[MIT](LICENSE) © James A. Rolfsen
|
|
@@ -0,0 +1,26 @@
|
|
|
1
|
+
thoughtflow/__init__.py,sha256=Jc_g5TDgnMFq3vNI5IBO8Xaja-f-KtjmW9NatIkUtYI,1375
|
|
2
|
+
thoughtflow/_util.py,sha256=64QWe9TV3reyhmnlZDO_c3AtntHY6AFXe4MyqpJ20hs,2804
|
|
3
|
+
thoughtflow/agent.py,sha256=yRL3OA1anQ6r_TUj8ncy0ZT5GF0G0rYaZxdV_YdpMig,4290
|
|
4
|
+
thoughtflow/message.py,sha256=5hR2Zs3tDRYLtYuuArqmJ4CgBDTUhjHj_RQhCN7tRrg,3800
|
|
5
|
+
thoughtflow/py.typed,sha256=Y3QpSe9qtWcL1vKplcWdRY0cn5071TLJQWBO0QbxTm8,84
|
|
6
|
+
thoughtflow/adapters/__init__.py,sha256=OmGEgr08B7kwsSydINBQzsW5S_YDrzhLII05F1aqdak,1235
|
|
7
|
+
thoughtflow/adapters/anthropic.py,sha256=IS-viYzbgde0em5cPiKkn8yQ6oHvkvBKL5_4JIBywG8,3500
|
|
8
|
+
thoughtflow/adapters/base.py,sha256=vZE3M84AiPWSaGJIEKjkfB-FEgEswtBahNuHC_yBuhs,4102
|
|
9
|
+
thoughtflow/adapters/local.py,sha256=XsCRtZ2HhLjXIOj-Du_RwLLgEOwGDVjvnQpze97wM1w,4037
|
|
10
|
+
thoughtflow/adapters/openai.py,sha256=RcE5Le__j8P_UQf3dF8WMTW1Ie7zTNYgBUOWK7r1Tcc,3287
|
|
11
|
+
thoughtflow/eval/__init__.py,sha256=WiXk5IarMdgQV-mCpWVq_ZwCq6iC6pAKwl9wbZsmmNA,866
|
|
12
|
+
thoughtflow/eval/harness.py,sha256=DH8EGajfxIGsb9HLk7g-hnQM0t1C90VAk7bOPLK9OBQ,5505
|
|
13
|
+
thoughtflow/eval/replay.py,sha256=-osU4BbjVdThLeM1bygCss7sqqHHvg9I43XEvVZkNd8,4011
|
|
14
|
+
thoughtflow/memory/__init__.py,sha256=jwakjf3Rfi4Rk9HfadNHy6WGJ3VNG9GI3gSZO5Ebe5I,691
|
|
15
|
+
thoughtflow/memory/base.py,sha256=WjnrJYT_b72BX3M6DontoVNhNW-SGVDbR2bAtyxy1-Q,4224
|
|
16
|
+
thoughtflow/tools/__init__.py,sha256=1bDivRtNS2rGDForiLMOGKjStBeZAWFH8wylAN3Ihjk,648
|
|
17
|
+
thoughtflow/tools/base.py,sha256=VYRFDhzG912HFUR6W82kykm_FU-r4xg4aEzHBDN_b8M,4069
|
|
18
|
+
thoughtflow/tools/registry.py,sha256=ERKStxvh_UkfLg7GebVFaifSuudFYAfYXbnxr7lC5o0,3335
|
|
19
|
+
thoughtflow/trace/__init__.py,sha256=fQSpJJyYdtaI_L_QAD4NqvYA6yXS5xCJXxS5-rVUpoM,891
|
|
20
|
+
thoughtflow/trace/events.py,sha256=jJtVzs2xSLb43CAW6_CqgBVGgM0gBJ1x-_xmQjwUGkw,4647
|
|
21
|
+
thoughtflow/trace/schema.py,sha256=teyUJ3gV80ZgsU8oCYJmku_f-SDULKtvqqLjvp1eQ_E,3180
|
|
22
|
+
thoughtflow/trace/session.py,sha256=ZYKMGe3t98A7LujG-nSuRQo83BvzqhZGKFXHZZU0amw,4225
|
|
23
|
+
thoughtflow-0.0.2.dist-info/METADATA,sha256=50ieenI8zDoK1IuHmNU1Tpa4ginxmUUuY7DQ5hw_Hck,7548
|
|
24
|
+
thoughtflow-0.0.2.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
|
|
25
|
+
thoughtflow-0.0.2.dist-info/licenses/LICENSE,sha256=Z__Z0xyty_n2lxI7UNvfqkgemXIP0_UliF5sZN8GsPw,1073
|
|
26
|
+
thoughtflow-0.0.2.dist-info/RECORD,,
|