strands-swarms 0.1.0__py3-none-any.whl → 0.1.2__py3-none-any.whl

strands_swarms/orchestrator.py

@@ -1,265 +1,116 @@
-"""Orchestrator agent that plans, creates sub-agents, assigns tasks, and synthesizes completion."""
+"""Orchestrator agent that plans and creates sub-agents and tasks."""
 
 from __future__ import annotations
 
 from typing import TYPE_CHECKING, Any
 
 from strands import Agent, tool
-from strands.hooks import HookRegistry
-
-from .events import AgentInfo, AgentSpawnedEvent, PlanningCompletedEvent, TaskCreatedEvent, TaskInfo
 
 if TYPE_CHECKING:
     from strands.models import Model
 
-    from .swarm import SwarmConfig
-
+    from .definition import SwarmDefinition
 
-# --- System Prompt ---
 
 ORCHESTRATOR_SYSTEM_PROMPT = """\
-You are a workflow orchestrator that plans, creates sub-agents, assigns tasks, and synthesizes completion.
-
-## Your Four Responsibilities
-
-### 1. Planning
-Analyze the request and break it into logical steps. Determine what specialized agents are needed.
-
-### 2. Creating Sub-agents
-Spawn specialized agents with appropriate tools and models. Each agent should have a focused role.
-
-### 3. Assigning Tasks
-Create tasks and assign them to agents. Define dependencies when one task needs results from another.
-
-### 4. Synthesizing Completion
-After all tasks complete, synthesize outputs into a cohesive final response. Be direct - deliver
-the result as if you completed the task yourself without mentioning sub-agents or the process.
-
-## Your Process
-
-Think through the problem step-by-step:
-
-1. **Analyze the request** - What needs to be done? Break it into logical steps.
-2. **Design agents** - What specialized agents are needed? What tools does each need?
-3. **Plan dependencies** - Which tasks must wait for others? Draw the dependency graph.
-4. **Finalize** - Call finalize_plan when done creating agents and tasks.
-
-## Output Format
-
-Structure your response clearly:
-
-```
-### Analysis
-[Brief analysis of what's needed]
-
-### Agents Needed
-[List agents you'll create and why]
-
-### Workflow Dependencies
-[Show which tasks depend on which, e.g., "write_report waits for research to complete"]
-
-### Building Workflow
-[Then call the tools]
-```
+You are a workflow orchestrator. Your job is to break down requests into sub-agents and tasks.
 
 ## Tools
 
-**spawn_agent(name, role, tools, model)**
-- Creates an agent with specific capabilities
+- **spawn_agent(name, role, tools)** - Create a specialized agent
+- **create_task(name, agent_name, description, depends_on)** - Create a task for an agent
+- **finalize_plan()** - Call when done planning
 
-**create_task(name, agent_name, description, depends_on)**
-- Creates a task assigned to an agent
-- depends_on: list of task names that must finish BEFORE this task starts
+## Process
 
-**finalize_plan()**
-- Signals that planning is complete
-- Call this after you've created all agents and tasks
+1. Analyze what needs to be done
+2. Create agents with the tools they need
+3. Create tasks, specifying dependencies if one task needs another's output
+   - Important: dependencies must already exist (create dependency tasks first)
+4. Call finalize_plan()
 
 ## Example
 
-For "Research AI and write a report":
-
-### Analysis
-Need to: 1) Research AI trends, 2) Write a report based on research.
-The report cannot be written until research is done.
-
-### Agents Needed
-- researcher: Gathers information (needs search_web)
-- writer: Creates reports (needs write_file)
-
-### Workflow Dependencies
-research_task → write_task (writer waits for researcher)
-
-### Building Workflow
-[spawn agents, create tasks with depends_on, finalize_plan]
-
-Now analyze the request and build the workflow.
-"""
-
-
-# --- Swarm Config Management ---
-
-_swarm_config: SwarmConfig | None = None
-_hook_registry: HookRegistry | None = None
-
-
-def set_swarm_config(config: SwarmConfig | None, hook_registry: HookRegistry | None = None) -> None:
-    """Set swarm config and hook registry. Called by DynamicSwarm before orchestration."""
-    global _swarm_config, _hook_registry
-    _swarm_config = config
-    _hook_registry = hook_registry
-
+Request: "Research AI trends and write a summary"
 
-def get_swarm_config() -> SwarmConfig:
-    """Get swarm config, raising RuntimeError if not set."""
-    if _swarm_config is None:
-        raise RuntimeError("No swarm config set. Orchestrator tools must be used within DynamicSwarm.")
-    return _swarm_config
+1. spawn_agent(name="researcher", role="research specialist", tools=["search_web"])
+2. spawn_agent(name="writer", role="technical writer", tools=[])
+3. create_task(name="research", agent_name="researcher", description="Research AI trends")
+4. create_task(name="write", agent_name="writer", description="Write summary", depends_on=["research"])
+5. finalize_plan()
 
