{"id":24905788,"url":"https://github.com/danedens/swarmonomicon","last_synced_at":"2025-04-14T08:12:48.450Z","repository":{"id":274995706,"uuid":"924372942","full_name":"DanEdens/Swarmonomicon","owner":"DanEdens","description":"Ai Agent transfer station for Madness_interactive","archived":false,"fork":false,"pushed_at":"2025-04-09T15:20:49.000Z","size":2495,"stargazers_count":3,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-04-09T16:32:13.081Z","etag":null,"topics":["agents","ai","rust","rust-"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/DanEdens.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2025-01-29T22:03:59.000Z","updated_at":"2025-04-09T15:20:54.000Z","dependencies_parsed_at":"2025-02-17T16:30:46.711Z","dependency_job_id":"4aab09ff-cd8b-4320-b488-a55ce4d7c64d","html_url":"https://github.com/DanEdens/Swarmonomicon","commit_stats":null,"previous_names":["danedens/swarmonomicon"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DanEdens%2FSwarmonomicon","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DanEdens%2FSwarmonomicon/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DanEdens%2FSwarmonomicon/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DanEdens%2FSwarmonomicon/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/DanEdens","download_url":"https://codeload.github.com/DanEdens/Swarmonomicon/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248843941,"owners_count":21170495,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agents","ai","rust","rust-"],"created_at":"2025-02-02T00:25:12.920Z","updated_at":"2025-04-14T08:12:48.437Z","avatar_url":"https://github.com/DanEdens.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Swarmonomicon: The Mad Tinker's Codex\n\n\n![Cover Art](docs/assets/Cover-Art.jpeg)\n\n🛠️ Welcome to the Swarmonomicon,\\\nA fusion of meticulous craftsmanship and heavily version controlled chaos.\\\nInspired by OpenAI's Realtime Agents Demo, this project doesn't just reimagine agent collaboration—\\\nIt invites you to dive headfirst into the Uncharted 🌀 and the Unhinged. 🤖🦾\n\nHere, Rust-powered agents weave intricate patterns of logic, improvisation, and mischief.\\\nIt's a spellbook for Mad Tinkerers ready to push boundaries and embrace the unpredictable.\\\nThrow UX in the trash, grab an extra keyboard, a bin of raspiberries and Buckle up.\n\n⚙️ Tinker responsibly. \\\nSome assembly required[^1].\\\nUnintended Hilarity guaranteed[^2].\n\n\n[^1]: Always assume \"some\" means \"extensive\" when dealing with Tinkers.\n\n[^2]: May cause mqtt related restructuring of your entire codebase[^3].\n\n[^3]: You're welcome, this is a feature not a bug.\n\n## Features current under development\n\n- Multiple specialized agents with different capabilities:\n  - Greeter Agent: Welcomes users and directs them to appropriate agents\n  - Git Assistant: Helps with git operations\n  - Haiku Agent: Creates haikus based on user input\n  - Project Init Agent: Helps initialize new projects\n  - Browser Agent: Handles browser automation tasks\n\n- Independent Task Processing:\n  - Each agent has its own todo list\n  - Tasks are processed asynchronously in the background\n  - Agents can delegate tasks to other agents\n  - Priority-based task scheduling\n  - Task status tracking (Pending, InProgress, Completed, Failed)\n  - AI-powered task enhancement and prioritization\n  - Dual description system (original + enhanced)\n\n- Real-time Communication:\n  - WebSocket support for live updates\n  - Agent-to-agent communication\n  - Task delegation between agents\n  - Intelligent task routing based on enhanced descriptions\n\n- Extensible Architecture:\n  - Easy to add new agents\n  - Configurable task processing intervals\n  - Support for agent-specific state machines\n  - Flexible message routing\n  - AI-enhanced task processing capabilities\n  - Fallback mechanisms for AI enhancement failures\n  - GPT-4 Batch Processing Tool:\n    - Efficient handling of multiple AI requests\n    - Automatic request batching with configurable window (1 second default)\n    - Rate limiting (3500 requests/minute for GPT-4)\n    - Exponential backoff retry mechanism (max 3 retries)\n    - Support for OpenAI function calling\n    - Built-in token usage tracking\n    - Automatic error handling and recovery\n    - Concurrent request processing with configurable batch size\n    - Request pooling for optimal API usage\n\n\n## Inspiration and Credits\n\nThis project is a Rust reimplementation inspired by the [OpenAI Realtime Agents Demo](https://github.com/openai/openai-realtime-agents). The original project, created by [Noah MacCallum](https://x.com/noahmacca)] and [Ilan Bigio](https://github.com/ibigio), demonstrates advanced agentic patterns built on top of a Realtime API.\nMy version is designed with plans to later become a [Tinker](https://github.com/DanEdens/Tinker) module.\nMuch of the theming ideas stem from [J.S. Morin's Twinborn and Black Ocean universes](https://www.jsmorin.com/)\n\n### Original Project Highlights\nThe original OpenAI Realtime Agents project showcases:\n- Sequential agent handoffs\n- Background escalation to intelligent models\n- State machine-driven user interactions\n- Realtime voice application prototyping\n\n## Our Implementation\n\nOur Rust implementation aims to explore similar concepts of multi-agent systems, focusing on:\n- Websocket-based realtime communication\n- Modular agent system with configurable tools and behaviors\n- Async runtime using tokio\n\n\n### Current Implementation Status\n\n#### Completed ✅\n- Basic agent system with registry and transfer capabilities\n- Websocket communication layer\n- REST API endpoints for agent management\n- Greeter and Haiku example agents\n- Tool system with support for custom executors\n- Configuration management for agents and tools\n- Centralized AI client with LM Studio integration\n- Intelligent conversation handling with history\n- Git operations with AI-powered commit messages\n\n#### In Progress 🚧\n- Adding entry point for greeter\n- Update todo_worker to keep a record of tasks and to log more items\n- Add mqtt logging for log agent to watch and react to\n- Enhance conversation context preservation\n- Improve error handling for AI communication\n- Add more sophisticated state machine transitions\n\n## Setup\n\n### Prerequisites\n- Rust toolchain (latest stable)\n- LM Studio running locally (default: http://127.0.0.1:1234)\n- Git (for version control features)\n\n### Installation\n1. Clone the repository\n2. Install dependencies with `cargo build`\n3. Start LM Studio with the Qwen model\n4. Run tests with `cargo test`\n5. Start the server with `cargo run`\n6. The server will start on [http://localhost:3000](http://localhost:3000)\n\n### Configuration\nThe system can be configured through environment variables:\n- `AI_ENDPOINT`: LLM API endpoint (default: http://127.0.0.1:1234)\n- `AI_MODEL`: Model to use (default: qwen2.5-7b-instruct)\n- `RUST_LOG`: Logging level (default: info)\n\n## Architecture\n\n### Core Components\n\n1. **Agent System**\n   - `AgentRegistry`: Manages available agents\n   - `TransferService`: Handles agent transfers and message routing\n   - `Agent` trait: Interface for implementing custom agents\n   - `AiClient`: Centralized LLM communication\n\n2. **API Layer**\n   - REST endpoints for agent management\n   - Websocket handler for realtime communication\n   - Session management\n   - AI-powered conversation handling\n\n3. **Tool System**\n   - `ToolExecutor` trait for implementing custom tools\n   - Support for async tool execution\n   - Mqtt topic structure for agent state exchange\n\n### Configuration\n\nAgent configurations are defined in code, with support for:\n- Custom instructions\n- Tool assignments\n- Downstream agent connections\n- State machine definitions (in progress)\n\n## Contributing\n\nContributions are welcome! Open Issues, I welcome them.\n\n## License\nMIT\n\n## Subrepo Structure\n\nWelcome, the few and the Mad, to the wondrous world of subrepos!\\\nThis project is but a cog in the grand machine of the [Madness Interactive](https://github.com/DanEdens/madness_interactive) repository—\\\nA playground for my various Mad Science and other monstrosities of Automation.\\\nEmbrace the mess of modular development, each project is but a part of the glorious, interconnected ***machine***.\n\nFerrum Corde!\n\n## Features\n\n- Agent-based architecture for modular task handling\n- Tool registry for extensible functionality\n- State machine support for complex workflows\n- WebSocket API for real-time communication\n- CLI interface for common operations\n\n### Git Operations\n\nThe framework includes a Git assistant agent that can be used via CLI:\n\n```bash\n# Auto-generate commit message\nswarm git\n\n# Commit with specific message\nswarm git -m \"feat: add new feature\"\n\n# Create and switch to new branch\nswarm git -b feature/new-branch\n\n# Merge current branch into target\nswarm git -t main\n```\n\nThe Git assistant uses AI to generate meaningful commit messages based on the changes in your working directory.\n\n## API Endpoints\n\n### Agent Management\n- `GET /api/agents` - List all available agents\n- `GET /api/agents/:name` - Get details about a specific agent\n- `POST /api/agents/:name/message` - Send a message to an agent\n- `POST /api/agents/:name/send` - Send a command to an agent\n\n### Task Management\n- `GET /api/agents/:name/tasks` - Get all tasks for an agent\n- `POST /api/agents/:name/tasks` - Add a task to an agent's todo list\n- `GET /api/agents/:name/tasks/:task_id` - Get details about a specific task\n\n### WebSocket\n- `GET /ws` - WebSocket endpoint for real-time communication\n\n## Task System\n\nThe system uses a sophisticated task management system with AI enhancement capabilities:\n\n#### Task Priority Levels\n- Critical: Highest priority tasks that need immediate attention\n- High: Important tasks that should be processed soon\n- Medium: Regular priority tasks\n- Low: Background tasks that can wait\n\n#### Task Status Flow\n1. Pending: Task has been added to the todo list\n2. InProgress: Task is currently being processed\n3. Completed: Task has been successfully completed\n4. Failed: Task processing failed\n\n#### Task Structure\n```rust\npub struct TodoTask {\n    pub id: String,\n    pub description: String,           // Original task description\n    pub enhanced_description: Option\u003cString\u003e,  // AI-enhanced version with additional context\n    pub priority: TaskPriority,\n    pub source_agent: Option\u003cString\u003e,\n    pub target_agent: String,\n    pub status: TaskStatus,\n    pub created_at: i64,\n    pub completed_at: Option\u003ci64\u003e,\n}\n```\n\n#### AI Enhancement System\n\nThe system implements a layered approach to AI task enhancement:\n\n1. Infrastructure Layer (API/Worker):\n   - Handles basic task creation and routing\n   - No AI enhancement at this level\n   - Preserves original task descriptions\n\n2. Agent Layer:\n   - Implements AI enhancement during task processing\n   - Adds technical details and context\n   - Maintains task integrity\n\n3. Storage Layer:\n   - MongoDB-based persistent storage\n   - Configurable database via RTK_MONGO_DB\n   - Stores both original and enhanced descriptions\n\n#### Task Creation\n\nTasks can be created through multiple channels:\n1. API endpoints\n2. MQTT messages\n3. Agent-to-agent delegation\n\nExample API request:\n```bash\ncurl -X POST http://localhost:3000/api/agents/greeter/tasks \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"description\": \"Welcome new user John\",\n    \"priority\": \"High\",\n    \"source_agent\": null\n  }'\n```\n\nResponse:\n```json\n{\n  \"id\": \"123e4567-e89b-12d3-a456-426614174000\",\n  \"description\": \"Welcome new user John\",\n  \"enhanced_description\": null,\n  \"priority\": \"High\",\n  \"source_agent\": null,\n  \"target_agent\": \"greeter\",\n  \"status\": \"Pending\",\n  \"created_at\": 1677721600,\n  \"completed_at\": null\n}\n```\n\nThe task will be enhanced during processing by the target agent, adding technical details and context while preserving the original description.\n\n## Usage\n\n### Starting the Server\n```bash\ncargo run --bin swarm\n```\n\n### Adding a Task via API\n```bash\ncurl -X POST http://localhost:3000/api/agents/greeter/tasks \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"description\": \"Welcome new user John\",\n    \"priority\": \"High\",\n    \"source_agent\": null\n  }'\n```\n\nThe response will include both the original and AI-enhanced descriptions:\n```json\n{\n  \"id\": \"123e4567-e89b-12d3-a456-426614174000\",\n  \"description\": \"Welcome new user John\",\n  \"enhanced_description\": \"Initiate personalized welcome sequence for new user John, including system introduction and available agent overview. Ensure proper onboarding experience and gather initial user preferences for future interactions.\",\n  \"priority\": \"High\",\n  \"source_agent\": null,\n  \"target_agent\": \"greeter\",\n  \"status\": \"Pending\",\n  \"created_at\": 1677721600,\n  \"completed_at\": null\n}\n```\n\n### Getting Tasks for an Agent\n```bash\ncurl http://localhost:3000/api/agents/greeter/tasks\n```\n\n## Development\n\n### Prerequisites\n- Rust 1.70 or higher\n- Cargo\n- Optional: Chrome/Chromium (for browser automation features)\n\n### Building\n```bash\ncargo build\n```\n\n### Running Tests\n```bash\ncargo test\n```\n\n### Feature Flags\n- `git-agent`: Enable Git assistant functionality\n- `haiku-agent`: Enable Haiku generation\n- `greeter-agent`: Enable Greeter agent\n- `browser-agent`: Enable browser automation\n- `project-init-agent`: Enable project initialization\n\n## Architecture\n\nThe system uses a modular architecture where each agent is an independent entity that can:\n1. Process messages directly\n2. Handle tasks asynchronously\n3. Delegate work to other agents\n4. Maintain its own state and todo list\n\nEach agent runs in its own async task, processing its todo list at configurable intervals. This allows for true parallel processing and independent operation.\n\n## Contributing\n\n1. Fork the repository\n2. Create a feature branch\n3. Make your changes\n4. Add tests for new functionality\n5. Submit a pull request\n\n## License\n\nThis project is licensed under the MIT License - see the LICENSE file for details.\n\n## MCP Topic Routing\n\nAdded support for subscribing to `mcp/*` topics in the MCP Todo Server and routing todos to the appropriate target agent based on the topic path.\n\nChanges made:\n- Updated the MQTT subscription in `mcp_todo_server.rs` from `mcp/todo` to `mcp/*` to subscribe to all mcp topics\n- Parse the topic path from received messages and pass it to the `TodoTool.add_todo()` method as the `target_agent` parameter\n- Modified the `TodoTool.add_todo()` method to accept a `target_agent` parameter and use it when creating new `TodoTask` instances\n- Fixed a \"temporary value dropped while borrowed\" error in `todo.rs` by assigning the default `target_agent` value to a variable before using it in `unwrap_or()`\n\nThese changes allow for more flexible routing of todos based on the MQTT topic they are published to. The target agent can be determined from the topic path.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdanedens%2Fswarmonomicon","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdanedens%2Fswarmonomicon","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdanedens%2Fswarmonomicon/lists"}