cadence-app 0.1.0
Cadence AI - Multi-agent AI orchestration system with plugin management
License: MIT
Requires Python: <3.14,>=3.13
Keywords: ai, agents, cadence-ai, orchestration, coordination, langchain, langgraph, multi-agent, cli

# Cadence 🤖 Multi-agents AI Framework

A plugin-based multi-agent conversational AI framework built on FastAPI, designed for building intelligent chatbot systems with extensible agent architectures.

## 🚀 Features

- **Multi-Agent Orchestration**: Intelligent routing and coordination between AI agents
- **Plugin System**: Extensible architecture for custom agents and tools
- **Multi-LLM Support**: OpenAI, Anthropic, Google AI, and more
- **Flexible Storage**: PostgreSQL, Redis, MongoDB, and in-memory backends
- **REST API**: FastAPI-based API with automatic documentation
- **Streamlit UI**: Built-in web interface for testing and management
- **Docker Support**: Containerized deployment with Docker Compose

## 🏗️ Architecture

Cadence follows a layered architecture with clear separation of concerns:

- **API Layer**: FastAPI routers and middleware
- **Application Layer**: Business logic and orchestration services
- **Domain Layer**: Core business models and DTOs
- **Infrastructure Layer**: External services and data persistence
- **Plugin Layer**: Extensible agent and tool system

## 📦 Installation

### Prerequisites

- Python 3.13+
- Poetry (for dependency management)
- Docker (optional, for containerized deployment)

### Quick Start

1. **Clone the repository**

   ```bash
   git clone https://github.com/jonaskahn/cadence.git
   cd cadence
   ```

2. **Install dependencies**

   ```bash
   poetry install
   ```

3. **Set up environment variables**

   ```bash
   cp .env.example .env
   # Edit .env with your API keys and configuration
   ```

4. **Run the application**

   ```bash
   poetry run python -m cadence
   ```

## ⚙️ Configuration

### Environment Variables

All configuration is done through environment variables with the `CADENCE_` prefix:

```bash
# LLM Provider Configuration
CADENCE_DEFAULT_LLM_PROVIDER=openai
CADENCE_OPENAI_API_KEY=your-openai-key
CADENCE_ANTHROPIC_API_KEY=your-claude-key
CADENCE_GOOGLE_API_KEY=your-gemini-key

# Storage Configuration
CADENCE_CONVERSATION_STORAGE_BACKEND=memory  # or postgresql
CADENCE_POSTGRES_URL=postgresql://user:pass@localhost/cadence

# Plugin Configuration
CADENCE_PLUGINS_DIR=["./plugins/src/cadence_plugins"]

# Server Configuration
CADENCE_API_HOST=0.0.0.0
CADENCE_API_PORT=8000
CADENCE_DEBUG=true

# Advanced Configuration
CADENCE_MAX_AGENT_HOPS=25
CADENCE_MAX_TOOL_HOPS=50
CADENCE_GRAPH_RECURSION_LIMIT=50

# Session Management
CADENCE_SESSION_TIMEOUT=3600
CADENCE_MAX_SESSION_HISTORY=100
```

### Configuration File

You can also use a `.env` file for local development:

