{"owner":"katanemo","repo":"plano","hasSkills":true,"hasMcp":false,"mcpConfig":null,"found":["CLAUDE.md"],"skills":{"CLAUDE.md":"# CLAUDE.md\n\nPlano 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.\n\n## Build & Test Commands\n\n```bash\n# Rust — WASM plugins (must target wasm32-wasip1)\ncd crates && cargo build --release --target=wasm32-wasip1 -p llm_gateway -p prompt_gateway\n\n# Rust — brightstaff binary (native target)\ncd crates && cargo build --release -p brightstaff\n\n# Rust — tests, format, lint\ncd crates && cargo test --lib\ncd crates && cargo fmt --all -- --check\ncd crates && cargo clippy --locked --all-targets --all-features -- -D warnings\n\n# Python CLI\ncd cli && uv sync && uv run pytest -v\n\n# JS/TS (Turbo monorepo)\nnpm run build && npm run lint && npm run typecheck\n\n# Pre-commit (fmt, clippy, cargo test, black, yaml)\npre-commit run --all-files\n\n# Docker\ndocker build -t katanemo/plano:latest .\n```\n\nE2E tests require a Docker image and API keys: `tests/e2e/run_e2e_tests.sh`\n\n## Architecture\n\n```\nClient → Envoy (prompt_gateway.wasm → llm_gateway.wasm) → Agents/LLM Providers\n                              ↕\n                         brightstaff (native binary: state, routing, signals, tracing)\n```\n\n### Crates (crates/)\n\n- **prompt_gateway** (WASM) — Proxy-WASM filter for prompt processing, guardrails, filter chains\n- **llm_gateway** (WASM) — Proxy-WASM filter for LLM request/response handling and routing\n- **brightstaff** (native) — Core server: handlers, router, signals, state, tracing\n- **common** (lib) — Shared: config, HTTP, routing, rate limiting, tokenizer, PII, tracing\n- **hermesllm** (lib) — LLM API translation between providers. Key types: `ProviderId`, `ProviderRequest`, `ProviderResponse`, `ProviderStreamResponse`\n\n### Python CLI (cli/planoai/)\n\nEntry point: `main.py`. Built with `rich-click`. Commands: `up`, `down`, `build`, `logs`, `trace`, `init`, `cli_agent`.\n\n### Config (config/)\n\n- `plano_config_schema.yaml` — JSON Schema for validating user configs\n- `envoy.template.yaml` — Jinja2 template → Envoy config\n- `supervisord.conf` — Process supervisor for Envoy + brightstaff\n\n### JS Apps (apps/, packages/)\n\nTurbo monorepo with Next.js 16 / React 19. Not part of the core proxy.\n\n## WASM Plugin Rules\n\nCode in `prompt_gateway` and `llm_gateway` runs in Envoy's WASM sandbox:\n\n- **No std networking/filesystem** — use proxy-wasm host calls only\n- **No tokio/async** — synchronous, callback-driven. `Action::Pause` / `Action::Continue` for flow control\n- **Lifecycle**: `RootContext` → `on_configure`, `create_http_context`; `HttpContext` → `on_http_request/response_headers/body`\n- **HTTP callouts**: `dispatch_http_call()` → store context in `callouts: RefCell<HashMap<u32, CallContext>>` → match in `on_http_call_response()`\n- **Config**: `Rc`-wrapped, loaded once in `on_configure()` via `serde_yaml::from_slice()`\n- **Dependencies must be no_std compatible** (e.g., `governor` with `features = [\"no_std\"]`)\n- **Crate type**: `cdylib` → produces `.wasm`\n\n## Adding a New LLM Provider\n\n1. Add variant to `ProviderId` in `crates/hermesllm/src/providers/id.rs` + `TryFrom<&str>`\n2. Create request/response types in `crates/hermesllm/src/apis/` if non-OpenAI format\n3. Add variant to `ProviderRequestType`/`ProviderResponseType` enums, update all match arms\n4. Add models to `crates/hermesllm/src/providers/provider_models.yaml`\n5. Update `SupportedUpstreamAPIs` mapping if needed\n\n## Release Process\n\nUpdate version (e.g., `0.4.11` → `0.4.12`) in all of these files:\n\n- `.github/workflows/ci.yml`, `build_filter_image.sh`, `config/validate_plano_config.sh`\n- `cli/planoai/__init__.py`, `cli/planoai/consts.py`, `cli/pyproject.toml`\n- `docs/source/conf.py`, `docs/source/get_started/quickstart.rst`, `docs/source/resources/deployment.rst`\n- `apps/www/src/components/Hero.tsx`, `demos/llm_routing/preference_based_routing/README.md`\n\nDo NOT change version strings in `*.lock` files or `Cargo.lock`. Commit message: `release X.Y.Z`\n\n## Workflow Preferences\n\n- **Commits:** No `Co-Authored-By`. Short one-line messages. Never push directly to `main` — always feature branch + PR.\n- **Branches:** Use `adil/<feature_name>` format.\n- **Issues:** When a GitHub issue URL is pasted, fetch all context first. Goal is always a PR with passing tests.\n\n## Key Conventions\n\n- Rust edition 2021, `cargo fmt`, `cargo clippy -D warnings`\n- Python: Black. Rust errors: `thiserror` with `#[from]`\n- API keys from env vars or `.env`, never hardcoded\n- Provider dispatch: `ProviderRequestType`/`ProviderResponseType` enums implementing `ProviderRequest`/`ProviderResponse` traits\n"},"files":{"CLAUDE.md":"# CLAUDE.md\n\nPlano 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.\n\n## Build & Test Commands\n\n```bash\n# Rust — WASM plugins (must target wasm32-wasip1)\ncd crates && cargo build --release --target=wasm32-wasip1 -p llm_gateway -p prompt_gateway\n\n# Rust — brightstaff binary (native target)\ncd crates && cargo build --release -p brightstaff\n\n# Rust — tests, format, lint\ncd crates && cargo test --lib\ncd crates && cargo fmt --all -- --check\ncd crates && cargo clippy --locked --all-targets --all-features -- -D warnings\n\n# Python CLI\ncd cli && uv sync && uv run pytest -v\n\n# JS/TS (Turbo monorepo)\nnpm run build && npm run lint && npm run typecheck\n\n# Pre-commit (fmt, clippy, cargo test, black, yaml)\npre-commit run --all-files\n\n# Docker\ndocker build -t katanemo/plano:latest .\n```\n\nE2E tests require a Docker image and API keys: `tests/e2e/run_e2e_tests.sh`\n\n## Architecture\n\n```\nClient → Envoy (prompt_gateway.wasm → llm_gateway.wasm) → Agents/LLM Providers\n                              ↕\n                         brightstaff (native binary: state, routing, signals, tracing)\n```\n\n### Crates (crates/)\n\n- **prompt_gateway** (WASM) — Proxy-WASM filter for prompt processing, guardrails, filter chains\n- **llm_gateway** (WASM) — Proxy-WASM filter for LLM request/response handling and routing\n- **brightstaff** (native) — Core server: handlers, router, signals, state, tracing\n- **common** (lib) — Shared: config, HTTP, routing, rate limiting, tokenizer, PII, tracing\n- **hermesllm** (lib) — LLM API translation between providers. Key types: `ProviderId`, `ProviderRequest`, `ProviderResponse`, `ProviderStreamResponse`\n\n### Python CLI (cli/planoai/)\n\nEntry point: `main.py`. Built with `rich-click`. Commands: `up`, `down`, `build`, `logs`, `trace`, `init`, `cli_agent`.\n\n### Config (config/)\n\n- `plano_config_schema.yaml` — JSON Schema for validating user configs\n- `envoy.template.yaml` — Jinja2 template → Envoy config\n- `supervisord.conf` — Process supervisor for Envoy + brightstaff\n\n### JS Apps (apps/, packages/)\n\nTurbo monorepo with Next.js 16 / React 19. Not part of the core proxy.\n\n## WASM Plugin Rules\n\nCode in `prompt_gateway` and `llm_gateway` runs in Envoy's WASM sandbox:\n\n- **No std networking/filesystem** — use proxy-wasm host calls only\n- **No tokio/async** — synchronous, callback-driven. `Action::Pause` / `Action::Continue` for flow control\n- **Lifecycle**: `RootContext` → `on_configure`, `create_http_context`; `HttpContext` → `on_http_request/response_headers/body`\n- **HTTP callouts**: `dispatch_http_call()` → store context in `callouts: RefCell<HashMap<u32, CallContext>>` → match in `on_http_call_response()`\n- **Config**: `Rc`-wrapped, loaded once in `on_configure()` via `serde_yaml::from_slice()`\n- **Dependencies must be no_std compatible** (e.g., `governor` with `features = [\"no_std\"]`)\n- **Crate type**: `cdylib` → produces `.wasm`\n\n## Adding a New LLM Provider\n\n1. Add variant to `ProviderId` in `crates/hermesllm/src/providers/id.rs` + `TryFrom<&str>`\n2. Create request/response types in `crates/hermesllm/src/apis/` if non-OpenAI format\n3. Add variant to `ProviderRequestType`/`ProviderResponseType` enums, update all match arms\n4. Add models to `crates/hermesllm/src/providers/provider_models.yaml`\n5. Update `SupportedUpstreamAPIs` mapping if needed\n\n## Release Process\n\nUpdate version (e.g., `0.4.11` → `0.4.12`) in all of these files:\n\n- `.github/workflows/ci.yml`, `build_filter_image.sh`, `config/validate_plano_config.sh`\n- `cli/planoai/__init__.py`, `cli/planoai/consts.py`, `cli/pyproject.toml`\n- `docs/source/conf.py`, `docs/source/get_started/quickstart.rst`, `docs/source/resources/deployment.rst`\n- `apps/www/src/components/Hero.tsx`, `demos/llm_routing/preference_based_routing/README.md`\n\nDo NOT change version strings in `*.lock` files or `Cargo.lock`. Commit message: `release X.Y.Z`\n\n## Workflow Preferences\n\n- **Commits:** No `Co-Authored-By`. Short one-line messages. Never push directly to `main` — always feature branch + PR.\n- **Branches:** Use `adil/<feature_name>` format.\n- **Issues:** When a GitHub issue URL is pasted, fetch all context first. Goal is always a PR with passing tests.\n\n## Key Conventions\n\n- Rust edition 2021, `cargo fmt`, `cargo clippy -D warnings`\n- Python: Black. Rust errors: `thiserror` with `#[from]`\n- API keys from env vars or `.env`, never hardcoded\n- Provider dispatch: `ProviderRequestType`/`ProviderResponseType` enums implementing `ProviderRequest`/`ProviderResponse` traits\n"},"items":[{"name":"CLAUDE.md","path":"CLAUDE.md","title":"CLAUDE.md","content":"# CLAUDE.md\n\nPlano 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.\n\n## Build & Test Commands\n\n```bash\n# Rust — WASM plugins (must target wasm32-wasip1)\ncd crates && cargo build --release --target=wasm32-wasip1 -p llm_gateway -p prompt_gateway\n\n# Rust — brightstaff binary (native target)\ncd crates && cargo build --release -p brightstaff\n\n# Rust — tests, format, lint\ncd crates && cargo test --lib\ncd crates && cargo fmt --all -- --check\ncd crates && cargo clippy --locked --all-targets --all-features -- -D warnings\n\n# Python CLI\ncd cli && uv sync && uv run pytest -v\n\n# JS/TS (Turbo monorepo)\nnpm run build && npm run lint && npm run typecheck\n\n# Pre-commit (fmt, clippy, cargo test, black, yaml)\npre-commit run --all-files\n\n# Docker\ndocker build -t katanemo/plano:latest .\n```\n\nE2E tests require a Docker image and API keys: `tests/e2e/run_e2e_tests.sh`\n\n## Architecture\n\n```\nClient → Envoy (prompt_gateway.wasm → llm_gateway.wasm) → Agents/LLM Providers\n                              ↕\n                         brightstaff (native binary: state, routing, signals, tracing)\n```\n\n### Crates (crates/)\n\n- **prompt_gateway** (WASM) — Proxy-WASM filter for prompt processing, guardrails, filter chains\n- **llm_gateway** (WASM) — Proxy-WASM filter for LLM request/response handling and routing\n- **brightstaff** (native) — Core server: handlers, router, signals, state, tracing\n- **common** (lib) — Shared: config, HTTP, routing, rate limiting, tokenizer, PII, tracing\n- **hermesllm** (lib) — LLM API translation between providers. Key types: `ProviderId`, `ProviderRequest`, `ProviderResponse`, `ProviderStreamResponse`\n\n### Python CLI (cli/planoai/)\n\nEntry point: `main.py`. Built with `rich-click`. Commands: `up`, `down`, `build`, `logs`, `trace`, `init`, `cli_agent`.\n\n### Config (config/)\n\n- `plano_config_schema.yaml` — JSON Schema for validating user configs\n- `envoy.template.yaml` — Jinja2 template → Envoy config\n- `supervisord.conf` — Process supervisor for Envoy + brightstaff\n\n### JS Apps (apps/, packages/)\n\nTurbo monorepo with Next.js 16 / React 19. Not part of the core proxy.\n\n## WASM Plugin Rules\n\nCode in `prompt_gateway` and `llm_gateway` runs in Envoy's WASM sandbox:\n\n- **No std networking/filesystem** — use proxy-wasm host calls only\n- **No tokio/async** — synchronous, callback-driven. `Action::Pause` / `Action::Continue` for flow control\n- **Lifecycle**: `RootContext` → `on_configure`, `create_http_context`; `HttpContext` → `on_http_request/response_headers/body`\n- **HTTP callouts**: `dispatch_http_call()` → store context in `callouts: RefCell<HashMap<u32, CallContext>>` → match in `on_http_call_response()`\n- **Config**: `Rc`-wrapped, loaded once in `on_configure()` via `serde_yaml::from_slice()`\n- **Dependencies must be no_std compatible** (e.g., `governor` with `features = [\"no_std\"]`)\n- **Crate type**: `cdylib` → produces `.wasm`\n\n## Adding a New LLM Provider\n\n1. Add variant to `ProviderId` in `crates/hermesllm/src/providers/id.rs` + `TryFrom<&str>`\n2. Create request/response types in `crates/hermesllm/src/apis/` if non-OpenAI format\n3. Add variant to `ProviderRequestType`/`ProviderResponseType` enums, update all match arms\n4. Add models to `crates/hermesllm/src/providers/provider_models.yaml`\n5. Update `SupportedUpstreamAPIs` mapping if needed\n\n## Release Process\n\nUpdate version (e.g., `0.4.11` → `0.4.12`) in all of these files:\n\n- `.github/workflows/ci.yml`, `build_filter_image.sh`, `config/validate_plano_config.sh`\n- `cli/planoai/__init__.py`, `cli/planoai/consts.py`, `cli/pyproject.toml`\n- `docs/source/conf.py`, `docs/source/get_started/quickstart.rst`, `docs/source/resources/deployment.rst`\n- `apps/www/src/components/Hero.tsx`, `demos/llm_routing/preference_based_routing/README.md`\n\nDo NOT change version strings in `*.lock` files or `Cargo.lock`. Commit message: `release X.Y.Z`\n\n## Workflow Preferences\n\n- **Commits:** No `Co-Authored-By`. Short one-line messages. Never push directly to `main` — always feature branch + PR.\n- **Branches:** Use `adil/<feature_name>` format.\n- **Issues:** When a GitHub issue URL is pasted, fetch all context first. Goal is always a PR with passing tests.\n\n## Key Conventions\n\n- Rust edition 2021, `cargo fmt`, `cargo clippy -D warnings`\n- Python: Black. Rust errors: `thiserror` with `#[from]`\n- API keys from env vars or `.env`, never hardcoded\n- Provider dispatch: `ProviderRequestType`/`ProviderResponseType` enums implementing `ProviderRequest`/`ProviderResponse` traits\n","category":"root","tokens":1159}]}