# cola

**Repository Path**: heiwuqi/cola

## Basic Information

- **Project Name**: cola
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-19
- **Last Updated**: 2026-05-23

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 🥤 Cola - Intelligent Agent Orchestration Platform

A ToB platform for building, managing, and orchestrating AI agents and workflows.

## Architecture (5 Layers)

```
┌─────────────────────────────────────────┐
│  Layer 1: Industry Agent Templates      │  ← 销售单元
│  Pre-built templates per industry       │     Sales, CS, Marketing, Finance...
├─────────────────────────────────────────┤
│  Layer 2: Agent Orchestration           │  ← LangGraph-style Workflow Engine
│  Graph-based execution with conditions  │     Agent, Tool, Condition, Parallel
├─────────────────────────────────────────┤
│  Layer 3: Tools & Plugins               │  ← 行业 Tool / API / RAG
│  Registry: Web, RAG, CRM, Code, SEO...  │     Pluggable tool execution
├─────────────────────────────────────────┤
│  Layer 4: Model Adapter (LLM Router)    │  ← GPT / Claude / Gemini / Private
│  Multi-provider routing with fallback   │     Cost-aware model selection
├─────────────────────────────────────────┤
│  Layer 5: Multi-tenancy & Billing       │  ← 多租户隔离 + 计费
│  Tenant isolation + token tracking      │     Tier-based pricing + overage
└─────────────────────────────────────────┘
```

## Tech Stack

- **Backend**: Python + FastAPI
- **Frontend**: TypeScript + React + Vite
- **Database**: SQLite (default) / PostgreSQL
- **Cache/Queue**: Redis
- **Task Queue**: Celery
- **State Management**: Zustand

## ToB Features

### Layer 1: Industry Agent Templates (Sales Unit)
- Pre-built templates: Sales Assistant, Customer Service, Marketing, Financial Analyst
- One-click deploy → generates workflow graph
- Industry-specific node chains with system prompts
- Template execution with automatic tool routing

### Layer 2: Agent Orchestration
- LangGraph-style graph engine
- Node types: Agent, Tool, Condition, Parallel, Loop, Human-in-loop
- Conditional edges with field-based routing
- Execution state tracking with iteration limits

### Layer 3: Tools & Plugins
- Tool registry with 8 built-in tools
- Categories: Web, RAG, CRM, Code, SEO, File, Communication, Analytics
- Pluggable architecture - add custom tools easily
- Async tool execution with error handling

### Layer 4: Model Adapter (LLM Router)
- 8 supported models across 4 providers (OpenAI, Anthropic, Google, Mistral)
- Capability-based model selection (text, vision, function calling, streaming)
- Cost-aware routing with fallback models
- Per-model pricing for cost estimation

### Layer 5: Multi-tenancy & Billing
- `X-Tenant-ID` header for all API isolation
- 4 billing tiers: Free, Standard ($49), Premium ($149), Enterprise ($499)
- Token budget enforcement with overage calculation
- Per-tenant usage stats and cost tracking

## Quick Start

### Backend

```bash
cd backend
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate
pip install -r requirements.txt
cp .env.example .env
uvicorn app.main:app --reload
```

Backend: `http://localhost:8000` | API docs: `http://localhost:8000/docs`

### Celery Worker

```bash
cd backend
celery -A app.tasks worker --loglevel=info
```

### Frontend

```bash
cd frontend
npm install
npm run dev
```

Frontend: `http://localhost:3000`

### Docker

```bash
docker-compose up --build
```

## Project Structure

```
cola/
├── backend/app/
│   ├── core/                    # Config, database, celery, dependencies
│   ├── models/                  # Pydantic & SQLAlchemy models
│   ├── routers/                 # API endpoints
│   ├── templates/               # Layer 1: Industry Agent Templates
│   │   ├── models.py            # Template definitions
│   │   └── industry_templates.py # Pre-built templates
│   ├── orchestration/           # Layer 2: Agent Orchestration
│   │   ├── models.py            # Graph models
│   │   └── graph_engine.py      # LangGraph-style engine
│   ├── tools/                   # Layer 3: Tools & Plugins
│   │   ├── models.py            # Tool definitions
│   │   └── registry.py          # Tool registry + built-in tools
│   ├── adapters/                # Layer 4: Model Adapter
│   │   ├── models.py            # Model/provider definitions
│   │   └── llm_router.py        # Multi-provider LLM router
│   ├── billing/                 # Layer 5: Billing
│   │   └── models.py            # Tier pricing, invoices, usage
│   ├── services/                # Shared services (tokens, cache)
│   ├── tasks.py                 # Celery async tasks
│   ├── websocket.py             # WebSocket manager
│   └── main.py                  # FastAPI app
├── frontend/src/
│   ├── components/              # Layout with tenant selector
│   ├── pages/                   # Dashboard, Agents, Workflows, Tokens
│   ├── services/                # API client with tenant interceptor
│   ├── store/                   # Zustand state management
│   └── types/                   # TypeScript types
└── docker-compose.yml
```

## API Endpoints

### Layer 1: Templates
- `GET /api/templates/` - List all templates
- `GET /api/templates/{id}` - Get template detail
- `POST /api/templates/deploy` - Deploy template to tenant
- `POST /api/templates/{id}/execute` - Execute template

### Layer 2: Workflows
- `POST /api/workflows/` - Create workflow
- `GET /api/workflows/` - List workflows (tenant-scoped)
- `PUT /api/workflows/{id}` - Update workflow

### Layer 3: Tools
- `GET /api/tools/` - List all tools
- `GET /api/tools/{id}` - Get tool detail
- `POST /api/tools/{id}/execute` - Execute tool

### Layer 4: Models
- `GET /api/models/` - List available models
- `GET /api/models/{id}` - Get model info
- `POST /api/models/select` - Smart model selection
- `POST /api/models/chat` - Chat with LLM (auto-routed)
- `POST /api/models/chat/stream` - Streaming chat

### Layer 5: Tenants & Billing
- `POST /api/tenants/` - Create tenant
- `GET /api/billing/tiers` - List pricing tiers
- `GET /api/billing/usage-summary` - Get tenant usage
- `GET /api/billing/overage/calculate` - Calculate overage cost

### Agents & Executions
- `POST /api/agents/` - Create agent (tenant-scoped)
- `POST /api/executions/` - Queue workflow execution (async)
- `GET /api/executions/task/{task_id}` - Check task progress

### WebSocket
- `WS /ws/{tenant_id}` - Real-time updates

## License

MIT

## Documentation

| 文档 | 说明 |
|:---|:---|
| [功能文档](docs/functional.md) | 产品功能说明、使用指南、常见问题 |
| [技术文档](docs/technical.md) | 技术架构、API 规范、部署指南 |
| [测试报告](docs/test-report.md) | 单元测试结果 |
| [功能详细说明](docs/features/README.md) | 各功能模块详细说明 |