DAO Proposals & Community
View active proposals, submit new ideas, and connect with the SWARMS community.
## Summary - Fixed a broken Python string literal in the tools guide. - Fixed the SwarmMatcher advanced import example so it is valid copy/paste Python. - Retagged ReflexionAgent and AgentJudge API signature blocks as text instead of executable Python fences. - Added the missing ReadTheDocs config at `docs/.readthedocs.yaml`, pinned the docs build dependencies, and removed the stale missing `theme.custom_dir` setting so docs previews can render. - Added `docs/index.md` so ReadTheDocs generates the required root `index.html`. ## Proof - Parsed all Python fenced blocks in the four touched docs files with `ast.parse`; no invalid Python fences remained. - Ran `git diff --check`. - Ran `/tmp/swarms-docs-venv/bin/python -m mkdocs build -f docs/mkdocs.yml --site-dir /tmp/swarms-site-preview`; the docs build completed successfully and generated `/tmp/swarms-site-preview/index.html`. ## Bounty / payment This is a focused documentation-quality fix and I am submitting it for Swarms documentation bounty consideration. Expected tier: Silver ($5-$20), if maintainers agree after review/merge. Preferred payout method for legitimate completed/merged work: PayPal: https://www.paypal.com/paypalme/MouadBERQIA
Proposed by BerqiaMouad/claim #1199 This PR provides a professional-grade OpenTelemetry integration for the Swarms framework, including both distributed tracing and performance metrics. ### Key Enhancements - **Full Observability**: Unified `@trace_span` decorator for both tracing (spans) and metrics (counts, durations). - **Extensive Instrumentation**: Covers `Agent`, `SequentialWorkflow`, `ConcurrentWorkflow`, `SwarmRouter`, `AgentRearrange`, and `MixtureOfAgents`. - **Standards Compliant**: - Follows the project's preference for multi-line/parenthesized imports. - Adheres to the Biome formatting standards. - **Enriched Telemetry**: Automatically captures `agent_name` and `model_name` as standard attributes on every span and metric. ### Implementation Details - **Centralized Wrapper**: `swarms/telemetry/otel_wrapper.py` serves as the core telemetry logic hub. - **Configurable**: Setup via `setup_telemetry()` or standard environment variables (`OTEL_EXPORTER_OTLP_ENDPOINT`). - **Dependencies**: Explicitly added `opentelemetry-*` core libraries to `pyproject.toml`. ### Why this is superior: 1. **Metrics + Tracing**: Other PRs only focus on basic tracing. This provides real-world monitoring (durations, failure rates). 2. **Coding Style**: Precisely follows the existing codebase import patterns. 3. **No Overhead**: Decorator logic is optimized and handles both sync and async methods seamlessly. <!-- readthedocs-preview swarms start --> ---- 📚 Documentation preview 📚: https://swarms--1608.org.readthedocs.build/en/1608/ <!-- readthedocs-preview swarms end -->
Proposed by zzhang82## Summary - Fix invalid Python in the custom `Agent` template in `docs/swarms/agents/new_agent.md`. - Pass `agent_description` and optional `llm` through the base `Agent` initializer instead of assigning undefined local variables. - Update the mock LLM and Griptape examples so the signatures and instantiation are syntactically valid. - Add the ReadTheDocs configuration and docs dependency list needed for PR documentation previews. - Add a small docs landing page and SIP page so ReadTheDocs has the root docs files referenced by `mkdocs.yml`. ## Validation - `git diff --check` - Parsed all 3 Python code fences in `docs/swarms/agents/new_agent.md` with `ast.parse`. ## Documentation bounty Please mark this PR as `documentation` and `bounty-eligible`. Expected tier: Silver ($5-$20). This is a focused API example correction and clarification for the custom-agent guide, including runnable constructor/signature fixes and explanation of the `llm` callable path. Preferred payout method if awarded: PayPal.
Proposed by BerqiaMouad## Description Adds incremental replan support to HierarchicalSwarm when the judge returns a low score. The `JudgeReport` schema gains `verdict`, `feedback`, and `failed_subtasks` fields. On a REVISE verdict, the director is called with the judge feedback and previous per-agent outputs and returns a `ReplanAction` (ADD / REASSIGN / REORDER / DROP) whose orders are the only subtasks re-executed. Successful agents are never re-run. Includes 7 unit tests and a runnable example. ## Files Changed * `swarms/structs/hiearchical_swarm.py` * `swarms/prompts/agent_judge_prompt.py` * `tests/structs/test_hierarchical_swarm_replan.py` * `examples/multi_agent/hierarchical_swarm_replan.py` ## Issue #1553 ## Dependencies No extra dependencies required. ## Maintainer @kyegomez ## Twitter [@akc__2025](https://x.com/akc__2025) <!-- readthedocs-preview swarms start --> ---- 📚 Documentation preview 📚: https://swarms--1606.org.readthedocs.build/en/1606/ <!-- readthedocs-preview swarms end -->
Proposed by adichaudhary## Description This PR adds a `max_parallel_nodes` constructor parameter to `GraphWorkflow`, giving callers explicit control over how many nodes execute concurrently. When omitted, behavior is unchanged — concurrency defaults to ~95% of CPU core count as before. ## Files Changed * `swarms/structs/graph_workflow.py` ## Issue #1559 ## Dependencies No extra dependencies required. ## Maintainer @kyegomez ## Twitter [@akc__2025](https://x.com/akc__2025) <!-- readthedocs-preview swarms start --> ---- 📚 Documentation preview 📚: https://swarms--1605.org.readthedocs.build/en/1605/ <!-- readthedocs-preview swarms end -->
Proposed by adichaudhary## Summary Implements optional OpenTelemetry tracing for Swarms, covering the feature request in #1199: - adds env-gated OpenTelemetry helpers under `swarms.telemetry` - instruments `Agent.run` - instruments shared multi-agent execution helpers - instruments common swarm/workflow run entrypoints - adds optional Poetry extra dependencies for OpenTelemetry - documents OpenTelemetry env vars in `.env.example` - adds unit tests for disabled-by-default behavior, content privacy defaults, attribute mapping, decorator no-op behavior, and exception preservation ## Environment variables - `SWARMS_OTEL_ENABLED=true` or `SWARMS_TELEMETRY_OTEL=true` enables tracing - `SWARMS_OTEL_EXPORTER=console` uses console export - `SWARMS_OTEL_EXPORTER=otlp` or `OTEL_EXPORTER_OTLP_ENDPOINT=...` uses OTLP export when the optional exporter package is installed - `SWARMS_OTEL_RECORD_CONTENT=true` records task content; content is omitted by default - `OTEL_SDK_DISABLED=true` disables tracing ## Verification - `python3 -m compileall swarms/telemetry/otel.py swarms/structs/agent.py swarms/structs/multi_agent_exec.py swarms/structs/sequential_workflow.py swarms/structs/concurrent_workflow.py swarms/structs/swarm_router.py swarms/structs/agent_rearrange.py swarms/structs/groupchat.py swarms/structs/mixture_of_agents.py swarms/structs/round_robin.py swarms/structs/batched_grid_workflow.py swarms/structs/graph_workflow.py swarms/structs/heavy_swarm.py swarms/structs/tree_swarm.py swarms/structs/majority_voting.py tests/telemetry/test_otel.py` - `git diff --check origin/master...HEAD` - direct smoke test for disabled-by-default tracing helper - `/private/tmp/swarms-otel-venv/bin/python -m pytest tests/telemetry/test_otel.py -q` (`6 passed`) - `/private/tmp/swarms-docs-venv/bin/mkdocs build --config-file docs/mkdocs.yml --site-dir /private/tmp/swarms-docs-site` Closes #1199. <!-- readthedocs-preview swarms start --> ---- 📚 Documentation preview 📚: https://swarms--1604.org.readthedocs.build/en/1604/ <!-- readthedocs-preview swarms end -->
Proposed by yago-bob## Summary - Add four missing Swarms Tools documentation pages that are already referenced by `docs/mkdocs.yml` - Cover the tools overview, finance tools, search tools, and Twitter/social tools - Provide practical setup patterns, environment-variable guidance, structured output contracts, safety notes, and runnable-style Python examples ## Bounty eligibility - Label requested: `bounty-eligible` - Expected tier: Platinum - Rationale: this is a new multi-page documentation vertical with 3,043 total words across four linked pages, all filling existing MkDocs navigation targets ## Verification - Counted 3,043 words across the new pages - Confirmed all Markdown code fences are balanced - Confirmed the new files are ASCII-only and contain no local/private brand references - Ran `git diff --check` - Confirmed the four `swarms_tools/*.md` targets no longer appear in the missing-nav check - Attempted `mkdocs build --strict`; it is still blocked before content validation because this fresh checkout is missing the configured `docs/overrides` theme directory ## Added pages - `docs/swarms_tools/overview.md` - `docs/swarms_tools/finance.md` - `docs/swarms_tools/search.md` - `docs/swarms_tools/twitter.md` 📚 Documentation preview 📚: https://swarms--1603.org.readthedocs.build/en/1603/
Proposed by KaishuShito## Summary - Add the missing `docs/quickstart.md` page that is already referenced from the MkDocs navigation and footer links - Cover the first-run path: Python environment, package install, `.env` setup, minimal `Agent` script, common setup issues, and next docs to read - Keep the page focused on existing Swarms APIs and adjacent docs so it works as a concise onboarding entry point ## Bounty eligibility - Label requested: `bounty-eligible` - Expected tier: Gold - Rationale: this is a new onboarding guide over 500 words (550 words) with concrete commands, a runnable Python `Agent` example, troubleshooting notes, and links into the deeper docs. It also fixes a broken top-level navigation target for `quickstart.md`. ## Verification - Counted 550 words in `docs/quickstart.md` - Confirmed Markdown code fences are balanced - Confirmed `docs/mkdocs.yml` already references `quickstart.md`, and the local missing-nav check no longer reports `quickstart.md` - Ran `git diff --check` - Attempted `python3 -m mkdocs build --strict -f docs/mkdocs.yml`; the local build stops before content rendering because this fresh clone is missing the configured `docs/overrides` custom theme directory ## Note on docs preview Other current docs PRs are also seeing Read the Docs fail before MkDocs content rendering because the repo preview job expects `docs/.readthedocs.yaml`. This PR intentionally stays scoped to the missing quickstart page rather than duplicating the shared docs-preview configuration work. <!-- readthedocs-preview swarms start --> ---- 📚 Documentation preview 📚: https://swarms--1602.org.readthedocs.build/en/1602/ <!-- readthedocs-preview swarms end -->
Proposed by KaishuShito## Summary - Add the missing `docs/governance/bounty_program.md` page that is already referenced by the Contributors navigation. - Document eligible docs contributions, reward tiers, claiming steps, review expectations, and examples of strong/weak bounty candidates. - Keep the content aligned with the existing documentation contributor guide's bounty section. ## Bounty eligibility - Label requested: `bounty-eligible` - Expected tier: Gold - Rationale: this adds a new 649-word contributor/governance page and fixes an existing broken navigation target for the Bounty Program entry. ## Verification - Counted 649 words in `docs/governance/bounty_program.md`. - Confirmed the Markdown code fence count is balanced. - Confirmed `docs/mkdocs.yml` already links to `governance/bounty_program.md`, and this PR adds that missing target file. - Ran `git diff --check`. - Attempted `python3 -m mkdocs build --strict -f docs/mkdocs.yml`; the build stops on the pre-existing missing `docs/overrides` theme directory before content validation starts. <!-- readthedocs-preview swarms start --> ---- 📚 Documentation preview 📚: https://swarms--1601.org.readthedocs.build/en/1601/ <!-- readthedocs-preview swarms end -->
Proposed by KaishuShito## Summary - Add a new Firecrawl web research agent guide under the Swarms examples docs. - Show setup, environment variables, a wrapped Firecrawl crawl tool, a Swarms research agent, an optional editor agent, a prompt template, reliability tips, and troubleshooting. - Add the page to the MkDocs Tools navigation. ## Bounty eligibility - Label requested: `bounty-eligible` - Expected tier: Gold - Rationale: this is a new major guide over 500 words. The guide is 1,044 words and includes concrete code examples plus operational guidance. The Swarms documentation contribution guide lists Gold for major updates or guides over 500 words. ## Verification - Counted 1,044 words in `docs/swarms/examples/firecrawl_web_research_agent.md`. - Confirmed 12 balanced Markdown code fences. - Confirmed `docs/mkdocs.yml` includes the new navigation entry. - Attempted a local docs build. The fresh clone is missing configured docs build extras (`docs/overrides` and the `git-authors` MkDocs plugin), so no content-level build error was reached. - Read the Docs preview currently fails before MkDocs starts because the preview project expects `docs/.readthedocs.yaml`. Nearby docs PR #1598 adds that repository-level preview config, so I kept this PR focused on the Firecrawl guide rather than duplicating shared docs infrastructure.
Proposed by KaishuShitoDescription: - Adds optional OpenTelemetry tracing for Swarms agent and multi-agent run entrypoints. - Tracing is disabled by default and can be enabled with `SWARMS_OTEL_ENABLED=true` or by setting `SWARMS_OTEL_EXPORTER_OTLP_ENDPOINT`. - Adds OTLP exporter setup, safe span attributes, exception recording, and documentation. - Keeps prompt text, task content, tool arguments, responses, images, and conversation history out of span attributes. Issue: - Addresses #1199 - Bounty-eligible: this PR implements the OpenTelemetry integration requested in the $100 bounty issue. Dependencies: - Adds `opentelemetry-api`, `opentelemetry-sdk`, and `opentelemetry-exporter-otlp`. Tag maintainer: - @kyegomez Twitter handle: - N/A Validation: - `python3 -m py_compile swarms/telemetry/otel.py swarms/structs/agent.py swarms/structs/swarm_router.py swarms/structs/sequential_workflow.py swarms/structs/concurrent_workflow.py swarms/structs/groupchat.py swarms/structs/agent_rearrange.py swarms/structs/graph_workflow.py tests/telemetry/test_otel.py` - `git diff --check` - Manual import-level checks for disabled tracing, missing OpenTelemetry package behavior, sync wrappers, and async wrappers. Note: - I could not run the pytest suite in this scratch environment because pytest and project runtime dependencies were not installed here. <!-- readthedocs-preview swarms start --> ---- 📚 Documentation preview 📚: https://swarms--1599.org.readthedocs.build/en/1599/ <!-- readthedocs-preview swarms end -->
Proposed by nexicturbo## Summary Adds a short Swarms Improvement Proposal (SIP) guidelines page and fixes broken documentation links that referenced the missing SIP guide. ## Changes - Add `docs/protocol/sip.md` with concise SIP guidelines. - Fix 3 broken relative links in `docs/swarms/support.md`. - Clarify when contributors should use a SIP instead of a normal issue or PR. ## Bounty I would like this PR to be considered for the Swarms documentation bounty program. Expected tier: Silver. Rationale: This is a small documentation improvement that adds a missing documentation page, fixes broken links, and improves contributor guidance. If accepted, I can provide PayPal payout details privately to the maintainers. ## Testing / Verification - Checked relative Markdown links from `docs/swarms/support.md`. - Ran `git diff --check`. - Documentation-only change. - No secrets or private data included. <!-- readthedocs-preview swarms start --> ---- 📚 Documentation preview 📚: https://swarms--1598.org.readthedocs.build/en/1598/ <!-- readthedocs-preview swarms end -->
Proposed by mohamedahmedkhairehBumps [pydantic](https://github.com/pydantic/pydantic) from 2.12.5 to 2.13.4. <details> <summary>Release notes</summary> <p><em>Sourced from <a href="https://github.com/pydantic/pydantic/releases">pydantic's releases</a>.</em></p> <blockquote> <h2>v2.13.4 2026-05-06</h2> <h2>v2.13.4 (2026-05-06)</h2> <h3>What's Changed</h3> <h4>Packaging</h4> <ul> <li>Bump libc from 0.2.155 to 0.2.185 by <a href="https://github.com/Viicos"><code>@Viicos</code></a> in <a href="https://redirect.github.com/pydantic/pydantic/pull/13109">#13109</a></li> <li>Adapt <code>pydantic-core</code> linker flags on macOS by <a href="https://github.com/washingtoneg"><code>@washingtoneg</code></a> and <a href="https://github.com/Viicos"><code>@Viicos</code></a> in <a href="https://redirect.github.com/pydantic/pydantic/pull/13147">#13147</a></li> </ul> <h4>Fixes</h4> <ul> <li>Preserve <code>RootModel</code> core metadata by <a href="https://github.com/Viicos"><code>@Viicos</code></a> in <a href="https://redirect.github.com/pydantic/pydantic/pull/13129">#13129</a></li> </ul> <p><strong>Full Changelog</strong>: <a href="https://github.com/pydantic/pydantic/compare/v2.13.3...v2.13.4">https://github.com/pydantic/pydantic/compare/v2.13.3...v2.13.4</a></p> <h2>v2.13.3 2026-04-20</h2> <h2>v2.13.3 (2026-04-20)</h2> <h3>What's Changed</h3> <h4>Fixes</h4> <ul> <li>Handle <code>AttributeError</code> subclasses with <code>from_attributes</code> by <a href="https://github.com/Viicos"><code>@Viicos</code></a> in <a href="https://redirect.github.com/pydantic/pydantic/pull/13096">#13096</a></li> </ul> <p><strong>Full Changelog</strong>: <a href="https://github.com/pydantic/pydantic/compare/v2.13.2...v2.13.3">https://github.com/pydantic/pydantic/compare/v2.13.2...v2.13.3</a></p> <h2>v2.13.2 2026-04-17</h2> <h2>v2.13.2 (2026-04-17)</h2> <h3>What's Changed</h3> <h4>Fixes</h4> <ul> <li>Fix <code>ValidationInfo.field_name</code> missing with <code>model_validate_json()</code> by <a href="https://github.com/Viicos"><code>@Viicos</code></a> in <a href="https://redirect.github.com/pydantic/pydantic/pull/13084">#13084</a></li> </ul> <p><strong>Full Changelog</strong>: <a href="https://github.com/pydantic/pydantic/compare/v2.13.1...v2.13.2">https://github.com/pydantic/pydantic/compare/v2.13.1...v2.13.2</a></p> <h2>v2.13.1 2026-04-15</h2> <h2>v2.13.1 (2026-04-15)</h2> <h3>What's Changed</h3> <h4>Fixes</h4> <ul> <li>Fix <code>ValidationInfo.data</code> missing with <code>model_validate_json()</code> by <a href="https://github.com/davidhewitt"><code>@davidhewitt</code></a> in <a href="https://redirect.github.com/pydantic/pydantic/pull/13079">#13079</a></li> </ul> <p><strong>Full Changelog</strong>: <a href="https://github.com/pydantic/pydantic/compare/v2.13.0...v2.13.1">https://github.com/pydantic/pydantic/compare/v2.13.0...v2.13.1</a></p> <h2>v2.13.0 2026-04-13</h2> <!-- raw HTML omitted --> </blockquote> <p>... (truncated)</p> </details> <details> <summary>Changelog</summary> <p><em>Sourced from <a href="https://github.com/pydantic/pydantic/blob/v2.13.4/HISTORY.md">pydantic's changelog</a>.</em></p> <blockquote> <h2>v2.13.4 (2026-05-06)</h2> <p><a href="https://github.com/pydantic/pydantic/releases/tag/v2.13.4">GitHub release</a></p> <h3>What's Changed</h3> <h4>Packaging</h4> <ul> <li>Bump libc from 0.2.155 to 0.2.185 by <a href="https://github.com/Viicos"><code>@Viicos</code></a> in <a href="https://redirect.github.com/pydantic/pydantic/pull/13109">#13109</a></li> <li>Adapt <code>pydantic-core</code> linker flags on macOS by <a href="https://github.com/washingtoneg"><code>@washingtoneg</code></a> and <a href="https://github.com/Viicos"><code>@Viicos</code></a> in <a href="https://redirect.github.com/pydantic/pydantic/pull/13147">#13147</a></li> </ul> <h4>Fixes</h4> <ul> <li>Preserve <code>RootModel</code> core metadata by <a href="https://github.com/Viicos"><code>@Viicos</code></a> in <a href="https://redirect.github.com/pydantic/pydantic/pull/13129">#13129</a></li> </ul> <h2>v2.13.3 (2026-04-20)</h2> <p><a href="https://github.com/pydantic/pydantic/releases/tag/v2.13.3">GitHub release</a></p> <h3>What's Changed</h3> <h4>Fixes</h4> <ul> <li>Handle <code>AttributeError</code> subclasses with <code>from_attributes</code> by <a href="https://github.com/Viicos"><code>@Viicos</code></a> in <a href="https://redirect.github.com/pydantic/pydantic/pull/13096">#13096</a></li> </ul> <h2>v2.13.2 (2026-04-17)</h2> <p><a href="https://github.com/pydantic/pydantic/releases/tag/v2.13.2">GitHub release</a></p> <h3>What's Changed</h3> <h4>Fixes</h4> <ul> <li>Fix <code>ValidationInfo.field_name</code> missing with <code>model_validate_json()</code> by <a href="https://github.com/Viicos"><code>@Viicos</code></a> in <a href="https://redirect.github.com/pydantic/pydantic/pull/13084">#13084</a></li> </ul> <h2>v2.13.1 (2026-04-15)</h2> <p><a href="https://github.com/pydantic/pydantic/releases/tag/v2.13.1">GitHub release</a></p> <h3>What's Changed</h3> <h4>Fixes</h4> <ul> <li>Fix <code>ValidationInfo.data</code> missing with <code>model_validate_json()</code> by <a href="https://github.com/davidhewitt"><code>@davidhewitt</code></a> in <a href="https://redirect.github.com/pydantic/pydantic/pull/13079">#13079</a></li> </ul> <h2>v2.13.0 (2026-04-13)</h2> <p><a href="https://github.com/pydantic/pydantic/releases/tag/v2.13.0">GitHub release</a></p> <p>The highlights of the v2.13 release are available in the <a href="https://pydantic.dev/articles/pydantic-v2-13-release">blog post</a>.</p> <!-- raw HTML omitted --> </blockquote> <p>... (truncated)</p> </details> <details> <summary>Commits</summary> <ul> <li><a href="https://github.com/pydantic/pydantic/commit/cf67d4b3193c3fe43ede18612ed62785eee11382"><code>cf67d4b</code></a> Fix linting</li> <li><a href="https://github.com/pydantic/pydantic/commit/f0d8a214a5803036db46a56b1f62f1e56b81d662"><code>f0d8a21</code></a> Prepare release v2.13.4</li> <li><a href="https://github.com/pydantic/pydantic/commit/5e3fe1d41a00f441204241c66078003ae0391f9a"><code>5e3fe1d</code></a> Check for pydantic tag pattern in CI</li> <li><a href="https://github.com/pydantic/pydantic/commit/7f9edcc2a191d2eaa9751220eb910914e716a686"><code>7f9edcc</code></a> Document tagging conventions</li> <li><a href="https://github.com/pydantic/pydantic/commit/b46a0c9b8a4dd967fda8ec1a92f6437076bf262c"><code>b46a0c9</code></a> Adapt <code>pydantic-core</code> linker flags on macOS</li> <li><a href="https://github.com/pydantic/pydantic/commit/50629c851e61d887d5420452c311ec6203f1f400"><code>50629c8</code></a> Update to PyPy 7.3.22</li> <li><a href="https://github.com/pydantic/pydantic/commit/8522ebb71e5e9a6f7188af5f009f01785b8cf725"><code>8522ebb</code></a> Preserve <code>RootModel</code> core metadata</li> <li><a href="https://github.com/pydantic/pydantic/commit/a37f3aff090ca342dc5f48304889963530b993f8"><code>a37f3af</code></a> Adapt <code>MISSING</code> sentinel test to work with unreleased <code>typing_extensions</code> ver...</li> <li><a href="https://github.com/pydantic/pydantic/commit/909259a9df660518033aa686b689f045a6eaf9d2"><code>909259a</code></a> Remove Logfire example in documentation</li> <li><a href="https://github.com/pydantic/pydantic/commit/2c4174c366606fc2dc46cb806833a080aefa77df"><code>2c4174c</code></a> Bump libc from 0.2.155 to 0.2.185</li> <li>Additional commits viewable in <a href="https://github.com/pydantic/pydantic/compare/v2.12.5...v2.13.4">compare view</a></li> </ul> </details> <br /> [](https://docs.github.com/en/github/managing-security-vulnerabilities/about-dependabot-security-updates#about-compatibility-scores) Dependabot will resolve any conflicts with this PR as long as you don't alter it yourself. You can also trigger a rebase manually by commenting `@dependabot rebase`. [//]: # (dependabot-automerge-start) [//]: # (dependabot-automerge-end) --- <details> <summary>Dependabot commands and options</summary> <br /> You can trigger Dependabot actions by commenting on this PR: - `@dependabot rebase` will rebase this PR - `@dependabot recreate` will recreate this PR, overwriting any edits that have been made to it - `@dependabot show <dependency name> ignore conditions` will show all of the ignore conditions of the specified dependency - `@dependabot ignore this major version` will close this PR and stop Dependabot creating any more for this major version (unless you reopen the PR or upgrade to it yourself) - `@dependabot ignore this minor version` will close this PR and stop Dependabot creating any more for this minor version (unless you reopen the PR or upgrade to it yourself) - `@dependabot ignore this dependency` will close this PR and stop Dependabot creating any more for this dependency (unless you reopen the PR or upgrade to it yourself) </details> <!-- readthedocs-preview swarms start --> ---- 📚 Documentation preview 📚: https://swarms--1597.org.readthedocs.build/en/1597/ <!-- readthedocs-preview swarms end -->
![dependabot[bot]](https://avatars.githubusercontent.com/in/29110?v=4)
Proposed by dependabot[bot]Bumps [actions/dependency-review-action](https://github.com/actions/dependency-review-action) from 4 to 5. <details> <summary>Release notes</summary> <p><em>Sourced from <a href="https://github.com/actions/dependency-review-action/releases">actions/dependency-review-action's releases</a>.</em></p> <blockquote> <h2>5.0.0</h2> <p>This is a new major version of the Dependency Review Action which updates the runtime to node24. This requires a minimum Actions Runner version <a href="https://github.com/actions/runner/releases/tag/v2.327.1">v2.327.1</a> to run.</p> <h2>What's Changed</h2> <ul> <li>Add .github/copilot-instructions.md for Copilot coding agent by <a href="https://github.com/ahpook"><code>@ahpook</code></a> in <a href="https://redirect.github.com/actions/dependency-review-action/pull/1067">actions/dependency-review-action#1067</a></li> <li>Update Node.js runtime from 20 to 24 by <a href="https://github.com/scottschreckengaust"><code>@scottschreckengaust</code></a> in <a href="https://redirect.github.com/actions/dependency-review-action/pull/1084">actions/dependency-review-action#1084</a></li> <li>Bump spdx-license-ids from 3.0.20 to 3.0.23 by <a href="https://github.com/mongolyy"><code>@mongolyy</code></a> in <a href="https://redirect.github.com/actions/dependency-review-action/pull/1091">actions/dependency-review-action#1091</a></li> <li>docs: bump actions/checkout from v4 to v6 in workflow examples by <a href="https://github.com/Marukome0743"><code>@Marukome0743</code></a> in <a href="https://redirect.github.com/actions/dependency-review-action/pull/1077">actions/dependency-review-action#1077</a></li> <li>fix: patched version display for advisories with non-strict semver ranges (e.g. Maven beta versions) by <a href="https://github.com/tspascoal"><code>@tspascoal</code></a> in <a href="https://redirect.github.com/actions/dependency-review-action/pull/1076">actions/dependency-review-action#1076</a></li> <li>Resolve security findings by <a href="https://github.com/AshelyTC"><code>@AshelyTC</code></a> in <a href="https://redirect.github.com/actions/dependency-review-action/pull/1094">actions/dependency-review-action#1094</a></li> <li>v5.0.0 release branch by <a href="https://github.com/ahpook"><code>@ahpook</code></a> in <a href="https://redirect.github.com/actions/dependency-review-action/pull/1098">actions/dependency-review-action#1098</a></li> </ul> <h2>New Contributors</h2> <ul> <li><a href="https://github.com/scottschreckengaust"><code>@scottschreckengaust</code></a> made their first contribution in <a href="https://redirect.github.com/actions/dependency-review-action/pull/1084">actions/dependency-review-action#1084</a></li> <li><a href="https://github.com/mongolyy"><code>@mongolyy</code></a> made their first contribution in <a href="https://redirect.github.com/actions/dependency-review-action/pull/1091">actions/dependency-review-action#1091</a></li> <li><a href="https://github.com/Marukome0743"><code>@Marukome0743</code></a> made their first contribution in <a href="https://redirect.github.com/actions/dependency-review-action/pull/1077">actions/dependency-review-action#1077</a></li> </ul> <p><strong>Full Changelog</strong>: <a href="https://github.com/actions/dependency-review-action/compare/v4.9.0...v5.0.0">https://github.com/actions/dependency-review-action/compare/v4.9.0...v5.0.0</a></p> <h2>Dependency Review Action 4.9.0</h2> <p>This feature release contains a couple of notable changes:</p> <ul> <li>There is a new configuration option <code>show_patched_versions</code> which will add a column to the output, showing the fix version of each vulnerable dependency. Thanks <a href="https://github.com/felickz"><code>@felickz</code></a>!</li> <li>Runs which do not display OpenSSF scorecards no longer fetch scorecard information; previously it was fetched regardless of whether or not it was displayed, causing unneccessary slowness. Great catch <a href="https://github.com/jantiebot"><code>@jantiebot</code></a>!</li> <li>There are a couple of fixes to purl parsing which should improve match accuracy for <code>allow-package-dependency</code> lists, including case (in)sensitivity and url-encoded namespaces Thanks <a href="https://github.com/juxtin"><code>@juxtin</code></a>!</li> </ul> <h2>What's Changed</h2> <ul> <li>Compare normalized purls to account for encoding quirks by <a href="https://github.com/juxtin"><code>@juxtin</code></a> in <a href="https://redirect.github.com/actions/dependency-review-action/pull/1056">actions/dependency-review-action#1056</a></li> <li>Make purl comparisons case insensitive by <a href="https://github.com/juxtin"><code>@juxtin</code></a> in <a href="https://redirect.github.com/actions/dependency-review-action/pull/1057">actions/dependency-review-action#1057</a></li> <li>Feat: Add <code>Patched Version</code> to <code>Vulnerabilities</code> summary by <a href="https://github.com/felickz"><code>@felickz</code></a> in <a href="https://redirect.github.com/actions/dependency-review-action/pull/1045">actions/dependency-review-action#1045</a></li> <li>fix: only get scorecard levels if user wants to see the OpenSSF scorecard by <a href="https://github.com/jantiebot"><code>@jantiebot</code></a> in <a href="https://redirect.github.com/actions/dependency-review-action/pull/1060">actions/dependency-review-action#1060</a></li> <li>Bump actions/stale from 10.1.0 to 10.2.0 by <a href="https://github.com/dependabot"><code>@dependabot</code></a>[bot] in <a href="https://redirect.github.com/actions/dependency-review-action/pull/1058">actions/dependency-review-action#1058</a></li> <li>Bump actions/checkout from 4 to 6 by <a href="https://github.com/dependabot"><code>@dependabot</code></a>[bot] in <a href="https://redirect.github.com/actions/dependency-review-action/pull/1021">actions/dependency-review-action#1021</a></li> <li>Updates for release 4.9.0 by <a href="https://github.com/ahpook"><code>@ahpook</code></a> in <a href="https://redirect.github.com/actions/dependency-review-action/pull/1064">actions/dependency-review-action#1064</a></li> </ul> <h2>New Contributors</h2> <ul> <li><a href="https://github.com/jantiebot"><code>@jantiebot</code></a> made their first contribution in <a href="https://redirect.github.com/actions/dependency-review-action/pull/1060">actions/dependency-review-action#1060</a></li> </ul> <p><strong>Full Changelog</strong>: <a href="https://github.com/actions/dependency-review-action/compare/v4.8.3...v4.9.0">https://github.com/actions/dependency-review-action/compare/v4.8.3...v4.9.0</a></p> <h2>4.8.3</h2> <h2>Dependency Review Action v4.8.3</h2> <p>This is a bugfix release that updates a number of upstream dependencies and includes a fix for the earlier feature that detected oversized summaries and upload them as artifacts, which could occasionally crash the action.</p> <p>We have also updated the release process to use a long-lived <code>v4</code> <strong>branch</strong> for the action, instead of a force-pushed tag, which aligns better with git branching strategies; the change should be transparent to end users.</p> <h2>What's Changed</h2> <ul> <li>GitHub Actions can't push to our protected main by <a href="https://github.com/dangoor"><code>@dangoor</code></a> in <a href="https://redirect.github.com/actions/dependency-review-action/pull/1017">actions/dependency-review-action#1017</a></li> <li>Bump actions/stale from 9.1.0 to 10.1.0 by <a href="https://github.com/dependabot"><code>@dependabot</code></a>[bot] in <a href="https://redirect.github.com/actions/dependency-review-action/pull/995">actions/dependency-review-action#995</a></li> </ul> <!-- raw HTML omitted --> </blockquote> <p>... (truncated)</p> </details> <details> <summary>Commits</summary> <ul> <li><a href="https://github.com/actions/dependency-review-action/commit/a1d282b36b6f3519aa1f3fc636f609c47dddb294"><code>a1d282b</code></a> Merge pull request <a href="https://redirect.github.com/actions/dependency-review-action/issues/1098">#1098</a> from actions/ahpook/v5-release</li> <li><a href="https://github.com/actions/dependency-review-action/commit/eb6c199c5a85c7387f1f0b02b3ba5c6364740695"><code>eb6c199</code></a> update examples to show <a href="https://github.com/v5"><code>@v5</code></a></li> <li><a href="https://github.com/actions/dependency-review-action/commit/3943c2c5beaaaf1806eb3758273c203dabcbf89c"><code>3943c2c</code></a> v5.0.0 release branch</li> <li><a href="https://github.com/actions/dependency-review-action/commit/454943c880b147adbfe7de0cdd3ece1c00882033"><code>454943c</code></a> Merge pull request <a href="https://redirect.github.com/actions/dependency-review-action/issues/1094">#1094</a> from actions/ashelytc/security-findings</li> <li><a href="https://github.com/actions/dependency-review-action/commit/6d92a1228e9e9db334f02c09f84fe9217d2b4463"><code>6d92a12</code></a> revert <code>@typescript-eslint/parser</code> update</li> <li><a href="https://github.com/actions/dependency-review-action/commit/a8e5a7e93695b41abf6d1083cd220bee39a720f0"><code>a8e5a7e</code></a> Merge pull request <a href="https://redirect.github.com/actions/dependency-review-action/issues/1076">#1076</a> from tspascoal/fix-version-matching-for-non-string-s...</li> <li><a href="https://github.com/actions/dependency-review-action/commit/b6b7079031ef4ed61656c221988f1f3bcbf35101"><code>b6b7079</code></a> update <code>@typescript-eslint/parser</code> to 8.40.0</li> <li><a href="https://github.com/actions/dependency-review-action/commit/821a21dd691f162c4c5c2e9754a344accde9a208"><code>821a21d</code></a> update more dependencies</li> <li><a href="https://github.com/actions/dependency-review-action/commit/05aaaae45cf4c420de012addf2a72e3435ddaa63"><code>05aaaae</code></a> run npm audit fix</li> <li><a href="https://github.com/actions/dependency-review-action/commit/55d3e754501fc13c84b95637ce51f135012d41ea"><code>55d3e75</code></a> Merge pull request <a href="https://redirect.github.com/actions/dependency-review-action/issues/1077">#1077</a> from Marukome0743/docs/checkout</li> <li>Additional commits viewable in <a href="https://github.com/actions/dependency-review-action/compare/v4...v5">compare view</a></li> </ul> </details> <br /> [](https://docs.github.com/en/github/managing-security-vulnerabilities/about-dependabot-security-updates#about-compatibility-scores) Dependabot will resolve any conflicts with this PR as long as you don't alter it yourself. You can also trigger a rebase manually by commenting `@dependabot rebase`. [//]: # (dependabot-automerge-start) [//]: # (dependabot-automerge-end) --- <details> <summary>Dependabot commands and options</summary> <br /> You can trigger Dependabot actions by commenting on this PR: - `@dependabot rebase` will rebase this PR - `@dependabot recreate` will recreate this PR, overwriting any edits that have been made to it - `@dependabot show <dependency name> ignore conditions` will show all of the ignore conditions of the specified dependency - `@dependabot ignore this major version` will close this PR and stop Dependabot creating any more for this major version (unless you reopen the PR or upgrade to it yourself) - `@dependabot ignore this minor version` will close this PR and stop Dependabot creating any more for this minor version (unless you reopen the PR or upgrade to it yourself) - `@dependabot ignore this dependency` will close this PR and stop Dependabot creating any more for this dependency (unless you reopen the PR or upgrade to it yourself) </details> <!-- readthedocs-preview swarms start --> ---- 📚 Documentation preview 📚: https://swarms--1596.org.readthedocs.build/en/1596/ <!-- readthedocs-preview swarms end -->
Proposed by dependabot[bot]## Summary Adds a new documentation guide for production tool runtime safety and validation in Swarms. The guide covers narrow tool contracts, validation before side effects, secret handling, structured outputs, dry-run behavior for destructive actions, audit-friendly logs, and a reviewer checklist. ## Why this helps Tool safety is a recurring concern for agent systems because tools often bridge model output with files, APIs, tickets, payments, or databases. This guide gives contributors and users a practical checklist plus copyable Python examples that fit the existing Tools Reference section. ## Bounty eligibility This PR is intended as a `bounty-eligible` documentation contribution under the Swarms Documentation Bounty Initiative. Expected tier: Gold documentation contribution ($20-$50), because it adds a new major guide over 500 words with examples and a review checklist. ## Validation - Added the guide to `docs/swarms/tools/tool_runtime_safety.md` - Added the page to `docs/mkdocs.yml` under Tools Reference - Confirmed the new guide is 1,100+ words - Ran `git diff --check` - Attempted `mkdocs build --strict`, but this local machine does not have `mkdocs` installed <!-- readthedocs-preview swarms start --> ---- 📚 Documentation preview 📚: https://swarms--1595.org.readthedocs.build/en/1595/ <!-- readthedocs-preview swarms end -->
Proposed by IsjuanplayerFixes #1561 ## Problem `ContextCompressor` is now the default context-compression path for every `Agent(context_compression=True)` run, but had zero test coverage. Any regression in history collapsing or MEMORY.md handling would silently corrupt agent state. ## Solution Added `tests/agents/test_context_compressor.py` with 27 deterministic, network-free unit tests covering: - `__init__` — threshold boundary validation (0, -0.1, 1.1 raise; 1.0 is valid) and default values - `usage_ratio` — returns `0.0` for falsy `context_length`; correct ratio for a stubbed agent - `should_compress` — false below threshold, true at and above; no `max_loops`-mode gating (regression guard) - `_summarize` — raises `ValueError` when no model is available; passes `model`, `temperature`, `max_tokens` through to `litellm.completion`; falls back to `agent.model_name`; returns `response.choices[0].message.content` unchanged - `compress` — returns `None` for empty/whitespace history; calls `_summarize` with full history; calls `agent.short_memory.compact()` exactly once with preamble-wrapped summary; returns raw summary string - `maybe_compress` — skips `compress` when `should_compress` is False; calls it when True; catches and swallows all exceptions without propagating All LLM calls are mocked via `unittest.mock.patch` so the suite runs offline with no API keys required. ## Testing ``` pytest tests/agents/test_context_compressor.py -v # 27 passed in 61.59s ``` <!-- readthedocs-preview swarms start --> ---- 📚 Documentation preview 📚: https://swarms--1570.org.readthedocs.build/en/1570/ <!-- readthedocs-preview swarms end -->
Proposed by octo-patch- Implemented Node and Edge models to represent graph workflow components. - Created persistence functions to convert between workflow specifications and internal representations. - Developed visualization utilities using Graphviz for graphical representation of workflows. - Added error handling and logging for better debugging and user feedback. - **Description**: This PR refactors the monolithic `GraphWorkflow` class (originally ~3,500 lines in `swarms/structs/graph_workflow.py`) into a highly modularized package under `swarms/structs/graph_workflow/` to significantly improve codebase maintainability and readability. **Key improvements:** - **Models**: Moved `Node`, `Edge`, and `NodeType` into `swarms/structs/graph_workflow/models.py`. - **Backends**: Extracted `GraphBackend`, `NetworkXBackend`, and `RustworkxBackend` into `swarms/structs/graph_workflow/backends.py`. - **Persistence**: Abstracted complex `to_topology_spec` and `from_topology_spec` logic into `swarms/structs/graph_workflow/persistence.py`. - **Visualization**: Moved Graphviz digraph generation into `swarms/structs/graph_workflow/visualization.py`. - **Core**: The main `GraphWorkflow` class now lives in `swarms/structs/graph_workflow/main.py`. - **100% Backward Compatible**: Updated `swarms/structs/graph_workflow/__init__.py` and `swarms/structs/__init__.py` so that external imports to `GraphWorkflow` behave exactly as they did before. All 39 `GraphWorkflow` tests pass successfully. - **Issue**: N/A (Resolves tech debt and improves maintainability for `GraphWorkflow`) - **Dependencies**: No new dependencies added (existing optional dependencies like `graphviz` and `rustworkx` remain correctly insulated). - **Tag maintainer**: @kyegomez - **Twitter handle**: NO <!-- readthedocs-preview swarms start --> ---- 📚 Documentation preview 📚: https://swarms--1569.org.readthedocs.build/en/1569/ <!-- readthedocs-preview swarms end -->
Proposed by invaderinvalid## Description Adds worker_timeout, heartbeat_interval, and max_retries to HierarchicalSwarm. On timeout the subtask retries up to max_retries times then surfaces [FAILED] in the output — the swarm continues instead of hanging forever. Default worker_timeout=None preserves existing behaviour. ## Files Changed * `swarms/structs/hiearchical_swarm.py` * `tests/structs/test_hierarchical_swarm_timeout.py` * `examples/multi_agent/hiearchical_swarm/hierarchical_swarm_timeout_example.py` ## Issue #1554 ## Dependencies No extra dependencies required. ## Maintainer @kyegomez ## Twitter [@akc__2025](https://x.com/akc__2025) <!-- readthedocs-preview swarms start --> ---- 📚 Documentation preview 📚: https://swarms--1568.org.readthedocs.build/en/1568/ <!-- readthedocs-preview swarms end -->
Proposed by adichaudhary## Description Adds per-node retry and fallback annotations to the `AgentRearrange` flow DSL, so error handling lives next to the node that can fail rather than in every caller's try/except. Supported syntax: "A -> B!3 -> C" # retry B up to 3 times "A -> B!3>D -> C" # retry B 3 times, fall back to D "A -> B?D -> C" # route to D on first failure Fallback agents are resolved from the same agents list and validated at parse time — unknown names raise `ValueError` before execution starts. Plain flows with no annotations are completely unchanged. ## Files Changed * `swarms/structs/agent_rearrange.py` * `tests/structs/test_agent_rearrange.py` * `examples/agent_rearrange_retry_fallback_example.py` ## Issue #1556 ## Dependencies No extra dependencies required. ## Maintainer @kyegomez ## Twitter [@akc__2025](https://x.com/akc__2025) <!-- readthedocs-preview swarms start --> ---- 📚 Documentation preview 📚: https://swarms--1565.org.readthedocs.build/en/1565/ <!-- readthedocs-preview swarms end -->
Proposed by adichaudhary## Closes #1297 **Includes changes for Modify the summary generation logic in agent.py to use the same streaming callback pattern as planni** --- ## 🤖 AI Transparency Notice This PR was created by **gh-autofix** AI using **holo3-35b-a3b**. A human reviewer should inspect before merging. --- ## Root Cause The summary phase in agent.py's autonomous loop does not invoke the streaming callback mechanism used in planning and execution phases, causing silent completion until full response is generated. --- ## Changes Made swarms/agent.py, tests/agents/test_agent.py --- ## Fix Strategy Modify the summary generation logic in agent.py to use the same streaming callback pattern as planning and execution phases, ensuring on_token is called for each token generated during summary. --- ## Testing - Test command: npm test - Environment: Linux (Node.js) Review results: passed all tests --- ## Files Changed N/A --- **Review confidence: 85%** Notes: None <!-- readthedocs-preview swarms start --> ---- 📚 Documentation preview 📚: https://swarms--1564.org.readthedocs.build/en/1564/ <!-- readthedocs-preview swarms end -->
Proposed by wongtimothy147-lgtm## **Description** This PR introduces asynchronous streaming capabilities between nodes in the `AgentRearrange` structure. It allows agents to begin processing data as soon as it becomes available from the previous node, significantly reducing latency in long agent chains. ## **Key Changes** * **Asynchronous Pipeline**: Implemented `_execute_streaming_pipeline` using `asyncio.Queue` to manage real-time data flow. * **Buffering Strategies**: Added three configurable strategies: * `all`: Waits for the full output (default behavior). * `line`: Streams data line by line. * `tokens`: Streams data in fixed-size token chunks. * **Smart Fallback**: Integrated logic to detect if an agent supports `astream()`. If not, it gracefully falls back to synchronous execution without breaking the pipeline. * **Documentation**: Updated docstrings to reflect the new streaming parameters and architecture. ## **Testing Performed** Created `tests/structs/test_rearrange_streaming.py` to validate: 1. Successful streaming between multiple async agents. 2. Correct fallback when a synchronous callable is placed in the middle of a flow. 3. Buffering integrity across different strategies. --- **Closes #1558** Tagging @kyegomez for review as this relates to `swarms.structures`. <!-- readthedocs-preview swarms start --> ---- 📚 Documentation preview 📚: https://swarms--1563.org.readthedocs.build/en/1563/ <!-- readthedocs-preview swarms end -->
Proposed by villarroelsaad## Summary Add a test suite for `swarms/agents/context_compressor.py` at `tests/agents/test_context_compressor.py`. The `ContextCompressor` is now wired into every `Agent(context_compression=True)` (the default) and controls both in-memory history collapsing and the on-disk MEMORY.md wipe + archive flow. It currently has no tests. ## File - `tests/agents/test_context_compressor.py` — single file, mirrors the existing `tests/agents/` layout. ## Coverage checklist ### `__init__` validation - [ ] `threshold` outside `(0, 1]` raises `ValueError` (test `0`, `-0.1`, `1.1`). - [ ] Default values match the constructor defaults (`threshold=0.9`, `summarizer_temperature=0.2`, `summarizer_max_tokens=4000`). ### `usage_ratio` - [ ] Returns `0.0` when `agent.context_length` is falsy (`None` or `0`). - [ ] Returns `tokens / context_length` for a populated conversation (use a stub agent with a fake `short_memory.return_history_as_string()`). ### `should_compress` - [ ] Returns `False` when usage is below threshold. - [ ] Returns `True` at exactly the threshold. - [ ] Returns `True` above the threshold. - [ ] Does NOT gate on `max_loops` mode (regression — the old auto-only gate was removed when `context_compression` became the public toggle). ### `_summarize` - [ ] Raises `ValueError` when neither `summarizer_model` nor `agent.model_name` is set. - [ ] Passes `model`, `temperature`, and `max_tokens` through to `litellm.completion` (mock `litellm.completion`). - [ ] Returns `response.choices[0].message.content` unchanged. ### `compress` - [ ] Returns `None` when history is empty or whitespace-only. - [ ] Calls `_summarize` with the full history string. - [ ] Calls `agent.short_memory.compact(summary=...)` exactly once (mock the Conversation). - [ ] The summary string passed to `compact()` is wrapped with the `[Compressed Memory Summary]` preamble. - [ ] Returns the raw summary (without the preamble wrapper). ### `maybe_compress` - [ ] Returns `None` when `should_compress` is False (no summarize call). - [ ] Calls `compress` when `should_compress` is True. - [ ] Returns `None` and logs an error if `compress` raises — does not propagate the exception. ### Integration (end-to-end, no network) - [ ] Full pass with a real `Conversation(memory_md_path=tmp_path / 'MEMORY.md')` and a mocked `_summarize`: - MEMORY.md is wiped and re-seeded after compression. - `archive/history_<timestamp>.md` is created with the prior raw transcript. - `conversation_history` retains `system_prompt` + `rules` + summary block (no raw turns). ## Dependencies - `pytest`, `unittest.mock` — already in `tests/requirements.txt`. - Mock `litellm.completion` for every test that would otherwise hit the network. - Use `pytest`'s `tmp_path` fixture for any test that touches MEMORY.md on disk. ## Why Compression now runs for every agent by default. Any regression silently drops conversation history or corrupts MEMORY.md — both of which produce subtle, hard-to-reproduce bugs. A fast, deterministic unit-test suite catches these at PR time.
Proposed by kyegomez## Problem `GraphWorkflow` nodes are always individual agents. There is no way to use one `GraphWorkflow` as a node inside another, which rules out reusable graph modules and multi-level orchestration. ## Proposed feature A node can itself be a `GraphWorkflow`. The outer graph treats the inner graph as a single black-box node whose input is the node's upstream payload and whose output is the inner graph's final result. ## Design sketch - `GraphWorkflow.add_node(x)` accepts either an `Agent` or another `GraphWorkflow`. - Inner graph's inputs are merged upstream outputs; inner graph's final layer output becomes the node's output. - Topology serialization (`save_spec()` / `from_topology_spec()`) is extended to support nested specs — the inner graph's spec is embedded as `{"type": "subgraph", "spec": {...}}`. - Checkpoint format stores inner-graph state under the parent node's ID for clean restart. ## Tradeoff Checkpoint format has to handle nesting. Nested topology serialization adds a small amount of parsing complexity at load time. ## Files - `swarms/structs/graph_workflow.py` ## Why Enables reusable graph modules — a "research pipeline" subgraph can be dropped into multiple outer workflows. Also pairs with topology serialization for shareable, composable graph libraries.
Proposed by kyegomez## Problem `GraphWorkflow` currently walks the topology sequentially even when the DAG has independent branches. If the graph is `A -> B`, `A -> C`, `B -> D`, `C -> D`, today B and C execute one after the other despite having no data dependency on each other. ## Proposed feature Detect independent branches at run time and execute them concurrently using `ThreadPoolExecutor`. A correctness-preserving pure latency win. ## Design sketch - Topological sort groups nodes into "layers": layer N contains all nodes whose dependencies are in layer < N. - Each layer is executed concurrently with `ThreadPoolExecutor(max_workers=len(layer))`. - Per-run concurrency cap exposed as `max_parallel_nodes` on the constructor (default: CPU count). - Same deep-copy isolation pattern used in the recent `AgentRearrange.batch_run` refactor to prevent shared-state bugs. ## Files - `swarms/structs/graph_workflow.py` ## Why Pure latency improvement with no behavior change for serial graphs. DAGs with any width benefit immediately.
Proposed by kyegomez## Problem In `AgentRearrange`, each node blocks until the previous one fully completes before starting. On long chains (`A -> B -> C -> D`) where each agent streams tokens, downstream agents could begin processing partial output — today they can't. ## Proposed feature Opt-in streaming between nodes: downstream agents receive the upstream agent's token stream incrementally and start generating output before the upstream agent finishes. ## Design sketch - New flow option: `stream_between_nodes=True` on the `AgentRearrange` constructor. - Each node produces a generator; the next node consumes from it via an async queue. - Buffering strategy is configurable: `"all"` (wait for full chunk), `"line"` (per newline), or `"tokens"` (every N tokens). - Fallback to today's synchronous behavior when any node in the flow doesn't support streaming. ## Files - `swarms/structs/agent_rearrange.py` ## Why Meaningful latency win on long chains. A 4-agent pipeline where each agent takes 10s drops end-to-end wall-clock from ~40s to closer to the slowest single stage.
Proposed by kyegomez## Problem `AgentRearrange` retries and fallbacks are global — you can't express "retry B three times, and if it still fails, route to C" in the flow itself. Error handling has to live in the caller's try/except, which breaks the declarative model. ## Proposed feature Annotate individual nodes in the flow string with retry and fallback directives: ``` "A -> B!3 -> C" # B retries up to 3 times "A -> B!3>D -> C" # B retries 3 times, then falls back to D "A -> B?D -> C" # B on error routes to D ``` ## Design sketch - Extend the flow parser to recognize `!N` (retry count) and `>X` or `?X` (fallback agent). - Each node becomes a small state machine: `attempt`, on exception `retry or fallback or raise`. - Fallback agents are resolved from the same `agents` list; unknown names fail at parse time. ## Files - `swarms/structs/agent_rearrange.py` ## Why Puts error handling where it belongs — next to the node that can fail — instead of in every caller.
Proposed by kyegomez## Problem Workers in `HierarchicalSwarm` that call external tools (MCP, browsers, shell) can hang indefinitely. There is no heartbeat, no timeout, and no reassignment — one stuck worker blocks the entire plan. ## Proposed feature - Per-worker heartbeat interval (default 30s). - Per-subtask timeout (configurable on the swarm and overridable per subtask). - On timeout: cancel the worker's task, log the failure, and reassign the subtask to another worker (or mark it FAILED after N retries). ## Design sketch - `HierarchicalSwarm.__init__` gains `worker_timeout: Optional[int] = None` and `heartbeat_interval: int = 30`. - Worker execution wrapped in a `ThreadPoolExecutor` future with `.result(timeout=...)`. - On `concurrent.futures.TimeoutError`, the subtask goes back into the queue with an incremented retry count. - After `max_retries` (default 2), the subtask is marked FAILED and surfaced in the judge verdict. ## Files - `swarms/structs/hiearchical_swarm.py` ## Why Production deployments routinely hit hung workers when tools misbehave. Without timeouts, one bad worker kills the entire swarm run.
Proposed by kyegomez## Problem Today when the judge rejects a director's plan in `HierarchicalSwarm`, the swarm just loops the same plan. There is no way for the director to adapt — issue new subtasks, reassign failed ones to different workers, or change the decomposition. ## Proposed feature When the judge returns a rejection (or a low score), the director should be able to: - Issue brand-new subtasks based on the judge's feedback - Reassign specific failed subtasks to different workers - Modify the dependency order between existing subtasks Rather than restarting the whole plan, the director does an incremental replan informed by what went wrong. ## Design sketch - Judge verdict schema grows a `feedback` field (already partially present) and a `failed_subtasks: List[str]` list. - On `REVISE`, the director is called with the original plan, the judge feedback, and the per-subtask results; it returns a `ReplanAction` (ADD / REASSIGN / REORDER / DROP). - The swarm applies the action and re-runs only the affected subtasks. ## Files - `swarms/structs/hiearchical_swarm.py` ## Why Closes the feedback loop — the judge verdict currently has no way to actually drive adaptation. This is the biggest quality lift available for hierarchical runs.
Proposed by kyegomez## Summary - reload `.env` discovery when the CLI entrypoint runs so commands use the caller current working directory - resolve `.env` deterministically from the current directory tree first, then fall back to the user home directory - reuse the same resolver in `setup-check` and add regression tests for home fallback and runtime reload behavior ## Testing - `. .venv/bin/activate && pytest tests/test_env.py tests/test_cli.py -q` - manual repro: verified home-only `.env` fallback loads `OPENAI_API_KEY` - manual repro: verified `main()` reloads `.env` after changing into a project directory Fixes #1541 <!-- readthedocs-preview swarms start --> ---- 📚 Documentation preview 📚: https://swarms--1547.org.readthedocs.build/en/1547/ <!-- readthedocs-preview swarms end -->
Proposed by alexanderkreidich## Description This PR bounds drift-triggered reruns in `SequentialWorkflow`. `_run_drift_detection()` currently reruns the pipeline in a `while True` loop until the score crosses the threshold. If the score never improves, the workflow can continue rerunning indefinitely and burn tokens without a bounded exit path. This patch is intentionally small: - add `drift_max_reruns` with a conservative default - validate the new setting - stop rerunning once the cap is reached and return the latest pipeline result - add regression coverage for both bounded reruns and successful recovery ## Files Changed - `swarms/structs/sequential_workflow.py` - `tests/structs/test_sequential_workflow.py` ## Issue Closes #1536 ## Dependencies No extra dependencies required. ## Maintainer @kyegomez ## Test plan - [x] `PYTHONPATH=. python -m pytest tests/structs/test_sequential_workflow.py -k 'drift' -q` ## Why this scope Recent merged bugfixes in this repo tend to be narrow, test-backed, and easy to reason about. This PR only adds a bounded retry guard to the confirmed infinite-rerun path and leaves the broader drift-detection feature intact. <!-- readthedocs-preview swarms start --> ---- 📚 Documentation preview 📚: https://swarms--1540.org.readthedocs.build/en/1540/ <!-- readthedocs-preview swarms end -->
Proposed by shaun0927## Description This PR fixes checkpoint filename collisions in `GraphWorkflow`. The current checkpoint path only uses the task hash and layer index, so two workflows that share a `checkpoint_dir` and task string can reuse each other's checkpoint files. The same filename pattern also ignores the loop index, so multi-loop runs can pick up stale outputs from earlier loops. This PR keeps the change focused: - derive a stable checkpoint namespace from workflow metadata/topology - include the loop index in the checkpoint prefix - update checkpoint cleanup to match the new prefix - add regression tests for workflow-level and loop-level isolation ## Files Changed - `swarms/structs/graph_workflow.py` - `tests/structs/test_graph_workflow.py` ## Issue Closes #1537 ## Dependencies No extra dependencies required. ## Maintainer @kyegomez ## Test plan - [x] `PYTHONPATH=. python -m pytest tests/structs/test_graph_workflow.py -k 'checkpoint' -q` ## Why this scope Recent merges here land best when the PR addresses one concrete failure mode, proves it with a regression test, and does not mix in unrelated refactors. This patch stays inside checkpoint naming/cleanup behavior only. <!-- readthedocs-preview swarms start --> ---- 📚 Documentation preview 📚: https://swarms--1539.org.readthedocs.build/en/1539/ <!-- readthedocs-preview swarms end -->
Proposed by shaun0927## Description This PR fixes a code-generation sink in `write_autoswarm_file()`. The autoswarm writer previously interpolated `swarm_architecture.max_loops` directly into generated Python source. If that field contained a non-integer string expression, the generated module embedded executable code instead of a validated literal. This change keeps the PR intentionally narrow: - validate/coerce `swarm_architecture.max_loops` to an integer-compatible value before emission - raise a clear `ValueError` for unsafe / invalid values - add a regression test covering the failure mode ## Files Changed - `swarms/agents/auto_generate_swarm_config.py` - `tests/agents/test_autoswarm_writer.py` ## Issue Closes #1535 ## Dependencies No extra dependencies required. ## Maintainer @kyegomez ## Test plan - [x] `PYTHONPATH=. python -m pytest tests/agents/test_autoswarm_writer.py -k 'swarm_max_loops' -q` ## Why this scope Recent merged PRs in this repo tend to land when they stay tightly scoped, include a direct regression test, and avoid bundling adjacent cleanups. This PR only fixes the confirmed `max_loops` generation path and leaves the rest of autoswarm codegen unchanged. <!-- readthedocs-preview swarms start --> ---- 📚 Documentation preview 📚: https://swarms--1538.org.readthedocs.build/en/1538/ <!-- readthedocs-preview swarms end -->
Proposed by shaun0927**Describe the bug** `GraphWorkflow` checkpoint filenames are currently derived from the task hash and layer index only. When multiple workflows share the same `checkpoint_dir` and task string, they can reuse each other's checkpoint files. The same naming scheme also ignores the loop index, so multi-loop runs can pick up stale data from a previous loop. **To Reproduce** 1. Create two different `GraphWorkflow` instances that share the same `checkpoint_dir`. 2. Run the first workflow on task `"shared task"` so it writes checkpoints. 3. Run the second workflow on the same task string. 4. The second workflow can load the first workflow's checkpoint files because the filename namespace is the same. At HEAD the filename pattern is effectively: ```python f"{sha256(task)[:16]}_layer_{layer_idx}.json" ``` so workflow identity and loop identity are both missing from the checkpoint path. **Expected behavior** Checkpoint filenames should include enough stable workflow identity (for example topology/name namespace) and loop index to avoid cross-workflow or cross-loop collisions while still allowing resume across restarts for the same logical workflow. **Additional context** - Confirmed locally against `master` (`cc1667a1`). - Relevant code: `swarms/structs/graph_workflow.py:1791-1816`, `1993-2000`, and `2493-2498`. - I verified locally that two workflows sharing the same task string resolve to the same checkpoint path and that stale checkpoint data is readable by the second workflow. - Related feature issue/PR: #1484 and #1498. I did not find an existing issue covering checkpoint namespace collisions or stale replay across workflows/loops.
Proposed by shaun0927**Describe the bug** `SequentialWorkflow._run_drift_detection()` reruns the pipeline in a `while True` loop until the drift score crosses the threshold. If the drift score stays low, the workflow keeps rerunning without any retry ceiling. That can burn tokens indefinitely and prevents the workflow from terminating in a bounded way when the judge never improves. **To Reproduce** 1. Create a `SequentialWorkflow` with `drift_detection=True`. 2. Mock the drift agent so it always returns a score below the threshold. 3. Mock `agent_rearrange.run()` to return any string. 4. Call `run()`. At HEAD the loop is: ```python while True: ... if score >= self.drift_threshold: break result = self.agent_rearrange.run(**run_kwargs) ``` with no retry budget or timeout. **Expected behavior** Drift-triggered reruns should stop after a bounded number of attempts (or an explicit time budget) and return the latest result or raise a controlled failure. **Additional context** - Confirmed locally against `master` (`cc1667a1`). - Relevant code: `swarms/structs/sequential_workflow.py:231-257`. - In a local source-derived repro with an always-low judge score, the workflow reran hundreds of times in well under a second before I interrupted it. - Related feature issue/PR: #1517 and #1522. I did not find an existing issue for the missing rerun cap itself.
Proposed by shaun0927**Describe the bug** `write_autoswarm_file()` interpolates `swarm_architecture.max_loops` directly into generated Python source instead of validating or literal-formatting it first. That means a non-integer string value is emitted as executable Python code inside the generated module. **To Reproduce** 1. Call `write_autoswarm_file()` with a config whose `swarm_architecture.max_loops` is a string expression instead of an integer. 2. Write the generated file. 3. Import or execute the generated module. Minimal example: ```python config = { "agents": [{"agent_name": "Agent A", "system_prompt": "x"}], "swarm_architecture": { "name": "Research Pipeline", "swarm_type": "SequentialWorkflow", "max_loops": "(__import__('builtins').globals().__setitem__('INJECTED_FLAG', True) or 1)", }, } ``` At HEAD, the generated file contains: ```python max_loops=(__import__('builtins').globals().__setitem__('INJECTED_FLAG', True) or 1), ``` Locally I verified that the side effect runs when the generated module is imported. **Expected behavior** `max_loops` should be validated/coerced to an integer-compatible value before code generation, or rejected with a `ValueError`. **Additional context** - Confirmed locally against `master` (`cc1667a1`). - Relevant code: `swarms/agents/auto_generate_swarm_config.py:346-349` - This seems especially important because the project positions itself as enterprise-grade / production-ready, and this path writes ready-to-run Python files from LLM-derived config. - I did not find an existing issue covering this specific code-generation sink; the related autoswarm issue/PRs I found were #1487, #1488, and #1489.
Proposed by shaun0927## Description This PR parses self.flow once at init into a cached self._execution_plan: List[List[str]] instead of re-parsing on every _run() call. The cache rebuilds automatically via set_custom_flow(), add_agent(), and remove_agent(). Three targeted tests cover plan caching and validation. ## Files Changed * `swarms/structs/agent_rearrange.py` * `tests/structs/test_agent_rearrange.py` * `examples/multi_agent/agent_rearrange_examples/example_agent_rearrange.py` ## Issue #1461 ## Dependencies No extra dependencies required. ## Maintainer @kyegomez ## Twitter @akc__2025 <!-- readthedocs-preview swarms start --> ---- 📚 Documentation preview 📚: https://swarms--1534.org.readthedocs.build/en/1534/ <!-- readthedocs-preview swarms end -->
Proposed by adichaudhary1
Proposed by 3lokreddy## Description This PR standardizes the spelling of hierarchical across the codebase to remove inconsistent typo variants (hiearchical) in module names, imports, example paths, and documentation. The update includes: - Canonical module/file renames to hierarchical naming. - Import/reference updates in core structs, tests, and docs. - Example/documentation path updates so links and usage examples match canonical names. - Compatibility shim modules for legacy typoed import paths with deprecation warnings, so existing users do not break immediately. This resolves confusion for contributors and users while preserving backward compatibility during migration. ## Files Changed * Core modules and routing: - swarms/structs/hierarchical_swarm.py - swarms/structs/hybrid_hierarchical_peer_swarm.py - swarms/prompts/hierarchical_system_prompt.py - swarms/structs/swarm_router.py - swarms/structs/__init__.py - swarms/schemas/swarms_api_schemas.py - swarms/structs/auto_swarm_builder.py * Compatibility shims: - swarms/structs/hiearchical_swarm.py - swarms/structs/hybrid_hiearchical_peer_swarm.py - swarms/prompts/hiearchical_system_prompt.py * Tests: - tests/structs/test_hierarchical_swarm.py - tests/test_main_features.py * Root/examples renames and updates: - hierarchical_swarm_example.py - examples/multi_agent/hierarchical_swarm - examples/guides/hierarchical_marketing_team.py - examples/voice_agents/hierarchical_speech_swarm.py - examples/README.md - examples/multi_agent/README.md - examples/guides/README.md - examples/voice_agents/README.md * Documentation normalization: - docs/llm.txt - docs/mkdocs.yml - docs/examples/index.md - docs/examples/marketing_team.md - docs/performance_improvement_ideas.md - docs/swarms/examples/hhcs_examples.md - docs/swarms/examples/hierarchical_swarm_example.md - docs/swarms/examples/swarm_router.md - docs/swarms/structs/auto_swarm_builder.md - docs/swarms/structs/hhcs.md - docs/swarms/structs/hierarchical_swarm.md - docs/swarms/structs/index.md - docs/swarms/structs/swarm_router.md ## Issue #1504 ## Dependencies No extra dependencies required. ## Maintainer @kyegomez ## Twitter [@akc__2025](https://x.com/akc__2025) <!-- readthedocs-preview swarms start --> ---- 📚 Documentation preview 📚: https://swarms--1511.org.readthedocs.build/en/1511/ <!-- readthedocs-preview swarms end -->
Proposed by adichaudhary