strata-forge 0.0.1__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.
Files changed (162) hide show
  1. strata_forge/__init__.py +3 -0
  2. strata_forge/agents/README.md +20 -0
  3. strata_forge/agents/__init__.py +99 -0
  4. strata_forge/agents/agent.py +306 -0
  5. strata_forge/agents/memory/__init__.py +33 -0
  6. strata_forge/agents/memory/conversation.py +190 -0
  7. strata_forge/agents/memory/episodic.py +111 -0
  8. strata_forge/agents/memory/vector_store.py +25 -0
  9. strata_forge/agents/multi_agent.py +224 -0
  10. strata_forge/agents/tools/__init__.py +32 -0
  11. strata_forge/agents/tools/calculator.py +93 -0
  12. strata_forge/agents/tools/fetch_url.py +55 -0
  13. strata_forge/agents/tools/fs_read.py +121 -0
  14. strata_forge/agents/tools/web_search.py +104 -0
  15. strata_forge/cli/README.md +5 -0
  16. strata_forge/cli/__init__.py +5 -0
  17. strata_forge/cli/chat.py +168 -0
  18. strata_forge/cli/compute.py +241 -0
  19. strata_forge/cli/datasets.py +114 -0
  20. strata_forge/cli/doctor.py +132 -0
  21. strata_forge/cli/eval_cmd.py +212 -0
  22. strata_forge/cli/experiments.py +75 -0
  23. strata_forge/cli/helpers.py +94 -0
  24. strata_forge/cli/main.py +44 -0
  25. strata_forge/cli/prompts.py +140 -0
  26. strata_forge/cli/serve.py +152 -0
  27. strata_forge/cli/train.py +293 -0
  28. strata_forge/compute/README.md +19 -0
  29. strata_forge/compute/__init__.py +53 -0
  30. strata_forge/compute/backends/__init__.py +20 -0
  31. strata_forge/compute/backends/base.py +107 -0
  32. strata_forge/compute/backends/local.py +258 -0
  33. strata_forge/compute/backends/skypilot.py +238 -0
  34. strata_forge/compute/backends/ssh.py +332 -0
  35. strata_forge/compute/batch.py +141 -0
  36. strata_forge/compute/job.py +89 -0
  37. strata_forge/compute/serving.py +316 -0
  38. strata_forge/compute/task.py +167 -0
  39. strata_forge/config/README.md +5 -0
  40. strata_forge/config/__init__.py +39 -0
  41. strata_forge/config/env.py +38 -0
  42. strata_forge/config/overlays.py +100 -0
  43. strata_forge/config/settings.py +200 -0
  44. strata_forge/core/README.md +5 -0
  45. strata_forge/core/__init__.py +64 -0
  46. strata_forge/core/budget.py +159 -0
  47. strata_forge/core/errors.py +232 -0
  48. strata_forge/core/ids.py +63 -0
  49. strata_forge/core/logging.py +123 -0
  50. strata_forge/core/repro.py +115 -0
  51. strata_forge/core/retry.py +84 -0
  52. strata_forge/core/types.py +20 -0
  53. strata_forge/datasets/README.md +22 -0
  54. strata_forge/datasets/__init__.py +31 -0
  55. strata_forge/datasets/hf_bridge.py +133 -0
  56. strata_forge/datasets/schema.py +122 -0
  57. strata_forge/datasets/store.py +97 -0
  58. strata_forge/datasets/stores/__init__.py +15 -0
  59. strata_forge/datasets/stores/langfuse.py +316 -0
  60. strata_forge/datasets/stores/memory.py +86 -0
  61. strata_forge/datasets/synthetic/__init__.py +26 -0
  62. strata_forge/datasets/synthetic/distillation.py +109 -0
  63. strata_forge/datasets/synthetic/self_instruct.py +192 -0
  64. strata_forge/datasets/versioning.py +89 -0
  65. strata_forge/evals/README.md +15 -0
  66. strata_forge/evals/__init__.py +86 -0
  67. strata_forge/evals/ci_gate.py +201 -0
  68. strata_forge/evals/experiment.py +154 -0
  69. strata_forge/evals/graders/__init__.py +33 -0
  70. strata_forge/evals/graders/base.py +41 -0
  71. strata_forge/evals/graders/exact.py +112 -0
  72. strata_forge/evals/graders/json_grader.py +131 -0
  73. strata_forge/evals/graders/llm_judge.py +148 -0
  74. strata_forge/evals/graders/pairwise.py +169 -0
  75. strata_forge/evals/graders/semantic.py +122 -0
  76. strata_forge/evals/metrics.py +186 -0
  77. strata_forge/evals/reports/__init__.py +18 -0
  78. strata_forge/evals/reports/html.py +175 -0
  79. strata_forge/evals/reports/markdown.py +155 -0
  80. strata_forge/evals/runner.py +244 -0
  81. strata_forge/evals/sweeps.py +143 -0
  82. strata_forge/evals/trace_replay.py +234 -0
  83. strata_forge/llm/README.md +5 -0
  84. strata_forge/llm/__init__.py +198 -0
  85. strata_forge/llm/cache.py +238 -0
  86. strata_forge/llm/client.py +1256 -0
  87. strata_forge/llm/cost.py +53 -0
  88. strata_forge/llm/diagnostic.py +169 -0
  89. strata_forge/llm/errors.py +176 -0
  90. strata_forge/llm/fallback.py +212 -0
  91. strata_forge/llm/loop_events.py +174 -0
  92. strata_forge/llm/messages.py +213 -0
  93. strata_forge/llm/multimodal.py +160 -0
  94. strata_forge/llm/providers/__init__.py +45 -0
  95. strata_forge/llm/providers/anthropic.py +79 -0
  96. strata_forge/llm/providers/azure.py +57 -0
  97. strata_forge/llm/providers/base.py +111 -0
  98. strata_forge/llm/providers/bedrock.py +54 -0
  99. strata_forge/llm/providers/config.py +165 -0
  100. strata_forge/llm/providers/openai.py +87 -0
  101. strata_forge/llm/providers/openai_compat.py +56 -0
  102. strata_forge/llm/providers/vertex.py +108 -0
  103. strata_forge/llm/registry.py +241 -0
  104. strata_forge/llm/registry_data.yaml +273 -0
  105. strata_forge/llm/responses.py +105 -0
  106. strata_forge/llm/routing.py +102 -0
  107. strata_forge/llm/schemas.py +380 -0
  108. strata_forge/llm/streaming.py +240 -0
  109. strata_forge/llm/tokens.py +90 -0
  110. strata_forge/llm/tools.py +277 -0
  111. strata_forge/pipelines/__init__.py +7 -0
  112. strata_forge/pipelines/inference_runner.py +367 -0
  113. strata_forge/prompts/README.md +23 -0
  114. strata_forge/prompts/__init__.py +50 -0
  115. strata_forge/prompts/cache_aware.py +149 -0
  116. strata_forge/prompts/registry.py +189 -0
  117. strata_forge/prompts/rendering.py +156 -0
  118. strata_forge/prompts/stores/__init__.py +11 -0
  119. strata_forge/prompts/stores/langfuse.py +247 -0
  120. strata_forge/prompts/stores/memory.py +90 -0
  121. strata_forge/prompts/template.py +217 -0
  122. strata_forge/prompts/variables.py +106 -0
  123. strata_forge/py.typed +0 -0
  124. strata_forge/rag/README.md +5 -0
  125. strata_forge/rag/__init__.py +65 -0
  126. strata_forge/rag/bm25.py +157 -0
  127. strata_forge/rag/chunking.py +262 -0
  128. strata_forge/rag/dense.py +109 -0
  129. strata_forge/rag/embedding.py +130 -0
  130. strata_forge/rag/hybrid.py +128 -0
  131. strata_forge/rag/pipeline.py +194 -0
  132. strata_forge/rag/qdrant.py +247 -0
  133. strata_forge/rag/rerankers.py +242 -0
  134. strata_forge/rag/retrieval.py +57 -0
  135. strata_forge/rag/vector_store.py +138 -0
  136. strata_forge/storage/README.md +5 -0
  137. strata_forge/storage/__init__.py +29 -0
  138. strata_forge/storage/gateway.py +220 -0
  139. strata_forge/storage/hf_hub.py +384 -0
  140. strata_forge/sync.py +158 -0
  141. strata_forge/tracing/README.md +21 -0
  142. strata_forge/tracing/__init__.py +31 -0
  143. strata_forge/tracing/client.py +82 -0
  144. strata_forge/tracing/decorator.py +201 -0
  145. strata_forge/tracing/litellm_callback.py +93 -0
  146. strata_forge/tracing/metrics.py +138 -0
  147. strata_forge/tracing/score.py +115 -0
  148. strata_forge/tracing/span.py +122 -0
  149. strata_forge/training/README.md +5 -0
  150. strata_forge/training/__init__.py +64 -0
  151. strata_forge/training/chat_template.py +140 -0
  152. strata_forge/training/packing.py +109 -0
  153. strata_forge/training/peft.py +138 -0
  154. strata_forge/training/preference.py +335 -0
  155. strata_forge/training/progress.py +224 -0
  156. strata_forge/training/sft.py +264 -0
  157. strata_forge-0.0.1.dist-info/METADATA +184 -0
  158. strata_forge-0.0.1.dist-info/RECORD +162 -0
  159. strata_forge-0.0.1.dist-info/WHEEL +4 -0
  160. strata_forge-0.0.1.dist-info/entry_points.txt +2 -0
  161. strata_forge-0.0.1.dist-info/licenses/LICENSE +202 -0
  162. strata_forge-0.0.1.dist-info/licenses/NOTICE +4 -0
