{"id":30716390,"url":"https://github.com/jonaskahn/cadence","last_synced_at":"2025-09-06T19:04:06.001Z","repository":{"id":312596152,"uuid":"1048015757","full_name":"jonaskahn/cadence","owner":"jonaskahn","description":"Cadence Framework - Multi-agent AI orchestration framework with agent as plugin","archived":false,"fork":false,"pushed_at":"2025-09-04T08:58:47.000Z","size":680,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-09-04T15:03:26.754Z","etag":null,"topics":["ai-agent-framework","ai-agents","cadence-framework","langchain","langraph","multi-agents"],"latest_commit_sha":null,"homepage":"https://jonaskahn.github.io/cadence/","language":"Python","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/jonaskahn.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"docs/contributing/code-style.md","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,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-08-31T18:20:50.000Z","updated_at":"2025-09-04T08:58:51.000Z","dependencies_parsed_at":"2025-08-31T20:42:15.626Z","dependency_job_id":null,"html_url":"https://github.com/jonaskahn/cadence","commit_stats":null,"previous_names":["jonaskahn/cadence"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/jonaskahn/cadence","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jonaskahn%2Fcadence","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jonaskahn%2Fcadence/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jonaskahn%2Fcadence/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jonaskahn%2Fcadence/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jonaskahn","download_url":"https://codeload.github.com/jonaskahn/cadence/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jonaskahn%2Fcadence/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":273626180,"owners_count":25139423,"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","status":"online","status_checked_at":"2025-09-04T02:00:08.968Z","response_time":61,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":["ai-agent-framework","ai-agents","cadence-framework","langchain","langraph","multi-agents"],"created_at":"2025-09-03T08:01:22.569Z","updated_at":"2025-09-04T15:04:59.204Z","avatar_url":"https://github.com/jonaskahn.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Cadence 🤖 Multi-agents AI Framework\n\nA plugin-based multi-agent conversational AI framework built on FastAPI, designed for building intelligent chatbot\nsystems with extensible the plugin/modularization architecture.\n\n![demo](https://github.com/user-attachments/assets/ba7ceb1d-3226-4634-8491-abf7fab04add)\n\n## 🚀 Features\n\n- **Multi-Agent Orchestration**: Intelligent routing and coordination between AI agents\n- **Plugin System**: Extensible architecture for custom agents and tools\n- **Parallel Tool Execution**: Concurrent tool calls for improved performance and efficiency\n- **Multi-LLM Support**: OpenAI, Anthropic, Google AI, and more\n- **Flexible Storage**: PostgreSQL, Redis, MongoDB, and in-memory backends\n- **REST API**: FastAPI-based API with automatic documentation\n- **Streamlit UI**: Built-in web interface for testing and management\n- **Docker Support**: Containerized deployment with Docker Compose\n\n## 📦 Installation \u0026 Usage\n\n### 🎯 For End Users (Quick Start)\n\n**Install the package:**\n\n```bash\npip install cadence-py\n```\n\n**Verify installation:**\n\n```bash\n# Check if cadence is available\npython -m cadence --help\n\n# Should show available commands and options\n```\n\n**Run the application:**\n\n```bash\n# Start the API server\npython -m cadence start api\n\n# Start with custom host/port\npython -m cadence start api --host 0.0.0.0 --port 8000\n\n# Start the Streamlit UI\npython -m cadence start ui\n\n# Start both API and UI\npython -m cadence start all\n```\n\n**Available commands:**\n\n```bash\n# Show help\npython -m cadence --help\n\n# Show status\npython -m cadence status\n\n# Manage plugins\npython -m cadence plugins\n\n# Show configuration\npython -m cadence config\n\n# Health check\npython -m cadence health\n```\n\n### 🛠️ For Developers (Build from Source)\n\nIf you want to contribute, develop plugins, or customize the framework:\n\n#### Prerequisites\n\n- Python 3.13+\n- Poetry (for dependency management)\n- Docker (optional, for containerized deployment)\n\n#### Development Setup\n\n1. **Clone the repository**\n\n   ```bash\n   git clone https://github.com/jonaskahn/cadence.git\n   cd cadence\n   ```\n\n2. **Install dependencies**\n\n   ```bash\n   poetry install\n   poetry install --with local  # Include local SDK development\n   ```\n\n3. **Set up environment variables**\n\n   ```bash\n   cp .env.example .env\n   # Edit .env with your API keys and configuration\n   ```\n\n4. **Run the application**\n\n   ```bash\n   poetry run python -m cadence start api\n   ```\n\n## ⚙️ Configuration\n\n### Environment Variables\n\nAll configuration is done through environment variables with the `CADENCE_` prefix:\n\n```bash\n# LLM Provider Configuration\nCADENCE_DEFAULT_LLM_PROVIDER=openai\nCADENCE_OPENAI_API_KEY=your-openai-key\nCADENCE_ANTHROPIC_API_KEY=your-claude-key\nCADENCE_GOOGLE_API_KEY=your-gemini-key\n\n# Storage Configuration\nCADENCE_CONVERSATION_STORAGE_BACKEND=memory  # or postgresql\nCADENCE_POSTGRES_URL=postgresql://user:pass@localhost/cadence\n\n# Plugin Configuration\nCADENCE_PLUGINS_DIR=[\"./plugins/src/cadence_plugins\"]\n\n# Server Configuration\nCADENCE_API_HOST=0.0.0.0\nCADENCE_API_PORT=8000\nCADENCE_DEBUG=true\n\n# Advanced Configuration\nCADENCE_MAX_AGENT_HOPS=25\nCADENCE_GRAPH_RECURSION_LIMIT=50\n\n# Session Management\nCADENCE_SESSION_TIMEOUT=3600\nCADENCE_MAX_SESSION_HISTORY=100\n```\n\n### Configuration File\n\nYou can also use a `.env` file for local development:\n\n```bash\n# .env\nCADENCE_DEFAULT_LLM_PROVIDER=openai\nCADENCE_OPENAI_API_KEY=your_actual_openai_api_key_here\nCADENCE_ANTHROPIC_API_KEY=your_actual_claude_api_key_here\nCADENCE_GOOGLE_API_KEY=your_actual_gemini_api_key_here\n\nCADENCE_APP_NAME=\"Cadence 🤖 Multi-agents AI Framework\"\nCADENCE_DEBUG=false\n\nCADENCE_PLUGINS_DIR=./plugins/src/cadence_example_plugins\n\nCADENCE_API_HOST=0.0.0.0\nCADENCE_API_PORT=8000\n\n# For production, you might want to use PostgreSQL\nCADENCE_CONVERSATION_STORAGE_BACKEND=postgresql\nCADENCE_POSTGRES_URL=postgresql://user:pass@localhost/cadence\n\n# For development, you can use the built-in UI\nCADENCE_UI_HOST=0.0.0.0\nCADENCE_UI_PORT=8501\n\n# Plugin Configuration\nCADENCE_PLUGINS_DIR=./plugins/src/cadence_example_plugins\nCADENCE_MAX_AGENT_HOPS=25\nCADENCE_GRAPH_RECURSION_LIMIT=50\n\n# Parallel Tool Calls Configuration\n# Individual agents can control parallel tool execution in their constructor:\n# super().__init__(metadata, parallel_tool_calls=True)  # Enable (default)\n# super().__init__(metadata, parallel_tool_calls=False) # Disable\n```\n\n## 🚀 Usage\n\n### Command Line Interface\n\nCadence provides a comprehensive CLI for management tasks:\n\n```bash\n# Start the server\npython -m cadence start api --host 0.0.0.0 --port 8000\n\n# Show status\npython -m cadence status\n\n# Manage plugins\npython -m cadence plugins\n\n# Show configuration\npython -m cadence config\n\n# Health check\npython -m cadence health\n```\n\n### API Usage\n\nThe framework exposes a REST API for programmatic access:\n\n```python\nimport requests\n\n# Send a message\nresponse = requests.post(\"http://localhost:8000/api/v1/chat\", json={\n    \"message\": \"Hello, how are you?\",\n    \"user_id\": \"user123\",\n    \"org_id\": \"org456\"\n})\n\nprint(response.json())\n```\n\n### Plugin Development\n\nCreate custom agents and tools using the Cadence SDK with enhanced routing capabilities:\n\n```python\nfrom cadence_sdk import BaseAgent, BasePlugin, PluginMetadata, tool\n\n\nclass MyPlugin(BasePlugin):\n    @staticmethod\n    def get_metadata() -\u003e PluginMetadata:\n        return PluginMetadata(\n            name=\"my_agent\",\n            version=\"1.0.0\",\n            description=\"My custom AI agent\",\n            capabilities=[\"custom_task\"],\n            agent_type=\"specialized\",\n            dependencies=[\"cadence_sdk\u003e=1.0.2,\u003c2.0.0\"],\n        )\n\n    @staticmethod\n    def create_agent() -\u003e BaseAgent:\n        return MyAgent(MyPlugin.get_metadata())\n\n\nclass MyAgent(BaseAgent):\n    def __init__(self, metadata: PluginMetadata):\n        super().__init__(metadata)\n\n    def get_tools(self):\n        from .tools import my_custom_tool\n        return [my_custom_tool]\n\n    def get_system_prompt(self) -\u003e str:\n        return \"You are a helpful AI assistant.\"\n\n    @staticmethod\n    def should_continue(state: dict) -\u003e str:\n        \"\"\"Enhanced routing decision - decide whether to continue or return to coordinator.\n\n        This is the REAL implementation from the Cadence SDK - it's much simpler than you might expect!\n        The method simply checks if the agent's response has tool calls and routes accordingly.\n        \"\"\"\n        last_msg = state.get(\"messages\", [])[-1] if state.get(\"messages\") else None\n        if not last_msg:\n            return \"back\"\n\n        tool_calls = getattr(last_msg, \"tool_calls\", None)\n        return \"continue\" if tool_calls else \"back\"\n\n\n# Parallel Tool Calls Support\n# BaseAgent supports parallel tool execution for improved performance\n\nclass MyAgent(BaseAgent):\n    def __init__(self, metadata: PluginMetadata):\n        # Enable parallel tool calls (default: True)\n        super().__init__(metadata, parallel_tool_calls=True)\n\n    def get_tools(self):\n        return [my_tool1, my_tool2, my_tool3]\n\n    def get_system_prompt(self) -\u003e str:\n        return \"You are an agent that can execute multiple tools in parallel.\"\n\n\n@tool\ndef my_custom_tool(input_data: str) -\u003e str:\n    \"\"\"A custom tool for specific operations.\"\"\"\n    return f\"Processed: {input_data}\"\n```\n\n**Enhanced Features:**\n\n- **Intelligent Routing**: Agents automatically decide when to use tools or return to coordinator\n- **Fake Tool Calls**: Consistent routing flow even when agents answer directly\n- **No Circular Routing**: Eliminated infinite loops through proper edge configuration\n- **Better Debugging**: Clear routing decisions and comprehensive logging\n\n**Key Implementation Details:**\n\n- **`should_continue` is a static method**: Uses `@staticmethod` decorator\n- **Automatic fake tool calls**: The SDK automatically creates fake \"back\" tool calls when agents answer directly\n- **Consistent routing**: All responses go through the same flow regardless of whether tools are used\n\n## 🐳 Docker Deployment\n\n### Quick Start with Docker Compose\n\n```bash\n# Start all services\ndocker-compose -f docker/compose.yaml up -d\n\n# View logs\ndocker-compose -f docker/compose.yaml logs -f\n\n# Stop services\ndocker-compose -f docker/compose.yaml down\n```\n\n### Custom Docker Build\n\n```bash\n# Build the image\n./build.sh\n\n# Run the container\ndocker run -p 8000:8000 ifelsedotone/cadence:latest\n```\n\n## 🧪 Testing\n\nRun the test suite to ensure everything works correctly:\n\n```bash\n# Install test dependencies\npoetry install --with dev\n\n# Run tests\npoetry run pytest\n\n# Run with coverage\npoetry run pytest --cov=src/cadence\n\n# Run specific test categories\npoetry run pytest -m \"unit\"\npoetry run pytest -m \"integration\"\n```\n\n## 📚 Documentation\n\n- [Quick Start Guide](docs/getting-started/quick-start.md)\n- [Architecture Overview](docs/concepts/architecture.md)\n- [Plugin Development](docs/plugins/overview.md)\n- [API Reference](docs/api/)\n- [Deployment Guide](docs/deployment/)\n\n## 🤝 Contributing\n\nWe welcome contributions! Please see our [Contributing Guide](docs/contributing/development.md) for details.\n\n### Development Setup\n\n1. Fork the repository\n2. Create a feature branch\n3. Make your changes\n4. Add tests\n5. Submit a pull request\n\n## 📄 License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## 🙏 Acknowledgments\n\n- Built on [FastAPI](https://fastapi.tiangolo.com/) for high-performance APIs\n- Powered by [LangChain](https://langchain.com/) and [LangGraph](https://langchain.com/langgraph) for AI orchestration\n- UI built with [Streamlit](https://streamlit.io/) for rapid development\n- Containerized with [Docker](https://www.docker.com/) for easy deployment\n\n## 📞 Support\n\n- **Issues**: [GitHub Issues](https://github.com/jonaskahn/cadence/issues)\n- **Discussions**: [GitHub Discussions](https://github.com/jonaskahn/cadence/discussions)\n- **Documentation**: [Read the Docs](https://cadence.readthedocs.io/)\n\n---\n\n**Made with ❤️ by the Cadence AI Team**\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjonaskahn%2Fcadence","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjonaskahn%2Fcadence","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjonaskahn%2Fcadence/lists"}