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