mirror of
https://github.com/katanemo/plano.git
synced 2026-05-01 03:46:35 +02:00
ba651aaf71
* Rename all arch references to plano across the codebase
Complete rebrand from "Arch"/"archgw" to "Plano" including:
- Config files: arch_config_schema.yaml, workflow, demo configs
- Environment variables: ARCH_CONFIG_* → PLANO_CONFIG_*
- Python CLI: variables, functions, file paths, docker mounts
- Rust crates: config paths, log messages, metadata keys
- Docker/build: Dockerfile, supervisord, .dockerignore, .gitignore
- Docker Compose: volume mounts and env vars across all demos/tests
- GitHub workflows: job/step names
- Shell scripts: log messages
- Demos: Python code, READMEs, VS Code configs, Grafana dashboard
- Docs: RST includes, code comments, config references
- Package metadata: package.json, pyproject.toml, uv.lock
External URLs (docs.archgw.com, github.com/katanemo/archgw) left as-is.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* Update remaining arch references in docs
- Rename RST cross-reference labels: arch_access_logging, arch_overview_tracing, arch_overview_threading → plano_*
- Update label references in request_lifecycle.rst
- Rename arch_config_state_storage_example.yaml → plano_config_state_storage_example.yaml
- Update config YAML comments: "Arch creates/uses" → "Plano creates/uses"
- Update "the Arch gateway" → "the Plano gateway" in configuration_reference.rst
- Update arch_config_schema.yaml reference in provider_models.py
- Rename arch_agent_router → plano_agent_router in config example
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* Fix remaining arch references found in second pass
- config/docker-compose.dev.yaml: ARCH_CONFIG_FILE → PLANO_CONFIG_FILE,
arch_config.yaml → plano_config.yaml, archgw_logs → plano_logs
- config/test_passthrough.yaml: container mount path
- tests/e2e/docker-compose.yaml: source file path (was still arch_config.yaml)
- cli/planoai/core.py: comment and log message
- crates/brightstaff/src/tracing/constants.rs: doc comment
- tests/{e2e,archgw}/common.py: get_arch_messages → get_plano_messages,
arch_state/arch_messages variables renamed
- tests/{e2e,archgw}/test_prompt_gateway.py: updated imports and usages
- demos/shared/test_runner/{common,test_demos}.py: same renames
- tests/e2e/test_model_alias_routing.py: docstring
- .dockerignore: archgw_modelserver → plano_modelserver
- demos/use_cases/claude_code_router/pretty_model_resolution.sh: container name
Note: x-arch-* HTTP header values and Rust constant names intentionally
preserved for backwards compatibility with existing deployments.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
115 lines
4.4 KiB
Markdown
115 lines
4.4 KiB
Markdown
# CLAUDE.md
|
|
|
|
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
|
|
|
## Project Overview
|
|
|
|
Plano is an AI-native proxy server and data plane for agentic applications, built on Envoy proxy. It centralizes agent orchestration, LLM routing, observability, and safety guardrails as an out-of-process dataplane.
|
|
|
|
## Build & Test Commands
|
|
|
|
### Rust (crates/)
|
|
|
|
```bash
|
|
# Build WASM plugins (must target wasm32-wasip1)
|
|
cd crates && cargo build --release --target=wasm32-wasip1 -p llm_gateway -p prompt_gateway
|
|
|
|
# Build brightstaff binary (native target)
|
|
cd crates && cargo build --release -p brightstaff
|
|
|
|
# Run unit tests
|
|
cd crates && cargo test --lib
|
|
|
|
# Format check
|
|
cd crates && cargo fmt --all -- --check
|
|
|
|
# Lint
|
|
cd crates && cargo clippy --locked --all-targets --all-features -- -D warnings
|
|
```
|
|
|
|
### Python CLI (cli/)
|
|
|
|
```bash
|
|
cd cli && uv sync # Install dependencies
|
|
cd cli && uv run pytest -v # Run tests
|
|
cd cli && uv run planoai --help # Run CLI
|
|
```
|
|
|
|
### JavaScript/TypeScript (apps/, packages/)
|
|
|
|
```bash
|
|
npm run build # Build all (via Turbo)
|
|
npm run lint # Lint all
|
|
npm run dev # Dev servers
|
|
npm run typecheck # Type check
|
|
```
|
|
|
|
### Pre-commit (runs fmt, clippy, cargo test, black, yaml checks)
|
|
|
|
```bash
|
|
pre-commit run --all-files
|
|
```
|
|
|
|
### Docker
|
|
|
|
```bash
|
|
docker build -t katanemo/plano:latest .
|
|
```
|
|
|
|
### E2E Tests (tests/e2e/)
|
|
|
|
E2E tests require a built Docker image and API keys. They run via `tests/e2e/run_e2e_tests.sh` which executes three test suites: `test_prompt_gateway.py`, `test_model_alias_routing.py`, and `test_openai_responses_api_client_with_state.py`.
|
|
|
|
## Architecture
|
|
|
|
### Core Data Flow
|
|
|
|
Requests flow through Envoy proxy with two WASM filter plugins, backed by a native Rust binary:
|
|
|
|
```
|
|
Client → Envoy (prompt_gateway.wasm → llm_gateway.wasm) → Agents/LLM Providers
|
|
↕
|
|
brightstaff (native binary: state, routing, signals, tracing)
|
|
```
|
|
|
|
### Rust Crates (crates/)
|
|
|
|
All crates share a Cargo workspace. Two compile to `wasm32-wasip1` for Envoy, the rest are native:
|
|
|
|
- **prompt_gateway** (WASM) — Proxy-WASM filter for prompt/message processing, guardrails, and filter chains
|
|
- **llm_gateway** (WASM) — Proxy-WASM filter for LLM request/response handling and routing
|
|
- **brightstaff** (native binary) — Core application server: handlers, router, signals, state management, tracing
|
|
- **common** (library) — Shared across all crates: configuration, LLM provider abstractions, HTTP utilities, routing logic, rate limiting, tokenizer, PII detection, tracing
|
|
- **hermesllm** (library) — Translates LLM API formats between providers (OpenAI, Anthropic, Gemini, Mistral, Grok, AWS Bedrock, Azure, together.ai). Key types: `ProviderId`, `ProviderRequest`, `ProviderResponse`, `ProviderStreamResponse`
|
|
|
|
### Python CLI (cli/planoai/)
|
|
|
|
The `planoai` CLI manages the Plano lifecycle. Key commands:
|
|
- `planoai up <config.yaml>` — Validate config, check API keys, start Docker container
|
|
- `planoai down` — Stop container
|
|
- `planoai build` — Build Docker image from repo root
|
|
- `planoai logs` — Stream access/debug logs
|
|
- `planoai trace` — OTEL trace collection and analysis
|
|
- `planoai init` — Initialize new project
|
|
|
|
Entry point: `cli/planoai/main.py`. Container lifecycle in `core.py`. Docker operations in `docker_cli.py`.
|
|
|
|
### Configuration System (config/)
|
|
|
|
- `plano_config_schema.yaml` — JSON Schema (draft-07) for validating user config files
|
|
- `envoy.template.yaml` — Jinja2 template rendered into Envoy proxy config
|
|
- `supervisord.conf` — Process supervisor for Envoy + brightstaff in the container
|
|
|
|
User configs define: `agents` (id + url), `model_providers` (model + access_key), `listeners` (type: agent/model/prompt, with router strategy), `filters` (filter chains), and `tracing` settings.
|
|
|
|
### JavaScript Apps (apps/, packages/)
|
|
|
|
Turbo monorepo with Next.js 16 / React 19 applications and shared packages (UI components, Tailwind config, TypeScript config). Not part of the core proxy — these are web applications.
|
|
|
|
## Key Conventions
|
|
|
|
- Rust edition 2021, formatted with `cargo fmt`, linted with `cargo clippy -D warnings`
|
|
- Python formatted with Black
|
|
- WASM plugins must target `wasm32-wasip1` — they run inside Envoy, not as native binaries
|
|
- The Docker image bundles Envoy + WASM plugins + brightstaff + Python CLI into a single container managed by supervisord
|
|
- API keys come from environment variables or `.env` files, never hardcoded
|