agentx-dev 3.1.5__tar.gz → 3.3.0__tar.gz

{agentx_dev-3.1.5 → agentx_dev-3.3.0}/CHANGELOG.md

@@ -4,6 +4,255 @@ All notable changes to `agentx-dev` are documented here. Format loosely
 follows [Keep a Changelog](https://keepachangelog.com/); versioning is
 [Semver](https://semver.org/).
 
+## [3.3.0] - 2026-08-19
+
+Dependency DAGs for the Supervisor. Plans declare which steps consume
+which, and the executor derives ordering, parallelism, AND context
+routing from those edges — unifying the old split where sequential
+mode had threading but no parallelism and concurrent mode had
+parallelism but no threading. Design: docs/design/3.3-depends-on-dag.md.
+
+### Added
+
+- **`depends_on` plan steps.** Every plan step now carries an `id`;
+  a step that consumes an earlier step's output lists that id in
+  `depends_on`. Sync `Supervisor` executes in stable topological
+  order; `AsyncSupervisor` runs a completion-driven scheduler where a
+  step starts the MOMENT its dependencies finish (not on wave
+  barriers) and independent steps run concurrently. In DAG mode each
+  step is threaded ONLY its direct dependencies' results — explicit
+  routing instead of "everything prior", which also stops the
+  per-entry context budget shrinking as plans grow.
+
+- **Plan sanitization that never fails a run.** Missing/duplicate ids
+  auto-assigned, unknown dependencies dropped (a planner typo degrades
+  to a root step, not a dead run), self-deps dropped, cycles broken
+  deterministically (back-edge in plan order), spawn steps cannot be
+  depended on. If repairs were needed, the plan is re-requested once
+  (`max_plan_retries`, default 1) with the repair warnings appended;
+  the sanitized original is kept when the retry is no better.
+
+- **Failure cascade + `skipped` flag.** A step whose dependency failed
+  (after retries / success-check) is skipped, transitively, with
+  `SubtaskResult.skipped=True` and an error naming the failed dep.
+  Independent branches keep running; synthesis runs over what
+  succeeded. Skipped steps never dispatch — no tokens burned
+  downstream of garbage.
+
+- **`skip_when` conditional execution.** A step may declare
+  `{"step": <direct dep id>, "field": <typed output field>, "is": <value>}`;
+  evaluated in Python (no LLM call) against the dependency's 3.2
+  structured output, dotted paths supported, strictly FAIL-OPEN (any
+  doubt → the step runs). Condition-skips do NOT cascade — dependents
+  treat them as empty successes ("retrieval unnecessary" is not
+  "answering impossible").
+
+- **`Specialist` registry entries.** `agents={}` now also accepts
+  `Specialist(description, runner, depends_on=[...names...],
+  output_schema=..., when_to_use=...)`. The extras render into the
+  planning catalog (`typically after:` / `returns: Schema(fields)` /
+  `use when:`) so the planner can write real dependency graphs and
+  `skip_when` conditions against actual field names. `depends_on`
+  here is a planner HINT, never an execution constraint (the same
+  specialist can appear twice in one plan; step-ids disambiguate).
+  Classic `(description, runner)` tuples keep working — they are
+  wrapped internally, and `Specialist` tuple-unpacks for older code.
+
+- **`AsyncSupervisor(max_parallel=N)`.** Caps concurrent sub-tasks for
+  rate-limited deployments. `sequential=True` is now sugar for
+  `max_parallel=1` with all-prior threading.
+
+- **`SubtaskResult.step_id` / `.depends_on` / `.skipped`** and a
+  `step_id` field on `dispatch` / `subtask_result` stream events.
+
+### Backward compatibility
+
+A plan where NO step declares `depends_on` runs with byte-identical
+legacy semantics: sync + async-sequential thread all prior results in
+plan order; async-concurrent runs everything at once with no
+threading. Verified by regression tests against the 3.2 behaviour.
+
+## [3.2.0] - 2026-08-13
+
+Typed multi-agent pipelines. Specialists can now declare a Pydantic
+output schema once and pass validated instances to each other through
+the Supervisor, instead of downstream agents re-parsing prose.
+
+### Added
+
+- **`output_schema` on the `AgentRunner` / `AsyncAgentRunner`
+  constructor.** Declare the runner's output shape once
+  (`AgentRunner(..., output_schema=QueryIntent)`) instead of passing it
+  on every call or describing JSON in the prompt. A per-call
+  `output_schema=` still wins when both are set. `None` keeps the exact
+  pre-3.2 behaviour: no coercion, `completion.output` stays `None`.
+
+- **Schema coercion via forced native function calling.** When a schema
+  is in play, the final answer is converted by forcing a provider-native
+  tool call against the schema (constrained decoding), not by regexing
+  JSON out of prose. The ReAct loop itself is untouched: tool selection
+  and intermediate reasoning run exactly as before, and the coercion
+  happens once, after the loop finishes. Models without a
+  `call_with_tools` implementation fall back to the previous text-JSON
+  parsing, so custom `BaseChatModel` subclasses keep working.
+  `completion.content` keeps the human-readable answer alongside
+  `completion.output` in every case.
+
+- **`SubtaskResult.output`.** The Supervisor now preserves each
+  specialist's validated Pydantic instance next to its `content` text.
+  Consumers that only read `content` are unaffected.
+
+- **Structured specialist-to-specialist handoff.** When an earlier step
+  produced typed output, `_build_augmented_query` serializes it into the
+  next specialist's context as a labelled JSON block
+  (`STRUCTURED OUTPUT (QueryIntent): {...}`) followed by the summary
+  text, so downstream steps parse fields rather than interpreting
+  sentences like `INTENT: ... SEARCH_QUERY: ...`.
+
+- **`vector_search_tool` pipeline options.** New kwargs:
+  `max_text_chars` (default 500; pass `0` for full untruncated passages,
+  which a reranker judging evidence actually needs) and
+  `structured_output` (default False; when True the tool returns a JSON
+  array of `{id, text, vector_score, metadata}` instead of the
+  human-formatted list). Defaults preserve existing behaviour byte-for-
+  byte.
+
+### Fixed
+
+- **Supervisor planning prompt contradicted the execution engine.** The
+  planner rule said sub-agents "do NOT see previous steps' output" and
+  discouraged dependency chains, but the dispatcher has threaded prior
+  findings into every step since `_build_augmented_query` shipped.
+  The rule now tells the planner that sequential steps receive earlier
+  results (structured when available) and that chains like
+  intent -> retrieval -> reranking are a good plan shape, while still
+  requiring same-specialist steps to merge and banning report-only steps.
+
+## [3.1.7] — 2026-07-27
+
+### Changed
+
+- **`use_function_calling` default flipped to auto-detect** on
+  `AgentRunner` / `AsyncAgentRunner`. The parameter's default type is
+  now `Optional[bool] = None`; `None` resolves to `True` when the
+  model class overrides `BaseChatModel.call_with_tools` (both `GPT`
+  and `Claude` do) and to `False` when it doesn't (or when
+  `bind_tools_natively=True`). Callers passing `True`/`False`
+  explicitly are unaffected. Rationale: text-mode ReAct requires the
+  model to emit strict JSON with any long `action_input` string
+  properly escaped — a 1200-word markdown draft with unescaped
+  newlines or quotes reliably breaks `json.loads` and killed the run.
+  Function-calling mode routes the parser through the SDK's typed
+  channel so escaping is handled automatically. The historical
+  default (`False`) was the fragile option; the new default matches
+  what most users actually want.
+
+### Fixed
+
+- **Malformed parser JSON no longer crashes the run.** When the
+  text-mode assistant response failed `json.loads` (typically because
+  a long `action_input` string had unescaped `"`, `\n`, or backticks),
+  the framework used to raise `JSONDecodeError` and unwind the whole
+  invocation. The runner now (1) tries a regex-based salvage that
+  extracts `{Thought, action, action_input}` from the raw text
+  covering the common "outer envelope valid, inner string broke
+  escaping" failure, and (2) if salvage fails, feeds a targeted fix
+  hint back to the model (`"your last response was not valid JSON;
+  emit …, escape newlines as \n"`) and continues the loop bounded
+  by `max_iterations`. Exhaustion returns a clear framework message
+  rather than an uncaught exception. Applied to both sync and async
+  runners via a shared `_salvage_react_json` helper.
+  The salvager's action-name regex is intentionally strict
+  (`[A-Za-z_][A-Za-z0-9_.\- ]{0,79}`) so it can't hallucinate an
+  "action" out of an unrelated `"key":"value"` pair inside malformed
+  JSON.
+
+- **Verbose trace in `bind_tools_natively` mode now prints tool
+  name + args + response.** Previously native runs showed blank
+  `[tool.call.start]` / `[tool.call.complete]` pairs (the
+  observability layer fires them without the trace context), so you
+  couldn't tell which tool the model actually invoked or what came
+  back. The runner now prints `[tool] Invoking '<name>' with args:
+  <input>` and `[tool] Response: <preview>` (or `[tool] Error: ...`
+  when the dispatch raised) in the post-dispatch loop, matching the
+  format text-mode and function-calling mode use. Mirrored to the
+  async runner.
+
+- **`web_fetch_tool(vector_store=...)` auto-ingests fetched pages into
+  a vector store** instead of dumping raw HTML into the model's
+  context. Fixes the TPM-limit trap: when a research agent fetches
+  four articles in parallel (via ``multi_tool_use.parallel`` or
+  native binding), the combined bodies can easily exceed 40k tokens
+  and blow past a 30k TPM ceiling on the very next model call.
+  New parameters on ``web_fetch_tool``:
+
+  | Kwarg | Default | Effect |
+  |---|---|---|
+  | ``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. |
+  | ``chunk_size`` | ``1500`` | Characters per chunk when ``vector_store`` is set. Ignored otherwise. |
+  | ``chunk_overlap`` | ``200`` | Overlap between adjacent chunks so a fact spanning a boundary is still retrievable. Ignored otherwise. |
+
+  Backwards-compatible: the positional ``cache_dir`` signature keeps
+  working; `web_fetch_tool()` with no ``vector_store`` returns raw
+  body as before. Ingest and cache_dir compose — enable both and get
+  disk-cached full bodies AND searchable chunks. HTML stripping is
+  minimal and dependency-free (regex-based: script/style blocks
+  dropped whole, then tags stripped, whitespace collapsed) so the
+  ingest path adds no new install dependency. On JSON/plain-text
+  responses the stripper is a near no-op.
+
+  The observation returned to the model shows topical coverage --
+  first, middle, and last chunk previews (up to 3 samples,
+  deduplicated for short pages) -- so the model can tell what
+  topics the page actually covers, not just the intro paragraph.
+  Without this the model would only see the page's opening and
+  wouldn't know to query for topics discussed later in the same
+  page. Explicit instruction in the observation ("query with
+  SPECIFIC keywords from the topics above; do NOT re-fetch; do
+  NOT ask for the full body") steers the model toward the RAG path
+  on follow-up turns.
+
+- **`multi_tool_use.parallel` now reaches its dispatch path.**
+  When GPT wanted to batch several tool calls into one turn (fetch N
+  URLs concurrently, run M searches at once), it emitted OpenAI's
+  synthetic `multi_tool_use.parallel` meta-tool. The registry's
+  `_dispatch_multi_parallel` / `_adispatch_multi_parallel` handlers
+  already knew how to unpack it, but the runner loop's known-tools
+  guardrail rejected the name FIRST as unregistered — dumping the
+  raw `{"tool_uses": [...]}` payload into the user-facing "final
+  answer" and never invoking any of the nested calls. Added
+  `multi_tool_use.parallel` to the recognized action set in both
+  sync and async runners so the meta-tool flows through to dispatch
+  and the existing unpackers run. Nested calls with the `functions.`
+  prefix are normalized before dispatch (same as top-level FC
+  calls), so the model can emit either shape.
+
+- **`Permissions.full_access` / `read_only` auto-wrap a bare string.**
+  Passing `full_access("./workspace")` used to iterate the string
+  into 11 single-character "subtrees" (Python's `list("./workspace")`)
+  — every path check silently rejected because no real path could
+  ever match a `"."` or `"/"` "allowed subtree". The classmethod
+  now detects a bare string and treats it as `[allowed_paths]`, so
+  `full_access("./workspace")` does the intuitive thing (equivalent
+  to `full_access(["./workspace"])` and auto-infers the workspace).
+  Same fix on `read_only`. List inputs are unchanged.
+
+- **`Permissions.full_access` now accepts (and auto-infers)
+  `workspace`.** The classmethod set `allowed_paths` but not
+  `workspace`, so short paths like `write_file(path="report.md")`
+  resolved to CWD (outside the sandbox) and raised
+  `PermissionError: access denied` — a landmine that every caller of
+  `Permissions.full_access(["./workspace"])` hit sooner or later.
+  New signature: `full_access(allowed_paths, *, workspace=None)`.
+  When `workspace` isn't passed AND `allowed_paths` has exactly one
+  entry, that path is auto-set as the workspace (the "project-scoped
+  agent whose one allowed subtree IS its workspace" case, which is
+  99% of use). Two or more paths stay ambiguous and require an
+  explicit `workspace=` if short-path resolution is wanted. Pass an
+  explicit `workspace=` string to override the auto-choice.
+  Backwards-compatible on the positional signature; adds a keyword
+  argument that existing callers didn't use.
+
 ## [3.1.5] — 2026-07-26
 
 ### Fixed

{agentx_dev-3.1.5 → agentx_dev-3.3.0}/CONTRIBUTING.md

@@ -1,105 +1,105 @@
-# Contributing to agentx-dev
-
-Thanks for your interest. This is a solo-authored framework, so a few
-process choices are opinionated -- they exist to keep the surface area
-small and the codebase readable.
-
-## Getting set up
-
-```bash
-git clone https://github.com/shadrach098/Bruce_framework.git
-cd Bruce_framework
-python -m venv .venv && source .venv/bin/activate   # or .venv\Scripts\activate on Windows
-pip install -e ".[dev,anthropic]"
-```
-
-Sanity check:
-
-```bash
-pytest tests/            # should show 127 passing, 3 skipped
-python -c "import agentx_dev; print(agentx_dev.__all__)"
-```
-
-## Before you open a PR
-
-1. **Run the tests.** `pytest tests/ -q` from the repo root.
-2. **Add tests** for whatever you changed. Every existing subsystem
-   has a `tests/test_<module>.py`; add cases there.
-3. **Keep the change focused.** One PR per feature or fix. If your
-   change touches five modules and adds three exports, split it.
-4. **Preserve existing behavior** unless the change is explicitly a
-   breaking one. Backwards-compat is a real value.
-5. **Update docs** if you added or changed a public API. `docs/`
-   holds the source; run `python host/build_data.py` to regenerate
-   the browsable site's `data.js`.
-
-## Commit + PR style
-
-- **Commit messages:** `<type>: <short summary>` where type is one of
-  `feat` / `fix` / `docs` / `test` / `refactor` / `chore`. Follow
-  with a blank line and the body if the summary isn't enough. Look
-  at recent commits (`git log --oneline -20`) for the shape.
-- **PR titles:** same shape as the commit message. If the PR has
-  multiple commits, the title summarizes the whole PR.
-- **PR descriptions:** what changed, why, and one before/after
-  example if the change is user-visible.
-
-## What lands and what doesn't
-
-Things that land easily:
-
-- Bug fixes with a regression test.
-- New tools that follow the existing patterns.
-- Docs improvements (more examples, clearer explanations, fixing typos).
-- New vector-store adapters or provider adapters that follow the
-  existing interface.
-- Test coverage for uncovered paths.
-
-Things that need discussion first (open an issue):
-
-- New public classes or modules.
-- Changes to public method signatures.
-- Anything that grows the dependency footprint of the base install.
-- Anything that reshapes the runner loop, `Supervisor`, or
-  `HandoffCoordinator`.
-
-Things that don't land:
-
-- Style-only refactors that reshape existing files.
-- Adding a "generic" abstraction over one specific thing.
-- Wrapping existing SDKs "for consistency."
-- LangChain-compatibility shims.
-- Auto-generated boilerplate.
-
-## Code style
-
-- **Docstrings are the source of truth.** Every public class + method
-  gets one. Say *why* the choice was made, not just what it does.
-- **No trailing summary comments** at the end of functions.
-- **Type hints on public APIs.** Not needed on internal helpers if
-  the shape is obvious from three lines up.
-- **Small files > large files**, but one-module features > splitting
-  a single concept across three files for tidiness.
-
-## Security-sensitive changes
-
-The framework has explicit security surfaces:
-
-- `Permissions` + sandbox enforcement in `DefaultTools.py`
-- `run_python` HMAC-signed persistent state in `AutoSetup.py`
-- SSRF guard in `WebTools.py`
-- Session-id sanitizer in `DefaultTools.py`
-
-If your change touches any of these, please:
-
-1. Add a test that exercises the security check.
-2. Add a note in the PR describing the threat model you considered.
-
-See `AGENTX.md` at the repo root for the guardrails the framework
-imposes on itself.
-
-## Questions?
-
-Open an issue with the "question" label. Solo maintainer, so response
-time varies -- a good repro / minimal example is the single biggest
-help.
+# Contributing to agentx-dev
+
+Thanks for your interest. This is a solo-authored framework, so a few
+process choices are opinionated -- they exist to keep the surface area
+small and the codebase readable.
+
+## Getting set up
+
+```bash
+git clone https://github.com/shadrach098/agentx_dev.git
+cd agentx_dev
+python -m venv .venv && source .venv/bin/activate   # or .venv\Scripts\activate on Windows
+pip install -e ".[dev,anthropic]"
+```
+
+Sanity check:
+
+```bash
+pytest tests/            # should show 127 passing, 3 skipped
+python -c "import agentx_dev; print(agentx_dev.__all__)"
+```
+
+## Before you open a PR
+
+1. **Run the tests.** `pytest tests/ -q` from the repo root.
+2. **Add tests** for whatever you changed. Every existing subsystem
+   has a `tests/test_<module>.py`; add cases there.
+3. **Keep the change focused.** One PR per feature or fix. If your
+   change touches five modules and adds three exports, split it.
+4. **Preserve existing behavior** unless the change is explicitly a
+   breaking one. Backwards-compat is a real value.
+5. **Update docs** if you added or changed a public API. `docs/`
+   holds the source; run `python host/build_data.py` to regenerate
+   the browsable site's `data.js`.
+
+## Commit + PR style
+
+- **Commit messages:** `<type>: <short summary>` where type is one of
+  `feat` / `fix` / `docs` / `test` / `refactor` / `chore`. Follow
+  with a blank line and the body if the summary isn't enough. Look
+  at recent commits (`git log --oneline -20`) for the shape.
+- **PR titles:** same shape as the commit message. If the PR has
+  multiple commits, the title summarizes the whole PR.
+- **PR descriptions:** what changed, why, and one before/after
+  example if the change is user-visible.
+
+## What lands and what doesn't
+
+Things that land easily:
+
+- Bug fixes with a regression test.
+- New tools that follow the existing patterns.
+- Docs improvements (more examples, clearer explanations, fixing typos).
+- New vector-store adapters or provider adapters that follow the
+  existing interface.
+- Test coverage for uncovered paths.
+
+Things that need discussion first (open an issue):
+
+- New public classes or modules.
+- Changes to public method signatures.
+- Anything that grows the dependency footprint of the base install.
+- Anything that reshapes the runner loop, `Supervisor`, or
+  `HandoffCoordinator`.
+
+Things that don't land:
+
+- Style-only refactors that reshape existing files.
+- Adding a "generic" abstraction over one specific thing.
+- Wrapping existing SDKs "for consistency."
+- LangChain-compatibility shims.
+- Auto-generated boilerplate.
+
+## Code style
+
+- **Docstrings are the source of truth.** Every public class + method
+  gets one. Say *why* the choice was made, not just what it does.
+- **No trailing summary comments** at the end of functions.
+- **Type hints on public APIs.** Not needed on internal helpers if
+  the shape is obvious from three lines up.
+- **Small files > large files**, but one-module features > splitting
+  a single concept across three files for tidiness.
+
+## Security-sensitive changes
+
+The framework has explicit security surfaces:
+
+- `Permissions` + sandbox enforcement in `DefaultTools.py`
+- `run_python` HMAC-signed persistent state in `AutoSetup.py`
+- SSRF guard in `WebTools.py`
+- Session-id sanitizer in `DefaultTools.py`
+
+If your change touches any of these, please:
+
+1. Add a test that exercises the security check.
+2. Add a note in the PR describing the threat model you considered.
+
+See `AGENTX.md` at the repo root for the guardrails the framework
+imposes on itself.
+
+## Questions?
+
+Open an issue with the "question" label. Solo maintainer, so response
+time varies -- a good repro / minimal example is the single biggest
+help.

{agentx_dev-3.1.5 → agentx_dev-3.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentx-dev
-Version: 3.1.5
+Version: 3.3.0
 Summary: A production-grade Python framework for building LLM agents. Multi-provider chat, permission-gated tools, RAG (in-mem + Chroma/Qdrant/pgvector), semantic memory, Supervisor + Handoffs multi-agent orchestration with streaming, evals harness, prompt caching, Batch API, prompt-optimizer, MCP integration.
 Author-email: Bruce-Arhin Shadrach <brucearhin098@gmail.com>
 License: MIT License
@@ -25,9 +25,9 @@ License: MIT License
         OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
         SOFTWARE.
         
-Project-URL: Homepage, https://github.com/shadrach098/Bruce_framework
-Project-URL: Bug Tracker, https://github.com/shadrach098/Bruce_framework/issues
-Project-URL: Source, https://github.com/shadrach098/Bruce_framework
+Project-URL: Homepage, https://github.com/shadrach098/agentx_dev
+Project-URL: Bug Tracker, https://github.com/shadrach098/agentx_dev/issues
+Project-URL: Source, https://github.com/shadrach098/agentx_dev
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
@@ -479,7 +479,7 @@ project with **deny-all** defaults:
 ```json
 {
   "_comment": "Edit this file to control which capabilities the agent has...",
-  "_docs": "https://github.com/shadrach098/Bruce_framework",
+  "_docs": "https://github.com/shadrach098/agentx_dev",
   "read_files": false,
   "list_directories": false,
   "write_files": false,
@@ -1123,5 +1123,5 @@ print(f"Spent: ${llm.usage.estimate_cost(0.003, 0.015):.4f}")
 
 ## Links
 
-- Repo: https://github.com/shadrach098/Bruce_framework
-- Issues: https://github.com/shadrach098/Bruce_framework/issues
+- Repo: https://github.com/shadrach098/agentx_dev
+- Issues: https://github.com/shadrach098/agentx_dev/issues

{agentx_dev-3.1.5 → agentx_dev-3.3.0}/README.md

@@ -415,7 +415,7 @@ project with **deny-all** defaults:
 ```json
 {
   "_comment": "Edit this file to control which capabilities the agent has...",
-  "_docs": "https://github.com/shadrach098/Bruce_framework",
+  "_docs": "https://github.com/shadrach098/agentx_dev",
   "read_files": false,
   "list_directories": false,
   "write_files": false,
@@ -1059,5 +1059,5 @@ print(f"Spent: ${llm.usage.estimate_cost(0.003, 0.015):.4f}")
 
 ## Links
 
-- Repo: https://github.com/shadrach098/Bruce_framework
-- Issues: https://github.com/shadrach098/Bruce_framework/issues
+- Repo: https://github.com/shadrach098/agentx_dev
+- Issues: https://github.com/shadrach098/agentx_dev/issues