```bash
# .env
CADENCE_DEFAULT_LLM_PROVIDER=openai
CADENCE_OPENAI_API_KEY=your_actual_openai_api_key_here
CADENCE_ANTHROPIC_API_KEY=your_actual_claude_api_key_here
CADENCE_GOOGLE_API_KEY=your_actual_gemini_api_key_here

CADENCE_APP_NAME="Cadence 🤖 Multi-agents AI Framework"
CADENCE_DEBUG=false

CADENCE_DEFAULT_LLM_PROVIDER=openai
CADENCE_OPENAI_API_KEY=your_actual_openai_api_key_here
CADENCE_ANTHROPIC_API_KEY=your_actual_claude_api_key_here
CADENCE_GOOGLE_API_KEY=your_actual_gemini_api_key_here

CADENCE_PLUGINS_DIR=./plugins/src/cadence_example_plugins

CADENCE_API_HOST=0.0.0.0
CADENCE_API_PORT=8000

# For production, you might want to use PostgreSQL
CADENCE_CONVERSATION_STORAGE_BACKEND=postgresql
CADENCE_POSTGRES_URL=postgresql://user:pass@localhost/cadence

# For development, you can use the built-in UI
CADENCE_UI_HOST=0.0.0.0
CADENCE_UI_PORT=8501

# Test with a different port
CADENCE_API_PORT=8001

# Use a different plugins directory
CADENCE_PLUGINS_DIR=./plugins/src/cadence_example_plugins

# Verify your API keys are set
cadence $CADENCE_OPENAI_API_KEY
```

## 🚀 Usage

### Command Line Interface

Cadence provides a comprehensive CLI for management tasks:

```bash
# Start the server
cadence serve --host 0.0.0.0 --port 8000

# Show status
cadence status

# Manage plugins
cadence plugins

# Show configuration
cadence config

# Health check
cadence health
```

### API Usage

The framework exposes a REST API for programmatic access:

```python
import requests

# Send a message
response = requests.post("http://localhost:8000/api/v1/chat", json={
    "message": "Hello, how are you?",
    "user_id": "user123",
    "org_id": "org456"
})

print(response.json())
```

### Plugin Development

Create custom agents and tools using the Cadence SDK:

```python
from cadence_sdk.base.agent import Agent
from cadence_sdk.base.tools import Tool

class MyAgent(Agent):
    name = "my_agent"
    description = "A custom agent for specific tasks"
    
    def process(self, message: str) -> str:
        return f"Processed: {message}"

class MyTool(Tool):
    name = "my_tool"
    description = "A custom tool for specific operations"
    
    def execute(self, **kwargs) -> str:
        return "Tool executed successfully"
```

## 🐳 Docker Deployment

### Quick Start with Docker Compose

```bash
# Start all services
docker-compose -f docker/compose.yaml up -d

# View logs
docker-compose -f docker/compose.yaml logs -f

# Stop services
docker-compose -f docker/compose.yaml down
```

### Custom Docker Build

```bash
# Build the image
./build.sh

# Run the container
docker run -p 8000:8000 ifelsedotone/cadence:latest
```

## 🧪 Testing

Run the test suite to ensure everything works correctly:

```bash
# Install test dependencies
poetry install --with dev

# Run tests
poetry run pytest

# Run with coverage
poetry run pytest --cov=src/cadence

# Run specific test categories
poetry run pytest -m "unit"
poetry run pytest -m "integration"
```

## 📚 Documentation

- [Quick Start Guide](docs/getting-started/quick-start.md)
- [Architecture Overview](docs/concepts/architecture.md)
- [Plugin Development](docs/plugins/overview.md)
- [API Reference](docs/api/)
- [Deployment Guide](docs/deployment/)

## 🤝 Contributing

We welcome contributions! Please see our [Contributing Guide](docs/contributing/development.md) for details.

### Development Setup

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests
5. Submit a pull request

## 📄 License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## 🙏 Acknowledgments

- Built on [FastAPI](https://fastapi.tiangolo.com/) for high-performance APIs
- Powered by [LangChain](https://langchain.com/) and [LangGraph](https://langchain.com/langgraph) for AI orchestration
- UI built with [Streamlit](https://streamlit.io/) for rapid development
- Containerized with [Docker](https://www.docker.com/) for easy deployment

## 📞 Support

- **Issues**: [GitHub Issues](https://github.com/jonaskahn/cadence/issues)
- **Discussions**: [GitHub Discussions](https://github.com/jonaskahn/cadence/discussions)
- **Documentation**: [Read the Docs](https://cadence.readthedocs.io/)

---

**Made with ❤️ by the Cadence AI Team**