AgentX-Dev 3.4.3__tar.gz → 3.5.0__tar.gz

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 (74) hide show
  1. {agentx_dev-3.4.3 → agentx_dev-3.5.0}/CHANGELOG.md +851 -808
  2. {agentx_dev-3.4.3 → agentx_dev-3.5.0}/LICENSE +21 -21
  3. {agentx_dev-3.4.3 → agentx_dev-3.5.0}/PKG-INFO +38 -1
  4. {agentx_dev-3.4.3 → agentx_dev-3.5.0}/README.md +37 -0
  5. {agentx_dev-3.4.3 → agentx_dev-3.5.0}/agentx_dev/Agents/Agent.py +10 -2
  6. {agentx_dev-3.4.3 → agentx_dev-3.5.0}/agentx_dev/Compiler.py +308 -308
  7. {agentx_dev-3.4.3 → agentx_dev-3.5.0}/agentx_dev/DefaultTools.py +2120 -2120
  8. {agentx_dev-3.4.3 → agentx_dev-3.5.0}/agentx_dev/Planner.py +271 -271
  9. {agentx_dev-3.4.3 → agentx_dev-3.5.0}/agentx_dev/Runner/AgentRun.py +124 -11
  10. {agentx_dev-3.4.3 → agentx_dev-3.5.0}/agentx_dev/Runner/AsyncAgentRun.py +125 -7
  11. agentx_dev-3.5.0/agentx_dev/Runner/Persistence.py +860 -0
  12. {agentx_dev-3.4.3 → agentx_dev-3.5.0}/agentx_dev/Splitters.py +306 -306
  13. {agentx_dev-3.4.3 → agentx_dev-3.5.0}/agentx_dev/Supervisor.py +622 -104
  14. {agentx_dev-3.4.3 → agentx_dev-3.5.0}/agentx_dev/VectorStores/__init__.py +43 -43
  15. {agentx_dev-3.4.3 → agentx_dev-3.5.0}/agentx_dev/VectorStores/chroma_store.py +171 -171
  16. {agentx_dev-3.4.3 → agentx_dev-3.5.0}/agentx_dev/VectorStores/pg_store.py +237 -237
  17. {agentx_dev-3.4.3 → agentx_dev-3.5.0}/agentx_dev/__init__.py +2 -0
  18. {agentx_dev-3.4.3 → agentx_dev-3.5.0}/agentx_dev.egg-info/PKG-INFO +38 -1
  19. {agentx_dev-3.4.3 → agentx_dev-3.5.0}/agentx_dev.egg-info/SOURCES.txt +1 -0
  20. {agentx_dev-3.4.3 → agentx_dev-3.5.0}/pyproject.toml +79 -79
  21. {agentx_dev-3.4.3 → agentx_dev-3.5.0}/AGENTX.md +0 -0
  22. {agentx_dev-3.4.3 → agentx_dev-3.5.0}/CONTRIBUTING.md +0 -0
  23. {agentx_dev-3.4.3 → agentx_dev-3.5.0}/MANIFEST.in +0 -0
  24. {agentx_dev-3.4.3 → agentx_dev-3.5.0}/agentx_dev/Agents/__init__.py +0 -0
  25. {agentx_dev-3.4.3 → agentx_dev-3.5.0}/agentx_dev/AsyncTools.py +0 -0
  26. {agentx_dev-3.4.3 → agentx_dev-3.5.0}/agentx_dev/AutoSetup.py +0 -0
  27. {agentx_dev-3.4.3 → agentx_dev-3.5.0}/agentx_dev/Cache.py +0 -0
  28. {agentx_dev-3.4.3 → agentx_dev-3.5.0}/agentx_dev/ChatModel.py +0 -0
  29. {agentx_dev-3.4.3 → agentx_dev-3.5.0}/agentx_dev/Config.py +0 -0
  30. {agentx_dev-3.4.3 → agentx_dev-3.5.0}/agentx_dev/Embeddings.py +0 -0
  31. {agentx_dev-3.4.3 → agentx_dev-3.5.0}/agentx_dev/Evals.py +0 -0
  32. {agentx_dev-3.4.3 → agentx_dev-3.5.0}/agentx_dev/Handoffs.py +0 -0
  33. {agentx_dev-3.4.3 → agentx_dev-3.5.0}/agentx_dev/Loader.py +0 -0
  34. {agentx_dev-3.4.3 → agentx_dev-3.5.0}/agentx_dev/MCP.py +0 -0
  35. {agentx_dev-3.4.3 → agentx_dev-3.5.0}/agentx_dev/Media.py +0 -0
  36. {agentx_dev-3.4.3 → agentx_dev-3.5.0}/agentx_dev/Memory.py +0 -0
  37. {agentx_dev-3.4.3 → agentx_dev-3.5.0}/agentx_dev/Observability.py +0 -0
  38. {agentx_dev-3.4.3 → agentx_dev-3.5.0}/agentx_dev/Runner/__init__.py +0 -0
  39. {agentx_dev-3.4.3 → agentx_dev-3.5.0}/agentx_dev/Runner/promptTemplate.yaml +0 -0
  40. {agentx_dev-3.4.3 → agentx_dev-3.5.0}/agentx_dev/Session.py +0 -0
  41. {agentx_dev-3.4.3 → agentx_dev-3.5.0}/agentx_dev/Streaming.py +0 -0
  42. {agentx_dev-3.4.3 → agentx_dev-3.5.0}/agentx_dev/Tools.py +0 -0
  43. {agentx_dev-3.4.3 → agentx_dev-3.5.0}/agentx_dev/VectorStores/qdrant_store.py +0 -0
  44. {agentx_dev-3.4.3 → agentx_dev-3.5.0}/agentx_dev/WebTools.py +0 -0
  45. {agentx_dev-3.4.3 → agentx_dev-3.5.0}/agentx_dev/resources/__init__.py +0 -0
  46. {agentx_dev-3.4.3 → agentx_dev-3.5.0}/agentx_dev/resources/promptTemplate.yaml +0 -0
  47. {agentx_dev-3.4.3 → agentx_dev-3.5.0}/agentx_dev.egg-info/dependency_links.txt +0 -0
  48. {agentx_dev-3.4.3 → agentx_dev-3.5.0}/agentx_dev.egg-info/requires.txt +0 -0
  49. {agentx_dev-3.4.3 → agentx_dev-3.5.0}/agentx_dev.egg-info/top_level.txt +0 -0
  50. {agentx_dev-3.4.3 → agentx_dev-3.5.0}/examples/README.md +0 -0
  51. {agentx_dev-3.4.3 → agentx_dev-3.5.0}/examples/agentic_rag_demo.py +0 -0
  52. {agentx_dev-3.4.3 → agentx_dev-3.5.0}/examples/async_example.py +0 -0
  53. {agentx_dev-3.4.3 → agentx_dev-3.5.0}/examples/async_quickstart.py +0 -0
  54. {agentx_dev-3.4.3 → agentx_dev-3.5.0}/examples/auto_features_example.py +0 -0
  55. {agentx_dev-3.4.3 → agentx_dev-3.5.0}/examples/caching_example.py +0 -0
  56. {agentx_dev-3.4.3 → agentx_dev-3.5.0}/examples/chatbot_example.py +0 -0
  57. {agentx_dev-3.4.3 → agentx_dev-3.5.0}/examples/complete_example.py +0 -0
  58. {agentx_dev-3.4.3 → agentx_dev-3.5.0}/examples/concurrent_example.py +0 -0
  59. {agentx_dev-3.4.3 → agentx_dev-3.5.0}/examples/concurrent_tool_example.py +0 -0
  60. {agentx_dev-3.4.3 → agentx_dev-3.5.0}/examples/file_agent_demo.py +0 -0
  61. {agentx_dev-3.4.3 → agentx_dev-3.5.0}/examples/function_calling_demo.py +0 -0
  62. {agentx_dev-3.4.3 → agentx_dev-3.5.0}/examples/mcp_demo.py +0 -0
  63. {agentx_dev-3.4.3 → agentx_dev-3.5.0}/examples/mcp_github_triage_demo.py +0 -0
  64. {agentx_dev-3.4.3 → agentx_dev-3.5.0}/examples/observability_example.py +0 -0
  65. {agentx_dev-3.4.3 → agentx_dev-3.5.0}/examples/orchestration_demo.py +0 -0
  66. {agentx_dev-3.4.3 → agentx_dev-3.5.0}/examples/planner_example.py +0 -0
  67. {agentx_dev-3.4.3 → agentx_dev-3.5.0}/examples/robust_link_scraper.py +0 -0
  68. {agentx_dev-3.4.3 → agentx_dev-3.5.0}/examples/supervisor_codebase_analysis_demo.py +0 -0
  69. {agentx_dev-3.4.3 → agentx_dev-3.5.0}/examples/supervisor_example.py +0 -0
  70. {agentx_dev-3.4.3 → agentx_dev-3.5.0}/examples/sync_quickstart.py +0 -0
  71. {agentx_dev-3.4.3 → agentx_dev-3.5.0}/examples/v3_1_1_features_demo.py +0 -0
  72. {agentx_dev-3.4.3 → agentx_dev-3.5.0}/examples/v3_1_comprehensive_demo.py +0 -0
  73. {agentx_dev-3.4.3 → agentx_dev-3.5.0}/examples/v3_1_features_demo.py +0 -0
  74. {agentx_dev-3.4.3 → agentx_dev-3.5.0}/setup.cfg +0 -0
