DAO Proposals & Community
View active proposals, submit new ideas, and connect with the SWARMS community.
## Problem ReflexionAgent had the **same death spiral issue as IRE agent**, causing excessive iterations and API calls: 1. **Fragile score extraction** - Failed to parse scores from LLM responses with markdown or varied formatting 2. **Never triggered early termination** - Score defaulted to 0.5 when parsing failed, which never exceeded 0.9 threshold 3. **Always ran full iterations** - Even simple tasks used all max_loops iterations 4. **Exceeded timeout thresholds** - Simple tasks: 61s, Complex tasks: 203s 5. **Wasted API calls** - 9-15 LLM calls per task instead of 3 ## Root Cause Identical to IRE agent issue: - Early termination logic existed but depended on score extraction - Score parsing used single fragile regex pattern: `r"(?:final|overall)\s+score:?\s*(\d+(?:\.\d+)?)"` - LLM responses with markdown (`**Score**: 8/10`) or different formats (`Rating: 8/10`) failed to parse - When extraction failed → defaulted to 0.5 → never met 0.9 threshold → ran all iterations ## Solution Applied the **proven fix pattern from IRE agent** with robust score extraction and improved termination logic. ### 1. Robust Score Extraction Added `_extract_score_robust()` method with multiple fallback strategies: ```python def _extract_score_robust(self, evaluation: str) -> float: # Strategy 1: Multiple regex patterns (handles markdown, different formats) score_patterns = [ r"(?:final|overall)\s+score:?\s*(\d+(?:\.\d+)?)", r"score:?\s*(\d+(?:\.\d+)?)\s*/\s*10", r"(?:rating|grade):?\s*(\d+(?:\.\d+)?)\s*/\s*10", r"(?:rating|grade):?\s*(\d+(?:\.\d+)?)", ] # Strategy 2: Context-aware patterns (X/10, X out of 10) # Strategy 3: Sentiment analysis fallback # Default: 0.6 (better than old 0.5) Now handles: - **Final Score**: 8/10 ✅ - Rating: 8.6/10 ✅ - Grade: 8 out of 10 ✅ - Markdown formatting ✅ - Sentiment-based scoring ✅ 2. Configuration Constants EARLY_TERMINATION_THRESHOLD = 0.8 # Lower than 0.9 for realistic termination DEFAULT_SCORE = 0.6 # Higher than 0.5 to increase termination chance SCORE_IMPROVEMENT_THRESHOLD = 0.05 # Minimum improvement to continue 3. Dual Termination Conditions # Condition 1: Score is high enough if current_score >= EARLY_TERMINATION_THRESHOLD: # 0.8 instead of 0.9 logger.info(f"✓ High score achieved ({current_score:.2f}). Stopping early.") break # Condition 2: Score not improving if iteration > 0 and (current_score - prev_score) < SCORE_IMPROVEMENT_THRESHOLD: logger.info(f"✓ Score improvement minimal. Stopping early.") break 4. Progress Logging ============================================================ Processing task 1/1 ============================================================ Task: Explain photosynthesis in one sentence... --- Iteration 1/3 --- Evaluation complete. Score: 0.80 Iteration 1 complete | Score: 0.80 | Best: 0.80 ✓ High score achieved (0.80 >= 0.8). Stopping early. ============================================================ Task complete | Iterations used: 1/3 | Best score: 0.80 ============================================================ Changes Modified Files: - swarms/agents/flexion_agent.py - Core ReflexionAgent implementation Key Changes: - Line 2: Added import re - Lines 11-14: Added configuration constants - Lines 306-371: Added _extract_score_robust() method - Lines 439-443: Updated evaluate() to use robust extraction - Lines 603-673: Enhanced termination logic and progress logging <!-- readthedocs-preview swarms start --> ---- 📚 Documentation preview 📚: https://swarms--1266.org.readthedocs.build/en/1266/ <!-- readthedocs-preview swarms end -->
# Fix: IRE Agent Infinite Iteration and Performance Issues ## Problem The Iterative Reflective Expansion (IRE) agent had critical issues causing it to run indefinitely or excessively, especially with complex prompts or higher `max_iterations` values: 1. **No early termination** - Always ran full iterations even when excellent solutions were found 2. **Score parsing failures** - LLM responses with markdown formatting (`**Score**: 0.9`) failed to parse, defaulting to 0.0, triggering unnecessary revisions 3. **Exponential path growth** - Paths multiplied uncontrollably (5 → 15 → 45 → ...) 4. **No path limits** - Could accumulate hundreds of paths per iteration 5. **Excessive LLM calls** - Up to 150+ calls for simple tasks 6. **Poor visibility** - No progress logging to understand what was happening ## Solution Implemented comprehensive fixes to control iteration behavior while maintaining reasoning quality: ### 1. Robust Score Extraction (`_extract_score_robust`) - Handles markdown formatting in LLM responses - Multiple fallback strategies: regex patterns, sentiment analysis - Default score of 0.5 (instead of 0.0) prevents unnecessary revisions - Clamps scores to valid 0.0-1.0 range ### 2. Hard Path Limits - `MAX_PATHS_PER_ITERATION = 5` enforced throughout - Initial hypotheses limited to 5 paths - Revisions per path capped at 3 - Path selection enforces hard limits with fallback ### 3. Early Termination - Score ≥ 0.9: Immediate termination - Score ≥ 0.85: Marked as high-quality - 2+ high-quality paths after iteration 1: Stop iterating - Prevents wasted computation on already-good solutions ### 4. Comprehensive Progress Logging - Clear iteration headers and summaries - Per-path simulation status - Score tracking (iteration best & overall best) - High-quality path counts - Helps debug and understand reasoning progress ### 5. Improved Path Selection - Truncates long paths for LLM display (prevents context overflow) - Falls back to first N paths if LLM selection fails - Always returns exactly `MAX_PATHS_PER_ITERATION` paths ### 6. Better Extraction Parsing - Handles both plain text and markdown formatting - Case-insensitive matching - Robust error handling ## Changes **Modified Files:** - `swarms/agents/i_agent.py` - Core IRE agent implementation **Key Changes:** - Added configuration constants (lines 40-44) - New `_extract_score_robust()` method (lines 87-142) - Updated `simulate_path()` with better parsing (lines 170-216) - Improved `select_promising_paths()` with hard limits (lines 263-310) - Rewrote `run()` method with termination logic (lines 339-450) ## Configuration Tunable constants in `swarms/agents/i_agent.py`: ```python MAX_PATHS_PER_ITERATION = 5 # Max paths to keep per iteration SCORE_THRESHOLD = 0.7 # Revise paths below this score EARLY_TERMINATION_SCORE = 0.85 # High-quality threshold DEFAULT_SCORE = 0.5 # Fallback when parsing fails Testing Before Fix: - Simple prompt with max_iterations=5: Could run indefinitely or take minutes - Complex prompts: Never terminated, exponential path growth After Fix: from swarms.agents.reasoning_agents import ReasoningAgentRouter # Test 1: Simple prompt (triggers early termination) router = ReasoningAgentRouter(swarm_type="ire", model_name="gpt-4o-mini", num_samples=3) result = router.run("Explain photosynthesis in one sentence.") # Expected: Terminates after 1 iteration with score 0.9+ # Test 2: Complex prompt (runs full iterations with control) complex_prompt = """ Design a DDoS prevention algorithm for cloud infrastructure handling 1M requests/sec... """ result = router.run(complex_prompt) # Expected: Runs 3 iterations, max 5 paths each, completes in reasonable time Run: python ire.py Performance Impact Before: - Simple tasks: 50-150+ LLM calls - Runtime: Minutes or indefinite - Path count: Uncontrolled growth After: - Simple tasks: 1-5 LLM calls (early termination) - Complex tasks: 15-45 LLM calls (3 iterations × 5 paths) - Runtime: Seconds to complete - Path count: Hard-limited to 5 per iteration Breaking Changes None. All changes are internal improvements. The API remains unchanged. Related Issues Fixes issues where IRE agent: - Never terminates with max_iterations > 1 - Runs excessively with complex prompts - Provides no visibility into reasoning progress <!-- readthedocs-preview swarms start --> ---- 📚 Documentation preview 📚: https://swarms--1265.org.readthedocs.build/en/1265/ <!-- readthedocs-preview swarms end -->
Updates the requirements on [mypy-protobuf](https://github.com/nipunn1313/mypy-protobuf) to permit the latest version. <details> <summary>Changelog</summary> <p><em>Sourced from <a href="https://github.com/nipunn1313/mypy-protobuf/blob/main/CHANGELOG.md">mypy-protobuf's changelog</a>.</em></p> <blockquote> <h2>4.0.0</h2> <ul> <li>BREAKING: Drop support for <code>py_generic_services</code> as it was removed from the protobuf compiler starting in version 6.30 <ul> <li><a href="https://protobuf.dev/news/2024-10-02/#rpc-service-interfaces">https://protobuf.dev/news/2024-10-02/#rpc-service-interfaces</a></li> </ul> </li> <li>Drop testing support for protobuf <6.32 because they don't support editions <ul> <li>With some more work this could be added back in a testing refactor</li> <li>Protobuf <6.32 still had the edition enums and field options, so it <em>should</em> still work. But is untested</li> </ul> </li> <li>Add support for editions (up to 2024)</li> <li>Add <code>generate_concrete_servicer_stubs</code> option to generate concrete instead of abstract servicer stubs</li> <li>Add <code>sync_only</code>/<code>async_only</code> options to generate only sync or async version of GRPC stubs</li> <li>Switch to types-grpcio instead of no longer maintained grpc-stubs</li> <li>Add <code>_HasFieldArgType</code> and <code>_ClearFieldArgType</code> aliases to allow for typing field manipulation functions</li> <li>Add <code>_WhichOneofArgType_<oneof_name></code> and <code>_WhichOneofReturnType_<oneof_name></code> type aliases</li> <li>Use <code>__new__</code> overloads for async stubs instead of <code>TypeVar</code> based <code>__init__</code> overloads. <ul> <li><a href="https://redirect.github.com/nipunn1313/mypy-protobuf/issues/707">nipunn1313/mypy-protobuf#707</a></li> </ul> </li> <li>Support file level field presence feature setting</li> </ul> <h2>3.7.0</h2> <ul> <li>Mark top-level mangled identifiers as <code>TypeAlias</code>.</li> <li>Change the top-level mangling prefix from <code>global___</code> to <code>Global___</code> to respect <a href="https://github.com/PyCQA/flake8-pyi/blob/main/ERRORCODES.md#list-of-warnings">Y042</a> naming convention.</li> <li>Support client stub async typing overloads</li> <li>Support <a href="https://peps.python.org/pep-0702/">PEP702</a> deprecations <ul> <li>Message deprecations are supported</li> <li>Field deprecations are not. This may be possible with init overloads</li> <li>Service deprecations are supported for Sync stubs <ul> <li>Not for async stubs</li> </ul> </li> <li>Enum message deprecation is supported <ul> <li>Enum field deprecation is not</li> </ul> </li> </ul> </li> <li>Drop Python 3.8 testing. Newer protobuf versions are incompatible. Generated code may still work</li> </ul> <h2>3.6.0</h2> <ul> <li>Remove 3.7 compatibility for typing_extensions.final/Literal</li> <li>Bump protobuf to 4.25.3</li> </ul> <h2>3.5.0</h2> <ul> <li>Add gRPC aio stub and servicer generation (<a href="https://redirect.github.com/nipunn1313/mypy-protobuf/issues/489">#489</a>)</li> <li>Bump tested dependencies to pyright==1.1.319, mypy==1.4.1, protobuf==4.23.4, grpcio-tools==1.56.2</li> <li>Drop support for py 3.7. Add support for py 3.11.</li> <li>Don't add unnecessary flake8 noqa F821 comments. (Become compatible with flake8-pyi>=23.5.0.)</li> </ul> <h2>3.4.0</h2> <ul> <li>Mark messages as <a href="https://github.com/typing"><code>@typing</code></a>.final</li> <li>Switch to use the reserved mypy-protobuf extension option numbers <a href="https://github.com/protocolbuffers/protobuf/blob/main/docs/options.md">https://github.com/protocolbuffers/protobuf/blob/main/docs/options.md</a></li> <li>Bump protobuf dependency to 4.21.8</li> <li>Skip unnecessary flake8 noqa F821 on module scope fwd reference classes</li> </ul> <!-- raw HTML omitted --> </blockquote> <p>... (truncated)</p> </details> <details> <summary>Commits</summary> <ul> <li><a href="https://github.com/nipunn1313/mypy-protobuf/commit/7d68665906b16a0fa4e880af8bf940dc7492211a"><code>7d68665</code></a> prep 3.8.0 release (<a href="https://redirect.github.com/nipunn1313/mypy-protobuf/issues/715">#715</a>)</li> <li><a href="https://github.com/nipunn1313/mypy-protobuf/commit/7b20d4eeebb3a8161d2c0591fe66847a5909ba55"><code>7b20d4e</code></a> Support file level field presence feature setting (<a href="https://redirect.github.com/nipunn1313/mypy-protobuf/issues/717">#717</a>)</li> <li><a href="https://github.com/nipunn1313/mypy-protobuf/commit/f35584a0834f0e9d59efc44b2320eeabd6c43982"><code>f35584a</code></a> Add flags to generate only sync or only async stubs (<a href="https://redirect.github.com/nipunn1313/mypy-protobuf/issues/694">#694</a>)</li> <li><a href="https://github.com/nipunn1313/mypy-protobuf/commit/38362fb1c84c9203d49c6972a91b42ae3e7a2bd8"><code>38362fb</code></a> Overload <strong>new</strong> (<a href="https://redirect.github.com/nipunn1313/mypy-protobuf/issues/710">#710</a>)</li> <li><a href="https://github.com/nipunn1313/mypy-protobuf/commit/c89ee56b83af4e0068a96ebbeec67edf47abf80b"><code>c89ee56</code></a> Move to types-grpcio (<a href="https://redirect.github.com/nipunn1313/mypy-protobuf/issues/703">#703</a>)</li> <li><a href="https://github.com/nipunn1313/mypy-protobuf/commit/505e3a0ec601841c21e2b64d7ff458a5326325eb"><code>505e3a0</code></a> Aidan/clear has field type aliases (<a href="https://redirect.github.com/nipunn1313/mypy-protobuf/issues/696">#696</a>)</li> <li><a href="https://github.com/nipunn1313/mypy-protobuf/commit/6fa9547042d0396d9549172a5e476a40fb283c00"><code>6fa9547</code></a> Bump mypy from 1.14.1 to 1.19.0 (<a href="https://redirect.github.com/nipunn1313/mypy-protobuf/issues/700">#700</a>)</li> <li><a href="https://github.com/nipunn1313/mypy-protobuf/commit/5c7686d7635bb54e22264bf2b950ca6967fcaa81"><code>5c7686d</code></a> Bump pytest-asyncio from 0.24.0 to 0.25.3 (<a href="https://redirect.github.com/nipunn1313/mypy-protobuf/issues/674">#674</a>)</li> <li><a href="https://github.com/nipunn1313/mypy-protobuf/commit/caade91c9eea98c56a0cfad0b3c2bf1f0c3768a0"><code>caade91</code></a> Bump actions/checkout from 4 to 6 (<a href="https://redirect.github.com/nipunn1313/mypy-protobuf/issues/702">#702</a>)</li> <li><a href="https://github.com/nipunn1313/mypy-protobuf/commit/d86fe02674ab785d90925e54094f90db32793167"><code>d86fe02</code></a> Bump actions/setup-python from 5 to 6 (<a href="https://redirect.github.com/nipunn1313/mypy-protobuf/issues/701">#701</a>)</li> <li>Additional commits viewable in <a href="https://github.com/nipunn1313/mypy-protobuf/compare/v3.0.0...v4.0.0">compare view</a></li> </ul> </details> <br /> 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 merge` will merge this PR after your CI passes on it - `@dependabot squash and merge` will squash and merge this PR after your CI passes on it - `@dependabot cancel merge` will cancel a previously requested merge and block automerging - `@dependabot reopen` will reopen this PR if it is closed - `@dependabot close` will close this PR and stop Dependabot recreating it. You can achieve the same result by closing it manually - `@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--1263.org.readthedocs.build/en/1263/ <!-- readthedocs-preview swarms end -->
Bumps [pypdf](https://github.com/py-pdf/pypdf) from 5.1.0 to 6.5.0. <details> <summary>Release notes</summary> <p><em>Sourced from <a href="https://github.com/py-pdf/pypdf/releases">pypdf's releases</a>.</em></p> <blockquote> <h2>Version 6.5.0, 2025-12-21</h2> <h2>What's new</h2> <h3>New Features (ENH)</h3> <ul> <li>Limit jbig2dec memory usage (<a href="https://redirect.github.com/py-pdf/pypdf/issues/3576">#3576</a>) by <a href="https://github.com/stefan6419846"><code>@stefan6419846</code></a></li> <li>FontDescriptor: Initiate from embedded font resource (<a href="https://redirect.github.com/py-pdf/pypdf/issues/3551">#3551</a>) by <a href="https://github.com/PJBrs"><code>@PJBrs</code></a></li> </ul> <h3>Robustness (ROB)</h3> <ul> <li>Allow fallback to PBM files for jbig2dec without PNG support (<a href="https://redirect.github.com/py-pdf/pypdf/issues/3567">#3567</a>) by <a href="https://github.com/stefan6419846"><code>@stefan6419846</code></a></li> <li>Use warning instead of error for early EOD for RunLengthDecode (<a href="https://redirect.github.com/py-pdf/pypdf/issues/3548">#3548</a>) by <a href="https://github.com/stefan6419846"><code>@stefan6419846</code></a></li> </ul> <h3>Developer Experience (DEV)</h3> <ul> <li>Test with macOS as well (<a href="https://redirect.github.com/py-pdf/pypdf/issues/3401">#3401</a>) by <a href="https://github.com/stefan6419846"><code>@stefan6419846</code></a></li> </ul> <p><a href="https://github.com/py-pdf/pypdf/compare/6.4.2...6.5.0">Full Changelog</a></p> <h2>Version 6.4.2, 2025-12-14</h2> <h2>What's new</h2> <h3>Bug Fixes (BUG)</h3> <ul> <li>Fix KeyError when flattening form field without /Font in resources (<a href="https://redirect.github.com/py-pdf/pypdf/issues/3554">#3554</a>) by <a href="https://github.com/jgillard"><code>@jgillard</code></a></li> </ul> <h3>Robustness (ROB)</h3> <ul> <li>Allow deleting non-existent annotations (<a href="https://redirect.github.com/py-pdf/pypdf/issues/3559">#3559</a>) by <a href="https://github.com/stefan6419846"><code>@stefan6419846</code></a></li> </ul> <h3>Documentation (DOC)</h3> <ul> <li>Fix level of attachment heading (<a href="https://redirect.github.com/py-pdf/pypdf/issues/3560">#3560</a>) by <a href="https://github.com/stefan6419846"><code>@stefan6419846</code></a></li> </ul> <p><a href="https://github.com/py-pdf/pypdf/compare/6.4.1...6.4.2">Full Changelog</a></p> <h2>Version 6.4.1, 2025-12-07</h2> <h2>What's new</h2> <h3>Performance Improvements (PI)</h3> <ul> <li>Optimize loop for layout mode text extraction (<a href="https://redirect.github.com/py-pdf/pypdf/issues/3543">#3543</a>) by <a href="https://github.com/FelipeErmeson"><code>@FelipeErmeson</code></a></li> </ul> <h3>Bug Fixes (BUG)</h3> <ul> <li>Do not fail on choice field without /Opt key (<a href="https://redirect.github.com/py-pdf/pypdf/issues/3540">#3540</a>) by <a href="https://github.com/jhuber-de"><code>@jhuber-de</code></a></li> </ul> <h3>Documentation (DOC)</h3> <ul> <li>Document possible issues with merge_page and clipping (<a href="https://redirect.github.com/py-pdf/pypdf/issues/3546">#3546</a>) by <a href="https://github.com/stefan6419846"><code>@stefan6419846</code></a></li> <li>Add some notes about library security (<a href="https://redirect.github.com/py-pdf/pypdf/issues/3545">#3545</a>) by <a href="https://github.com/stefan6419846"><code>@stefan6419846</code></a></li> </ul> <h3>Maintenance (MAINT)</h3> <ul> <li>Use CORE_FONT_METRICS for widths where possible (<a href="https://redirect.github.com/py-pdf/pypdf/issues/3526">#3526</a>) by <a href="https://github.com/PJBrs"><code>@PJBrs</code></a></li> </ul> <p><a href="https://github.com/py-pdf/pypdf/compare/6.4.0...6.4.1">Full Changelog</a></p> <h2>Version 6.4.0, 2025-11-23</h2> <h2>What's new</h2> <!-- raw HTML omitted --> </blockquote> <p>... (truncated)</p> </details> <details> <summary>Changelog</summary> <p><em>Sourced from <a href="https://github.com/py-pdf/pypdf/blob/main/CHANGELOG.md">pypdf's changelog</a>.</em></p> <blockquote> <h2>Version 6.5.0, 2025-12-21</h2> <h3>New Features (ENH)</h3> <ul> <li>Limit jbig2dec memory usage (<a href="https://redirect.github.com/py-pdf/pypdf/issues/3576">#3576</a>)</li> <li>FontDescriptor: Initiate from embedded font resource (<a href="https://redirect.github.com/py-pdf/pypdf/issues/3551">#3551</a>)</li> </ul> <h3>Robustness (ROB)</h3> <ul> <li>Allow fallback to PBM files for jbig2dec without PNG support (<a href="https://redirect.github.com/py-pdf/pypdf/issues/3567">#3567</a>)</li> <li>Use warning instead of error for early EOD for RunLengthDecode (<a href="https://redirect.github.com/py-pdf/pypdf/issues/3548">#3548</a>)</li> </ul> <h3>Developer Experience (DEV)</h3> <ul> <li>Test with macOS as well (<a href="https://redirect.github.com/py-pdf/pypdf/issues/3401">#3401</a>)</li> </ul> <p><a href="https://github.com/py-pdf/pypdf/compare/6.4.2...6.5.0">Full Changelog</a></p> <h2>Version 6.4.2, 2025-12-14</h2> <h3>Bug Fixes (BUG)</h3> <ul> <li>Fix KeyError when flattening form field without /Font in resources (<a href="https://redirect.github.com/py-pdf/pypdf/issues/3554">#3554</a>)</li> </ul> <h3>Robustness (ROB)</h3> <ul> <li>Allow deleting non-existent annotations (<a href="https://redirect.github.com/py-pdf/pypdf/issues/3559">#3559</a>)</li> </ul> <h3>Documentation (DOC)</h3> <ul> <li>Fix level of attachment heading (<a href="https://redirect.github.com/py-pdf/pypdf/issues/3560">#3560</a>)</li> </ul> <p><a href="https://github.com/py-pdf/pypdf/compare/6.4.1...6.4.2">Full Changelog</a></p> <h2>Version 6.4.1, 2025-12-07</h2> <h3>Performance Improvements (PI)</h3> <ul> <li>Optimize loop for layout mode text extraction (<a href="https://redirect.github.com/py-pdf/pypdf/issues/3543">#3543</a>)</li> </ul> <h3>Bug Fixes (BUG)</h3> <ul> <li>Do not fail on choice field without /Opt key (<a href="https://redirect.github.com/py-pdf/pypdf/issues/3540">#3540</a>)</li> </ul> <h3>Documentation (DOC)</h3> <ul> <li>Document possible issues with merge_page and clipping (<a href="https://redirect.github.com/py-pdf/pypdf/issues/3546">#3546</a>)</li> <li>Add some notes about library security (<a href="https://redirect.github.com/py-pdf/pypdf/issues/3545">#3545</a>)</li> </ul> <h3>Maintenance (MAINT)</h3> <ul> <li>Use CORE_FONT_METRICS for widths where possible (<a href="https://redirect.github.com/py-pdf/pypdf/issues/3526">#3526</a>)</li> </ul> <p><a href="https://github.com/py-pdf/pypdf/compare/6.4.0...6.4.1">Full Changelog</a></p> <h2>Version 6.4.0, 2025-11-23</h2> <h3>Security (SEC)</h3> <ul> <li>Reduce default limit for LZW decoding</li> </ul> <!-- raw HTML omitted --> </blockquote> <p>... (truncated)</p> </details> <details> <summary>Commits</summary> <ul> <li><a href="https://github.com/py-pdf/pypdf/commit/52fb020800c61244c8b9e94e201150029919775d"><code>52fb020</code></a> REL: 6.5.0</li> <li><a href="https://github.com/py-pdf/pypdf/commit/2430864c4a20b95886e7b1680937ab4986cf2588"><code>2430864</code></a> ENH: Limit jbig2dec memory usage (<a href="https://redirect.github.com/py-pdf/pypdf/issues/3576">#3576</a>)</li> <li><a href="https://github.com/py-pdf/pypdf/commit/c17e4ac6a22551105fa426c5cdc00fb3c99f8eed"><code>c17e4ac</code></a> DEV: Improve test file caching, especially for CI (<a href="https://redirect.github.com/py-pdf/pypdf/issues/3575">#3575</a>)</li> <li><a href="https://github.com/py-pdf/pypdf/commit/12d9488558c5ba64e230dbecf25b625ab3ab291a"><code>12d9488</code></a> MAINT: Update filelock version to 3.20.1</li> <li><a href="https://github.com/py-pdf/pypdf/commit/b0b68c96a523c6f30f41285ed879927979c4a197"><code>b0b68c9</code></a> DEV: Cache test files on macOS and Windows as well (<a href="https://redirect.github.com/py-pdf/pypdf/issues/3572">#3572</a>)</li> <li><a href="https://github.com/py-pdf/pypdf/commit/33559c8eed34bf3ca0625a7b8948043c98ccd407"><code>33559c8</code></a> ENH: FontDescriptor: Initiate from embedded font resource (<a href="https://redirect.github.com/py-pdf/pypdf/issues/3551">#3551</a>)</li> <li><a href="https://github.com/py-pdf/pypdf/commit/5acf671e8ba2a2e1f3daf6625cea97fe0a394f2b"><code>5acf671</code></a> DEV: Test with macOS as well (<a href="https://redirect.github.com/py-pdf/pypdf/issues/3401">#3401</a>)</li> <li><a href="https://github.com/py-pdf/pypdf/commit/a373c8a4eaa5bf296e53ba070f26dc20157682a1"><code>a373c8a</code></a> ROB: Allow fallback to PBM files for jbig2dec without PNG support (<a href="https://redirect.github.com/py-pdf/pypdf/issues/3567">#3567</a>)</li> <li><a href="https://github.com/py-pdf/pypdf/commit/98f9f6210b34cad08ac71995bd6446d964363e6a"><code>98f9f62</code></a> ROB: Use warning instead of error for early EOD for RunLengthDecode (<a href="https://redirect.github.com/py-pdf/pypdf/issues/3548">#3548</a>)</li> <li><a href="https://github.com/py-pdf/pypdf/commit/a245e4a857d1f343edd07a5232cbe0f3a5dcb188"><code>a245e4a</code></a> DEV: Bump actions/download-artifact from 6 to 7 (<a href="https://redirect.github.com/py-pdf/pypdf/issues/3563">#3563</a>)</li> <li>Additional commits viewable in <a href="https://github.com/py-pdf/pypdf/compare/5.1.0...6.5.0">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 merge` will merge this PR after your CI passes on it - `@dependabot squash and merge` will squash and merge this PR after your CI passes on it - `@dependabot cancel merge` will cancel a previously requested merge and block automerging - `@dependabot reopen` will reopen this PR if it is closed - `@dependabot close` will close this PR and stop Dependabot recreating it. You can achieve the same result by closing it manually - `@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--1262.org.readthedocs.build/en/1262/ <!-- readthedocs-preview swarms end -->
To re-create: run ``` from swarms.agents.i_agent import IterativeReflectiveExpansion agent = IterativeReflectiveExpansion( max_iterations=5, ) agent.run("What is the 2nd prime number?") ``` Root problem: Evidence from Your Logs 2025-12-18 17:23:40 | INFO - Iteration 1/5 [Agent generates 9 initial hypotheses] ... [Still processing paths from iteration 1] ... 2025-12-18 17:26:20 | INFO - [Still in iteration 1, hasn't moved to iteration 2] Key observation: Agent ran for ~3 minutes but never finished iteration 1. It's stuck processing an exponentially growing number of paths. Root Cause Analysis Problem 1: Unlimited Path Generation ⚠️ Evidence: Generating initial hypotheses for the problem. [Returns 9 hypotheses - see the 9 numbered approaches in your logs] - LLM generates 9 initial paths for a simple question ("What is the 2nd prime number?") - No limit on initial hypotheses Problem 2: Revision Explosion ⚠️⚠️⚠️ Evidence from logs: Score: 0.7 [or 0.8, 0.9 - anything < threshold] → meta_reflect: Performing meta-reflection → revise_path: Revising reasoning path based on feedback → [Returns 9 NEW revised paths - see the numbered list in logs] The death spiral: - Path scores 0.7 (below threshold) - Calls revise_path() - revise_path() asks LLM "generate revised reasoning paths" (plural) - LLM returns 9 new paths for each bad path - If 3 paths need revision: 3 × 9 = 27 new paths added Problem 3: No Stop Conditions Within Iterations ⚠️ Evidence: # Original code (lines 264-277) for path in candidate_paths: outcome, score, error_info = self.simulate_path(path) if score < 0.7: revised_paths = self.revise_path(path, feedback) expanded_paths.extend(revised_paths) # Adds ALL revisions else: expanded_paths.append(path) # Processes ALL paths, no early exit - No limit on paths processed per iteration - No early stopping when good paths found - Processes every path even if you already have perfect solutions Problem 4: Unbounded Accumulation ⚠️ Evidence: # Line 275 memory_pool.extend(candidate_paths) # Grows forever The math: Iteration 1: 9 paths → after revisions → 40 paths → select keeps 30 Iteration 2: 30 paths → after revisions → 120 paths → select keeps 80 Iteration 3: 80 paths → after revisions → 400+ paths ... EXPLOSION Summary Table | Issue | Evidence | Impact | |------------------------|-------------------------------------------|------------------------------| | Too many initial paths | Log shows 9 hypotheses generated | Iteration starts overwhelmed | | Unlimited revisions | revise_path returns 9 new paths each time | 1 bad path → 9 new paths | | No iteration limits | Processes all paths regardless | Can't finish iteration 1 | | No early exit | Continues even with 3 perfect scores | Wasted computation | | Unbounded accumulation | select_promising_paths keeps 20-30 | Next iteration has even more | The Smoking Gun Your log evidence: 2025-12-18 17:23:40 - Iteration 1/5 [3 minutes of processing] 2025-12-18 17:26:20 - [Still in iteration 1] For a question with a trivial answer ("What is the 2nd prime number? → 3"), the agent: - ✅ Found correct answer (score 1.0) in first few paths - ❌ Kept processing 9 total paths - ❌ Generated revisions for paths that scored 0.7-0.9 - ❌ Never finished iteration 1 due to path explosion Root Cause in One Sentence The LLM returns multiple paths (plural) every time it's asked to generate or revise reasoning paths, causing exponential growth from 9 → 40 → 120 → 400+ paths across iterations, with no limits to stop the explosion.
<!-- readthedocs-preview swarms start --> ---- 📚 Documentation preview 📚: https://swarms--1260.org.readthedocs.build/en/1260/ <!-- readthedocs-preview swarms end -->
- Agent that has multiple tools - Tools for bazzar, tool to buy service, abunch of x402 tools, give it access to it's own wallet, and more
- Description: Using memory of a company's info with a ChromaDB, a sequential swarm is able to satisfy customer needs. - https://www.loom.com/share/dc3fe1bf84ed45f5ae67fd2ea6d47122 <!-- readthedocs-preview swarms start --> ---- 📚 Documentation preview 📚: https://swarms--1252.org.readthedocs.build/en/1252/ <!-- readthedocs-preview swarms end -->
### Summary Fixed a pervasive misspelling of "hierarchical" as "hiearchical" throughout the entire codebase. This typo was causing bugs due to mismatches between file names, import paths, class names, and variable references. ### Problem The misspelling "hiearchical" appeared in: - File names and directory paths - Import statements - Variable names - Class references - Documentation and examples This mismatch was causing import errors and runtime bugs when trying to use hierarchical swarm functionality. ### Changes Made **Core Source Files (3 renamed):** - `swarms/prompts/hiearchical_system_prompt.py` → `hierarchical_system_prompt.py` - `swarms/structs/hiearchical_swarm.py` → `hierarchical_swarm.py` - `swarms/structs/hybrid_hiearchical_peer_swarm.py` → `hybrid_hierarchical_peer_swarm.py` **Directories (3 renamed):** - `examples/multi_agent/hiearchical_swarm/` → `hierarchical_swarm/` - `examples/multi_agent/hierarchical_swarm/hiearchical_examples/` → `hierarchical_examples/` - `examples/multi_agent/hierarchical_swarm/hiearchical_swarm_ui/` → `hierarchical_swarm_ui/` **Content Updates (47 files total):** - Updated all imports: `from swarms.structs.hiearchical_swarm` → `from swarms.structs.hierarchical_swarm` - Fixed variable references: `HIEARCHICAL_SWARM_SYSTEM_PROMPT` → `HIERARCHICAL_SWARM_SYSTEM_PROMPT` - Updated SwarmType literal: `"HiearchicalSwarm"` → `"HierarchicalSwarm"` - Fixed variable name bugs (e.g., `hiearchical_swarm.run()` → `hierarchical_swarm.run()`) - Updated all documentation and README files ### Testing ✅ Verified all imports work correctly: - `from swarms.structs.hierarchical_swarm import HierarchicalSwarm` - `from swarms.prompts.hierarchical_system_prompt import HIERARCHICAL_SWARM_SYSTEM_PROMPT` - `from swarms.structs.hybrid_hierarchical_peer_swarm import HybridHierarchicalClusterSwarm` ✅ Confirmed zero instances of "hiearchical" remain in codebase ### Impact - Fixes import errors and runtime bugs related to hierarchical swarm functionality - Improves code maintainability and consistency - No breaking changes for users (they were using the wrong spelling which was causing bugs) <!-- readthedocs-preview swarms start --> ---- 📚 Documentation preview 📚: https://swarms--1251.org.readthedocs.build/en/1251/ <!-- readthedocs-preview swarms end -->
added documentation for circular swarm <!-- readthedocs-preview swarms start --> ---- 📚 Documentation preview 📚: https://swarms--1244.org.readthedocs.build/en/1244/ <!-- readthedocs-preview swarms end -->
## Description This PR fixes a widespread misspelling throughout the codebase: "hiearchical" → "hierarchical". The misspelling was present in: - 8 file names - 3 directory names - 97 code references (imports, variable names, strings, documentation) **Changes made:** - Renamed all files with misspelled "hiearchical" to correctly spelled "hierarchical" - Renamed all directories with misspelled "hiearchical" to correctly spelled "hierarchical" - Updated all import statements across the codebase - Updated all variable names and string literals - Updated all documentation files (README.md, docs/*.md, docs/llm.txt) - Fixed references in code examples and comments **Files renamed:** - `swarms/structs/hiearchical_swarm.py` → `hierarchical_swarm.py` - `swarms/structs/hybrid_hiearchical_peer_swarm.py` → `hybrid_hierarchical_peer_swarm.py` - `swarms/prompts/hiearchical_system_prompt.py` → `hierarchical_system_prompt.py` - `examples/guides/hiearchical_marketing_team.py` → `hierarchical_marketing_team.py` - `hiearchical_swarm_example.py` → `hierarchical_swarm_example.py` - `examples/multi_agent/hiearchical_swarm/` → `hierarchical_swarm/` (directory) - `examples/multi_agent/hiearchical_swarm/hiearchical_examples/` → `hierarchical_examples/` (directory) - `examples/multi_agent/hiearchical_swarm/hiearchical_swarm_ui/` → `hierarchical_swarm_ui/` (directory) - Plus all files within the renamed directories **Impact:** - 40 files modified - 24 files/directories renamed - 97 occurrences corrected - No functional changes, only spelling corrections ## Issue https://github.com/kyegomez/swarms/issues/1232 ## Dependencies None - CLEANUP ## Tag maintainer @kyegomez --- ## Testing All existing tests should continue to pass as this is purely a naming/spelling correction with no functional changes. The changes have been verified by: - Checking all imports resolve correctly - Verifying file paths in documentation are updated - Confirming no remaining instances of "hiearchical" in the codebase ## Checklist - [x] All files renamed correctly - [x] All imports updated - [x] All documentation updated - [x] All code references fixed - [x] No remaining misspellings in codebase <!-- readthedocs-preview swarms start --> ---- 📚 Documentation preview 📚: https://swarms--1236.org.readthedocs.build/en/1236/ <!-- readthedocs-preview swarms end -->
description ----------------- Introduces a lightweight causal reasoning Agent implementing the core ASTT/CR-CA primitives with LLM integration. This Agent provides both deterministic causal simulation and LLM-based causal analysis, enabling flexible causal reasoning workflows without requiring networkx, pandas, scipy, cvxpy, or other heavyweight libraries. Background / Motivation ----------------------- The existing `CRCAAgent` in `swarms/agents/cr_ca_agent.py` provides full-featured causal reasoning with LLM integration, advanced optimization, and extensive statistical methods. However, many use cases require a deterministic, dependency-light agent that provides core causal simulation capabilities without external API calls. This PR introduces `CRCAAgent` (Lite) as a lightweight Agent in the swarms framework that: - Implements the full Agent interface with `run()` method supporting both LLM-based and deterministic modes - Provides LLM integration for sophisticated causal reasoning (like the full version) - Supports deterministic causal simulation without external API calls - Requires only `numpy` and swarms Agent base (no networkx, pandas, scipy, cvxpy) - Provides predictable, reproducible results for deterministic workflows - Serves as a flexible causal reasoning Agent that can operate with or without LLM calls The Lite implementation maintains mathematical rigor while prioritizing simplicity and performance, making it a versatile Agent for causal reasoning that combines LLM capabilities with deterministic simulation. Architecture Overview --------------------- ```mermaid graph TB A[Task/Initial State] --> B{Mode Selection} B -->|LLM Mode| C[Build Causal Prompt] B -->|Deterministic Mode| D[Standardize to z-space] C --> E[LLM Causal Analysis] E --> F[Multi-loop Reasoning] F --> G[Synthesize Analysis] G --> H[Generate Counterfactuals] D --> I[Topological Sort] I --> J[Linear SCM Propagation] J --> K[De-standardize] K --> L[Evolved State] L --> M[Counterfactual Generation] N[Causal Graph] --> I N --> O[Edge Strengths] O --> J N --> C style A fill:#e1f5ff style L fill:#c8e6c9 style M fill:#fff9c4 style G fill:#ffcccb ``` Core Components --------------- The implementation centers on four key capabilities: 1. **LLM-Based Causal Analysis**: Multi-loop reasoning with structured output - Uses CR-CA schema for function calling - Builds causal prompts with graph context - Synthesizes comprehensive causal analysis reports - Supports memory context across reasoning loops 2. **Evolution Operator E(x)**: Implements linear structural causal model (SCM) in standardized z-space - Formula: `z_y = Σᵢ βᵢ·z_xi` where βᵢ are edge strengths - Topological ordering ensures causal dependencies are respected - Standardization provides numerical stability and scale-invariance 3. **Counterfactual Generation**: Implements Pearl's do-operator and abduction-action-prediction - Generates intervention scenarios with probability estimates - Uses Mahalanobis-like distance for plausibility scoring - Supports multi-variable interventions and cascading effects 4. **Causal Graph Operations**: Pure-Python DAG implementation - Adjacency dictionary representation (no external graph libraries) - Topological sort via Kahn's algorithm - Path finding via BFS for causal chain identification ```mermaid sequenceDiagram participant User participant Agent participant LLM participant Graph participant SCM User->>Agent: run(task/initial_state) alt LLM Mode (task string) Agent->>Agent: _build_causal_prompt() loop max_loops Agent->>LLM: step(prompt) LLM-->>Agent: causal_analysis Agent->>Agent: update_memory_context() end Agent->>LLM: synthesize_analysis() LLM-->>Agent: final_analysis Agent->>Agent: generate_counterfactual_scenarios() else Deterministic Mode (initial_state dict) Agent->>Graph: topological_sort() Graph-->>Agent: ordered_nodes Agent->>SCM: _predict_outcomes(state, {}) SCM->>SCM: standardize(state) SCM->>SCM: propagate(parents → children) SCM->>SCM: de-standardize(predictions) SCM-->>Agent: evolved_state Agent->>Agent: generate_counterfactual_scenarios() end Agent-->>User: {analysis/evolved_state, counterfactuals, graph_info} ``` What changed (files) -------------------- - `ceca_lite/crca-lite.py` — Core Lite implementation (CRCAgent class) - `swarms/agents/cr_ca_agent.py` — Integration point (CRCAAgent class reference) - `docs/swarms/agents/crca_agent.md` — Documentation and usage examples Key Design Decisions --------------------- **Pure-Python Graph Representation** - Uses nested dictionaries `{node: {child: strength}}` instead of networkx - Enables zero external dependencies beyond numpy - Provides O(1) edge lookups and O(V+E) topological operations **Standardized Linear SCM** - All computations occur in z-space (standardized values) - Prevents numerical instability from scale mismatches - Allows direct comparison of causal effects across variables - Linear model is intentionally simple; non-linear extensions can subclass **Dual-Mode Operation** - LLM mode: Multi-loop causal reasoning with structured output (like full CRCAAgent) - Deterministic mode: Pure causal simulation without LLM calls - Automatic mode selection based on input type (string vs dict) - Both modes generate counterfactual scenarios using deterministic methods **LLM Integration** - Uses CR-CA schema for structured function calling - Multi-loop reasoning with memory context - Synthesizes comprehensive causal analysis reports - Compatible with swarms Agent LLM infrastructure **Agent-First API** - `run()` method accepts task string (LLM mode) or initial_state dict (deterministic mode) - Returns structured output matching Swarms agent conventions - Supports `max_loops` parameter for multi-step LLM reasoning or evolution Value Proposition ------------------ **Performance Characteristics** - Forward pass: O(V + E) where V = variables, E = edges (deterministic mode) - Memory: O(V + E) for graph representation - LLM mode: Network latency depends on model provider - Suitable for both high-frequency simulation and sophisticated causal analysis **Integration Benefits** - Minimal dependency footprint (numpy + swarms Agent base) - LLM integration enables sophisticated causal reasoning - Deterministic mode enables reproducible testing - Pure Python graph implementation simplifies debugging - Flexible dual-mode operation adapts to use case **Use Cases Enabled** - LLM-based causal analysis for complex problems - Real-time deterministic causal simulation in production systems - Testing and validation of causal models - Educational and research applications requiring transparency - Systems requiring both LLM reasoning and deterministic simulation Testing and validation ---------------------- ```bash # Unit tests pytest tests/ -k crca # Linting make lint && make format # Quick validation python -c " from swarms.agents.cr_ca_agent import CRCAAgent agent = CRCAAgent(variables=['price', 'demand', 'inventory']) agent.add_causal_relationship('price', 'demand', strength=-0.5) result = agent.run({'price': 100.0, 'demand': 1000.0, 'inventory': 5000.0}) assert 'evolved_state' in result assert 'counterfactual_scenarios' in result print('✓ Core functionality validated') " ``` Security & Performance ---------------------- - **LLM Mode**: Uses swarms Agent LLM infrastructure (secure, configurable) - **Deterministic Mode**: No external API calls, fully deterministic operations - **Safe**: Pure Python computation, no code execution or deserialization risks - **Performant**: O(V+E) complexity for deterministic operations, minimal memory overhead - **Scalable**: Handles graphs with hundreds of variables efficiently Compatibility & Breaking Changes -------------------------------- - **New module**: Introduces `CRCAAgent` class at `swarms/agents/cr_ca_agent.py` - **No breaking changes**: Existing `CRCAAgent` (full version) remains unchanged - **Import path**: `from swarms.agents.cr_ca_agent import CRCAAgent` - **Backward compatible**: Existing code using full `CRCAAgent` continues to work Documentation ------------- - Quickstart guide in `docs/swarms/agents/crca_agent.md` - API reference with mathematical foundations - Example usage patterns for common scenarios - Integration guide for orchestrator systems Checklist (required before merge) --------------------------------- - [ ] Code builds and passes unit tests: `make test` - [ ] Linting and formatting checks pass: `make lint` / `make format` - [ ] Documentation updated and examples validated - [ ] Performance benchmarks documented (if applicable) - [ ] No references to deprecated paths remain - [ ] Release notes / changelog entry added Reviewer guidance ------------------ **Critical areas for review:** 1. **`_predict_outcomes` correctness** - Verify topological ordering is respected - Check standardization/de-standardization round-trip accuracy - Validate do-operator semantics (interventions break parent dependencies) 2. **Counterfactual generation** - Ensure intervention space exploration is systematic - Verify probability calculations are bounded and reasonable - Check edge cases (zero std, missing stats) 3. **Graph operations** - Validate topological sort handles all DAG cases - Verify cycle detection in `is_dag()` - Check path finding correctness 4. **API design** - Confirm `run()` method signature matches agent conventions - Verify return structure is consistent with Swarms patterns - Check error handling for invalid inputs 5. **Dependencies** - Confirm only numpy + swarms.structs.agent are required (LLM via Agent base) - Verify no hidden imports or optional dependencies (networkx, pandas, scipy, cvxpy) - Check LLM integration uses swarms Agent infrastructure correctly 6. **LLM Integration** - Verify CR-CA schema is correctly defined and used - Check multi-loop reasoning works as expected - Validate prompt building and memory context - Ensure both LLM and deterministic modes work correctly Notes for maintainers --------------------- - `CRCAAgent` (Lite) is a full Agent in the swarms framework with `run()` method supporting both LLM and deterministic modes - This Lite implementation provides essential causal reasoning capabilities with LLM integration (like full version) - Full-featured `CRCAAgent` adds advanced optimization, statistical methods, and extensive features on top - Lite version provides core causal reasoning with LLM support while maintaining minimal dependencies - Consider exporting from `swarms/agents/__init__.py` for canonical imports Contacts / Authors ------------------ - Primary author: https://x.com/IlumTheProtogen - Maintainer: @kyegomez Optional: Link to issue(s) -------------------------- - Issue: https://github.com/kyegomez/swarms/issues/1169 <!-- readthedocs-preview swarms start --> ---- 📚 Documentation preview 📚: https://swarms--1233.org.readthedocs.build/en/1233/ <!-- readthedocs-preview swarms end -->
- fix grammatical errors in filesnames, especially those surrounding the hierarchical swarm. - The correct word is "Hierarchical," not hiearchical, not hirearchical.
Implements Token-Oriented Object Notation (TOON) SDK integration providing significant token optimization for LLM prompts. Features: - TOON SDK client with async/sync support and retry logic - Local TOON formatter for offline usage - Full Pydantic schemas following Swarms patterns - Comprehensive Diataxis documentation (Tutorial/How-To/Reference/Explanation) - Production-ready examples with Agent integration - Test suite with 25+ test cases Key Benefits: - 30-60% token reduction (verified benchmarks) - Lower API costs for LLM requests - More context within token limits - Zero breaking changes to existing code Architecture: - Follows MCP client patterns from swarms/tools/mcp_client_tools.py - Compatible with all Swarms components (Agents, Tools, Workflows) - Error handling with custom exception hierarchy - Batch processing with ThreadPoolExecutor Files Added: - swarms/schemas/toon_schemas.py (370 lines) - swarms/tools/toon_sdk_client.py (820 lines) - swarms/utils/toon_formatter.py (450 lines) - examples/tools/toon_sdk_basic_example.py (380 lines) - examples/tools/toon_sdk_agent_integration.py (420 lines) - docs/swarms/tools/toon_sdk.md (920 lines) - tests/tools/test_toon_formatter.py (380 lines) - TOON_SDK_INTEGRATION_SUMMARY.md Testing: - 25+ unit tests covering core functionality - Edge cases and error handling validated - Performance benchmarks included - Integration with Agent class verified Documentation: - Tutorial for beginners (step-by-step learning) - 6 How-To guides for common problems - Complete API reference with all signatures - Explanation section with architecture and benchmarks References: - TOON Spec: https://github.com/toon-format - Benchmarks: 73.9% retrieval accuracy for tables Signed-off-by: Claude Code Assistant Thank you for contributing to Swarms! Replace this comment with: - Description: a description of the change, - Issue: the issue # it fixes (if applicable), - Dependencies: any dependencies required for this change, - Tag maintainer: for a quicker response, tag the relevant maintainer (see below), - Twitter handle: we announce bigger features on Twitter. If your PR gets announced and you'd like a mention, we'll gladly shout you out! Please make sure your PR is passing linting and testing before submitting. Run `make format`, `make lint` and `make test` to check this locally. See contribution guidelines for more information on how to write/run tests, lint, etc: https://github.com/kyegomez/swarms/blob/master/CONTRIBUTING.md If you're adding a new integration, please include: 1. a test for the integration, preferably unit tests that do not rely on network access, 2. an example notebook showing its use. Maintainer responsibilities: - General / Misc / if you don't know who to tag: kye@swarms.world - DataLoaders / VectorStores / Retrievers: kye@swarms.world - swarms.models: kye@swarms.world - swarms.memory: kye@swarms.world - swarms.structures: kye@swarms.world If no one reviews your PR within a few days, feel free to email Kye at kye@swarms.world See contribution guidelines for more information on how to write/run tests, lint, etc: https://github.com/kyegomez/swarms <!-- readthedocs-preview swarms start --> ---- 📚 Documentation preview 📚: https://swarms--1230.org.readthedocs.build/en/1230/ <!-- readthedocs-preview swarms end -->
# Update AgentRearrange Documentation ## Summary Updated the `agent_rearrange2.md` documentation file to include all missing features and methods from the `AgentRearrange` Python implementation. The documentation now accurately reflects all public methods, internal methods, and features available in the `swarms/structs/agent_rearrange.py` file. ## Changes Made ### Added Missing Methods 1. **`reliability_check(self)`** - Public method documentation - Validates configuration parameters (agents, max_loops, flow, output_type) - Automatically called during initialization - Can be manually called to validate configuration after changes - Raises `ValueError` if validation fails 2. **`track_history(self, agent_name: str, result: str)`** - Public method documentation - Tracks execution history for specific agents - Records results for analysis and debugging - Can be called manually or internally ### Enhanced Existing Documentation 1. **`__init__` method** - Added note about automatic `reliability_check()` call during initialization 2. **`set_custom_flow()` method** - Added note about flow validation on next execution 3. **Internal Methods section** - Expanded with: - Detailed documentation of `_run()` method's `custom_tasks` parameter (Dict[str, str] for per-agent task customization) - Additional details on internal helper methods: - `_serialize_callable()` - Helper for serializing callable attributes - `_serialize_attr()` - Helper for serializing individual attributes with non-serializable object handling - Clarified purpose and usage of each internal method 4. **Updated examples** - - Made the example simpler and easier to understand - Focuses on core AgentRearrange features - Avoids unnecessary complexity - Is more portable (doesn't require specific LLM setup) <!-- readthedocs-preview swarms start --> ---- 📚 Documentation preview 📚: https://swarms--1219.org.readthedocs.build/en/1219/ <!-- readthedocs-preview swarms end -->
- Description: Developed tests for all files in swarms.structs not having any. Resolves #1154 <!-- readthedocs-preview swarms start --> ---- 📚 Documentation preview 📚: https://swarms--1201.org.readthedocs.build/en/1201/ <!-- readthedocs-preview swarms end -->
## Description This PR adds comprehensive OpenTelemetry telemetry integration to the Swarms framework, enabling distributed tracing, metrics, and logging capabilities across agents and multi-agent structures. The implementation follows OpenTelemetry standards and provides observability for agent executions, swarm router operations, and LLM calls. ### Key Features - **Distributed Tracing**: Automatic span creation for agent runs, LLM calls, and swarm router executions - **Metrics Collection**: Counter and histogram metrics for agent executions, loops, LLM calls, and errors - **Structured Logging**: OpenTelemetry-compatible logging with severity levels and attributes - **Context Propagation**: Trace context propagation for distributed tracing across agents - **Configurable via Environment Variables**: Full configuration through standard OTEL environment variables - **Graceful Degradation**: Telemetry is optional and gracefully handles missing dependencies ### Implementation Details The telemetry system is integrated at multiple levels: - **Agent Level**: Traces agent runs, LLM calls, tool executions, and records execution metrics - **Swarm Router Level**: Traces swarm router operations and propagates trace context to child swarms - **Error Tracking**: Automatic error recording in spans and metrics for debugging ## File Changes ### `swarms/telemetry/opentelemetry_integration.py` (NEW FILE) - Core OpenTelemetry integration module - Provides `trace_span()` context manager for creating spans - Implements `record_metric()` for metrics collection - Includes `log_event()` for structured logging - Supports trace context propagation via `get_current_trace_context()` and `set_trace_context()` - Configurable via environment variables (OTEL_ENABLED, OTEL_EXPORTER_OTLP_ENDPOINT, etc.) - Gracefully handles missing OpenTelemetry dependencies ### `swarms/telemetry/__init__.py` - Updated to export OpenTelemetry integration functions - Conditionally exports telemetry functions when OpenTelemetry packages are available - Maintains backward compatibility when OpenTelemetry is not installed ### `swarms/structs/agent.py` - Added `enable_telemetry` parameter to Agent `__init__()` method - Integrated telemetry in `_run()` method: - Creates trace span for agent execution with attributes (agent.id, agent.name, agent.model, etc.) - Records metrics for agent executions (total, success, errors) - Records loop count metrics - Integrated telemetry in `call_llm()` method: - Creates trace span for LLM calls with attributes (model, loop number, task length, etc.) - Records metrics for LLM call duration and total calls - Records error metrics for failed LLM calls - Error handling with telemetry: - Records error metrics with error type - Logs error events with OpenTelemetry logging - Sets span status to ERROR on exceptions ### `swarms/structs/swarm_router.py` - Added `telemetry_enabled` parameter to SwarmRouter `__init__()` method - Integrated telemetry in `_run()` method: - Creates trace span for swarm router execution with attributes (router.id, router.name, swarm_type, etc.) - Records metrics for swarm router executions (total, errors) - Propagates trace context to child swarms for distributed tracing - Error handling with telemetry: - Records error metrics with error type and swarm type - Sets span status to ERROR on exceptions ## Dependencies - `opentelemetry-api>=1.20.0` - `opentelemetry-sdk>=1.20.0` - `opentelemetry-exporter-otlp>=1.20.0` Note: These dependencies are optional. The framework works without them, but telemetry features will be disabled. ## Configuration Telemetry is configured via environment variables: - `OTEL_ENABLED`: Enable/disable OpenTelemetry (default: "true") - `OTEL_SERVICE_NAME`: Service name for traces (default: "swarms") - `OTEL_EXPORTER_OTLP_ENDPOINT`: OTLP endpoint URL (e.g., "http://localhost:4317") - `OTEL_EXPORTER_OTLP_HEADERS`: Headers for OTLP exporter (JSON format) - `OTEL_TRACES_EXPORTER`: Traces exporter (default: "otlp") - `OTEL_METRICS_EXPORTER`: Metrics exporter (default: "otlp") - `OTEL_LOGS_EXPORTER`: Logs exporter (default: "otlp") - `OTEL_SDK_DISABLED`: Disable OpenTelemetry SDK (default: "false") ## Usage Example ```python import os from swarms import Agent # Configure OpenTelemetry os.environ["OTEL_ENABLED"] = "true" os.environ["OTEL_SERVICE_NAME"] = "my-swarm-service" os.environ["OTEL_EXPORTER_OTLP_ENDPOINT"] = "http://localhost:4317" # Create agent with telemetry enabled agent = Agent( agent_name="MyAgent", model_name="gpt-4o-mini", enable_telemetry=True, # Enable telemetry ) # Run agent - traces and metrics will be automatically collected result = agent.run("Your task here") ``` ## Testing - Telemetry integration is tested with Jaeger, Tempo, and OpenTelemetry Collector - Verified trace propagation across agent hierarchies - Confirmed metrics collection and export - Tested graceful degradation when OpenTelemetry packages are not installed - Video of testing with Jaeger: https://github.com/user-attachments/assets/66641bba-45c2-418f-b848-27eb09744410 ## Issue: https://github.com/kyegomez/swarms/issues/1199 ## Tag Maintainer @kyegomez ## Twitter Handle https://x.com/IlumTheProtogen <!-- readthedocs-preview swarms start --> ---- 📚 Documentation preview 📚: https://swarms--1200.org.readthedocs.build/en/1200/ <!-- readthedocs-preview swarms end -->
- Integrate open telemetry into agent.py - Integrate telemetry across all multi-agent structures - Export via env variable
Description: This PR implements a REACT (Reason, Act, Observe) workflow for the Agent class when max_loops is set to "auto". This brings structured reasoning and action capabilities similar to how modern AI coding assistants like Cursor handle complex, multi-step tasks. Issue: https://github.com/kyegomez/swarms/issues/1178 The REACT workflow enables agents to: 1. Create a detailed step-by-step plan for the given task 2. Execute each subtask through a structured "Think -> Act -> Observe" loop 3. Use specialized tools (action, subtask_complete, objective_complete) to track progress 4. Work through tasks systematically until completion Key Changes: - Added REACT workflow implementation in _run_react_workflow() method - Integrated REACT tools: action, subtask_complete, and objective_complete - When max_loops="auto", the agent now uses the REACT workflow instead of simple infinite loops - Context length is set to infinite (sys.maxsize) during REACT workflows to prevent context limit issues - Users can integrate their own custom tools alongside REACT tools - Maintains backward compatibility - existing functionality remains unchanged How REACT Works: REACT (Reason, Act, Observe) is a reasoning framework that combines: - Reasoning: The agent thinks about what needs to be done - Acting: The agent takes actions using tools - Observing: The agent observes the results and adjusts its approach This creates a feedback loop where the agent can iteratively refine its approach based on the results of previous actions. How Cursor Uses REACT: Cursor uses a REACT-like workflow to handle complex coding tasks: 1. It breaks down user requests into smaller subtasks 2. For each subtask, it reasons about what needs to be done 3. It takes actions (editing files, running commands, etc.) 4. It observes the results and continues to the next subtask 5. It uses tools like "action", "subtask_complete", and "objective_complete" to track progress This allows Cursor to handle multi-file edits, complex refactorings, and multi-step debugging tasks systematically. How Swarms Now Uses REACT: When max_loops="auto" is set, Swarms agents now follow this workflow: ```mermaid graph TD A[User Task] --> B{max_loops = 'auto'?} B -->|Yes| C[REACT Workflow] B -->|No| Z[Standard Loop] C --> D[Create Plan] D --> E[Generate Step-by-Step Plan] E --> F[Store Plan in Memory] F --> G[REACT Loop Start] G --> H[Think: Analyze Current Subtask] H --> I[Act: Use action tool] I --> J[Observe: Review Results] J --> K{Subtask Complete?} K -->|Yes| L[Call subtask_complete tool] K -->|No| H L --> M{All Subtasks Done?} M -->|No| G M -->|Yes| N[Call objective_complete tool] N --> O[Return Full History] O --> P[End] style C fill:#e1f5ff style D fill:#fff4e1 style G fill:#e8f5e9 style N fill:#f3e5f5 ``` 1. Plan Creation Phase: - The agent analyzes the task and creates a detailed, numbered plan - This plan breaks down the objective into clear, actionable subtasks - The plan is stored in memory and displayed to the user 2. Execution Phase: - For each subtask, the agent enters a "Think -> Act -> Observe" loop - The agent uses the "action" tool to execute specific steps - The agent tracks completed subtasks using "subtask_complete" - The agent continues until all subtasks are done 3. Completion Phase: - When all subtasks are complete, the agent calls "objective_complete" - The workflow terminates and returns the full conversation history Key Features: - Infinite context length during REACT workflows to prevent truncation - Custom tool integration alongside REACT tools - Progress tracking through subtask completion - Detailed logging and error handling - Graceful restoration of original context length after workflow completion Technical Implementation: - Added REACT_ACTION_TOOL, REACT_SUBTASK_COMPLETE_TOOL, and REACT_OBJECTIVE_COMPLETE_TOOL - Created _create_react_plan() method to generate initial plans - Created _handle_react_tool_call() method to parse and execute REACT tool calls - Created _run_react_workflow() method to orchestrate the entire REACT process - Modified _run() method to check for max_loops="auto" and route to REACT workflow - Integrated REACT_SYS_PROMPT from swarms.prompts.react_base_prompt Code Examples: 1. Basic REACT Workflow Usage: ```python from swarms import Agent # Initialize agent with max_loops="auto" to enable REACT workflow agent = Agent( model_name="gpt-4o", max_loops="auto", system_prompt="You are a helpful assistant that can break down complex tasks." ) # Run a complex task - agent will automatically create a plan and execute it result = agent.run("Build a web scraper that fetches data from a website and saves it to a CSV file") ``` 2. REACT Workflow with Custom Tools: ```python from swarms import Agent def search_web(query: str) -> str: """Search the web for information about a query.""" # Implementation here return f"Search results for: {query}" def save_to_file(content: str, filename: str) -> str: """Save content to a file.""" # Implementation here return f"Saved to {filename}" # Agent with custom tools - REACT tools are automatically included agent = Agent( model_name="gpt-4o", max_loops="auto", tools=[search_web, save_to_file], system_prompt="You are a research assistant." ) # Agent will use both REACT tools (action, subtask_complete, objective_complete) # and custom tools (search_web, save_to_file) during execution result = agent.run("Research Python best practices and save findings to a file") ``` 3. REACT Tool Definitions: ```python # REACT_ACTION_TOOL - For executing actions within subtasks REACT_ACTION_TOOL = { "type": "function", "function": { "name": "action", "description": "Execute an action or use a tool to make progress on the current subtask.", "parameters": { "type": "object", "properties": { "action_description": {"type": "string"}, "action_result": {"type": "string"} }, "required": ["action_description", "action_result"] } } } # REACT_SUBTASK_COMPLETE_TOOL - For marking subtasks as complete REACT_SUBTASK_COMPLETE_TOOL = { "type": "function", "function": { "name": "subtask_complete", "description": "Mark the current subtask as complete.", "parameters": { "type": "object", "properties": { "subtask_number": {"type": "integer"}, "subtask_summary": {"type": "string"} }, "required": ["subtask_number", "subtask_summary"] } } } # REACT_OBJECTIVE_COMPLETE_TOOL - For marking entire objective as complete REACT_OBJECTIVE_COMPLETE_TOOL = { "type": "function", "function": { "name": "objective_complete", "description": "Mark the entire objective as complete.", "parameters": { "type": "object", "properties": { "final_summary": {"type": "string"} }, "required": ["final_summary"] } } } ``` 4. Workflow Routing in _run() Method: ```python def _run(self, task, img=None, streaming_callback=None, *args, **kwargs): # ... existing code ... # Use REACT workflow when max_loops is "auto" if self.max_loops == "auto": return self._run_react_workflow( task=task, img=img, streaming_callback=streaming_callback, *args, **kwargs, ) # ... continue with standard loop ... ``` 5. Plan Creation Method: ```python def _create_react_plan(self, task: str) -> str: """Create a detailed plan for REACT workflow execution.""" plan_prompt = f"""Create a detailed, step-by-step plan to complete the following task. Break down the task into clear, actionable subtasks that can be completed sequentially. Number each subtask starting from 1. Task: {task} Format your response as a numbered list of subtasks...""" plan = self.llm.run(task=plan_prompt) self.short_memory.add( role=self.agent_name, content=f"Plan created:\n{plan}", ) return plan ``` Dependencies: - No new external dependencies required - Uses existing swarms.prompts.react_base_prompt module - Compatible with existing tool integration system Tag maintainer: @kyegomez Twitter handle: https://x.com/IlumTheProtogen Testing: - Tested with various complex tasks requiring multiple steps - Verified backward compatibility with existing max_loops integer values - Confirmed custom tools work alongside REACT tools - Tested context length handling during long workflows - Verified error handling and recovery mechanisms Backward Compatibility: - All existing functionality remains unchanged - max_loops as integer values work exactly as before - Only max_loops="auto" triggers the new REACT workflow - Existing tools and configurations are fully supported <!-- readthedocs-preview swarms start --> ---- 📚 Documentation preview 📚: https://swarms--1182.org.readthedocs.build/en/1182/ <!-- readthedocs-preview swarms end -->
- If agent.max_loops is = "auto" - Agent must create a plan - Then for each item in that plan it needs to loop into a thinking -> action loop like cursor does with tools such as action, sub task complete, and then proceed with the next task, - Then a final tool to signify that the entire objective is complete - User can input their own custom tools as well
- Enable every agent to be monetize-able via aop, have a new pydantic model to customize the parameters - https://docs.cdp.coinbase.com/x402/quickstart-for-sellers#python - Every agent in the aop server can accept payments
- Implement the paper ParallelMuse: Agentic Parallel Thinking for Deep Information Seeking in `swarms.structs` - Paper link: https://huggingface.co/papers/2510.24698