feat: add shannon

2026-04-01 17:33:42 +08:00
parent b55fa9819b
commit 6ae63c5d86
16 changed files with 820 additions and 19 deletions
@@ -0,0 +1,125 @@
+# Shannon
+
+[English](./README.md) | [中文](./README.zh.md)
+
+This service deploys [Shannon](https://github.com/Kocoro-lab/Shannon), a production-oriented multi-agent orchestration framework. Shannon provides time-travel debugging via Temporal workflows, hard token budgets per task/agent, real-time observability dashboards, WASI sandbox for secure code execution, OPA policy governance, and multi-tenant isolation — all with native support for OpenAI, Anthropic, Google, DeepSeek, and local models.
+
+> **Note:** The `agent-core` service is only built for `linux/amd64`. On Apple Silicon (ARM64), Docker Desktop uses Rosetta emulation automatically.
+
+## Services
+
+- **gateway**: HTTP API gateway — primary entry point for all client requests (port `8080`)
+- **orchestrator**: Core workflow orchestration engine powered by Temporal
+- **llm-service**: LLM provider abstraction with model routing, fallback, and budget control
+- **agent-core**: Rust-based agent execution runtime with WASI sandbox support
+- **postgres**: PostgreSQL with pgvector extension for state and vector storage
+- **redis**: Redis for caching, job queues, and rate limiting
+- **qdrant**: Qdrant vector database for semantic memory
+- **temporal**: Temporal workflow engine for durable, fault-tolerant task execution
+- **temporal-ui**: Temporal Web UI for workflow debugging (enabled via `metrics` profile)
+
+## Quick Start
+
+### Prerequisites
+
+- Docker & Docker Compose v2
+- `curl` (for the setup script)
+- At least one LLM API key (OpenAI, Anthropic, Google, etc.)
+
+### 1. Run Setup
+
+```bash
+make setup
+```
+
+This downloads the required `config/models.yaml` and `config/features.yaml` from the Shannon repository and creates a local `.env` file.
+
+### 2. Add Your LLM API Key
+
+Edit `.env` and set at least one LLM provider key:
+
+```env
+# Choose at least one:
+OPENAI_API_KEY=sk-...
+ANTHROPIC_API_KEY=sk-ant-...
+```
+
+Also update `JWT_SECRET` and set `GATEWAY_SKIP_AUTH=0` for production deployments.
+
+### 3. Start Services
+
+```bash
+make up
+```
+
+Access the Shannon API at `http://localhost:8080`.
+
+### 4. (Optional) Enable Temporal UI Dashboard
+
+To also start the Temporal workflow debugging UI:
+
+```bash
+make up-monitoring
+```
+
+Access Temporal UI at `http://localhost:8088`.
+
+## Core Environment Variables
+
+| Variable                    | Description                                | Default                                        |
+| --------------------------- | ------------------------------------------ | ---------------------------------------------- |
+| `SHANNON_VERSION`           | Version for all Shannon service images     | `v0.3.1`                                       |
+| `OPENAI_API_KEY`            | OpenAI API key (at least one key required) | ``                                             |
+| `ANTHROPIC_API_KEY`         | Anthropic API key                          | ``                                             |
+| `GOOGLE_API_KEY`            | Google AI API key                          | ``                                             |
+| `JWT_SECRET`                | Secret for JWT token signing               | `development-only-secret-change-in-production` |
+| `GATEWAY_SKIP_AUTH`         | Skip auth (set to `0` to enable in prod)   | `1`                                            |
+| `GATEWAY_PORT_OVERRIDE`     | Host port for the API gateway              | `8080`                                         |
+| `TEMPORAL_UI_PORT_OVERRIDE` | Host port for the Temporal UI              | `8088`                                         |
+
+## Database Configuration
+
+| Variable            | Description              | Default      |
+| ------------------- | ------------------------ | ------------ |
+| `POSTGRES_VERSION`  | pgvector image tag       | `pg16`       |
+| `POSTGRES_USER`     | PostgreSQL username      | `shannon`    |
+| `POSTGRES_PASSWORD` | PostgreSQL password      | `shannon`    |
+| `POSTGRES_DB`       | PostgreSQL database name | `shannon`    |
+| `REDIS_VERSION`     | Redis image tag          | `7.2-alpine` |
+| `QDRANT_VERSION`    | Qdrant image tag         | `v1.17`      |
+
+## Agent Configuration
+
+| Variable                   | Description                            | Default   |
+| -------------------------- | -------------------------------------- | --------- |
+| `DEFAULT_MODEL_TIER`       | Default model complexity tier          | `small`   |
+| `SHANNON_USE_WASI_SANDBOX` | Enable WASI sandbox for code execution | `1`       |
+| `WASI_MEMORY_LIMIT_MB`     | Memory limit for WASI sandbox (MB)     | `512`     |
+| `WASI_TIMEOUT_SECONDS`     | Execution timeout for WASI sandbox     | `60`      |
+| `TEMPORAL_NAMESPACE`       | Temporal namespace for workflows       | `default` |
+
+## Observability (Optional)
+
+| Variable                      | Description                  | Default |
+| ----------------------------- | ---------------------------- | ------- |
+| `OTEL_ENABLED`                | Enable OpenTelemetry tracing | `false` |
+| `OTEL_EXPORTER_OTLP_ENDPOINT` | OTLP collector endpoint      | ``      |
+
+## Security Notes
+
+- By default, `GATEWAY_SKIP_AUTH=1` disables JWT authentication for easy local development.
+- **For production**, set `GATEWAY_SKIP_AUTH=0` and use a strong `JWT_SECRET`.
+- Passwords in `.env.example` are for local development only — always change them before deploying to a shared or public environment.
+
+## Configuration Files
+
+Shannon uses YAML configuration files under `./config/`:
+
+- `config/models.yaml` — LLM providers, model tiers, pricing, and routing rules
+- `config/features.yaml` — Feature flags, execution modes, and workflow settings
+
+These are downloaded from the official Shannon repository by `make setup` and can be customized as needed.
+
+## License
+
+Shannon is licensed under the [Apache 2.0 License](https://github.com/Kocoro-lab/Shannon/blob/main/LICENSE).