@@ -0,0 +1,3 @@
1
+ """AI Forge — typed, async-first baseline for AI/LLM experiments."""
2
+
3
+ __version__ = "0.0.1"
@@ -0,0 +1,20 @@
1
+ # strata_forge.agents
2
+
3
+ A thin agent layer on top of `strata_forge.llm`. An `Agent` bundles an
4
+ `LLMClient`, a system prompt, and a set of tools; its `.run()`
5
+ method dispatches through `LLMClient.run_tool_loop`
6
+ (when tools are present) or `LLMClient.complete` (when not), and
7
+ returns an `AgentResult` carrying the final text plus the input
8
+ conversation.
9
+
10
+ By design, the agent layer does not re-implement tool calling,
11
+ structured output, or the multi-turn tool loop — every primitive
12
+ comes straight from `strata_forge.llm`. See
13
+ [ADR 0011](../../../docs/architecture/adr/0011-agents-thin-wrapper-over-forge-llm.md)
14
+ for the rationale.
15
+
16
+ The 3.1 foundation ships the `Agent` runtime and the `AgentResult`
17
+ shape. Built-in tools (Phase 3.2), conversation and episodic memory
18
+ (Phase 3.3), and multi-agent patterns — hand-off and critic-refiner
19
+ (Phase 3.4) — land in subsequent sub-phases. See
20
+ `docs/roadmap.md` for status.
@@ -0,0 +1,99 @@
1
+ """Agent builder, built-in tools, memory, and multi-agent patterns.
2
+
3
+ Per ADR 0011, this module is a thin composition layer over
4
+ :mod:`strata_forge.llm`; the tool calling primitives — :class:`Tool`,
5
+ :func:`tool`, the message types, and the multi-turn tool loop — are
6
+ re-exported here for convenience but live in :mod:`strata_forge.llm`.
7
+ """
8
+
9
+ from strata_forge.agents.agent import Agent, AgentResult
10
+ from strata_forge.agents.memory import (
11
+ ConversationMemory,
12
+ EmbedFn,
13
+ EpisodicMemory,
14
+ InMemoryVectorStore,
15
+ VectorItem,
16
+ VectorSearchResult,
17
+ VectorStore,
18
+ )
19
+ from strata_forge.agents.multi_agent import (
20
+ CritiqueVerdict,
21
+ RouterChoice,
22
+ critic_refiner_run,
23
+ handoff,
24
+ )
25
+ from strata_forge.agents.tools import (
26
+ CalculatorArgs,
27
+ FetchURLArgs,
28
+ FSReadArgs,
29
+ SearchBackend,
30
+ SearchResult,
31
+ WebSearchArgs,
32
+ calculator,
33
+ fetch_url,
34
+ fs_read_tool,
35
+ web_search_tool,
36
+ )
37
+
38
+ # Re-export the strata_forge.llm primitives that agents compose with. Users
39
+ # can build agents without ever importing from strata_forge.llm directly.
40
+ from strata_forge.llm.loop_events import (
41
+ Done,
42
+ IterationStart,
43
+ LoopError,
44
+ LoopEvent,
45
+ TextDelta,
46
+ ToolCallStarted,
47
+ ToolResult,
48
+ )
49
+ from strata_forge.llm.messages import (
50
+ AnyMessage,
51
+ AssistantMessage,
52
+ Message,
53
+ SystemMessage,
54
+ ToolResultMessage,
55
+ UserMessage,
56
+ )
57
+ from strata_forge.llm.tools import Tool, ToolLoopExceededError, tool
58
+
59
+ __all__ = [
60
+ "Agent",
61
+ "AgentResult",
62
+ "AnyMessage",
63
+ "AssistantMessage",
64
+ "CalculatorArgs",
65
+ "ConversationMemory",
66
+ "CritiqueVerdict",
67
+ "Done",
68
+ "EmbedFn",
69
+ "EpisodicMemory",
70
+ "FSReadArgs",
71
+ "FetchURLArgs",
72
+ "InMemoryVectorStore",
73
+ "IterationStart",
74
+ "LoopError",
75
+ "LoopEvent",
76
+ "Message",
77
+ "RouterChoice",
78
+ "SearchBackend",
79
+ "SearchResult",
80
+ "SystemMessage",
81
+ "TextDelta",
82
+ "Tool",
83
+ "ToolCallStarted",
84
+ "ToolLoopExceededError",
85
+ "ToolResult",
86
+ "ToolResultMessage",
87
+ "UserMessage",
88
+ "VectorItem",
89
+ "VectorSearchResult",
90
+ "VectorStore",
91
+ "WebSearchArgs",
92
+ "calculator",
93
+ "critic_refiner_run",
94
+ "fetch_url",
95
+ "fs_read_tool",
96
+ "handoff",
97
+ "tool",
98
+ "web_search_tool",
99
+ ]
@@ -0,0 +1,306 @@
1
+ """Single-agent runtime — a thin wrapper over :class:`strata_forge.llm.LLMClient`.
2
+
3
+ An :class:`Agent` holds a system prompt, a set of tools (instances of
4
+ :class:`strata_forge.llm.Tool`), and a reference to an :class:`LLMClient`.
5
+ Calling :meth:`Agent.run` builds the full message list (system +
6
+ user) and dispatches it through :meth:`LLMClient.run_tool_loop` when
7
+ tools are present, or :meth:`LLMClient.complete` otherwise. The
8
+ returned :class:`AgentResult` bundles the final text, the conversation
9
+ that was sent, and the raw :class:`LLMResponse`.
10
+
11
+ See [ADR 0011](../../../docs/architecture/adr/0011-agents-thin-wrapper-over-forge-llm.md)
12
+ for the no-reimplementation design principle.
13
+ """
14
+
15
+ from __future__ import annotations
16
+
17
+ from typing import TYPE_CHECKING, Any, TypeVar
18
+
19
+ from pydantic import BaseModel, ConfigDict
20
+
21
+ from strata_forge.llm.messages import (
22
+ AnyMessage,
23
+ SystemMessage,
24
+ UserMessage,
25
+ )
26
+ from strata_forge.llm.responses import (
27
+ LLMResponse, # noqa: TC001 — Pydantic needs runtime resolution
28
+ )
29
+
30
+ if TYPE_CHECKING:
31
+ from collections.abc import AsyncIterator, Mapping, Sequence
32
+
33
+ from strata_forge.llm.client import LLMClient
34
+ from strata_forge.llm.loop_events import LoopEvent
35
+ from strata_forge.llm.registry import ProviderName
36
+ from strata_forge.llm.tools import Tool
37
+
38
+ __all__ = [
39
+ "Agent",
40
+ "AgentResult",
41
+ ]
42
+
43
+
44
+ M = TypeVar("M", bound=BaseModel)
45
+
46
+
47
+ class AgentResult(BaseModel):
48
+ """The outcome of an :meth:`Agent.run` invocation.
49
+
50
+ Attributes:
51
+ text: The final assistant text — empty when the model exited
52
+ with no textual content (rare, but possible after a tool
53
+ loop that terminated immediately).
54
+ messages: The conversation sent to the LLM (system prompt +
55
+ user input). Intermediate tool-call / tool-result
56
+ messages from inside the tool loop are NOT included
57
+ here — :class:`LLMClient.run_tool_loop` doesn't expose
58
+ them, and capturing them would require re-implementing
59
+ the loop. Callers that need the full trace consult
60
+ ``strata_forge.tracing`` (Langfuse) or the
61
+ ``FORGE_DIAGNOSTIC`` NDJSON dump.
62
+ final_response: The raw final :class:`LLMResponse` from the
63
+ underlying client. Carries usage, cost, latency, the
64
+ resolved provider route, and ``cache_hit`` exactly as
65
+ ``strata_forge.llm`` produced them.
66
+ parsed: When :meth:`Agent.run_structured` produced a typed
67
+ output, the validated Pydantic instance lives here.
68
+ ``None`` for plain :meth:`Agent.run` calls.
69
+ """
70
+
71
+ model_config = ConfigDict(extra="forbid", arbitrary_types_allowed=True, frozen=True)
72
+
73
+ text: str
74
+ messages: tuple[AnyMessage, ...]
75
+ final_response: LLMResponse
76
+ parsed: Any = None
77
+
78
+ @property
79
+ def cost_usd(self) -> float:
80
+ """Convenience accessor: final-response cost.
81
+
82
+ Note this is the **final completion's** cost only; cost
83
+ across all tool-loop iterations is not aggregated. Use
84
+ Langfuse tracing for cumulative accounting.
85
+ """
86
+ return self.final_response.cost_usd
87
+
88
+ @property
89
+ def latency_ms(self) -> float:
90
+ """Convenience accessor: final-response latency."""
91
+ return self.final_response.latency_ms
92
+
93
+
94
+ class Agent:
95
+ """A single-agent runtime built on :class:`LLMClient`.
96
+
97
+ Args:
98
+ name: Human-readable identifier. Surfaces in multi-agent
99
+ handoff messages (Phase 3.4) and report output.
100
+ client: The :class:`LLMClient` the agent uses. Models with
101
+ ``tool_calling=False`` in the registry can still be
102
+ wrapped in an :class:`Agent`, but calling :meth:`run`
103
+ with non-empty ``tools`` raises
104
+ :class:`strata_forge.core.errors.RegistryError`.
105
+ system_prompt: Optional system message prepended to every
106
+ run. When ``None``, the agent sends only the user input.
107
+ tools: Tool instances built via :func:`strata_forge.llm.tool`. May
108
+ be empty.
109
+ max_iterations: Tool-loop iteration cap forwarded to
110
+ :meth:`LLMClient.run_tool_loop`. Default 8 — same as
111
+ :meth:`LLMClient.run_tool_loop`.
112
+ """
113
+
114
+ def __init__(
115
+ self,
116
+ name: str,
117
+ *,
118
+ client: LLMClient,
119
+ system_prompt: str | None = None,
120
+ tools: Sequence[Tool] = (),
121
+ max_iterations: int = 8,
122
+ ) -> None:
123
+ if not name:
124
+ err = "Agent name must be non-empty"
125
+ raise ValueError(err)
126
+ if max_iterations < 1:
127
+ err = f"max_iterations must be >= 1; got {max_iterations}"
128
+ raise ValueError(err)
129
+ self._name = name
130
+ self._client = client
131
+ self._system_prompt = system_prompt
132
+ self._tools: tuple[Tool, ...] = tuple(tools)
133
+ self._max_iterations = max_iterations
134
+
135
+ @property
136
+ def name(self) -> str:
137
+ return self._name
138
+
139
+ @property
140
+ def client(self) -> LLMClient:
141
+ return self._client
142
+
143
+ @property
144
+ def system_prompt(self) -> str | None:
145
+ return self._system_prompt
146
+
147
+ @property
148
+ def tools(self) -> tuple[Tool, ...]:
149
+ return self._tools
150
+
151
+ @property
152
+ def max_iterations(self) -> int:
153
+ return self._max_iterations
154
+
155
+ def _build_messages(self, user_input: str | Sequence[AnyMessage]) -> list[AnyMessage]:
156
+ messages: list[AnyMessage] = []
157
+ if self._system_prompt is not None:
158
+ messages.append(SystemMessage(content=self._system_prompt))
159
+ if isinstance(user_input, str):
160
+ messages.append(UserMessage(content=user_input))
161
+ else:
162
+ messages.extend(user_input)
163
+ return messages
164
+
165
+ async def run(
166
+ self,
167
+ user_input: str | Sequence[AnyMessage],
168
+ *,
169
+ temperature: float | None = None,
170
+ max_tokens: int | None = None,
171
+ top_p: float | None = None,
172
+ provider_extras: Mapping[ProviderName, Mapping[str, Any]] | None = None,
173
+ ) -> AgentResult:
174
+ """Run the agent over ``user_input`` and return the result.
175
+
176
+ When the agent has tools, dispatches through
177
+ :meth:`LLMClient.run_tool_loop`; otherwise calls
178
+ :meth:`LLMClient.complete` once.
179
+
180
+ Args:
181
+ user_input: A user-message string (wrapped into
182
+ :class:`UserMessage`) or a sequence of
183
+ :class:`AnyMessage` to pass through verbatim. The
184
+ agent's system prompt is prepended either way.
185
+ temperature, max_tokens, top_p: Forwarded to the
186
+ underlying call.
187
+ provider_extras: Forwarded to the underlying call.
188
+
189
+ Returns:
190
+ An :class:`AgentResult` with the final text, the input
191
+ conversation, and the raw :class:`LLMResponse`.
192
+ """
193
+ messages = self._build_messages(user_input)
194
+ if self._tools:
195
+ response = await self._client.run_tool_loop(
196
+ messages,
197
+ tools=self._tools,
198
+ max_iterations=self._max_iterations,
199
+ temperature=temperature,
200
+ max_tokens=max_tokens,
201
+ top_p=top_p,
202
+ provider_extras=provider_extras,
203
+ )
204
+ else:
205
+ response = await self._client.complete(
206
+ messages=messages,
207
+ temperature=temperature,
208
+ max_tokens=max_tokens,
209
+ top_p=top_p,
210
+ provider_extras=provider_extras,
211
+ )
212
+ return AgentResult(
213
+ text=response.text,
214
+ messages=tuple(messages),
215
+ final_response=response,
216
+ )
217
+
218
+ async def run_streaming(
219
+ self,
220
+ user_input: str | Sequence[AnyMessage],
221
+ *,
222
+ temperature: float | None = None,
223
+ max_tokens: int | None = None,
224
+ top_p: float | None = None,
225
+ provider_extras: Mapping[ProviderName, Mapping[str, Any]] | None = None,
226
+ ) -> AsyncIterator[LoopEvent]:
227
+ """Stream the agent's tool-use loop as typed events.
228
+
229
+ Builds the message list (system prompt + ``user_input``) like
230
+ :meth:`run`, then delegates to
231
+ :meth:`LLMClient.stream_tool_loop` with the agent's tools and
232
+ ``max_iterations``, yielding each
233
+ :data:`~strata_forge.llm.loop_events.LoopEvent` as it arrives. When the
234
+ agent has NO tools, the loop degenerates to a single streamed turn
235
+ (one ``IterationStart``, its ``TextDelta``s, and a terminal
236
+ ``Done``).
237
+
238
+ This is a true async generator — iterate it directly
239
+ (``async for event in agent.run_streaming(...)``). There is no
240
+ streaming variant of :meth:`run_structured`.
241
+ """
242
+ messages = self._build_messages(user_input)
243
+ async for event in self._client.stream_tool_loop(
244
+ messages,
245
+ tools=self._tools,
246
+ max_iterations=self._max_iterations,
247
+ temperature=temperature,
248
+ max_tokens=max_tokens,
249
+ top_p=top_p,
250
+ provider_extras=provider_extras,
251
+ ):
252
+ yield event
253
+
254
+ async def run_structured(
255
+ self,
256
+ user_input: str | Sequence[AnyMessage],
257
+ *,
258
+ output_schema: type[M],
259
+ temperature: float | None = None,
260
+ max_tokens: int | None = None,
261
+ top_p: float | None = None,
262
+ max_reprompt_attempts: int = 3,
263
+ provider_extras: Mapping[ProviderName, Mapping[str, Any]] | None = None,
264
+ ) -> AgentResult:
265
+ """Run the agent and require a typed output.
266
+
267
+ Calls :meth:`LLMClient.complete_structured` against the
268
+ agent's system prompt + user input. Tools are NOT applied
269
+ in this path — the structured-output dispatch in
270
+ :mod:`strata_forge.llm` already uses forced-tool mode internally
271
+ for providers that need it, and combining application tools
272
+ with that machinery has too many cross-product edge cases
273
+ for the foundation sub-phase. Run :meth:`Agent.run` first
274
+ when the agent needs to call tools before producing a
275
+ structured answer.
276
+
277
+ Args:
278
+ user_input: Same shape as :meth:`run`.
279
+ output_schema: The Pydantic schema the response must
280
+ validate against. The validated instance lives at
281
+ :attr:`AgentResult.parsed`.
282
+ temperature, max_tokens, top_p: Forwarded.
283
+ max_reprompt_attempts: Forwarded to
284
+ :meth:`LLMClient.complete_structured`.
285
+ provider_extras: Forwarded.
286
+
287
+ Returns:
288
+ An :class:`AgentResult` whose ``parsed`` carries the
289
+ validated Pydantic instance.
290
+ """
291
+ messages = self._build_messages(user_input)
292
+ response = await self._client.complete_structured(
293
+ messages=messages,
294
+ schema=output_schema,
295
+ temperature=temperature,
296
+ max_tokens=max_tokens,
297
+ top_p=top_p,
298
+ max_reprompt_attempts=max_reprompt_attempts,
299
+ provider_extras=provider_extras,
300
+ )
301
+ return AgentResult(
302
+ text=response.text,
303
+ messages=tuple(messages),
304
+ final_response=response,
305
+ parsed=response.parsed,
306
+ )
@@ -0,0 +1,33 @@
1
+ """Memory primitives for :class:`strata_forge.agents.Agent`.
2
+
3
+ Two flavours of memory ship:
4
+
5
+ - :class:`ConversationMemory` — in-process append-only message
6
+ history with optional token-budget or message-count trimming.
7
+ Preserves the system message across trims so the agent's
8
+ instructions never get evicted.
9
+ - :class:`EpisodicMemory` — vector-backed long-term memory against a
10
+ pluggable :class:`VectorStore` Protocol. A concrete
11
+ :class:`InMemoryVectorStore` ships here for tests and prototyping;
12
+ :mod:`strata_forge.rag` (Phase 4) will provide a Qdrant-backed
13
+ implementation that satisfies the same Protocol.
14
+ """
15
+
16
+ from strata_forge.agents.memory.conversation import ConversationMemory
17
+ from strata_forge.agents.memory.episodic import EmbedFn, EpisodicMemory
18
+ from strata_forge.agents.memory.vector_store import (
19
+ InMemoryVectorStore,
20
+ VectorItem,
21
+ VectorSearchResult,
22
+ VectorStore,
23
+ )
24
+
25
+ __all__ = [
26
+ "ConversationMemory",
27
+ "EmbedFn",
28
+ "EpisodicMemory",
29
+ "InMemoryVectorStore",
30
+ "VectorItem",
31
+ "VectorSearchResult",
32
+ "VectorStore",
33
+ ]
@@ -0,0 +1,190 @@
1
+ """In-process conversation memory — append-only with optional trimming.
2
+
3
+ A :class:`ConversationMemory` holds the rolling history of an agent's
4
+ interactions: a system message (immutable for the memory's lifetime)
5
+ plus an append-only list of subsequent messages.
6
+
7
+ Two trim modes are supported:
8
+
9
+ - :meth:`trim_to_messages` — keep the last ``N`` non-system messages.
10
+ - :meth:`trim_to_tokens` — drop oldest non-system messages until the
11
+ total token count fits a budget (via :func:`strata_forge.llm.count_tokens`).
12
+
13
+ Both trim modes preserve the system message — the agent's
14
+ instructions don't get evicted under any memory pressure.
15
+ """
16
+
17
+ from __future__ import annotations
18
+
19
+ from typing import TYPE_CHECKING, Any, cast
20
+
21
+ from strata_forge.llm.messages import AssistantMessage, SystemMessage, UserMessage
22
+ from strata_forge.llm.tokens import count_tokens
23
+
24
+ if TYPE_CHECKING:
25
+ from collections.abc import Iterable
26
+
27
+ from strata_forge.llm.messages import AnyMessage
28
+
29
+ __all__ = [
30
+ "ConversationMemory",
31
+ ]
32
+
33
+
34
+ def _message_text(message: AnyMessage) -> str:
35
+ """Extract the text content of a message for token counting.
36
+
37
+ Handles list-of-content-parts (:class:`UserMessage` multimodal)
38
+ and tool-result / assistant variants. Returns an empty string for
39
+ messages whose content isn't textual (e.g. image-only).
40
+ """
41
+ content = getattr(message, "content", None)
42
+ if content is None:
43
+ return ""
44
+ if isinstance(content, str):
45
+ return content
46
+ # UserMessage.content can be a list of parts (text + image).
47
+ parts: list[str] = []
48
+ if isinstance(content, list):
49
+ items = cast("list[Any]", content)
50
+ for part in items:
51
+ if isinstance(part, str):
52
+ parts.append(part)
53
+ else:
54
+ text: Any = getattr(part, "text", None)
55
+ if isinstance(text, str):
56
+ parts.append(text)
57
+ return " ".join(parts)
58
+
59
+
60
+ class ConversationMemory:
61
+ """A rolling conversation history with a fixed system message.
62
+
63
+ Args:
64
+ system_message: Optional system message that opens every
65
+ rendered conversation. When provided, this message is
66
+ never evicted by :meth:`trim_to_messages` or
67
+ :meth:`trim_to_tokens`. Can be a :class:`SystemMessage`
68
+ instance or a plain string (which is wrapped).
69
+ """
70
+
71
+ def __init__(self, *, system_message: SystemMessage | str | None = None) -> None:
72
+ if system_message is None:
73
+ self._system: SystemMessage | None = None
74
+ elif isinstance(system_message, SystemMessage):
75
+ self._system = system_message
76
+ else:
77
+ self._system = SystemMessage(content=system_message)
78
+ self._history: list[AnyMessage] = []
79
+
80
+ @property
81
+ def system_message(self) -> SystemMessage | None:
82
+ return self._system
83
+
84
+ @property
85
+ def messages(self) -> tuple[AnyMessage, ...]:
86
+ """All messages in chronological order — system first when set."""
87
+ if self._system is None:
88
+ return tuple(self._history)
89
+ return (self._system, *self._history)
90
+
91
+ @property
92
+ def non_system_messages(self) -> tuple[AnyMessage, ...]:
93
+ """The history excluding the system message."""
94
+ return tuple(self._history)
95
+
96
+ def append(self, message: AnyMessage) -> None:
97
+ """Append one message to the history.
98
+
99
+ Raises :class:`ValueError` when a :class:`SystemMessage` is
100
+ appended — system messages live in the dedicated slot and
101
+ can't be inserted mid-conversation.
102
+ """
103
+ if isinstance(message, SystemMessage):
104
+ err = (
105
+ "ConversationMemory holds at most one system message — pass it to "
106
+ "the constructor or use replace_system_message()."
107
+ )
108
+ raise ValueError(err)
109
+ self._history.append(message)
110
+
111
+ def extend(self, messages: Iterable[AnyMessage]) -> None:
112
+ """Append several messages."""
113
+ for message in messages:
114
+ self.append(message)
115
+
116
+ def replace_system_message(self, system_message: SystemMessage | str | None) -> None:
117
+ """Replace the system message (or clear it with ``None``)."""
118
+ if system_message is None:
119
+ self._system = None
120
+ elif isinstance(system_message, SystemMessage):
121
+ self._system = system_message
122
+ else:
123
+ self._system = SystemMessage(content=system_message)
124
+
125
+ def clear(self) -> None:
126
+ """Drop every non-system message. The system message survives."""
127
+ self._history.clear()
128
+
129
+ def __len__(self) -> int:
130
+ return len(self.messages)
131
+
132
+ def trim_to_messages(self, max_messages: int) -> None:
133
+ """Keep the last ``max_messages`` non-system messages.
134
+
135
+ The system message (when present) is preserved on top of the
136
+ budget — a memory with a system message and ``max_messages=2``
137
+ renders 3 messages total when read.
138
+
139
+ Raises :class:`ValueError` when ``max_messages`` is negative.
140
+ """
141
+ if max_messages < 0:
142
+ err = f"max_messages must be >= 0; got {max_messages}"
143
+ raise ValueError(err)
144
+ if max_messages == 0:
145
+ self._history.clear()
146
+ elif len(self._history) > max_messages:
147
+ self._history = self._history[-max_messages:]
148
+
149
+ def trim_to_tokens(self, max_tokens: int, *, model: str | None = None) -> None:
150
+ """Drop oldest non-system messages until the total fits ``max_tokens``.
151
+
152
+ Token counts use :func:`strata_forge.llm.count_tokens` against the
153
+ named ``model`` (or the default encoding when ``model`` is
154
+ ``None``). System message tokens count toward the budget but
155
+ the system message itself is never evicted.
156
+
157
+ When ``max_tokens`` is small enough that even the system
158
+ message exceeds the budget, no trimming yields a fit — the
159
+ memory keeps the system message plus an empty history.
160
+
161
+ Raises :class:`ValueError` when ``max_tokens`` is negative.
162
+ """
163
+ if max_tokens < 0:
164
+ err = f"max_tokens must be >= 0; got {max_tokens}"
165
+ raise ValueError(err)
166
+
167
+ def _tokens_for(message: AnyMessage) -> int:
168
+ return count_tokens(_message_text(message), model=model)
169
+
170
+ system_tokens = _tokens_for(self._system) if self._system else 0
171
+ history_tokens = [_tokens_for(m) for m in self._history]
172
+ total = system_tokens + sum(history_tokens)
173
+
174
+ if total <= max_tokens:
175
+ return
176
+
177
+ # Drop from the oldest end of the non-system history until we fit.
178
+ drop = 0
179
+ while drop < len(self._history) and total > max_tokens:
180
+ total -= history_tokens[drop]
181
+ drop += 1
182
+ self._history = self._history[drop:]
183
+
184
+ def append_user(self, content: str) -> None:
185
+ """Convenience: append a :class:`UserMessage` with text ``content``."""
186
+ self._history.append(UserMessage(content=content))
187
+
188
+ def append_assistant(self, content: str) -> None:
189
+ """Convenience: append an :class:`AssistantMessage` with text ``content``."""
190
+ self._history.append(AssistantMessage(content=content))