@@ -1,808 +1,851 @@
1
- # Changelog
2
-
3
- All notable changes to `agentx-dev` are documented here. Format loosely
4
- follows [Keep a Changelog](https://keepachangelog.com/); versioning is
5
- [Semver](https://semver.org/).
6
-
7
- ## [3.4.3] - 2026-09-26
8
-
9
- Two path-resolution fixes for Windows sandboxes. Non-breaking.
10
-
11
- ### Fixed
12
-
13
- - **`full_access(["/workspace"])` now means the project's workspace
14
- folder, not the drive root.** On Windows a rooted path without a drive
15
- letter resolves to the current drive, so the sandbox became
16
- `C:\workspace`; `auto_create_paths` then created it, and an agent
17
- asked for `workspace/spam.csv` searched an empty directory outside the
18
- project and reported the file missing. Slash-rooted sandbox roots are
19
- now re-rooted at the running project, matching what a leading slash
20
- already meant for tool arguments. POSIX absolute paths (`/workspace`
21
- as a Docker mount) and drive-qualified paths are untouched.
22
- - **`workspace/report.md` no longer nests into
23
- `<workspace>/workspace/report.md`.** The `workspace` field documented
24
- this pass-through, but only the `./workspace/...` spelling had it.
25
- Models name the workspace folder constantly, so the missing case hit
26
- often; new files still resolve into the workspace as before.
27
-
28
- ## [3.4.2] - 2026-09-19
29
-
30
- `media=` everywhere, CSV / text / Excel attachments, and structured output
31
- on models that need the Responses API. Non-breaking.
32
-
33
- ### Added
34
-
35
- - **`media=` on chat models and structured output.** `llm.invoke`,
36
- `llm.ainvoke`, and `with_structured_output(...).invoke` / `.ainvoke` take
37
- `media=[...]` (paths, URLs, `Media`, part dicts), appended to the last
38
- user turn, matching the agent runner. Media inside `content` lists
39
- already worked; this adds the argument.
40
- - **CSV, text files, and Excel in `media=`.** Text-like files (CSV, TSV,
41
- TXT, Markdown, JSON, XML, YAML, HTML) are read as text -- exactly as
42
- written, UTF-8 or Windows-1252, CRLF normalised -- and spreadsheets
43
- (.xlsx / .xls / .ods) are converted with pandas (`dtype=object`, so
44
- cell values aren't re-inferred) to one CSV block per sheet. Both reach
45
- GPT (chat and Responses) and Claude as a labelled text block, which
46
- every model accepts. New `Media.text()` / `Media.spreadsheet()`; a
47
- 100,000-character cap (`max_chars=`, `truncate=True`). pandas and
48
- openpyxl are now core dependencies, so spreadsheets work after a plain
49
- `pip install agentx-dev` (`[excel]` still works). Date cells without a
50
- time are written as dates, not `... 00:00:00`.
51
- - **Media docs section.** Its own nav group: Overview & flow, With chat
52
- models, With agents, Reference (constructors, per-provider wire
53
- formats, errors). `docs/guides/media.md` is now a pointer to it.
54
-
55
- ### Fixed
56
-
57
- - **`with_structured_output` on models that need the Responses API.**
58
- Structured output forces a single tool; if the Responses API rejects a
59
- forced tool choice for the model, `GPT` retries with
60
- `tool_choice="required"` (the same tool when there is only one), then
61
- `"auto"`, remembering it per model. `StructuredOutputRunnable` also
62
- accepts a JSON text answer that validates against the schema.
63
- - **`.txt` media failed on Claude.** 3.4.0 stored text files as base64
64
- documents, which Anthropic only accepts for PDFs. Text files now go
65
- out as text; older base64 text parts in saved histories are decoded
66
- on the way out.
67
- - **Unsupported files reached the provider.** `Media.document()`
68
- accepted any file type -- including CSV, which Windows' own type table
69
- labels `application/vnd.ms-excel` -- and sent it as an attachment
70
- neither provider accepts. Word, PowerPoint and archives now raise
71
- `ValueError` with the fix before any request; a text file or
72
- spreadsheet by URL raises too, since only PDFs can be fetched by URL.
73
- - **Misleading WARNING on recovered calls.** The retry wrapper logged
74
- every non-retryable 400 at WARNING before the caller could recover, so a
75
- call that switched to the Responses API and succeeded still printed the
76
- original "Function tools with reasoning_effort are not supported" text.
77
- Now DEBUG; recoveries log their own WARNING and real failures log ERROR.
78
-
79
- ## [3.4.1] - 2026-09-18
80
-
81
- Tool calls on OpenAI models that require the Responses API.
82
-
83
- ### Fixed
84
-
85
- - **Tool calls failed on models that need the Responses API.** Some
86
- OpenAI models (e.g. `gpt-6-astra`) reject function tools combined with
87
- reasoning on `/v1/chat/completions`, and the error's suggested fix --
88
- `reasoning_effort='none'` -- is itself rejected by those models, so
89
- 3.4.0's parameter adaptation had nowhere to go. `GPT` now switches a
90
- model's tool calls to `/v1/responses` when the provider says to,
91
- retries, and remembers it (WARNING-logged). History is translated only
92
- at the wire (`function_call` / `function_call_output` items paired by
93
- `call_id`), so agents, `tool_calls`, and completions are unchanged.
94
- Learned parameter fixes carry across endpoints (`reasoning.effort` maps
95
- to `reasoning_effort`). Requests are sent with `store=False`, matching
96
- chat completions. Plain text calls and streaming stay on chat
97
- completions.
98
- - Requests chat completions can't express (a document URL) go to the
99
- Responses API, which accepts `file_url`, instead of raising.
100
-
101
- ### Added
102
-
103
- - `GPT(use_responses_api=None | True | False)`: automatic (default),
104
- always, or never.
105
-
106
- ## [3.4.0] - 2026-09-18
107
-
108
- Media input for GPT and Claude, models that adapt to each generation's
109
- parameter support, and workspace-rooted paths. Non-breaking; two
110
- defaults changed -- see docs/guides/upgrading.md.
111
-
112
- ### Added
113
-
114
- - **Media input for GPT and Claude.** New `Media` type
115
- (`Media.image()`, `.document()`, `.audio()`, `.from_path()`,
116
- `.from_url()`, `.from_bytes()`) and a `media=[...]` argument on
117
- `AgentRunner.invoke` / `stream` and `AsyncAgentRunner.ainvoke` /
118
- `astream`. Items can be paths, URLs, `Media`, or content-part dicts
119
- in either provider's native shape; each model renders them in its
120
- own wire format (OpenAI `image_url` / `file` / `input_audio`,
121
- Anthropic `image` / `document`). Unsupported combinations -- audio to
122
- Claude, a document URL to GPT -- raise `ValueError` before any
123
- request. Media is stored as plain JSON dicts, so `completion.history`
124
- and `Session.save()` keep working. Guide: docs/guides/media.md.
125
-
126
- - **Models adapt to per-generation parameter support.** `GPT` and
127
- `Claude` read a parameter-compatibility 400 (which names the
128
- parameter and, for enums, the allowed values), make the smallest
129
- change it asks for, retry, and remember it per model: an unsupported
130
- `reasoning_effort` moves to the nearest supported value, `max_tokens`
131
- becomes `max_completion_tokens` on reasoning models (up front for
132
- known families), parameters a model lacks are dropped, and Claude's
133
- `max_tokens` is clamped to the model's cap. Logged at WARNING; other
134
- 400s raise unchanged. `adapt_params=False` opts out.
135
-
136
- - **`Claude` gains `top_p`, `top_k`, `thinking`, `stop_sequences`.**
137
-
138
- ### Changed
139
-
140
- - `Claude(temperature=)` defaults to `None` (not sent; the API default is
141
- the old 1.0). Always sending it conflicted with `top_p` on newer models
142
- and with extended thinking.
143
- - `GPT(reasoning_effort=)` accepts any string, not just
144
- `none | low | medium | high`, so `minimal` and `xhigh` are expressible.
145
-
146
- ### Fixed
147
-
148
- - **`reasoning_effort="none"` crashed on models that don't take it**
149
- ("Unsupported value: 'reasoning_effort' does not support 'none' with
150
- this model"). The models docs even recommended `"none"` as a fix for
151
- tool-calling conflicts; that advice is gone.
152
- - **Workspace-rooted paths resolved to the drive root.** With a workspace
153
- set, `/bruce.jpeg` became `C:\bruce.jpeg` on Windows (a leading slash
154
- with no drive means the current drive's root) and the sandbox rejected
155
- it. A leading slash now means the workspace root; the re-rooted path
156
- is still sandbox-checked, so traversal is rejected as before.
157
- - **`run_python` ran in the host process's directory, not the
158
- workspace.** It passed no `cwd`, so `open("bruce.jpeg")` looked
159
- wherever the program was launched from. It now starts in the workspace,
160
- matching `run_shell`.
161
- - **Message-list input stringified media into the prompt.** A user turn
162
- whose content was a list (text + image) went through `str()`, so an
163
- attached image reached the model as base64 text. Text and media are
164
- now split, and earlier turns keep their list content.
165
- - **Claude returned the wrong block with extended thinking.** It read
166
- `response.content[0].text`; with thinking the first block is a
167
- `thinking` block. Text blocks are now joined.
168
- - `GPT.Initialize` / `stream_text` / `astream_text` now run messages
169
- through the same OpenAI translator as `call_with_tools`.
170
-
171
- ## [3.3.1] - 2026-09-09
172
-
173
- Correctness fixes in the agent loop, found by driving it with a
174
- scripted model rather than reading it. No API changes; every fix
175
- replaces a silent wrong answer or a runaway cost with correct
176
- behaviour. Nine regression tests ship with them
177
- (`tests/test_agent_loop_flaws.py`).
178
-
179
- ### Fixed
180
-
181
- - **Native binding had no loop-level spiral guard.** The repeat breaker
182
- sat after the native branch's `continue`, so `bind_tools_natively`
183
- runs never reached it: a model stuck re-issuing one call burned the
184
- full `max_iterations` (20 LLM turns where text mode stopped at 3) and
185
- returned the "hit max_iterations" recap quoting the dup-guard's own
186
- warning text instead of the data.
187
-
188
- - **`respond` batched with real tool calls dropped them.** A model that
189
- emitted "do X, and here is my answer" in one turn had X silently
190
- discarded -- never dispatched, never in `completion.tool_calls`, no
191
- error. The batch now runs and the answer defers one turn.
192
-
193
- - **`completion.history` could not be replayed as `chat_history`.** The
194
- copy filter kept only truthy `{role, content}`, which dropped every
195
- tool-calling assistant turn (`content=""`), stripped `tool_call_id`
196
- off `role="tool"` messages, and replayed a stored system prompt on top
197
- of the fresh one -- so a follow-up call sent two system messages, zero
198
- assistant turns, and an orphaned tool message providers reject. Fixed
199
- in both runners.
200
-
201
- - **A sync `AgentRunner` silently ignored async tools.** `known_tools`
202
- unioned only the two sync registry tables while the registry accepted,
203
- listed and prompt-advertised async ones, so calling one fell through
204
- to implicit-final and returned `action_input` as the answer with an
205
- empty `tool_calls` list. Now unions all four, matching the async
206
- runner; the sync dispatcher already returns a clear `ToolError`, so
207
- the silent wrong answer became an actionable one.
208
-
209
- - **`AsyncAgentRunner` regressed the function-calling message shape.**
210
- It appended its FC turn as raw JSON text with no `tool_calls` block
211
- and never set `_last_function_call_id`, so observations went back as
212
- `role="user"` -- text-mode shape while in FC mode, losing provider
213
- correlation and the cached prefix.
214
-
215
- - **A `BaseException` from a specialist orphaned its siblings.**
216
- `CancelledError` and `KeyboardInterrupt` are not `Exception`, so
217
- `_run_subtask`'s handler never saw them; `t.result()` re-raised and
218
- left sibling tasks running unowned, with in-flight LLM calls still
219
- billing. The scheduler now owns its tasks in a `try`/`finally`, which
220
- also covers a consumer that stops iterating `astream` early.
221
-
222
- - **The tool cache collided on tool name.** It is a process-wide
223
- singleton keyed on `(tool_name, args)` with no record of which
224
- implementation ran, so two runners whose tools merely share a name --
225
- `search`, `fetch`, `query`, routine across Supervisor specialists --
226
- served each other's results and the second function never ran. Keys
227
- now fold in the callable's `module.qualname`, so same-name /
228
- different-implementation misses while genuinely identical tools still
229
- share, including across processes for the disk-backed `FileCache`.
230
-
231
- ### Docs
232
-
233
- - Streaming documentation described parameters the API rejects.
234
- `AsyncAgentRunner.astream()` and `HandoffCoordinator.stream()` take no
235
- `stream_tokens` (only the sync `AgentRunner.stream()` does), and every
236
- `text_delta` example was built on a default model where
237
- `use_function_calling` auto-detects to `True` and yields zero deltas.
238
- `simple_stream` was documented with the wrong signature entirely.
239
- Added a table naming exactly which stream methods accept what.
240
-
241
- ### Tests
242
-
243
- - Repaired 20 stale text-mode tests. `MockModel` defined
244
- `call_with_tools` unconditionally, so 3.1.7's auto-detect routed every
245
- text script down the function-calling path and the runner returned
246
- `""`. The mock now advertises the capability only when scripted for
247
- it. Suite: 206 passed, 3 skipped.
248
-
249
- ## [3.3.0] - 2026-08-19
250
-
251
- Dependency DAGs for the Supervisor. Plans declare which steps consume
252
- which, and the executor derives ordering, parallelism, AND context
253
- routing from those edges — unifying the old split where sequential
254
- mode had threading but no parallelism and concurrent mode had
255
- parallelism but no threading. Design: docs/design/3.3-depends-on-dag.md.
256
-
257
- ### Added
258
-
259
- - **`depends_on` plan steps.** Every plan step now carries an `id`;
260
- a step that consumes an earlier step's output lists that id in
261
- `depends_on`. Sync `Supervisor` executes in stable topological
262
- order; `AsyncSupervisor` runs a completion-driven scheduler where a
263
- step starts the MOMENT its dependencies finish (not on wave
264
- barriers) and independent steps run concurrently. In DAG mode each
265
- step is threaded ONLY its direct dependencies' results — explicit
266
- routing instead of "everything prior", which also stops the
267
- per-entry context budget shrinking as plans grow.
268
-
269
- - **Plan sanitization that never fails a run.** Missing/duplicate ids
270
- auto-assigned, unknown dependencies dropped (a planner typo degrades
271
- to a root step, not a dead run), self-deps dropped, cycles broken
272
- deterministically (back-edge in plan order), spawn steps cannot be
273
- depended on. If repairs were needed, the plan is re-requested once
274
- (`max_plan_retries`, default 1) with the repair warnings appended;
275
- the sanitized original is kept when the retry is no better.
276
-
277
- - **Failure cascade + `skipped` flag.** A step whose dependency failed
278
- (after retries / success-check) is skipped, transitively, with
279
- `SubtaskResult.skipped=True` and an error naming the failed dep.
280
- Independent branches keep running; synthesis runs over what
281
- succeeded. Skipped steps never dispatch — no tokens burned
282
- downstream of garbage.
283
-
284
- - **`skip_when` conditional execution.** A step may declare
285
- `{"step": <direct dep id>, "field": <typed output field>, "is": <value>}`;
286
- evaluated in Python (no LLM call) against the dependency's 3.2
287
- structured output, dotted paths supported, strictly FAIL-OPEN (any
288
- doubt → the step runs). Condition-skips do NOT cascade — dependents
289
- treat them as empty successes ("retrieval unnecessary" is not
290
- "answering impossible").
291
-
292
- - **`Specialist` registry entries.** `agents={}` now also accepts
293
- `Specialist(description, runner, depends_on=[...names...],
294
- output_schema=..., when_to_use=...)`. The extras render into the
295
- planning catalog (`typically after:` / `returns: Schema(fields)` /
296
- `use when:`) so the planner can write real dependency graphs and
297
- `skip_when` conditions against actual field names. `depends_on`
298
- here is a planner HINT, never an execution constraint (the same
299
- specialist can appear twice in one plan; step-ids disambiguate).
300
- Classic `(description, runner)` tuples keep working — they are
301
- wrapped internally, and `Specialist` tuple-unpacks for older code.
302
-
303
- - **`AsyncSupervisor(max_parallel=N)`.** Caps concurrent sub-tasks for
304
- rate-limited deployments. `sequential=True` is now sugar for
305
- `max_parallel=1` with all-prior threading.
306
-
307
- - **`SubtaskResult.step_id` / `.depends_on` / `.skipped`** and a
308
- `step_id` field on `dispatch` / `subtask_result` stream events.
309
-
310
- ### Backward compatibility
311
-
312
- A plan where NO step declares `depends_on` runs with byte-identical
313
- legacy semantics: sync + async-sequential thread all prior results in
314
- plan order; async-concurrent runs everything at once with no
315
- threading. Verified by regression tests against the 3.2 behaviour.
316
-
317
- ## [3.2.0] - 2026-08-13
318
-
319
- Typed multi-agent pipelines. Specialists can now declare a Pydantic
320
- output schema once and pass validated instances to each other through
321
- the Supervisor, instead of downstream agents re-parsing prose.
322
-
323
- ### Added
324
-
325
- - **`output_schema` on the `AgentRunner` / `AsyncAgentRunner`
326
- constructor.** Declare the runner's output shape once
327
- (`AgentRunner(..., output_schema=QueryIntent)`) instead of passing it
328
- on every call or describing JSON in the prompt. A per-call
329
- `output_schema=` still wins when both are set. `None` keeps the exact
330
- pre-3.2 behaviour: no coercion, `completion.output` stays `None`.
331
-
332
- - **Schema coercion via forced native function calling.** When a schema
333
- is in play, the final answer is converted by forcing a provider-native
334
- tool call against the schema (constrained decoding), not by regexing
335
- JSON out of prose. The ReAct loop itself is untouched: tool selection
336
- and intermediate reasoning run exactly as before, and the coercion
337
- happens once, after the loop finishes. Models without a
338
- `call_with_tools` implementation fall back to the previous text-JSON
339
- parsing, so custom `BaseChatModel` subclasses keep working.
340
- `completion.content` keeps the human-readable answer alongside
341
- `completion.output` in every case.
342
-
343
- - **`SubtaskResult.output`.** The Supervisor now preserves each
344
- specialist's validated Pydantic instance next to its `content` text.
345
- Consumers that only read `content` are unaffected.
346
-
347
- - **Structured specialist-to-specialist handoff.** When an earlier step
348
- produced typed output, `_build_augmented_query` serializes it into the
349
- next specialist's context as a labelled JSON block
350
- (`STRUCTURED OUTPUT (QueryIntent): {...}`) followed by the summary
351
- text, so downstream steps parse fields rather than interpreting
352
- sentences like `INTENT: ... SEARCH_QUERY: ...`.
353
-
354
- - **`vector_search_tool` pipeline options.** New kwargs:
355
- `max_text_chars` (default 500; pass `0` for full untruncated passages,
356
- which a reranker judging evidence actually needs) and
357
- `structured_output` (default False; when True the tool returns a JSON
358
- array of `{id, text, vector_score, metadata}` instead of the
359
- human-formatted list). Defaults preserve existing behaviour byte-for-
360
- byte.
361
-
362
- ### Fixed
363
-
364
- - **Supervisor planning prompt contradicted the execution engine.** The
365
- planner rule said sub-agents "do NOT see previous steps' output" and
366
- discouraged dependency chains, but the dispatcher has threaded prior
367
- findings into every step since `_build_augmented_query` shipped.
368
- The rule now tells the planner that sequential steps receive earlier
369
- results (structured when available) and that chains like
370
- intent -> retrieval -> reranking are a good plan shape, while still
371
- requiring same-specialist steps to merge and banning report-only steps.
372
-
373
- ## [3.1.7] — 2026-07-27
374
-
375
- ### Changed
376
-
377
- - **`use_function_calling` default flipped to auto-detect** on
378
- `AgentRunner` / `AsyncAgentRunner`. The parameter's default type is
379
- now `Optional[bool] = None`; `None` resolves to `True` when the
380
- model class overrides `BaseChatModel.call_with_tools` (both `GPT`
381
- and `Claude` do) and to `False` when it doesn't (or when
382
- `bind_tools_natively=True`). Callers passing `True`/`False`
383
- explicitly are unaffected. Rationale: text-mode ReAct requires the
384
- model to emit strict JSON with any long `action_input` string
385
- properly escaped — a 1200-word markdown draft with unescaped
386
- newlines or quotes reliably breaks `json.loads` and killed the run.
387
- Function-calling mode routes the parser through the SDK's typed
388
- channel so escaping is handled automatically. The historical
389
- default (`False`) was the fragile option; the new default matches
390
- what most users actually want.
391
-
392
- ### Fixed
393
-
394
- - **Malformed parser JSON no longer crashes the run.** When the
395
- text-mode assistant response failed `json.loads` (typically because
396
- a long `action_input` string had unescaped `"`, `\n`, or backticks),
397
- the framework used to raise `JSONDecodeError` and unwind the whole
398
- invocation. The runner now (1) tries a regex-based salvage that
399
- extracts `{Thought, action, action_input}` from the raw text
400
- covering the common "outer envelope valid, inner string broke
401
- escaping" failure, and (2) if salvage fails, feeds a targeted fix
402
- hint back to the model (`"your last response was not valid JSON;
403
- emit …, escape newlines as \n"`) and continues the loop bounded
404
- by `max_iterations`. Exhaustion returns a clear framework message
405
- rather than an uncaught exception. Applied to both sync and async
406
- runners via a shared `_salvage_react_json` helper.
407
- The salvager's action-name regex is intentionally strict
408
- (`[A-Za-z_][A-Za-z0-9_.\- ]{0,79}`) so it can't hallucinate an
409
- "action" out of an unrelated `"key":"value"` pair inside malformed
410
- JSON.
411
-
412
- - **Verbose trace in `bind_tools_natively` mode now prints tool
413
- name + args + response.** Previously native runs showed blank
414
- `[tool.call.start]` / `[tool.call.complete]` pairs (the
415
- observability layer fires them without the trace context), so you
416
- couldn't tell which tool the model actually invoked or what came
417
- back. The runner now prints `[tool] Invoking '<name>' with args:
418
- <input>` and `[tool] Response: <preview>` (or `[tool] Error: ...`
419
- when the dispatch raised) in the post-dispatch loop, matching the
420
- format text-mode and function-calling mode use. Mirrored to the
421
- async runner.
422
-
423
- - **`web_fetch_tool(vector_store=...)` auto-ingests fetched pages into
424
- a vector store** instead of dumping raw HTML into the model's
425
- context. Fixes the TPM-limit trap: when a research agent fetches
426
- four articles in parallel (via ``multi_tool_use.parallel`` or
427
- native binding), the combined bodies can easily exceed 40k tokens
428
- and blow past a 30k TPM ceiling on the very next model call.
429
- New parameters on ``web_fetch_tool``:
430
-
431
- | Kwarg | Default | Effect |
432
- |---|---|---|
433
- | ``vector_store`` | ``None`` | When set, each fetch is HTML-stripped, chunked with ``TextSplitter``, embedded via the store's embeddings, and added with ``{src: url, chunk_index, total_chunks}`` metadata. The tool response becomes a compact summary (URL, byte count, chunk count, 240-char preview) — NOT the raw body. The model then calls ``vector_search`` / ``Rag`` to pull only the passages it needs. |
434
- | ``chunk_size`` | ``1500`` | Characters per chunk when ``vector_store`` is set. Ignored otherwise. |
435
- | ``chunk_overlap`` | ``200`` | Overlap between adjacent chunks so a fact spanning a boundary is still retrievable. Ignored otherwise. |
436
-
437
- Backwards-compatible: the positional ``cache_dir`` signature keeps
438
- working; `web_fetch_tool()` with no ``vector_store`` returns raw
439
- body as before. Ingest and cache_dir compose — enable both and get
440
- disk-cached full bodies AND searchable chunks. HTML stripping is
441
- minimal and dependency-free (regex-based: script/style blocks
442
- dropped whole, then tags stripped, whitespace collapsed) so the
443
- ingest path adds no new install dependency. On JSON/plain-text
444
- responses the stripper is a near no-op.
445
-
446
- The observation returned to the model shows topical coverage --
447
- first, middle, and last chunk previews (up to 3 samples,
448
- deduplicated for short pages) -- so the model can tell what
449
- topics the page actually covers, not just the intro paragraph.
450
- Without this the model would only see the page's opening and
451
- wouldn't know to query for topics discussed later in the same
452
- page. Explicit instruction in the observation ("query with
453
- SPECIFIC keywords from the topics above; do NOT re-fetch; do
454
- NOT ask for the full body") steers the model toward the RAG path
455
- on follow-up turns.
456
-
457
- - **`multi_tool_use.parallel` now reaches its dispatch path.**
458
- When GPT wanted to batch several tool calls into one turn (fetch N
459
- URLs concurrently, run M searches at once), it emitted OpenAI's
460
- synthetic `multi_tool_use.parallel` meta-tool. The registry's
461
- `_dispatch_multi_parallel` / `_adispatch_multi_parallel` handlers
462
- already knew how to unpack it, but the runner loop's known-tools
463
- guardrail rejected the name FIRST as unregistered — dumping the
464
- raw `{"tool_uses": [...]}` payload into the user-facing "final
465
- answer" and never invoking any of the nested calls. Added
466
- `multi_tool_use.parallel` to the recognized action set in both
467
- sync and async runners so the meta-tool flows through to dispatch
468
- and the existing unpackers run. Nested calls with the `functions.`
469
- prefix are normalized before dispatch (same as top-level FC
470
- calls), so the model can emit either shape.
471
-
472
- - **`Permissions.full_access` / `read_only` auto-wrap a bare string.**
473
- Passing `full_access("./workspace")` used to iterate the string
474
- into 11 single-character "subtrees" (Python's `list("./workspace")`)
475
- — every path check silently rejected because no real path could
476
- ever match a `"."` or `"/"` "allowed subtree". The classmethod
477
- now detects a bare string and treats it as `[allowed_paths]`, so
478
- `full_access("./workspace")` does the intuitive thing (equivalent
479
- to `full_access(["./workspace"])` and auto-infers the workspace).
480
- Same fix on `read_only`. List inputs are unchanged.
481
-
482
- - **`Permissions.full_access` now accepts (and auto-infers)
483
- `workspace`.** The classmethod set `allowed_paths` but not
484
- `workspace`, so short paths like `write_file(path="report.md")`
485
- resolved to CWD (outside the sandbox) and raised
486
- `PermissionError: access denied` — a landmine that every caller of
487
- `Permissions.full_access(["./workspace"])` hit sooner or later.
488
- New signature: `full_access(allowed_paths, *, workspace=None)`.
489
- When `workspace` isn't passed AND `allowed_paths` has exactly one
490
- entry, that path is auto-set as the workspace (the "project-scoped
491
- agent whose one allowed subtree IS its workspace" case, which is
492
- 99% of use). Two or more paths stay ambiguous and require an
493
- explicit `workspace=` if short-path resolution is wanted. Pass an
494
- explicit `workspace=` string to override the auto-choice.
495
- Backwards-compatible on the positional signature; adds a keyword
496
- argument that existing callers didn't use.
497
-
498
- ## [3.1.5] — 2026-07-26
499
-
500
- ### Fixed
501
-
502
- - **Text-mode tool results no longer use `role: "function"`.** In text
503
- mode (the default — no `use_function_calling`) the runner fed each tool
504
- observation back to the model as a `role: "function"` message. Newer
505
- OpenAI models reject that role outright (`400 … 'messages[N].role' does
506
- not support 'function' with this model`, e.g. gpt-5.x), and Anthropic
507
- never accepted it — text-mode multi-tool runs on Claude were latently
508
- broken too; older GPT models simply still tolerated the legacy role.
509
- Tool observations now go back as a plain `role: "user"` turn framed as
510
- `Observation: …`, which every provider and model generation accepts and
511
- which matches the ReAct template's own few-shot convention.
512
- Function-calling mode is unchanged (native `role: "tool"` +
513
- `tool_call_id`). The async runner was additionally emitting `function`
514
- unconditionally (even in FC mode); it now uses the same shared helper.
515
-
516
- ### Added
517
-
518
- - **`subtask_success_check` on `Supervisor` / `AsyncSupervisor`.** Opt-in
519
- predicate `(SubtaskResult) -> bool | str` that decides whether a
520
- *returned* (non-raised) sub-task result is actually acceptable — the
521
- "ran fine but produced nothing useful" case a plain retry can't catch
522
- (a scraper that saved 0 links, an extractor that found nothing). Return
523
- `True` to accept, or `False`/a `str` reason to reject; a rejected
524
- result is retried like a raised error, with the reason fed back into the
525
- query, bounded by `max_subtask_retries`. After retries are exhausted the
526
- last result is returned with its `error` set (content preserved). A
527
- check that itself raises is treated as "accept" so a buggy predicate
528
- can't wedge the run. Default `None` keeps the exceptions-only behavior.
529
- New example `examples/robust_link_scraper.py` wires it together with a
530
- scraping `system_addendum` (parse relative+absolute hrefs, fall back to
531
- `sitemap.xml` on JS-rendered sites).
532
-
533
- ## [3.1.4] — 2026-07-26
534
-
535
- ### Fixed
536
-
537
- - **A malformed-JSON tool argument no longer crashes the whole agent
538
- run.** When a model emitted a Python snippet or a Windows path as a
539
- tool-call argument — `re.findall(r'\d+')`, `C:\Users` — the `\d` / `\U`
540
- are illegal JSON escapes, and the OpenAI adapter's eager
541
- `json.loads(call.function.arguments)` raised `JSONDecodeError` and
542
- `raise`d it, unwinding the entire ReAct loop before the agent's own
543
- retry machinery could act. Under a Supervisor this surfaced as a bare
544
- `ERROR: Invalid \escape: line 1 column 598` and the sub-task was
545
- abandoned. Now:
546
- - `_parse_tool_arguments` repairs the common case (backslashes that
547
- don't begin a valid JSON escape are doubled), recovering `\d`,
548
- `\w`, `\s`, etc. with zero extra round-trips. A backslash before a
549
- valid-escape letter (`\b`, `\n`, …) remains ambiguous and is left
550
- as the escape — a documented limit.
551
- - When repair fails, `call_with_tools` returns a dedicated
552
- `invalid_tool_args` result and the loop feeds the error back as a
553
- retryable observation ("your arguments weren't valid JSON — escape
554
- backslashes and resend"), bounded by `max_iterations`, in all
555
- three modes across both `AgentRunner` and `AsyncAgentRunner`.
556
- `Claude` was already immune (its tool inputs arrive pre-parsed).
557
-
558
- - **A tool-call preamble is no longer returned as the final answer.**
559
- Models routinely end a turn with an announcement instead of an action
560
- — "I'll look up your recent scores to get a clear view of your
561
- communication skills. Just a second!" — and every "no tool call
562
- found" branch in both runners was coded as *this text is the answer,
563
- break*. The loop terminated on iteration 1 and the caller got a
564
- promise instead of a result. Three sites per runner were affected:
565
- the native-binding path (`type != "tool_use"`), the
566
- `use_function_calling` path (parser unresolved), and the JSON-text
567
- path (response didn't parse). `max_iterations` never helped, because
568
- the break happened before any iteration was spent.
569
-
570
- The runner now feeds the model one corrective nudge — "your last turn
571
- had no action, so nothing happened; do it, don't announce it" — and
572
- continues the loop. Verified against both `AgentRunner` and
573
- `AsyncAgentRunner` in all three modes.
574
-
575
- ### Added
576
-
577
- - **Proactive "act, don't announce" system-prompt clause.** The reactive
578
- `text_turn_nudges` fix corrects an agent *after* it narrates instead of
579
- acting; this clause heads it off. When (and only when) an agent has
580
- tools, its system prompt now tells it to call the tool rather than
581
- reply "I'll do X / just a second" and stop — and to report what it DID
582
- in past tense. Injected in all three modes across both runners; skipped
583
- for tool-less chat agents, where prose is the correct answer. Sits
584
- before any `system_addendum` so a caller's role instructions still win.
585
-
586
- - **`max_subtask_retries` on `Supervisor` / `AsyncSupervisor`** (default
587
- `1`). A sub-task that raised used to be recorded as an error and the
588
- Supervisor moved straight to synthesis — no second attempt. Now a
589
- failed sub-task is re-dispatched up to this many times, with the prior
590
- error appended to the query so the specialist knows what to fix
591
- ("your previous attempt failed with X — diagnose and try again").
592
- Bounded and informed: only raised exceptions trigger a retry (a
593
- sub-task that returns content is accepted as-is, since the Supervisor
594
- can't tell "terse but correct" from "wrong"), and the error text is
595
- fed back rather than blindly re-running. Set to `0` for the old
596
- quit-on-first-failure behavior. Applies in both sequential and
597
- concurrent async modes.
598
-
599
- - **`text_turn_nudges` on `AgentRunner` / `AsyncAgentRunner`** (default
600
- `1`). Caps the re-prompts described above at one extra LLM call per
601
- run; after the budget is spent the model's text stands as the answer.
602
- Set to `0` for the previous behavior. Automatically skipped when no
603
- tools are registered, since a runner with no tools is a plain chat
604
- call and prose genuinely is the answer there.
605
-
606
- ## [3.1.3] — 2026-07-22
607
-
608
- Docs-only patch. No code changes since 3.1.2. Users on 3.1.2 don't
609
- need to upgrade for functionality; upgrade to pick up the improved
610
- onboarding docs bundled in the sdist.
611
-
612
- ### Documentation
613
-
614
- - **Tools doc rewritten to answer "how do I actually use these?"**
615
- Added §0 `How each built-in tool is registered` as the entry
616
- section. Two registration paths — auto vs manual — laid out in a
617
- table on the first screen. Six runnable subsections covering every
618
- combination:
619
- - §0.1 DefaultTools via `Permissions(...)` (auto)
620
- - §0.2 WebTools via `tools=[web_search_tool(), web_fetch_tool()]`
621
- - §0.3 RAG via `TextSplitter` -> `VectorStore.add_documents` ->
622
- `vector_search_tool(store)`
623
- - §0.4 Handoffs via `handoff_tool` + `HandoffCoordinator`
624
- - §0.5 Custom `StructuredTool` from scratch
625
- - §0.6 Fully-loaded runner combining all of the above
626
- - §0.7 Rules on name collisions, invisible-denied-capabilities,
627
- async-tool behavior
628
- The existing inventory + wrapper / controls / cheat-sheet sections
629
- are unchanged; they now sit after the "how to use them" primer
630
- instead of before it.
631
-
632
- ## [3.1.2] — 2026-07-22
633
-
634
- Patch release. Two independent fixes.
635
-
636
- ### Fixed
637
-
638
- - **`llm_judge` correctly parses YES/NO across providers.** The judge
639
- parser was comparing the reply's first word to the literal string
640
- `"YES"`. GPT-4o answers `"YES,"` (comma-suffixed), which failed the
641
- equality check and marked every genuine PASS as FAIL. Claude replies
642
- `"YES"` without punctuation so the bug hid during local development.
643
- Fixed by matching `\b(YES|NO)\b` (word-boundary regex, case-
644
- insensitive) at the start of the reply. Handles every real shape:
645
- `YES`, `YES.`, `YES!`, `YES, exactly right`, `Yes.`, `yes -- reason`.
646
- Ambiguous replies (`Maybe`, empty string) still fail closed.
647
- - Regression test `test_llm_judge_parses_various_verdict_shapes`
648
- covers 8 YES shapes, 5 NO shapes, and 4 ambiguous replies.
649
-
650
- ### Added
651
-
652
- - **`agentx_dev.Tools` is a one-stop tools namespace.** Users no
653
- longer need to remember which module each tool lives in:
654
-
655
- ```python
656
- from agentx_dev.Tools import (
657
- StandardTool, StructuredTool,
658
- AsyncStandardTool, AsyncStructuredTool,
659
- web_search_tool, web_fetch_tool,
660
- vector_search_tool, handoff_tool,
661
- DefaultTools, Permissions,
662
- )
663
- ```
664
-
665
- Both this form and the pre-existing `from agentx_dev import X`
666
- form coexist. Implementation uses PEP 562 module `__getattr__`
667
- and `__dir__` so re-exports are lazy (no import cost for modules
668
- the caller doesn't touch) and show up in IDE autocomplete +
669
- `dir(agentx_dev.Tools)`.
670
-
671
- ## [3.1.1] — 2026-07-21
672
-
673
- Second batch of 3.1 features + a full docs + brand pass.
674
-
675
- ### Added
676
-
677
- **Streaming through orchestration**
678
- - `Supervisor.stream()` / `AsyncSupervisor.astream()` emit
679
- `plan_start` / `plan` / `dispatch` / `subtask_result` /
680
- `synthesize_start` / `final` / `completion` events.
681
- - `HandoffCoordinator.stream()` / `.astream()` emit `invoke` /
682
- `completion` / `handoff` / `final` / `result` events per hop.
683
- - Legacy `.run()` / `.arun()` refactored to consume the streams (no
684
- code duplication).
685
-
686
- **Prompt optimization — `Compiled`**
687
- - New `agentx_dev.Compiler` module.
688
- - `Compiled(runner_factory, trainset, ...)` iteratively refines a
689
- runner's `system_addendum` against the eval harness. Half of
690
- DSPy's power at a tenth of the surface.
691
-
692
- **Anthropic Batch API**
693
- - `Claude.batch(requests)` submits many prompts at Anthropic's 50%-off
694
- batch rate, polls to completion, returns results in submission order.
695
- - Per-request error dicts on failure; token usage funneled into
696
- `TokenUsage` so cost tracking stays a single source of truth.
697
-
698
- **Vector store adapters — `agentx_dev.VectorStores`**
699
- - `ChromaVectorStore`, `QdrantVectorStore`, `PgVectorStore` — same
700
- public shape as the in-memory `VectorStore` (`add` / `search` /
701
- `delete` / `clear` / `__len__` / `embeddings`).
702
- - `vector_search_tool()` and `SemanticMemory` accept any of them.
703
- - SDK imports lazy; friendly `ImportError` when the underlying SDK
704
- is missing.
705
-
706
- **Trace viewer (`viewer/`)**
707
- - Self-hosted single-page app that reads `FileHook` JSONL and renders
708
- a timeline with type/text filters, summary sidebar, JSON drill-down.
709
- - Works from `file://`, no server required.
710
-
711
- **Docs site (`host/`)**
712
- - Full editorial dark-first design system (JetBrains Mono headings,
713
- Inter body, `#B8FF3E` electric-lime accent).
714
- - Command palette (`Cmd+K`) with keyboard navigation and live search.
715
- - Hero code snippet with hand-tinted syntax highlighting.
716
- - Reading progress bar, breadcrumbs, header anchor links.
717
- - Sidebar sliding active marker, collapsible groups.
718
- - Code copy buttons, language labels.
719
- - Right-rail auto-TOC with `IntersectionObserver` scrollspy.
720
- - Dark/light theme toggle, persisted.
721
- - Cache-busted assets so edits land on refresh without hard-reload.
722
-
723
- **Brand identity (`brand/`)**
724
- - Full brand kit: 5 SVG assets (`mark`, `mono`, `wordmark`, `logo-full`,
725
- `app-icon`), `BRAND.md` strategy doc, rendered brand-kit HTML deck.
726
- - Copy audit dropped "small" (weak) and "LangChain" references from
727
- all marketing surfaces.
728
- - Favicon wired into docs + trace viewer.
729
-
730
- **Test suite (`tests/`)**
731
- - Restored + expanded pytest suite: 127 tests passing (3 skipped for
732
- absent optional SDKs).
733
- - Coverage: parser + all `AgentType` variants, `ToolRegistry`
734
- (dispatch / dup-guard / circuit-breaker / timeout), Permissions
735
- (capability gating + sandbox + traversal), budgets (cost / rate /
736
- retry / non-retryable HTTP), runner loop (streaming + output_schema
737
- + chat history), embeddings + `VectorStore` + `SemanticMemory`,
738
- handoffs (bounded hops + history sanitization), evals harness
739
- (all assertion helpers + JSON case loaders), vector-store adapter
740
- shape conformance.
741
-
742
- **Docs (`docs/`)**
743
- - Full docs tree (34 pages), including new pages for:
744
- vector store adapters, prompt optimization, batch API, trace viewer,
745
- and a **use-cases** landing (13 concrete scenarios with runnable code).
746
- - Rewrote **Tools** page to enumerate every built-in tool with args,
747
- return shape, capability flag, and use-case guidance.
748
- - Rewrote **Agents** page to cover all four orchestration
749
- architectures (Solo / Supervisor / Handoffs / Compiled) with
750
- decision trees, worked examples, and cheat sheet.
751
- - **Agentic RAG chatbot** as use case §13 — multi-query decomposition,
752
- parallel retrieval, self-critique, citations, user memory.
753
-
754
- **Examples**
755
- - `examples/agentic_rag_demo.py` — the runnable version of the
756
- agentic RAG use case. Auto-seeds a KB if none exists, `--demo` flag
757
- runs a 3-turn scripted session proving user-notes recall works.
758
-
759
- **Package**
760
- - `[chroma]`, `[qdrant]`, `[pgvector]`, `[dev]` extras added.
761
- - `[anthropic]` bumped to `>=0.36` (Batch API + prompt cache).
762
-
763
- ### Fixed
764
-
765
- - `AgentRunner._iter_run` in `bind_tools_natively=True` mode uses a
766
- minimal system prompt instead of the AgentType template so the
767
- ReAct `action/action_input` scaffold no longer fights the native
768
- tool interface. Previously produced JSON-blob answers under GPT.
769
- - `HandoffCoordinator._sanitize_history_for_next_agent` strips tool
770
- and function role messages between hops so tool_call_ids from a
771
- previous agent don't leak into the next model's call (OpenAI 400).
772
- - Docs site marker positioning uses double-`requestAnimationFrame` +
773
- `document.fonts.ready` so the sidebar accent bar lands on the
774
- correct row even on a cold font cache.
775
- - Primary hero CTA color uses `#doc .hero-cta a.primary` selector to
776
- outrank `#doc a` link styling (previously rendered lime-on-lime
777
- and was invisible).
778
-
779
- ### Notes
780
-
781
- - Package version bumped from `3.0.6` to `3.1.1`. The 3.1.0 release
782
- did not ship publicly — 3.1.1 is the first 3.1-tagged PyPI release
783
- and includes both batches of features.
784
-
785
- ## [3.1.0] — internal only (commits 52840e7)
786
-
787
- First batch of 3.1 features. Committed but not released to PyPI.
788
- Merged into 3.1.1 for the public release.
789
-
790
- ### Added
791
- - Anthropic prompt caching (`Claude(enable_prompt_cache=True)`).
792
- - Parallel per-turn tool dispatch in `AgentRunner`
793
- (`bind_tools_natively=True`, `parallel_tool_workers`).
794
- - Semantic memory (`SemanticMemory`, embeddings-backed retrieval).
795
- - RAG core (`Embeddings`, `HashEmbeddings`, `OpenAIEmbeddings`,
796
- `VectorStore`, `VectorHit`, `vector_search_tool()`).
797
- - Agent-to-agent handoffs (`HandoffRequest`, `handoff_tool`,
798
- `HandoffCoordinator`, `HandoffResult`).
799
- - Evals harness (`EvalCase`, `EvalRunner`, `EvalReport`, 7 assertion
800
- helpers, JSON case loader, `python -m agentx_dev.Evals run` CLI).
801
- - `TokenUsage.cache_hit_ratio` property.
802
-
803
- ## [3.0.6] — 2026-03 (baseline)
804
-
805
- Security hardening baseline (SSRF guard on `web_fetch`, HMAC-signed
806
- persistent state, scrubbed subprocess env, path sanitizer,
807
- `permissions.json` mode 0o600, ReDoS guard on `grep`,
808
- `invoke`/`ainvoke` accept bare strings and message lists).
1
+ # Changelog
2
+
3
+ All notable changes to `agentx-dev` are documented here. Format loosely
4
+ follows [Keep a Changelog](https://keepachangelog.com/); versioning is
5
+ [Semver](https://semver.org/).
6
+
7
+ ## [3.5.0] - 2026-10-04
8
+
9
+ Agents that keep working through errors. Opt-in; one default change (below).
10
+
11
+ ### Added
12
+
13
+ - **Persistent mode** (`persistence=Persistence(...)`) for `AgentRunner`,
14
+ `AsyncAgentRunner`, `Supervisor` and `AsyncSupervisor`. When a run gets
15
+ stuck (the same call repeated, or tool errors in a row) it is
16
+ asked, in four escalating steps, to find the root cause, try a
17
+ different approach, probe its assumptions, and say what blocks it,
18
+ before it may stop; real progress resets the ladder. Runs stop on
19
+ `max_minutes` or the model's cost cap, not a step count.
20
+ - **Context compaction** for long runs: old turns become notes, the task
21
+ (with its attachments) and recent turns are untouched, and the failed
22
+ attempts are kept word for word.
23
+ - **Patient retries**: transient provider errors (429, 5xx, timeouts,
24
+ connection errors) are retried with backoff until the deadline; auth
25
+ and invalid-request errors still raise at once.
26
+ - **Supervisors replan**: a step that does not finish is replanned
27
+ around under one shared deadline; finished steps are kept and can be
28
+ depended on. A recovery step names the steps it redoes
29
+ (`"replaces": [...]`); a failed step counts as resolved only when its
30
+ replacement finishes. New `replan`, `reflect`, `compact` and `budget`
31
+ stream events.
32
+ - **Outcomes**: every completion has `.outcome` and (persistent runs)
33
+ `.progress`; `SubtaskResult` and `SupervisorResult` have `.outcome`.
34
+ - New guide: Long-running agents.
35
+
36
+ ### Changed
37
+
38
+ - A `Supervisor`/`AsyncSupervisor` now treats a specialist that finished
39
+ with an outcome other than `done` (for example `iteration_limit`) as a
40
+ failed attempt: it retries up to `max_subtask_retries` with the reason
41
+ fed back, then flags the step. Previously such a result was accepted
42
+ as a success. This applies without `persistence`. Consequences: each
43
+ give-up costs one extra attempt by default (`max_subtask_retries=1`);
44
+ the flagged step's recap is no longer passed to downstream
45
+ specialists; steps that `depends_on` it are skipped; and
46
+ `SupervisorResult.outcome` is `partial` or `stuck`.
47
+ - While `persistence` is set the tool-result cache is off, and the
48
+ iteration cap is `persistence.max_turns`.
49
+
50
+ ## [3.4.3] - 2026-09-26
51
+
52
+ Two path-resolution fixes for Windows sandboxes. Non-breaking.
53
+
54
+ ### Fixed
55
+
56
+ - **`full_access(["/workspace"])` now means the project's workspace
57
+ folder, not the drive root.** On Windows a rooted path without a drive
58
+ letter resolves to the current drive, so the sandbox became
59
+ `C:\workspace`; `auto_create_paths` then created it, and an agent
60
+ asked for `workspace/spam.csv` searched an empty directory outside the
61
+ project and reported the file missing. Slash-rooted sandbox roots are
62
+ now re-rooted at the running project, matching what a leading slash
63
+ already meant for tool arguments. POSIX absolute paths (`/workspace`
64
+ as a Docker mount) and drive-qualified paths are untouched.
65
+ - **`workspace/report.md` no longer nests into
66
+ `<workspace>/workspace/report.md`.** The `workspace` field documented
67
+ this pass-through, but only the `./workspace/...` spelling had it.
68
+ Models name the workspace folder constantly, so the missing case hit
69
+ often; new files still resolve into the workspace as before.
70
+
71
+ ## [3.4.2] - 2026-09-19
72
+
73
+ `media=` everywhere, CSV / text / Excel attachments, and structured output
74
+ on models that need the Responses API. Non-breaking.
75
+
76
+ ### Added
77
+
78
+ - **`media=` on chat models and structured output.** `llm.invoke`,
79
+ `llm.ainvoke`, and `with_structured_output(...).invoke` / `.ainvoke` take
80
+ `media=[...]` (paths, URLs, `Media`, part dicts), appended to the last
81
+ user turn, matching the agent runner. Media inside `content` lists
82
+ already worked; this adds the argument.
83
+ - **CSV, text files, and Excel in `media=`.** Text-like files (CSV, TSV,
84
+ TXT, Markdown, JSON, XML, YAML, HTML) are read as text -- exactly as
85
+ written, UTF-8 or Windows-1252, CRLF normalised -- and spreadsheets
86
+ (.xlsx / .xls / .ods) are converted with pandas (`dtype=object`, so
87
+ cell values aren't re-inferred) to one CSV block per sheet. Both reach
88
+ GPT (chat and Responses) and Claude as a labelled text block, which
89
+ every model accepts. New `Media.text()` / `Media.spreadsheet()`; a
90
+ 100,000-character cap (`max_chars=`, `truncate=True`). pandas and
91
+ openpyxl are now core dependencies, so spreadsheets work after a plain
92
+ `pip install agentx-dev` (`[excel]` still works). Date cells without a
93
+ time are written as dates, not `... 00:00:00`.
94
+ - **Media docs section.** Its own nav group: Overview & flow, With chat
95
+ models, With agents, Reference (constructors, per-provider wire
96
+ formats, errors). `docs/guides/media.md` is now a pointer to it.
97
+
98
+ ### Fixed
99
+
100
+ - **`with_structured_output` on models that need the Responses API.**
101
+ Structured output forces a single tool; if the Responses API rejects a
102
+ forced tool choice for the model, `GPT` retries with
103
+ `tool_choice="required"` (the same tool when there is only one), then
104
+ `"auto"`, remembering it per model. `StructuredOutputRunnable` also
105
+ accepts a JSON text answer that validates against the schema.
106
+ - **`.txt` media failed on Claude.** 3.4.0 stored text files as base64
107
+ documents, which Anthropic only accepts for PDFs. Text files now go
108
+ out as text; older base64 text parts in saved histories are decoded
109
+ on the way out.
110
+ - **Unsupported files reached the provider.** `Media.document()`
111
+ accepted any file type -- including CSV, which Windows' own type table
112
+ labels `application/vnd.ms-excel` -- and sent it as an attachment
113
+ neither provider accepts. Word, PowerPoint and archives now raise
114
+ `ValueError` with the fix before any request; a text file or
115
+ spreadsheet by URL raises too, since only PDFs can be fetched by URL.
116
+ - **Misleading WARNING on recovered calls.** The retry wrapper logged
117
+ every non-retryable 400 at WARNING before the caller could recover, so a
118
+ call that switched to the Responses API and succeeded still printed the
119
+ original "Function tools with reasoning_effort are not supported" text.
120
+ Now DEBUG; recoveries log their own WARNING and real failures log ERROR.
121
+
122
+ ## [3.4.1] - 2026-09-18
123
+
124
+ Tool calls on OpenAI models that require the Responses API.
125
+
126
+ ### Fixed
127
+
128
+ - **Tool calls failed on models that need the Responses API.** Some
129
+ OpenAI models (e.g. `gpt-6-astra`) reject function tools combined with
130
+ reasoning on `/v1/chat/completions`, and the error's suggested fix --
131
+ `reasoning_effort='none'` -- is itself rejected by those models, so
132
+ 3.4.0's parameter adaptation had nowhere to go. `GPT` now switches a
133
+ model's tool calls to `/v1/responses` when the provider says to,
134
+ retries, and remembers it (WARNING-logged). History is translated only
135
+ at the wire (`function_call` / `function_call_output` items paired by
136
+ `call_id`), so agents, `tool_calls`, and completions are unchanged.
137
+ Learned parameter fixes carry across endpoints (`reasoning.effort` maps
138
+ to `reasoning_effort`). Requests are sent with `store=False`, matching
139
+ chat completions. Plain text calls and streaming stay on chat
140
+ completions.
141
+ - Requests chat completions can't express (a document URL) go to the
142
+ Responses API, which accepts `file_url`, instead of raising.
143
+
144
+ ### Added
145
+
146
+ - `GPT(use_responses_api=None | True | False)`: automatic (default),
147
+ always, or never.
148
+
149
+ ## [3.4.0] - 2026-09-18
150
+
151
+ Media input for GPT and Claude, models that adapt to each generation's
152
+ parameter support, and workspace-rooted paths. Non-breaking; two
153
+ defaults changed -- see docs/guides/upgrading.md.
154
+
155
+ ### Added
156
+
157
+ - **Media input for GPT and Claude.** New `Media` type
158
+ (`Media.image()`, `.document()`, `.audio()`, `.from_path()`,
159
+ `.from_url()`, `.from_bytes()`) and a `media=[...]` argument on
160
+ `AgentRunner.invoke` / `stream` and `AsyncAgentRunner.ainvoke` /
161
+ `astream`. Items can be paths, URLs, `Media`, or content-part dicts
162
+ in either provider's native shape; each model renders them in its
163
+ own wire format (OpenAI `image_url` / `file` / `input_audio`,
164
+ Anthropic `image` / `document`). Unsupported combinations -- audio to
165
+ Claude, a document URL to GPT -- raise `ValueError` before any
166
+ request. Media is stored as plain JSON dicts, so `completion.history`
167
+ and `Session.save()` keep working. Guide: docs/guides/media.md.
168
+
169
+ - **Models adapt to per-generation parameter support.** `GPT` and
170
+ `Claude` read a parameter-compatibility 400 (which names the
171
+ parameter and, for enums, the allowed values), make the smallest
172
+ change it asks for, retry, and remember it per model: an unsupported
173
+ `reasoning_effort` moves to the nearest supported value, `max_tokens`
174
+ becomes `max_completion_tokens` on reasoning models (up front for
175
+ known families), parameters a model lacks are dropped, and Claude's
176
+ `max_tokens` is clamped to the model's cap. Logged at WARNING; other
177
+ 400s raise unchanged. `adapt_params=False` opts out.
178
+
179
+ - **`Claude` gains `top_p`, `top_k`, `thinking`, `stop_sequences`.**
180
+
181
+ ### Changed
182
+
183
+ - `Claude(temperature=)` defaults to `None` (not sent; the API default is
184
+ the old 1.0). Always sending it conflicted with `top_p` on newer models
185
+ and with extended thinking.
186
+ - `GPT(reasoning_effort=)` accepts any string, not just
187
+ `none | low | medium | high`, so `minimal` and `xhigh` are expressible.
188
+
189
+ ### Fixed
190
+
191
+ - **`reasoning_effort="none"` crashed on models that don't take it**
192
+ ("Unsupported value: 'reasoning_effort' does not support 'none' with
193
+ this model"). The models docs even recommended `"none"` as a fix for
194
+ tool-calling conflicts; that advice is gone.
195
+ - **Workspace-rooted paths resolved to the drive root.** With a workspace
196
+ set, `/bruce.jpeg` became `C:\bruce.jpeg` on Windows (a leading slash
197
+ with no drive means the current drive's root) and the sandbox rejected
198
+ it. A leading slash now means the workspace root; the re-rooted path
199
+ is still sandbox-checked, so traversal is rejected as before.
200
+ - **`run_python` ran in the host process's directory, not the
201
+ workspace.** It passed no `cwd`, so `open("bruce.jpeg")` looked
202
+ wherever the program was launched from. It now starts in the workspace,
203
+ matching `run_shell`.
204
+ - **Message-list input stringified media into the prompt.** A user turn
205
+ whose content was a list (text + image) went through `str()`, so an
206
+ attached image reached the model as base64 text. Text and media are
207
+ now split, and earlier turns keep their list content.
208
+ - **Claude returned the wrong block with extended thinking.** It read
209
+ `response.content[0].text`; with thinking the first block is a
210
+ `thinking` block. Text blocks are now joined.
211
+ - `GPT.Initialize` / `stream_text` / `astream_text` now run messages
212
+ through the same OpenAI translator as `call_with_tools`.
213
+
214
+ ## [3.3.1] - 2026-09-09
215
+
216
+ Correctness fixes in the agent loop, found by driving it with a
217
+ scripted model rather than reading it. No API changes; every fix
218
+ replaces a silent wrong answer or a runaway cost with correct
219
+ behaviour. Nine regression tests ship with them
220
+ (`tests/test_agent_loop_flaws.py`).
221
+
222
+ ### Fixed
223
+
224
+ - **Native binding had no loop-level spiral guard.** The repeat breaker
225
+ sat after the native branch's `continue`, so `bind_tools_natively`
226
+ runs never reached it: a model stuck re-issuing one call burned the
227
+ full `max_iterations` (20 LLM turns where text mode stopped at 3) and
228
+ returned the "hit max_iterations" recap quoting the dup-guard's own
229
+ warning text instead of the data.
230
+
231
+ - **`respond` batched with real tool calls dropped them.** A model that
232
+ emitted "do X, and here is my answer" in one turn had X silently
233
+ discarded -- never dispatched, never in `completion.tool_calls`, no
234
+ error. The batch now runs and the answer defers one turn.
235
+
236
+ - **`completion.history` could not be replayed as `chat_history`.** The
237
+ copy filter kept only truthy `{role, content}`, which dropped every
238
+ tool-calling assistant turn (`content=""`), stripped `tool_call_id`
239
+ off `role="tool"` messages, and replayed a stored system prompt on top
240
+ of the fresh one -- so a follow-up call sent two system messages, zero
241
+ assistant turns, and an orphaned tool message providers reject. Fixed
242
+ in both runners.
243
+
244
+ - **A sync `AgentRunner` silently ignored async tools.** `known_tools`
245
+ unioned only the two sync registry tables while the registry accepted,
246
+ listed and prompt-advertised async ones, so calling one fell through
247
+ to implicit-final and returned `action_input` as the answer with an
248
+ empty `tool_calls` list. Now unions all four, matching the async
249
+ runner; the sync dispatcher already returns a clear `ToolError`, so
250
+ the silent wrong answer became an actionable one.
251
+
252
+ - **`AsyncAgentRunner` regressed the function-calling message shape.**
253
+ It appended its FC turn as raw JSON text with no `tool_calls` block
254
+ and never set `_last_function_call_id`, so observations went back as
255
+ `role="user"` -- text-mode shape while in FC mode, losing provider
256
+ correlation and the cached prefix.
257
+
258
+ - **A `BaseException` from a specialist orphaned its siblings.**
259
+ `CancelledError` and `KeyboardInterrupt` are not `Exception`, so
260
+ `_run_subtask`'s handler never saw them; `t.result()` re-raised and
261
+ left sibling tasks running unowned, with in-flight LLM calls still
262
+ billing. The scheduler now owns its tasks in a `try`/`finally`, which
263
+ also covers a consumer that stops iterating `astream` early.
264
+
265
+ - **The tool cache collided on tool name.** It is a process-wide
266
+ singleton keyed on `(tool_name, args)` with no record of which
267
+ implementation ran, so two runners whose tools merely share a name --
268
+ `search`, `fetch`, `query`, routine across Supervisor specialists --
269
+ served each other's results and the second function never ran. Keys
270
+ now fold in the callable's `module.qualname`, so same-name /
271
+ different-implementation misses while genuinely identical tools still
272
+ share, including across processes for the disk-backed `FileCache`.
273
+
274
+ ### Docs
275
+
276
+ - Streaming documentation described parameters the API rejects.
277
+ `AsyncAgentRunner.astream()` and `HandoffCoordinator.stream()` take no
278
+ `stream_tokens` (only the sync `AgentRunner.stream()` does), and every
279
+ `text_delta` example was built on a default model where
280
+ `use_function_calling` auto-detects to `True` and yields zero deltas.
281
+ `simple_stream` was documented with the wrong signature entirely.
282
+ Added a table naming exactly which stream methods accept what.
283
+
284
+ ### Tests
285
+
286
+ - Repaired 20 stale text-mode tests. `MockModel` defined
287
+ `call_with_tools` unconditionally, so 3.1.7's auto-detect routed every
288
+ text script down the function-calling path and the runner returned
289
+ `""`. The mock now advertises the capability only when scripted for
290
+ it. Suite: 206 passed, 3 skipped.
291
+
292
+ ## [3.3.0] - 2026-08-19
293
+
294
+ Dependency DAGs for the Supervisor. Plans declare which steps consume
295
+ which, and the executor derives ordering, parallelism, AND context
296
+ routing from those edges — unifying the old split where sequential
297
+ mode had threading but no parallelism and concurrent mode had
298
+ parallelism but no threading. Design: docs/design/3.3-depends-on-dag.md.
299
+
300
+ ### Added
301
+
302
+ - **`depends_on` plan steps.** Every plan step now carries an `id`;
303
+ a step that consumes an earlier step's output lists that id in
304
+ `depends_on`. Sync `Supervisor` executes in stable topological
305
+ order; `AsyncSupervisor` runs a completion-driven scheduler where a
306
+ step starts the MOMENT its dependencies finish (not on wave
307
+ barriers) and independent steps run concurrently. In DAG mode each
308
+ step is threaded ONLY its direct dependencies' results — explicit
309
+ routing instead of "everything prior", which also stops the
310
+ per-entry context budget shrinking as plans grow.
311
+
312
+ - **Plan sanitization that never fails a run.** Missing/duplicate ids
313
+ auto-assigned, unknown dependencies dropped (a planner typo degrades
314
+ to a root step, not a dead run), self-deps dropped, cycles broken
315
+ deterministically (back-edge in plan order), spawn steps cannot be
316
+ depended on. If repairs were needed, the plan is re-requested once
317
+ (`max_plan_retries`, default 1) with the repair warnings appended;
318
+ the sanitized original is kept when the retry is no better.
319
+
320
+ - **Failure cascade + `skipped` flag.** A step whose dependency failed
321
+ (after retries / success-check) is skipped, transitively, with
322
+ `SubtaskResult.skipped=True` and an error naming the failed dep.
323
+ Independent branches keep running; synthesis runs over what
324
+ succeeded. Skipped steps never dispatch — no tokens burned
325
+ downstream of garbage.
326
+
327
+ - **`skip_when` conditional execution.** A step may declare
328
+ `{"step": <direct dep id>, "field": <typed output field>, "is": <value>}`;
329
+ evaluated in Python (no LLM call) against the dependency's 3.2
330
+ structured output, dotted paths supported, strictly FAIL-OPEN (any
331
+ doubt → the step runs). Condition-skips do NOT cascade — dependents
332
+ treat them as empty successes ("retrieval unnecessary" is not
333
+ "answering impossible").
334
+
335
+ - **`Specialist` registry entries.** `agents={}` now also accepts
336
+ `Specialist(description, runner, depends_on=[...names...],
337
+ output_schema=..., when_to_use=...)`. The extras render into the
338
+ planning catalog (`typically after:` / `returns: Schema(fields)` /
339
+ `use when:`) so the planner can write real dependency graphs and
340
+ `skip_when` conditions against actual field names. `depends_on`
341
+ here is a planner HINT, never an execution constraint (the same
342
+ specialist can appear twice in one plan; step-ids disambiguate).
343
+ Classic `(description, runner)` tuples keep working — they are
344
+ wrapped internally, and `Specialist` tuple-unpacks for older code.
345
+
346
+ - **`AsyncSupervisor(max_parallel=N)`.** Caps concurrent sub-tasks for
347
+ rate-limited deployments. `sequential=True` is now sugar for
348
+ `max_parallel=1` with all-prior threading.
349
+
350
+ - **`SubtaskResult.step_id` / `.depends_on` / `.skipped`** and a
351
+ `step_id` field on `dispatch` / `subtask_result` stream events.
352
+
353
+ ### Backward compatibility
354
+
355
+ A plan where NO step declares `depends_on` runs with byte-identical
356
+ legacy semantics: sync + async-sequential thread all prior results in
357
+ plan order; async-concurrent runs everything at once with no
358
+ threading. Verified by regression tests against the 3.2 behaviour.
359
+
360
+ ## [3.2.0] - 2026-08-13
361
+
362
+ Typed multi-agent pipelines. Specialists can now declare a Pydantic
363
+ output schema once and pass validated instances to each other through
364
+ the Supervisor, instead of downstream agents re-parsing prose.
365
+
366
+ ### Added
367
+
368
+ - **`output_schema` on the `AgentRunner` / `AsyncAgentRunner`
369
+ constructor.** Declare the runner's output shape once
370
+ (`AgentRunner(..., output_schema=QueryIntent)`) instead of passing it
371
+ on every call or describing JSON in the prompt. A per-call
372
+ `output_schema=` still wins when both are set. `None` keeps the exact
373
+ pre-3.2 behaviour: no coercion, `completion.output` stays `None`.
374
+
375
+ - **Schema coercion via forced native function calling.** When a schema
376
+ is in play, the final answer is converted by forcing a provider-native
377
+ tool call against the schema (constrained decoding), not by regexing
378
+ JSON out of prose. The ReAct loop itself is untouched: tool selection
379
+ and intermediate reasoning run exactly as before, and the coercion
380
+ happens once, after the loop finishes. Models without a
381
+ `call_with_tools` implementation fall back to the previous text-JSON
382
+ parsing, so custom `BaseChatModel` subclasses keep working.
383
+ `completion.content` keeps the human-readable answer alongside
384
+ `completion.output` in every case.
385
+
386
+ - **`SubtaskResult.output`.** The Supervisor now preserves each
387
+ specialist's validated Pydantic instance next to its `content` text.
388
+ Consumers that only read `content` are unaffected.
389
+
390
+ - **Structured specialist-to-specialist handoff.** When an earlier step
391
+ produced typed output, `_build_augmented_query` serializes it into the
392
+ next specialist's context as a labelled JSON block
393
+ (`STRUCTURED OUTPUT (QueryIntent): {...}`) followed by the summary
394
+ text, so downstream steps parse fields rather than interpreting
395
+ sentences like `INTENT: ... SEARCH_QUERY: ...`.
396
+
397
+ - **`vector_search_tool` pipeline options.** New kwargs:
398
+ `max_text_chars` (default 500; pass `0` for full untruncated passages,
399
+ which a reranker judging evidence actually needs) and
400
+ `structured_output` (default False; when True the tool returns a JSON
401
+ array of `{id, text, vector_score, metadata}` instead of the
402
+ human-formatted list). Defaults preserve existing behaviour byte-for-
403
+ byte.
404
+
405
+ ### Fixed
406
+
407
+ - **Supervisor planning prompt contradicted the execution engine.** The
408
+ planner rule said sub-agents "do NOT see previous steps' output" and
409
+ discouraged dependency chains, but the dispatcher has threaded prior
410
+ findings into every step since `_build_augmented_query` shipped.
411
+ The rule now tells the planner that sequential steps receive earlier
412
+ results (structured when available) and that chains like
413
+ intent -> retrieval -> reranking are a good plan shape, while still
414
+ requiring same-specialist steps to merge and banning report-only steps.
415
+
416
+ ## [3.1.7] — 2026-07-27
417
+
418
+ ### Changed
419
+
420
+ - **`use_function_calling` default flipped to auto-detect** on
421
+ `AgentRunner` / `AsyncAgentRunner`. The parameter's default type is
422
+ now `Optional[bool] = None`; `None` resolves to `True` when the
423
+ model class overrides `BaseChatModel.call_with_tools` (both `GPT`
424
+ and `Claude` do) and to `False` when it doesn't (or when
425
+ `bind_tools_natively=True`). Callers passing `True`/`False`
426
+ explicitly are unaffected. Rationale: text-mode ReAct requires the
427
+ model to emit strict JSON with any long `action_input` string
428
+ properly escaped — a 1200-word markdown draft with unescaped
429
+ newlines or quotes reliably breaks `json.loads` and killed the run.
430
+ Function-calling mode routes the parser through the SDK's typed
431
+ channel so escaping is handled automatically. The historical
432
+ default (`False`) was the fragile option; the new default matches
433
+ what most users actually want.
434
+
435
+ ### Fixed
436
+
437
+ - **Malformed parser JSON no longer crashes the run.** When the
438
+ text-mode assistant response failed `json.loads` (typically because
439
+ a long `action_input` string had unescaped `"`, `\n`, or backticks),
440
+ the framework used to raise `JSONDecodeError` and unwind the whole
441
+ invocation. The runner now (1) tries a regex-based salvage that
442
+ extracts `{Thought, action, action_input}` from the raw text
443
+ covering the common "outer envelope valid, inner string broke
444
+ escaping" failure, and (2) if salvage fails, feeds a targeted fix
445
+ hint back to the model (`"your last response was not valid JSON;
446
+ emit …, escape newlines as \n"`) and continues the loop bounded
447
+ by `max_iterations`. Exhaustion returns a clear framework message
448
+ rather than an uncaught exception. Applied to both sync and async
449
+ runners via a shared `_salvage_react_json` helper.
450
+ The salvager's action-name regex is intentionally strict
451
+ (`[A-Za-z_][A-Za-z0-9_.\- ]{0,79}`) so it can't hallucinate an
452
+ "action" out of an unrelated `"key":"value"` pair inside malformed
453
+ JSON.
454
+
455
+ - **Verbose trace in `bind_tools_natively` mode now prints tool
456
+ name + args + response.** Previously native runs showed blank
457
+ `[tool.call.start]` / `[tool.call.complete]` pairs (the
458
+ observability layer fires them without the trace context), so you
459
+ couldn't tell which tool the model actually invoked or what came
460
+ back. The runner now prints `[tool] Invoking '<name>' with args:
461
+ <input>` and `[tool] Response: <preview>` (or `[tool] Error: ...`
462
+ when the dispatch raised) in the post-dispatch loop, matching the
463
+ format text-mode and function-calling mode use. Mirrored to the
464
+ async runner.
465
+
466
+ - **`web_fetch_tool(vector_store=...)` auto-ingests fetched pages into
467
+ a vector store** instead of dumping raw HTML into the model's
468
+ context. Fixes the TPM-limit trap: when a research agent fetches
469
+ four articles in parallel (via ``multi_tool_use.parallel`` or
470
+ native binding), the combined bodies can easily exceed 40k tokens
471
+ and blow past a 30k TPM ceiling on the very next model call.
472
+ New parameters on ``web_fetch_tool``:
473
+
474
+ | Kwarg | Default | Effect |
475
+ |---|---|---|
476
+ | ``vector_store`` | ``None`` | When set, each fetch is HTML-stripped, chunked with ``TextSplitter``, embedded via the store's embeddings, and added with ``{src: url, chunk_index, total_chunks}`` metadata. The tool response becomes a compact summary (URL, byte count, chunk count, 240-char preview) — NOT the raw body. The model then calls ``vector_search`` / ``Rag`` to pull only the passages it needs. |
477
+ | ``chunk_size`` | ``1500`` | Characters per chunk when ``vector_store`` is set. Ignored otherwise. |
478
+ | ``chunk_overlap`` | ``200`` | Overlap between adjacent chunks so a fact spanning a boundary is still retrievable. Ignored otherwise. |
479
+
480
+ Backwards-compatible: the positional ``cache_dir`` signature keeps
481
+ working; `web_fetch_tool()` with no ``vector_store`` returns raw
482
+ body as before. Ingest and cache_dir compose — enable both and get
483
+ disk-cached full bodies AND searchable chunks. HTML stripping is
484
+ minimal and dependency-free (regex-based: script/style blocks
485
+ dropped whole, then tags stripped, whitespace collapsed) so the
486
+ ingest path adds no new install dependency. On JSON/plain-text
487
+ responses the stripper is a near no-op.
488
+
489
+ The observation returned to the model shows topical coverage --
490
+ first, middle, and last chunk previews (up to 3 samples,
491
+ deduplicated for short pages) -- so the model can tell what
492
+ topics the page actually covers, not just the intro paragraph.
493
+ Without this the model would only see the page's opening and
494
+ wouldn't know to query for topics discussed later in the same
495
+ page. Explicit instruction in the observation ("query with
496
+ SPECIFIC keywords from the topics above; do NOT re-fetch; do
497
+ NOT ask for the full body") steers the model toward the RAG path
498
+ on follow-up turns.
499
+
500
+ - **`multi_tool_use.parallel` now reaches its dispatch path.**
501
+ When GPT wanted to batch several tool calls into one turn (fetch N
502
+ URLs concurrently, run M searches at once), it emitted OpenAI's
503
+ synthetic `multi_tool_use.parallel` meta-tool. The registry's
504
+ `_dispatch_multi_parallel` / `_adispatch_multi_parallel` handlers
505
+ already knew how to unpack it, but the runner loop's known-tools
506
+ guardrail rejected the name FIRST as unregistered — dumping the
507
+ raw `{"tool_uses": [...]}` payload into the user-facing "final
508
+ answer" and never invoking any of the nested calls. Added
509
+ `multi_tool_use.parallel` to the recognized action set in both
510
+ sync and async runners so the meta-tool flows through to dispatch
511
+ and the existing unpackers run. Nested calls with the `functions.`
512
+ prefix are normalized before dispatch (same as top-level FC
513
+ calls), so the model can emit either shape.
514
+
515
+ - **`Permissions.full_access` / `read_only` auto-wrap a bare string.**
516
+ Passing `full_access("./workspace")` used to iterate the string
517
+ into 11 single-character "subtrees" (Python's `list("./workspace")`)
518
+ — every path check silently rejected because no real path could
519
+ ever match a `"."` or `"/"` "allowed subtree". The classmethod
520
+ now detects a bare string and treats it as `[allowed_paths]`, so
521
+ `full_access("./workspace")` does the intuitive thing (equivalent
522
+ to `full_access(["./workspace"])` and auto-infers the workspace).
523
+ Same fix on `read_only`. List inputs are unchanged.
524
+
525
+ - **`Permissions.full_access` now accepts (and auto-infers)
526
+ `workspace`.** The classmethod set `allowed_paths` but not
527
+ `workspace`, so short paths like `write_file(path="report.md")`
528
+ resolved to CWD (outside the sandbox) and raised
529
+ `PermissionError: access denied` — a landmine that every caller of
530
+ `Permissions.full_access(["./workspace"])` hit sooner or later.
531
+ New signature: `full_access(allowed_paths, *, workspace=None)`.
532
+ When `workspace` isn't passed AND `allowed_paths` has exactly one
533
+ entry, that path is auto-set as the workspace (the "project-scoped
534
+ agent whose one allowed subtree IS its workspace" case, which is
535
+ 99% of use). Two or more paths stay ambiguous and require an
536
+ explicit `workspace=` if short-path resolution is wanted. Pass an
537
+ explicit `workspace=` string to override the auto-choice.
538
+ Backwards-compatible on the positional signature; adds a keyword
539
+ argument that existing callers didn't use.
540
+
541
+ ## [3.1.5] — 2026-07-26
542
+
543
+ ### Fixed
544
+
545
+ - **Text-mode tool results no longer use `role: "function"`.** In text
546
+ mode (the default — no `use_function_calling`) the runner fed each tool
547
+ observation back to the model as a `role: "function"` message. Newer
548
+ OpenAI models reject that role outright (`400 … 'messages[N].role' does
549
+ not support 'function' with this model`, e.g. gpt-5.x), and Anthropic
550
+ never accepted it — text-mode multi-tool runs on Claude were latently
551
+ broken too; older GPT models simply still tolerated the legacy role.
552
+ Tool observations now go back as a plain `role: "user"` turn framed as
553
+ `Observation: …`, which every provider and model generation accepts and
554
+ which matches the ReAct template's own few-shot convention.
555
+ Function-calling mode is unchanged (native `role: "tool"` +
556
+ `tool_call_id`). The async runner was additionally emitting `function`
557
+ unconditionally (even in FC mode); it now uses the same shared helper.
558
+
559
+ ### Added
560
+
561
+ - **`subtask_success_check` on `Supervisor` / `AsyncSupervisor`.** Opt-in
562
+ predicate `(SubtaskResult) -> bool | str` that decides whether a
563
+ *returned* (non-raised) sub-task result is actually acceptable — the
564
+ "ran fine but produced nothing useful" case a plain retry can't catch
565
+ (a scraper that saved 0 links, an extractor that found nothing). Return
566
+ `True` to accept, or `False`/a `str` reason to reject; a rejected
567
+ result is retried like a raised error, with the reason fed back into the
568
+ query, bounded by `max_subtask_retries`. After retries are exhausted the
569
+ last result is returned with its `error` set (content preserved). A
570
+ check that itself raises is treated as "accept" so a buggy predicate
571
+ can't wedge the run. Default `None` keeps the exceptions-only behavior.
572
+ New example `examples/robust_link_scraper.py` wires it together with a
573
+ scraping `system_addendum` (parse relative+absolute hrefs, fall back to
574
+ `sitemap.xml` on JS-rendered sites).
575
+
576
+ ## [3.1.4] — 2026-07-26
577
+
578
+ ### Fixed
579
+
580
+ - **A malformed-JSON tool argument no longer crashes the whole agent
581
+ run.** When a model emitted a Python snippet or a Windows path as a
582
+ tool-call argument — `re.findall(r'\d+')`, `C:\Users` — the `\d` / `\U`
583
+ are illegal JSON escapes, and the OpenAI adapter's eager
584
+ `json.loads(call.function.arguments)` raised `JSONDecodeError` and
585
+ `raise`d it, unwinding the entire ReAct loop before the agent's own
586
+ retry machinery could act. Under a Supervisor this surfaced as a bare
587
+ `ERROR: Invalid \escape: line 1 column 598` and the sub-task was
588
+ abandoned. Now:
589
+ - `_parse_tool_arguments` repairs the common case (backslashes that
590
+ don't begin a valid JSON escape are doubled), recovering `\d`,
591
+ `\w`, `\s`, etc. with zero extra round-trips. A backslash before a
592
+ valid-escape letter (`\b`, `\n`, …) remains ambiguous and is left
593
+ as the escape — a documented limit.
594
+ - When repair fails, `call_with_tools` returns a dedicated
595
+ `invalid_tool_args` result and the loop feeds the error back as a
596
+ retryable observation ("your arguments weren't valid JSON — escape
597
+ backslashes and resend"), bounded by `max_iterations`, in all
598
+ three modes across both `AgentRunner` and `AsyncAgentRunner`.
599
+ `Claude` was already immune (its tool inputs arrive pre-parsed).
600
+
601
+ - **A tool-call preamble is no longer returned as the final answer.**
602
+ Models routinely end a turn with an announcement instead of an action
603
+ — "I'll look up your recent scores to get a clear view of your
604
+ communication skills. Just a second!" — and every "no tool call
605
+ found" branch in both runners was coded as *this text is the answer,
606
+ break*. The loop terminated on iteration 1 and the caller got a
607
+ promise instead of a result. Three sites per runner were affected:
608
+ the native-binding path (`type != "tool_use"`), the
609
+ `use_function_calling` path (parser unresolved), and the JSON-text
610
+ path (response didn't parse). `max_iterations` never helped, because
611
+ the break happened before any iteration was spent.
612
+
613
+ The runner now feeds the model one corrective nudge — "your last turn
614
+ had no action, so nothing happened; do it, don't announce it" — and
615
+ continues the loop. Verified against both `AgentRunner` and
616
+ `AsyncAgentRunner` in all three modes.
617
+
618
+ ### Added
619
+
620
+ - **Proactive "act, don't announce" system-prompt clause.** The reactive
621
+ `text_turn_nudges` fix corrects an agent *after* it narrates instead of
622
+ acting; this clause heads it off. When (and only when) an agent has
623
+ tools, its system prompt now tells it to call the tool rather than
624
+ reply "I'll do X / just a second" and stop — and to report what it DID
625
+ in past tense. Injected in all three modes across both runners; skipped
626
+ for tool-less chat agents, where prose is the correct answer. Sits
627
+ before any `system_addendum` so a caller's role instructions still win.
628
+
629
+ - **`max_subtask_retries` on `Supervisor` / `AsyncSupervisor`** (default
630
+ `1`). A sub-task that raised used to be recorded as an error and the
631
+ Supervisor moved straight to synthesis — no second attempt. Now a
632
+ failed sub-task is re-dispatched up to this many times, with the prior
633
+ error appended to the query so the specialist knows what to fix
634
+ ("your previous attempt failed with X — diagnose and try again").
635
+ Bounded and informed: only raised exceptions trigger a retry (a
636
+ sub-task that returns content is accepted as-is, since the Supervisor
637
+ can't tell "terse but correct" from "wrong"), and the error text is
638
+ fed back rather than blindly re-running. Set to `0` for the old
639
+ quit-on-first-failure behavior. Applies in both sequential and
640
+ concurrent async modes.
641
+
642
+ - **`text_turn_nudges` on `AgentRunner` / `AsyncAgentRunner`** (default
643
+ `1`). Caps the re-prompts described above at one extra LLM call per
644
+ run; after the budget is spent the model's text stands as the answer.
645
+ Set to `0` for the previous behavior. Automatically skipped when no
646
+ tools are registered, since a runner with no tools is a plain chat
647
+ call and prose genuinely is the answer there.
648
+
649
+ ## [3.1.3] — 2026-07-22
650
+
651
+ Docs-only patch. No code changes since 3.1.2. Users on 3.1.2 don't
652
+ need to upgrade for functionality; upgrade to pick up the improved
653
+ onboarding docs bundled in the sdist.
654
+
655
+ ### Documentation
656
+
657
+ - **Tools doc rewritten to answer "how do I actually use these?"**
658
+ Added §0 `How each built-in tool is registered` as the entry
659
+ section. Two registration paths — auto vs manual — laid out in a
660
+ table on the first screen. Six runnable subsections covering every
661
+ combination:
662
+ - §0.1 DefaultTools via `Permissions(...)` (auto)
663
+ - §0.2 WebTools via `tools=[web_search_tool(), web_fetch_tool()]`
664
+ - §0.3 RAG via `TextSplitter` -> `VectorStore.add_documents` ->
665
+ `vector_search_tool(store)`
666
+ - §0.4 Handoffs via `handoff_tool` + `HandoffCoordinator`
667
+ - §0.5 Custom `StructuredTool` from scratch
668
+ - §0.6 Fully-loaded runner combining all of the above
669
+ - §0.7 Rules on name collisions, invisible-denied-capabilities,
670
+ async-tool behavior
671
+ The existing inventory + wrapper / controls / cheat-sheet sections
672
+ are unchanged; they now sit after the "how to use them" primer
673
+ instead of before it.
674
+
675
+ ## [3.1.2] — 2026-07-22
676
+
677
+ Patch release. Two independent fixes.
678
+
679
+ ### Fixed
680
+
681
+ - **`llm_judge` correctly parses YES/NO across providers.** The judge
682
+ parser was comparing the reply's first word to the literal string
683
+ `"YES"`. GPT-4o answers `"YES,"` (comma-suffixed), which failed the
684
+ equality check and marked every genuine PASS as FAIL. Claude replies
685
+ `"YES"` without punctuation so the bug hid during local development.
686
+ Fixed by matching `\b(YES|NO)\b` (word-boundary regex, case-
687
+ insensitive) at the start of the reply. Handles every real shape:
688
+ `YES`, `YES.`, `YES!`, `YES, exactly right`, `Yes.`, `yes -- reason`.
689
+ Ambiguous replies (`Maybe`, empty string) still fail closed.
690
+ - Regression test `test_llm_judge_parses_various_verdict_shapes`
691
+ covers 8 YES shapes, 5 NO shapes, and 4 ambiguous replies.
692
+
693
+ ### Added
694
+
695
+ - **`agentx_dev.Tools` is a one-stop tools namespace.** Users no
696
+ longer need to remember which module each tool lives in:
697
+
698
+ ```python
699
+ from agentx_dev.Tools import (
700
+ StandardTool, StructuredTool,
701
+ AsyncStandardTool, AsyncStructuredTool,
702
+ web_search_tool, web_fetch_tool,
703
+ vector_search_tool, handoff_tool,
704
+ DefaultTools, Permissions,
705
+ )
706
+ ```
707
+
708
+ Both this form and the pre-existing `from agentx_dev import X`
709
+ form coexist. Implementation uses PEP 562 module `__getattr__`
710
+ and `__dir__` so re-exports are lazy (no import cost for modules
711
+ the caller doesn't touch) and show up in IDE autocomplete +
712
+ `dir(agentx_dev.Tools)`.
713
+
714
+ ## [3.1.1] — 2026-07-21
715
+
716
+ Second batch of 3.1 features + a full docs + brand pass.
717
+
718
+ ### Added
719
+
720
+ **Streaming through orchestration**
721
+ - `Supervisor.stream()` / `AsyncSupervisor.astream()` emit
722
+ `plan_start` / `plan` / `dispatch` / `subtask_result` /
723
+ `synthesize_start` / `final` / `completion` events.
724
+ - `HandoffCoordinator.stream()` / `.astream()` emit `invoke` /
725
+ `completion` / `handoff` / `final` / `result` events per hop.
726
+ - Legacy `.run()` / `.arun()` refactored to consume the streams (no
727
+ code duplication).
728
+
729
+ **Prompt optimization — `Compiled`**
730
+ - New `agentx_dev.Compiler` module.
731
+ - `Compiled(runner_factory, trainset, ...)` iteratively refines a
732
+ runner's `system_addendum` against the eval harness. Half of
733
+ DSPy's power at a tenth of the surface.
734
+
735
+ **Anthropic Batch API**
736
+ - `Claude.batch(requests)` submits many prompts at Anthropic's 50%-off
737
+ batch rate, polls to completion, returns results in submission order.
738
+ - Per-request error dicts on failure; token usage funneled into
739
+ `TokenUsage` so cost tracking stays a single source of truth.
740
+
741
+ **Vector store adapters — `agentx_dev.VectorStores`**
742
+ - `ChromaVectorStore`, `QdrantVectorStore`, `PgVectorStore` — same
743
+ public shape as the in-memory `VectorStore` (`add` / `search` /
744
+ `delete` / `clear` / `__len__` / `embeddings`).
745
+ - `vector_search_tool()` and `SemanticMemory` accept any of them.
746
+ - SDK imports lazy; friendly `ImportError` when the underlying SDK
747
+ is missing.
748
+
749
+ **Trace viewer (`viewer/`)**
750
+ - Self-hosted single-page app that reads `FileHook` JSONL and renders
751
+ a timeline with type/text filters, summary sidebar, JSON drill-down.
752
+ - Works from `file://`, no server required.
753
+
754
+ **Docs site (`host/`)**
755
+ - Full editorial dark-first design system (JetBrains Mono headings,
756
+ Inter body, `#B8FF3E` electric-lime accent).
757
+ - Command palette (`Cmd+K`) with keyboard navigation and live search.
758
+ - Hero code snippet with hand-tinted syntax highlighting.
759
+ - Reading progress bar, breadcrumbs, header anchor links.
760
+ - Sidebar sliding active marker, collapsible groups.
761
+ - Code copy buttons, language labels.
762
+ - Right-rail auto-TOC with `IntersectionObserver` scrollspy.
763
+ - Dark/light theme toggle, persisted.
764
+ - Cache-busted assets so edits land on refresh without hard-reload.
765
+
766
+ **Brand identity (`brand/`)**
767
+ - Full brand kit: 5 SVG assets (`mark`, `mono`, `wordmark`, `logo-full`,
768
+ `app-icon`), `BRAND.md` strategy doc, rendered brand-kit HTML deck.
769
+ - Copy audit dropped "small" (weak) and "LangChain" references from
770
+ all marketing surfaces.
771
+ - Favicon wired into docs + trace viewer.
772
+
773
+ **Test suite (`tests/`)**
774
+ - Restored + expanded pytest suite: 127 tests passing (3 skipped for
775
+ absent optional SDKs).
776
+ - Coverage: parser + all `AgentType` variants, `ToolRegistry`
777
+ (dispatch / dup-guard / circuit-breaker / timeout), Permissions
778
+ (capability gating + sandbox + traversal), budgets (cost / rate /
779
+ retry / non-retryable HTTP), runner loop (streaming + output_schema
780
+ + chat history), embeddings + `VectorStore` + `SemanticMemory`,
781
+ handoffs (bounded hops + history sanitization), evals harness
782
+ (all assertion helpers + JSON case loaders), vector-store adapter
783
+ shape conformance.
784
+
785
+ **Docs (`docs/`)**
786
+ - Full docs tree (34 pages), including new pages for:
787
+ vector store adapters, prompt optimization, batch API, trace viewer,
788
+ and a **use-cases** landing (13 concrete scenarios with runnable code).
789
+ - Rewrote **Tools** page to enumerate every built-in tool with args,
790
+ return shape, capability flag, and use-case guidance.
791
+ - Rewrote **Agents** page to cover all four orchestration
792
+ architectures (Solo / Supervisor / Handoffs / Compiled) with
793
+ decision trees, worked examples, and cheat sheet.
794
+ - **Agentic RAG chatbot** as use case §13 — multi-query decomposition,
795
+ parallel retrieval, self-critique, citations, user memory.
796
+
797
+ **Examples**
798
+ - `examples/agentic_rag_demo.py` — the runnable version of the
799
+ agentic RAG use case. Auto-seeds a KB if none exists, `--demo` flag
800
+ runs a 3-turn scripted session proving user-notes recall works.
801
+
802
+ **Package**
803
+ - `[chroma]`, `[qdrant]`, `[pgvector]`, `[dev]` extras added.
804
+ - `[anthropic]` bumped to `>=0.36` (Batch API + prompt cache).
805
+
806
+ ### Fixed
807
+
808
+ - `AgentRunner._iter_run` in `bind_tools_natively=True` mode uses a
809
+ minimal system prompt instead of the AgentType template so the
810
+ ReAct `action/action_input` scaffold no longer fights the native
811
+ tool interface. Previously produced JSON-blob answers under GPT.
812
+ - `HandoffCoordinator._sanitize_history_for_next_agent` strips tool
813
+ and function role messages between hops so tool_call_ids from a
814
+ previous agent don't leak into the next model's call (OpenAI 400).
815
+ - Docs site marker positioning uses double-`requestAnimationFrame` +
816
+ `document.fonts.ready` so the sidebar accent bar lands on the
817
+ correct row even on a cold font cache.
818
+ - Primary hero CTA color uses `#doc .hero-cta a.primary` selector to
819
+ outrank `#doc a` link styling (previously rendered lime-on-lime
820
+ and was invisible).
821
+
822
+ ### Notes
823
+
824
+ - Package version bumped from `3.0.6` to `3.1.1`. The 3.1.0 release
825
+ did not ship publicly — 3.1.1 is the first 3.1-tagged PyPI release
826
+ and includes both batches of features.
827
+
828
+ ## [3.1.0] — internal only (commits 52840e7)
829
+
830
+ First batch of 3.1 features. Committed but not released to PyPI.
831
+ Merged into 3.1.1 for the public release.
832
+
833
+ ### Added
834
+ - Anthropic prompt caching (`Claude(enable_prompt_cache=True)`).
835
+ - Parallel per-turn tool dispatch in `AgentRunner`
836
+ (`bind_tools_natively=True`, `parallel_tool_workers`).
837
+ - Semantic memory (`SemanticMemory`, embeddings-backed retrieval).
838
+ - RAG core (`Embeddings`, `HashEmbeddings`, `OpenAIEmbeddings`,
839
+ `VectorStore`, `VectorHit`, `vector_search_tool()`).
840
+ - Agent-to-agent handoffs (`HandoffRequest`, `handoff_tool`,
841
+ `HandoffCoordinator`, `HandoffResult`).
842
+ - Evals harness (`EvalCase`, `EvalRunner`, `EvalReport`, 7 assertion
843
+ helpers, JSON case loader, `python -m agentx_dev.Evals run` CLI).
844
+ - `TokenUsage.cache_hit_ratio` property.
845
+
846
+ ## [3.0.6] — 2026-03 (baseline)
847
+
848
+ Security hardening baseline (SSRF guard on `web_fetch`, HMAC-signed
849
+ persistent state, scrubbed subprocess env, path sanitizer,
850
+ `permissions.json` mode 0o600, ReDoS guard on `grep`,
851
+ `invoke`/`ainvoke` accept bare strings and message lists).