+Keep it simple - only create what's necessary."""
 
-def _emit(event: Any) -> None:
-    if _hook_registry and _hook_registry.has_callbacks():
-        _hook_registry.invoke_callbacks(event)
 
+def create_orchestrator_tools(definition: "SwarmDefinition") -> list[Any]:
+    """Create orchestrator tools that capture the SwarmDefinition via closure."""
+    from .definition import AgentDefinition, TaskDefinition
 
-def _build_agents_info(config: SwarmConfig) -> list[AgentInfo]:
-    return [
-        AgentInfo(
-            name=a.name, role=a.role, tools=a.tools, model=a.model, color=a.color
-        )
-        for a in config.agents.values()
-    ]
-
-
-def _build_tasks_info(config: SwarmConfig) -> list[TaskInfo]:
-    return [
-        TaskInfo(
-            name=t.name, agent=t.agent, description=t.description, depends_on=t.depends_on
-        )
-        for t in config.tasks.values()
-    ]
-
-
-# --- Orchestrator Tools ---
-
-
-@tool
-def list_available_tools() -> str:
-    """List all tools available for spawned agents."""
-    tools = get_swarm_config().available_tool_names
-    return "Available tools:\n" + "\n".join(f"  - {t}" for t in tools) if tools else "No tools available."
-
-
-@tool
-def list_available_models() -> str:
-    """List all models available for spawned agents."""
-    models = get_swarm_config().available_model_names
-    return "Available models:\n" + "\n".join(f"  - {m}" for m in models) if models else "No models configured."
-
-
-@tool
-def spawn_agent(
-    name: str,
-    role: str,
-    instructions: str = "",
-    tools: list[str] | None = None,
-    model: str | None = None,
-) -> str:
-    """Spawn a new sub-agent with specific capabilities."""
-    from .swarm import AgentDefinition
-
-    config = get_swarm_config()
-    definition = AgentDefinition(
-        name=name,
-        role=role,
-        instructions=instructions or None,
-        tools=tools or [],
-        model=model,
-    )
-
-    try:
-        config.register_agent(definition)
-        agent_def = config.agents.get(name)
-        _emit(AgentSpawnedEvent(
+    @tool
+    def spawn_agent(
+        name: str,
+        role: str,
+        tools: list[str] | None = None,
+        instructions: str = "",
+        model: str | None = None,
+    ) -> str:
+        """Create a sub-agent with specific capabilities."""
+        agent_def = AgentDefinition(
             name=name,
             role=role,
             instructions=instructions or None,
             tools=tools or [],
             model=model,
-            color=agent_def.color if agent_def else None,
-        ))
-        return f"✓ Spawned '{name}' ({role})"
-    except ValueError as e:
-        return f"✗ Failed: {e}"
-
-
-@tool
-def create_task(
-    name: str,
-    agent_name: str,
-    description: str = "",
-    depends_on: list[str] | None = None,
-) -> str:
-    """Create a task and assign it to a spawned agent."""
-    from .swarm import TaskDefinition
-
-    config = get_swarm_config()
-    definition = TaskDefinition(
-        name=name,
-        agent=agent_name,
-        description=description or None,
-        depends_on=depends_on or [],
-    )
+        )
 
-    try:
-        config.register_task(definition)
-        _emit(TaskCreatedEvent(
+        try:
+            definition.register_agent(agent_def)
+            return f"Created agent '{name}' ({role})"
+        except ValueError as e:
+            return f"Error: {e}"
+
+    @tool
+    def create_task(
+        name: str,
+        agent_name: str,
+        description: str = "",
+        depends_on: list[str] | None = None,
+    ) -> str:
+        """Create a task assigned to a sub-agent.
+
+        Note: any tasks listed in depends_on must already exist (create dependency tasks first).
+        """
+        task_def = TaskDefinition(
             name=name,
             agent=agent_name,
             description=description or None,
             depends_on=depends_on or [],
-        ))
-        return f"✓ Created '{name}' -> '{agent_name}'"
-    except ValueError as e:
-        return f"✗ Failed: {e}"
-
-
-@tool
-def get_planning_status() -> str:
-    """Get current planning status - agents and tasks defined so far."""
-    return get_swarm_config().get_summary()
-
-
-@tool
-def finalize_plan() -> str:
-    """Signal that planning is complete. Call after creating all agents and tasks."""
-    config = get_swarm_config()
-
-    _emit(PlanningCompletedEvent(
-        entry_task=None,
-        agents=_build_agents_info(config),
-        tasks=_build_tasks_info(config),
-    ))
-    return f"✓ Planning complete.\n\n{config.get_summary()}"
+        )
 
