DAO Proposals & Community
View active proposals, submit new ideas, and connect with the SWARMS community.
Bumps [pypdf](https://github.com/py-pdf/pypdf) from 5.1.0 to 6.6.1. <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.6.1, 2026-01-25</h2> <h2>What's new</h2> <h3>Robustness (ROB)</h3> <ul> <li><code>/AcroForm</code> might be NullObject (<a href="https://redirect.github.com/py-pdf/pypdf/issues/3601">#3601</a>) by <a href="https://github.com/joshkersey"><code>@joshkersey</code></a></li> <li>Handle missing font bounding boxes gracefully (<a href="https://redirect.github.com/py-pdf/pypdf/issues/3600">#3600</a>) by <a href="https://github.com/LudovA"><code>@LudovA</code></a></li> </ul> <p><a href="https://github.com/py-pdf/pypdf/compare/6.6.0...6.6.1">Full Changelog</a></p> <h2>Version 6.6.0, 2026-01-09</h2> <h2>What's new</h2> <h3>Security (SEC)</h3> <ul> <li>Improve handling of partially broken PDF files (<a href="https://redirect.github.com/py-pdf/pypdf/issues/3594">#3594</a>) by <a href="https://github.com/stefan6419846"><code>@stefan6419846</code></a></li> </ul> <h3>Deprecations (DEP)</h3> <ul> <li>Block common page content modifications when assigned to reader (<a href="https://redirect.github.com/py-pdf/pypdf/issues/3582">#3582</a>) by <a href="https://github.com/stefan6419846"><code>@stefan6419846</code></a></li> </ul> <h3>New Features (ENH)</h3> <ul> <li>Embellishments to generated text appearance streams (<a href="https://redirect.github.com/py-pdf/pypdf/issues/3571">#3571</a>) by <a href="https://github.com/PJBrs"><code>@PJBrs</code></a></li> </ul> <h3>Bug Fixes (BUG)</h3> <ul> <li>Do not consider multi-byte BOM-like sequences as BOMs (<a href="https://redirect.github.com/py-pdf/pypdf/issues/3589">#3589</a>) by <a href="https://github.com/stefan6419846"><code>@stefan6419846</code></a></li> </ul> <h3>Robustness (ROB)</h3> <ul> <li>Avoid empty FlateDecode outputs without warning (<a href="https://redirect.github.com/py-pdf/pypdf/issues/3579">#3579</a>) by <a href="https://github.com/stefan6419846"><code>@stefan6419846</code></a></li> </ul> <h3>Documentation (DOC)</h3> <ul> <li>Add outlines documentation and link it in User Guide (<a href="https://redirect.github.com/py-pdf/pypdf/issues/3511">#3511</a>) by <a href="https://github.com/mainuddin-md"><code>@mainuddin-md</code></a></li> </ul> <h3>Developer Experience (DEV)</h3> <ul> <li>Add PyPy 3.11 to test matrix and benchmarks (<a href="https://redirect.github.com/py-pdf/pypdf/issues/3574">#3574</a>) by <a href="https://github.com/rassie"><code>@rassie</code></a></li> </ul> <h3>Maintenance (MAINT)</h3> <ul> <li>Fix compatibility with Pillow >= 12.1.0 (<a href="https://redirect.github.com/py-pdf/pypdf/issues/3590">#3590</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.5.0...6.6.0">Full Changelog</a></p> <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> <!-- 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.6.1, 2026-01-25</h2> <h3>Robustness (ROB)</h3> <ul> <li><code>/AcroForm</code> might be NullObject (<a href="https://redirect.github.com/py-pdf/pypdf/issues/3601">#3601</a>)</li> <li>Handle missing font bounding boxes gracefully (<a href="https://redirect.github.com/py-pdf/pypdf/issues/3600">#3600</a>)</li> </ul> <p><a href="https://github.com/py-pdf/pypdf/compare/6.6.0...6.6.1">Full Changelog</a></p> <h2>Version 6.6.0, 2026-01-09</h2> <h3>Security (SEC)</h3> <ul> <li>Improve handling of partially broken PDF files (<a href="https://redirect.github.com/py-pdf/pypdf/issues/3594">#3594</a>)</li> </ul> <h3>Deprecations (DEP)</h3> <ul> <li>Block common page content modifications when assigned to reader (<a href="https://redirect.github.com/py-pdf/pypdf/issues/3582">#3582</a>)</li> </ul> <h3>New Features (ENH)</h3> <ul> <li>Embellishments to generated text appearance streams (<a href="https://redirect.github.com/py-pdf/pypdf/issues/3571">#3571</a>)</li> </ul> <h3>Bug Fixes (BUG)</h3> <ul> <li>Do not consider multi-byte BOM-like sequences as BOMs (<a href="https://redirect.github.com/py-pdf/pypdf/issues/3589">#3589</a>)</li> </ul> <h3>Robustness (ROB)</h3> <ul> <li>Avoid empty FlateDecode outputs without warning (<a href="https://redirect.github.com/py-pdf/pypdf/issues/3579">#3579</a>)</li> </ul> <h3>Documentation (DOC)</h3> <ul> <li>Add outlines documentation and link it in User Guide (<a href="https://redirect.github.com/py-pdf/pypdf/issues/3511">#3511</a>)</li> </ul> <h3>Developer Experience (DEV)</h3> <ul> <li>Add PyPy 3.11 to test matrix and benchmarks (<a href="https://redirect.github.com/py-pdf/pypdf/issues/3574">#3574</a>)</li> </ul> <h3>Maintenance (MAINT)</h3> <ul> <li>Fix compatibility with Pillow >= 12.1.0 (<a href="https://redirect.github.com/py-pdf/pypdf/issues/3590">#3590</a>)</li> </ul> <p><a href="https://github.com/py-pdf/pypdf/compare/6.5.0...6.6.0">Full Changelog</a></p> <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> <!-- raw HTML omitted --> </blockquote> <p>... (truncated)</p> </details> <details> <summary>Commits</summary> <ul> <li><a href="https://github.com/py-pdf/pypdf/commit/f18e13c91cd47fa740997df4a7307fbc976388e1"><code>f18e13c</code></a> REL: 6.6.1</li> <li><a href="https://github.com/py-pdf/pypdf/commit/19735763b856cccf0f69630d0f582a448ec5d8bb"><code>1973576</code></a> DEV: Bump wheel from 0.44.0 to 0.46.2 (<a href="https://redirect.github.com/py-pdf/pypdf/issues/3608">#3608</a>)</li> <li><a href="https://github.com/py-pdf/pypdf/commit/4740225eaa67ad2e032e63d0453ea6c80bcae158"><code>4740225</code></a> ROB: <code>/AcroForm</code> might be NullObject (<a href="https://redirect.github.com/py-pdf/pypdf/issues/3601">#3601</a>)</li> <li><a href="https://github.com/py-pdf/pypdf/commit/26fd6388754ed167e862bdd7a3eba614da191d34"><code>26fd638</code></a> ROB: Handle missing font bounding boxes gracefully (<a href="https://redirect.github.com/py-pdf/pypdf/issues/3600">#3600</a>)</li> <li><a href="https://github.com/py-pdf/pypdf/commit/affe8eddf185b2875dcfa45090b7d09f06d3ba12"><code>affe8ed</code></a> DEV: Bump virtualenv from 20.27.0 to 20.36.1 (<a href="https://redirect.github.com/py-pdf/pypdf/issues/3597">#3597</a>)</li> <li><a href="https://github.com/py-pdf/pypdf/commit/df1b91da41e38ffaf0815e3fd687c037b375c728"><code>df1b91d</code></a> DEV: Add missing dependency to URL check</li> <li><a href="https://github.com/py-pdf/pypdf/commit/10df9c72fa7fb9ab14101b9cb911d66e680282a8"><code>10df9c7</code></a> REL: 6.6.0</li> <li><a href="https://github.com/py-pdf/pypdf/commit/294165726b646bb7799be1cc787f593f2fdbcf45"><code>2941657</code></a> SEC: Improve handling of partially broken PDF files (<a href="https://redirect.github.com/py-pdf/pypdf/issues/3594">#3594</a>)</li> <li><a href="https://github.com/py-pdf/pypdf/commit/712688005e49d2d0a4427db0b16abbae160fe106"><code>7126880</code></a> DEV: Update to urllib3 2.6.3 (<a href="https://redirect.github.com/py-pdf/pypdf/issues/3593">#3593</a>)</li> <li><a href="https://github.com/py-pdf/pypdf/commit/f189f0755eb111564ae8667a990738a9e7ab4ba9"><code>f189f07</code></a> DOC: Add outlines documentation and link it in User Guide (<a href="https://redirect.github.com/py-pdf/pypdf/issues/3511">#3511</a>)</li> <li>Additional commits viewable in <a href="https://github.com/py-pdf/pypdf/compare/5.1.0...6.6.1">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--1332.org.readthedocs.build/en/1332/ <!-- readthedocs-preview swarms end -->
![dependabot[bot]](https://avatars.githubusercontent.com/in/29110?v=4)
Proposed by dependabot[bot]<!-- readthedocs-preview swarms start --> ---- 📚 Documentation preview 📚: https://swarms--1326.org.readthedocs.build/en/1326/ <!-- readthedocs-preview swarms end -->
Proposed by hughiwnl## Overview Implement a parallel worker execution system that coordinates hundreds of agents working on a single codebase for long-running autonomous projects. ## Background Reference: [Scaling long-running autonomous coding](https://www.cursor.com/blog/scaling-long-running-autonomous-coding) Traditional single-agent approaches are too slow for complex projects. The solution is parallel workers with clear responsibilities, but without the coordination overhead of flat structures. ## Proposed Solution ### Worker Architecture Create a focused worker system that: 1. **Worker Agent** - Picks up tasks from shared queue - Focuses entirely on completing assigned task - No coordination with other workers - No big-picture planning responsibilities - Pushes changes directly to branch when complete 2. **Conflict Resolution** - Workers handle merge conflicts themselves - No separate "integrator" role (creates bottlenecks) - Automatic retry on conflict with fresh codebase state - Workers re-plan locally if conflicts are significant 3. **Judge Agent** (Cycle Management) - Runs at end of each cycle - Determines whether to continue or restart - Analyzes overall progress and quality - Triggers fresh start to combat drift when needed ### Key Design Principles - **Single responsibility**: Workers only execute, no coordination - **Autonomous conflict handling**: Workers resolve their own conflicts - **Model selection**: Use best model for coding (e.g., GPT-5.2-codex for implementation) - **Horizontal scaling**: Hundreds of workers can run concurrently - **Minimal bottlenecks**: No locks, no central integrator ## Implementation Tasks - [ ] Design worker agent interface and lifecycle - [ ] Implement task claim mechanism from queue (optimistic concurrency) - [ ] Create worker execution loop with focus on single task - [ ] Add automatic conflict detection and retry logic - [ ] Implement direct branch push mechanism - [ ] Create judge agent for cycle completion assessment - [ ] Add worker-specific prompts for focused execution - [ ] Implement model selection configuration per worker type - [ ] Add observability: worker status, task progress, conflicts - [ ] Create worker pool management (spawn/scale workers) - [ ] Add failure recovery: timeout detection, stuck worker handling - [ ] Implement periodic fresh start mechanism ## Success Criteria - [ ] 100+ workers can run concurrently on single project - [ ] Minimal merge conflicts (<5% of pushes) - [ ] Workers handle conflicts autonomously without manual intervention - [ ] No coordination bottlenecks or lock contention - [ ] Workers maintain focus on assigned tasks (no drift) - [ ] Judge agent effectively determines cycle completion ## Real-World Validation Targets Based on Cursor's experiments: - [ ] Handle codebases of 1M+ LoC - [ ] Support 1000+ files - [ ] Run for 1+ weeks continuously - [ ] Process 10K+ commits - [ ] Handle +250K/-200K line migrations ## Technical Considerations - Workers should timeout if running too long (configurable threshold) - Implement exponential backoff for conflict retries - Add telemetry for worker efficiency metrics - Consider Git strategies: rebase vs merge for conflict resolution - Add circuit breaker for pathological behaviors - Implement graceful shutdown for long-running workers ## Anti-patterns to Avoid - ❌ Central integrator role (creates bottlenecks) - ❌ Worker-to-worker communication (adds complexity) - ❌ Locks or pessimistic concurrency (doesn't scale) - ❌ Risk-averse small changes (leads to churn without progress)
Proposed by kyegomez## Overview Implement a hierarchical planner system based on Cursor's multi-agent coordination architecture for long-running autonomous coding projects. ## Background Reference: [Scaling long-running autonomous coding](https://www.cursor.com/blog/scaling-long-running-autonomous-coding) Current flat agent structures fail at scale due to: - Risk-averse behavior and small, safe changes - No ownership of hard problems - Work churning without meaningful progress - Poor coordination at scale ## Proposed Solution ### Planner Architecture Create a hierarchical planning system with distinct responsibilities: 1. **Primary Planner Agent** - Continuously explores the codebase - Creates high-level tasks based on project goals - Monitors overall progress - Can spawn sub-planners for specific areas 2. **Sub-Planner Agents** (Recursive Planning) - Focus on specific domains/modules - Break down high-level tasks into actionable work items - Report back to parent planner - Enable parallel planning across the codebase 3. **Task Queue Management** - Shared task queue accessible by workers - Task metadata: priority, dependencies, estimated complexity - Optimistic concurrency control (no locks) - Task status tracking (pending, in-progress, completed, failed) ### Key Design Principles - **Separation of concerns**: Planners don't execute, workers don't plan - **Simplicity over complexity**: Avoid over-engineering coordination - **Model selection per role**: Use best model for planning (e.g., GPT-5.2 for long-context understanding) - **Recursive planning**: Break down complexity through parallel sub-planners ## Implementation Tasks - [ ] Design task queue schema and storage mechanism - [ ] Implement primary planner agent with codebase exploration - [ ] Create sub-planner spawning mechanism - [ ] Add optimistic concurrency control for task queue - [ ] Implement task metadata system (priority, dependencies, etc.) - [ ] Add planner-specific prompts for focused task generation - [ ] Create monitoring/observability for planner decisions - [ ] Implement model selection configuration per planner role - [ ] Add unit tests for planner coordination logic ## Success Criteria - [ ] Planners can explore large codebases (1M+ LoC) effectively - [ ] Sub-planners can be spawned recursively without bottlenecks - [ ] Task queue handles hundreds of concurrent reads/writes - [ ] No deadlocks or coordination failures - [ ] Clear task ownership and progress tracking ## Related Work - Agents should avoid tunnel vision and drift over extended periods - Prompts matter more than infrastructure for behavior control - System should self-recover from agent failures ## Technical Considerations - Consider using Redis or similar for task queue with atomic operations - Implement periodic "fresh start" cycles to combat drift - Add judge agent integration point for cycle completion assessment
Proposed by kyegomezResolves #1143 <!-- readthedocs-preview swarms start --> ---- 📚 Documentation preview 📚: https://swarms--1316.org.readthedocs.build/en/1316/ <!-- readthedocs-preview swarms end -->
Proposed by ZackBradshawresolves #1295 <!-- readthedocs-preview swarms start --> ---- 📚 Documentation preview 📚: https://swarms--1313.org.readthedocs.build/en/1313/ <!-- readthedocs-preview swarms end -->
Proposed by ZackBradshawResolves #1294 <!-- readthedocs-preview swarms start --> ---- 📚 Documentation preview 📚: https://swarms--1301.org.readthedocs.build/en/1301/ <!-- readthedocs-preview swarms end -->
Proposed by ZackBradshawresolves #1297 <!-- readthedocs-preview swarms start --> ---- 📚 Documentation preview 📚: https://swarms--1300.org.readthedocs.build/en/1300/ <!-- readthedocs-preview swarms end -->
Proposed by ZackBradshaw## Summary Fix and complete streaming support in the autonomous loop structure (`max_loops="auto"`). Currently, streaming works partially during planning and execution phases but **does not work in the final summary phase**, breaking the end-to-end streaming experience. The autonomous loop structure in `agent.py` supports three phases: 1. **Planning Phase** ✅ - Streaming works 2. **Execution Phase** ✅ - Streaming works 3. **Summary Phase** ❌ - Streaming does NOT work When users enable streaming (`streaming_on=True` or `stream=True`) with `max_loops="auto"`, they expect continuous token streaming throughout the entire autonomous loop. However, the final summary generation happens without streaming, causing an inconsistent user experience. ### Current Behavior ```python from swarms import Agent # User enables streaming with autonomous loop agent = Agent( agent_name="TaskAgent", system_prompt="You are a helpful assistant", model_name="gpt-4", max_loops="auto", # Autonomous loop enabled streaming_on=True, # User expects streaming throughout verbose=True ) def on_token(token): print(token, end="", flush=True) # Run with streaming callback result = agent.run( task="Create a comprehensive marketing plan", streaming_callback=on_token ) # Result: # ✅ Planning phase streams tokens # ✅ Execution phase streams tokens # ❌ Summary phase does NOT stream (silent until complete) ``` This improvement is essential for production-grade autonomous agents where real-time feedback and responsiveness are critical requirements.
Proposed by kyegomezCreate comprehensive documentation educating users about the various output formats available in `agent.py` and all swarm architectures (SwarmRouter, SequentialWorkflow, ConcurrentWorkflow, etc.), including their response types, streaming capabilities, and usage patterns. ## Background Swarms provides extensive output format customization across 15+ output types and 11+ swarm architectures, but this flexibility is not well-documented. Users need clear guidance on: 1. What output formats are available 2. When to use each format 3. How swarm architectures differ in their outputs 4. Streaming capabilities and callbacks 5. Response schemas and structured outputs ## Current State ### Output Formats Available (swarms/utils/output_types.py) The framework supports 15+ output types: ```python HistoryOutputType = Literal[ "list", # Returns conversation as a list of message dicts "dict", # Returns conversation as a dictionary "dictionary", # Alias for dict "string", # Returns conversation as a string "str", # Alias for string "final", # Returns content of the final message only "last", # Alias for final "json", # Returns conversation as JSON string "all", # Returns conversation as string (same as "string") "yaml", # Returns conversation as YAML string "xml", # Returns conversation as XML string "dict-all-except-first", # Returns all messages except first as dict "str-all-except-first", # Returns all messages except first as string "basemodel", # Returns as BaseModel "dict-final", # Returns final message as a dictionary "list-final", # Returns final message as a list ] ``` ### Swarm Architectures Summary | Swarm Type | Default Output | Execution Model | Key Feature | File Location | |-----------|----------------|-----------------|-------------|---------------| | SequentialWorkflow | `dict` | Sequential | Agent-to-agent passing | `swarms/structs/sequential_workflow.py` | | ConcurrentWorkflow | `dict-all-except-first` | Threaded | Dashboard + streaming | `swarms/structs/concurrent_workflow.py` | | SwarmRouter | `dict-all-except-first` | Routed | 18 swarm types | `swarms/structs/swarm_router.py` | | AgentRearrange | `all` | Custom flow | Flexible patterns | `swarms/structs/agent_rearrange.py` | | MixtureOfAgents | `final` | Multi-layer | Aggregator synthesis | `swarms/structs/mixture_of_agents.py` | - should be in the examples section of mkdocs - should be simple, and show the agent.py examples with maybe one or 2 multi agent architectures
Proposed by kyegomez## Summary Add support for `max_loops="auto"` in the Swarms CLI to enable the autonomous agent loop structure with automatic planning, subtask execution, and summarization. ## Background The `Agent` class in `swarms/structs/agent.py` already supports an autonomous loop feature that is triggered when `max_loops="auto"`. This powerful capability enables: 1. **Automatic Planning**: Agent breaks down complex tasks into subtasks 2. **Subtask Execution**: Sequential execution with tool integration 3. **Final Summarization**: Comprehensive summary of all work done However, the CLI currently doesn't expose this feature because the `--max-loops` argument is defined as `type=int`, preventing users from passing the string value `"auto"`. ## Current Implementation ### In agent.py (lines 536, 601, 1207, 1564, 2029, 4345) The agent already implements autonomous loop logic: ```python # Check if we should use autonomous loop structure use_autonomous_loop = ( self.max_loops == "auto" and self.interactive is False ) if use_autonomous_loop: # Use autonomous loop structure: plan -> execute subtasks -> summary output = self._run_autonomous_loop( task=task, img=img, imgs=imgs, ) ``` ### In CLI (swarms/cli/main.py:1661-1664) Currently restricts to integers only: ```python parser.add_argument( "--max-loops", type=int, # ❌ This prevents "auto" from being accepted help="Maximum number of loops for the agent", ) ``` ## Proposed Changes ### 1. Update CLI Argument Parser (swarms/cli/main.py) Change the `--max-loops` argument to accept both integers and the string "auto": ```python parser.add_argument( "--max-loops", type=str, # Change to str to allow "auto" help="Maximum number of loops for the agent (integer or 'auto' for autonomous loop structure)", ) ``` ### 2. Add Validation Logic Add validation to convert string integers to int type: ```python # In the agent creation section (around line 1940) max_loops_value = args.max_loops if max_loops_value is not None: if max_loops_value.lower() == "auto": additional_params["max_loops"] = "auto" else: try: additional_params["max_loops"] = int(max_loops_value) except ValueError: show_error( "Invalid max_loops value", "max_loops must be an integer or 'auto'" ) exit(1) ``` ### 3. Update Help Documentation Update the CLI help text and documentation to advertise this powerful feature: ```python # In show_features() and create_detailed_command_table() "--max-loops: Maximum loops (integer or 'auto' for autonomous planning)" ``` ## Benefits 1. **Exposes Powerful Feature**: Makes autonomous loop accessible to CLI users 2. **Better Task Decomposition**: Complex tasks are automatically broken down 3. **Tool Integration**: Seamlessly integrates with the autonomous loop's tool system 4. **Structured Execution**: Plan → Execute → Summarize workflow 5. **CLI Parity**: Brings CLI functionality in line with programmatic API ## Example Usage After implementation: ```bash # Enable autonomous loop with automatic planning swarms agent \ --name "Research Agent" \ --description "Deep research assistant" \ --system-prompt "You are a thorough research assistant" \ --task "Research the latest developments in quantum computing" \ --max-loops auto \ --verbose # Traditional fixed loops still work swarms agent \ --name "Simple Agent" \ --task "Summarize this text" \ --max-loops 3 ``` ## Related Files - `swarms/cli/main.py` (lines 1661-1664, 1940-1963) - CLI argument parsing and agent creation - `swarms/structs/agent.py` (lines 536, 601, 1207, 1564, 2029-2825, 4343-4351) - Autonomous loop implementation - `swarms/structs/autonomous_loop_utils.py` - Utility functions for autonomous loop ## References - Autonomous loop implementation: `swarms/structs/agent.py:2029-2825` - Planning phase: `swarms/structs/agent.py:2193-2374` - Execution phase: `swarms/structs/agent.py:2375-2811` - Summary phase: `swarms/structs/agent.py:2812-2825` ## Additional Notes The autonomous loop feature includes: - **Planning tools**: `create_subtasks` for task decomposition - **Execution tools**: `respond_to_user`, file operations (create, read, update, delete, list) - **Reflection tools**: `think` for reasoning before action - **Completion tools**: `mark_subtask_complete` for tracking progress - **Loop prevention**: `max_consecutive_thinks` to prevent infinite loops This is a high-value feature that significantly enhances the CLI's capabilities for complex, multi-step tasks.
Proposed by kyegomez- Implement the paper TCAndon-Router: Adaptive Reasoning Router for Multi-Agent Collaboration (https://arxiv.org/pdf/2601.04544) - Make a new file - Make it a class with a run parameter - Make sure input is a list of agents
Proposed by kyegomezBumps [pypdf](https://github.com/py-pdf/pypdf) from 5.1.0 to 6.6.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.6.0, 2026-01-09</h2> <h2>What's new</h2> <h3>Security (SEC)</h3> <ul> <li>Improve handling of partially broken PDF files (<a href="https://redirect.github.com/py-pdf/pypdf/issues/3594">#3594</a>) by <a href="https://github.com/stefan6419846"><code>@stefan6419846</code></a></li> </ul> <h3>Deprecations (DEP)</h3> <ul> <li>Block common page content modifications when assigned to reader (<a href="https://redirect.github.com/py-pdf/pypdf/issues/3582">#3582</a>) by <a href="https://github.com/stefan6419846"><code>@stefan6419846</code></a></li> </ul> <h3>New Features (ENH)</h3> <ul> <li>Embellishments to generated text appearance streams (<a href="https://redirect.github.com/py-pdf/pypdf/issues/3571">#3571</a>) by <a href="https://github.com/PJBrs"><code>@PJBrs</code></a></li> </ul> <h3>Bug Fixes (BUG)</h3> <ul> <li>Do not consider multi-byte BOM-like sequences as BOMs (<a href="https://redirect.github.com/py-pdf/pypdf/issues/3589">#3589</a>) by <a href="https://github.com/stefan6419846"><code>@stefan6419846</code></a></li> </ul> <h3>Robustness (ROB)</h3> <ul> <li>Avoid empty FlateDecode outputs without warning (<a href="https://redirect.github.com/py-pdf/pypdf/issues/3579">#3579</a>) by <a href="https://github.com/stefan6419846"><code>@stefan6419846</code></a></li> </ul> <h3>Documentation (DOC)</h3> <ul> <li>Add outlines documentation and link it in User Guide (<a href="https://redirect.github.com/py-pdf/pypdf/issues/3511">#3511</a>) by <a href="https://github.com/mainuddin-md"><code>@mainuddin-md</code></a></li> </ul> <h3>Developer Experience (DEV)</h3> <ul> <li>Add PyPy 3.11 to test matrix and benchmarks (<a href="https://redirect.github.com/py-pdf/pypdf/issues/3574">#3574</a>) by <a href="https://github.com/rassie"><code>@rassie</code></a></li> </ul> <h3>Maintenance (MAINT)</h3> <ul> <li>Fix compatibility with Pillow >= 12.1.0 (<a href="https://redirect.github.com/py-pdf/pypdf/issues/3590">#3590</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.5.0...6.6.0">Full Changelog</a></p> <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> <!-- 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.6.0, 2026-01-09</h2> <h3>Security (SEC)</h3> <ul> <li>Improve handling of partially broken PDF files (<a href="https://redirect.github.com/py-pdf/pypdf/issues/3594">#3594</a>)</li> </ul> <h3>Deprecations (DEP)</h3> <ul> <li>Block common page content modifications when assigned to reader (<a href="https://redirect.github.com/py-pdf/pypdf/issues/3582">#3582</a>)</li> </ul> <h3>New Features (ENH)</h3> <ul> <li>Embellishments to generated text appearance streams (<a href="https://redirect.github.com/py-pdf/pypdf/issues/3571">#3571</a>)</li> </ul> <h3>Bug Fixes (BUG)</h3> <ul> <li>Do not consider multi-byte BOM-like sequences as BOMs (<a href="https://redirect.github.com/py-pdf/pypdf/issues/3589">#3589</a>)</li> </ul> <h3>Robustness (ROB)</h3> <ul> <li>Avoid empty FlateDecode outputs without warning (<a href="https://redirect.github.com/py-pdf/pypdf/issues/3579">#3579</a>)</li> </ul> <h3>Documentation (DOC)</h3> <ul> <li>Add outlines documentation and link it in User Guide (<a href="https://redirect.github.com/py-pdf/pypdf/issues/3511">#3511</a>)</li> </ul> <h3>Developer Experience (DEV)</h3> <ul> <li>Add PyPy 3.11 to test matrix and benchmarks (<a href="https://redirect.github.com/py-pdf/pypdf/issues/3574">#3574</a>)</li> </ul> <h3>Maintenance (MAINT)</h3> <ul> <li>Fix compatibility with Pillow >= 12.1.0 (<a href="https://redirect.github.com/py-pdf/pypdf/issues/3590">#3590</a>)</li> </ul> <p><a href="https://github.com/py-pdf/pypdf/compare/6.5.0...6.6.0">Full Changelog</a></p> <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> <!-- raw HTML omitted --> </blockquote> <p>... (truncated)</p> </details> <details> <summary>Commits</summary> <ul> <li><a href="https://github.com/py-pdf/pypdf/commit/10df9c72fa7fb9ab14101b9cb911d66e680282a8"><code>10df9c7</code></a> REL: 6.6.0</li> <li><a href="https://github.com/py-pdf/pypdf/commit/294165726b646bb7799be1cc787f593f2fdbcf45"><code>2941657</code></a> SEC: Improve handling of partially broken PDF files (<a href="https://redirect.github.com/py-pdf/pypdf/issues/3594">#3594</a>)</li> <li><a href="https://github.com/py-pdf/pypdf/commit/712688005e49d2d0a4427db0b16abbae160fe106"><code>7126880</code></a> DEV: Update to urllib3 2.6.3 (<a href="https://redirect.github.com/py-pdf/pypdf/issues/3593">#3593</a>)</li> <li><a href="https://github.com/py-pdf/pypdf/commit/f189f0755eb111564ae8667a990738a9e7ab4ba9"><code>f189f07</code></a> DOC: Add outlines documentation and link it in User Guide (<a href="https://redirect.github.com/py-pdf/pypdf/issues/3511">#3511</a>)</li> <li><a href="https://github.com/py-pdf/pypdf/commit/a29e5326f543f93c4c317cf9f92df54aff68c584"><code>a29e532</code></a> BUG: Do not consider multi-byte BOM-like sequences as BOMs (<a href="https://redirect.github.com/py-pdf/pypdf/issues/3589">#3589</a>)</li> <li><a href="https://github.com/py-pdf/pypdf/commit/d9ce594772717fdcfcd505d0309843461579bbf7"><code>d9ce594</code></a> MAINT: Converge on one shared Font class for text extraction and appearance s...</li> <li><a href="https://github.com/py-pdf/pypdf/commit/a65708c778467f1525662dfe5614a486adbd16b0"><code>a65708c</code></a> DEV: Check for JavaScript library updates on GitHub Pages (<a href="https://redirect.github.com/py-pdf/pypdf/issues/3592">#3592</a>)</li> <li><a href="https://github.com/py-pdf/pypdf/commit/6951bb7c039afd02bd273dda412c3f36df76eba3"><code>6951bb7</code></a> MAINT: Fix compatibility with Pillow >= 12.1.0 (<a href="https://redirect.github.com/py-pdf/pypdf/issues/3590">#3590</a>)</li> <li><a href="https://github.com/py-pdf/pypdf/commit/97d47a001d574dfda54bf16c4dcee89ccbfabec8"><code>97d47a0</code></a> TST: Improve test coverage (<a href="https://redirect.github.com/py-pdf/pypdf/issues/3584">#3584</a>)</li> <li><a href="https://github.com/py-pdf/pypdf/commit/bda80a4846a8646419a04cc253d81b73773d3cec"><code>bda80a4</code></a> DEV: Add PyPy 3.11 to test matrix and benchmarks (<a href="https://redirect.github.com/py-pdf/pypdf/issues/3574">#3574</a>)</li> <li>Additional commits viewable in <a href="https://github.com/py-pdf/pypdf/compare/5.1.0...6.6.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) You can disable automated security fix PRs for this repo from the [Security Alerts page](https://github.com/kyegomez/swarms/network/alerts). </details> <!-- readthedocs-preview swarms start --> ---- 📚 Documentation preview 📚: https://swarms--1289.org.readthedocs.build/en/1289/ <!-- readthedocs-preview swarms end -->
Proposed by dependabot[bot]Create practical example tutorials for all multi-agent architectures that are exported in swarms.structs.__init__ and add them to the examples section of the mkdocs documentation.
Proposed by kyegomezImprove telemetry log capture so users can see all the agents they have created in the swarms telemetry platform. Consider implementing OpenTelemetry or other faster alternatives for better agent tracking and monitoring capabilities.
Proposed by kyegomezImprove autosaving logic for all multi-agent architectures to save configurations and state to workspace_dir/swarms/swarm-name/config.json and other related files for better organization and persistence.
Proposed by kyegomez## 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 -->
Proposed by Steve-Dusty# 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 -->
Proposed by Steve-DustyTo 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.
Proposed by Steve-Dusty<!-- readthedocs-preview swarms start --> ---- 📚 Documentation preview 📚: https://swarms--1260.org.readthedocs.build/en/1260/ <!-- readthedocs-preview swarms end -->
Proposed by hughiwnl- 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 -->
Proposed by aparekh02### 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 -->
Proposed by Steve-Dustyadded documentation for circular swarm <!-- readthedocs-preview swarms start --> ---- 📚 Documentation preview 📚: https://swarms--1244.org.readthedocs.build/en/1244/ <!-- readthedocs-preview swarms end -->
Proposed by hughiwnl## 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 -->
Proposed by IlumCIdescription ----------------- 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 -->
Proposed by IlumCI