+        try:
+            definition.register_task(task_def)
+            deps = f" (after: {depends_on})" if depends_on else ""
+            return f"Created task '{name}' -> {agent_name}{deps}"
+        except ValueError as e:
+            return f"Error: {e}"
 
-# --- Agent Factory ---
+    @tool
+    def finalize_plan() -> str:
+        """Signal that planning is complete."""
+        return f"Plan finalized.\n{definition.get_summary()}"
 
-ORCHESTRATOR_TOOLS = [
-    list_available_tools,
-    list_available_models,
-    spawn_agent,
-    create_task,
-    get_planning_status,
-    finalize_plan,
-]
+    return [spawn_agent, create_task, finalize_plan]
 
 
-def create_orchestrator_agent(model: Model | None = None) -> Agent:
-    """Create orchestrator agent that plans, creates sub-agents, assigns tasks, and synthesizes completion."""
+def create_orchestrator_agent(
+    definition: "SwarmDefinition",
+    model: "Model | None" = None,
+) -> Agent:
+    """Create the orchestrator agent."""
     return Agent(
         name="orchestrator",
         system_prompt=ORCHESTRATOR_SYSTEM_PROMPT,
         model=model,
-        tools=ORCHESTRATOR_TOOLS,
+        tools=create_orchestrator_tools(definition),
+        callback_handler=None,
     )

strands_swarms-0.1.2.dist-info/METADATA

@@ -0,0 +1,171 @@
+Metadata-Version: 2.4
+Name: strands-swarms
+Version: 0.1.2
+Summary: Task-based workflow orchestration for Strands Agents
+Project-URL: Homepage, https://github.com/JackXu0/strands-swarms
+Project-URL: Issues, https://github.com/JackXu0/strands-swarms/issues
+Author-email: Zhuocheng Xu <zhuocheng.xu@icloud.com>
+License: Apache-2.0
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Requires-Dist: strands-agents>=0.1.0
+Provides-Extra: dev
+Requires-Dist: mypy>=1.15.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=1.0.0; extra == 'dev'
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.13.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# strands-swarms
+
+[![CI](https://github.com/JackXu0/strands-swarms/actions/workflows/ci.yml/badge.svg)](https://github.com/JackXu0/strands-swarms/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/strands-swarms)](https://pypi.org/project/strands-swarms/)
+[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
+
+**Turn natural language into multi-agent workflows — automatically.**
+
+Give `DynamicSwarm` a query, and it automatically plans the workflow, spawns specialized agents, and executes tasks with dependencies. No manual graph configuration or agent wiring required.
+
+```python
+swarm = DynamicSwarm(available_tools={...}, available_models={...})
+result = swarm.execute("Research AI trends and write a summary report")
+# → Spawns researcher + writer agents, handles dependencies, returns final report
+```
+
+## Inspiration
+
+This project is inspired by [Kimi K2.5's Agent Swarm](https://www.kimi.com/blog/kimi-k2-5.html) — where a trainable orchestrator dynamically creates and coordinates sub-agents without predefined roles or workflows. The goal is to build an open-source foundation for training orchestrators that can spin up agent swarms on the fly.
+
+## How It Works
+
+![Architecture](assets/architecture.png)
+
+## Installation
+
+```bash
+pip install strands-swarms
+```
+
+## Quick Start
+
+```python
+from strands import tool
+from strands.models import BedrockModel
+from strands_swarms import DynamicSwarm
+
+# Define your tools
+@tool
+def search_web(query: str) -> str:
+    """Search the web for information."""
+    return f"[Search Results for '{query}']\n- Result 1: Latest developments..."
+
+@tool
+def analyze_data(data: str) -> str:
+    """Analyze data and extract insights."""
+    return f"[Analysis]\nKey insights: ..."
+
+@tool
+def write_file(path: str, content: str) -> str:
+    """Write content to a file."""
+    return f"Successfully wrote {len(content)} characters to {path}"
+
+# Configure models
+powerful_model = BedrockModel(model_id="us.anthropic.claude-3-opus-20240229-v1:0")
+fast_model = BedrockModel(model_id="us.anthropic.claude-3-5-haiku-20241022-v1:0")
+
+# Create the swarm
+swarm = DynamicSwarm(
+    available_tools={
+        "search_web": search_web,
+        "analyze_data": analyze_data,
+        "write_file": write_file,
+    },
+    available_models={
+        "powerful": powerful_model,
+        "fast": fast_model,
+    },
+    orchestrator_model=powerful_model,
+    default_agent_model="fast",
+)
+
+# Execute with natural language
+result = swarm.execute("Research the latest AI trends and write a summary report")
+
+print(f"Status: {result.status}")
+print(f"Agents spawned: {result.agents_spawned_count}")
+for agent in result.agents_spawned:
+    print(f"  - {agent.name}: {agent.role}")
+print(f"Tasks created: {result.tasks_created_count}")
+for task in result.tasks_created:
+    depends = f" (depends: [{', '.join(task.depends_on)}])" if task.depends_on else ""
+    print(f"  - {task.name} -> {task.agent}{depends}")
+print(f"Final response: {result.final_response}")
+```
+<details>
+<summary>Example output (see examples/simple.py)</summary>
+
+```
+Status: Status.COMPLETED
+Agents spawned: 2
+  - researcher: AI trends researcher
+  - writer: AI trends summary writer
+Tasks created: 3
+  - web_research -> researcher
+  - analyze_trends -> researcher (depends: [web_research])
+  - write_summary -> writer (depends: [analyze_trends])
+Final response: <thinking>
+The job is complete. The researchers gathered comprehensive information on the latest AI trends through web searches, analyzed that information to identify the most important developments and themes, and the writer put it together into a clear summary report touching on:
+
+- Major AI breakthroughs in the last year across language, vision, multimodal and generative models
+- Potential applications of these advancing AI capabilities 
+- Rapid growth in enterprise adoption and startup investment
+- Key technical challenges like robustness, interpretability and scalability 
+- Important societal and ethical considerations around safety, bias and responsible use
+- Longer-term possibilities around artificial general intelligence
+
+The report provides a succinct yet informative overview of the state of the art in AI and the key trends shaping the field. It directly addresses the original request, so no further analysis or synthesis is needed. The final report can be delivered as-is to the human who made the request.
+</thinking>
+
+Here is a summary report on the latest trends in artificial intelligence:
+
+Artificial intelligence continues to progress rapidly, with significant developments over the past year in areas like natural language processing, computer vision, multimodal learning, and generative AI. Powerful language models can now engage in human-like dialogue and assist with writing. AI systems can perceive and reason jointly about text, images, audio and video. New generative models can create highly realistic images from textual descriptions. And AI has achieved human-level performance on complex strategy games.
+
+These advances open up transformative potential applications — enhancing creative workflows, accelerating scientific discovery, enabling more natural human-computer interaction. Enterprises across sectors are increasingly adopting AI technologies, and venture capital investment into AI startups reached record levels in 2022.
+
+However, key technical challenges remain in making AI systems more robust, interpretable and scalable. Important societal considerations are also in play around AI ethics, safety, bias and responsible use. Longer-term, some believe AI could progress toward human-level artificial general intelligence, though this remains a future possibility.
+
+In summary, AI capabilities are advancing quickly, with potentially profound impacts across domains in the coming years. Ongoing research aims to further enhance performance while addressing crucial challenges. Organizations will need to balance leveraging AI's competitive advantages with deploying it in a trustworthy manner. The field's rapid progress looks set to continue — and to reshape the world in the process.
+```
+
+</details>
+
+## Status & Roadmap
+
+> **Current version: Rollout-only**
+>
+> This release supports **rollout execution** (string-in, string-out) — ideal for inference and deployment.
+>
+> **Coming soon:** RL support via [strands-sglang](https://github.com/strands-agents/strands-sglang) integration.
+
+- [x] Rollout execution — string-in, string-out multi-agent workflows
+- [x] Dynamic orchestration — automatic agent creation and task assignment
+- [ ] Streaming trajectory output — consume `stream_async()`
+- [ ] RL support — training and fine-tuning via strands-sglang
+
+## Contributing
+
+Contributions welcome! Please feel free to submit issues and pull requests.
+
+## License
+
+Apache-2.0

strands_swarms-0.1.2.dist-info/RECORD

@@ -0,0 +1,8 @@
+strands_swarms/__init__.py,sha256=S082nMANh4fzbXmUlhrK_TGKwuHsZM-TzLQ9p6y9Zr8,2252
+strands_swarms/definition.py,sha256=k6LLrci6gZwfTKZaHXmVYGSNglN7u-ErtjJYut-83Mw,5475
+strands_swarms/dynamic_swarm.py,sha256=c0hEMlleP6z1v9CMXT4fZGzlIqjmkrsCZSP59NFZg08,15512
+strands_swarms/orchestrator.py,sha256=ILpw5c6Cy-5EfElVXp6qvlfMDmhP8VEjid5d83FyvmI,3558
+strands_swarms-0.1.2.dist-info/METADATA,sha256=HihoCAsx-evgp0xyq0FpXirqsiHxiJw54LZHwYyYh7k,8056
+strands_swarms-0.1.2.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+strands_swarms-0.1.2.dist-info/licenses/LICENSE,sha256=fw8CKBXZ_-V6K5pxfUmJP3e_7QUvFq8XncuZ27tvarg,10177
+strands_swarms-0.1.2.dist-info/RECORD,,