mirror of
https://github.com/katanemo/plano.git
synced 2026-04-25 00:36:34 +02:00
743d074184
Some checks are pending
CI / pre-commit (push) Waiting to run
CI / plano-tools-tests (push) Waiting to run
CI / native-smoke-test (push) Waiting to run
CI / docker-build (push) Waiting to run
CI / validate-config (push) Waiting to run
CI / security-scan (push) Blocked by required conditions
CI / test-prompt-gateway (push) Blocked by required conditions
CI / test-model-alias-routing (push) Blocked by required conditions
CI / test-responses-api-with-state (push) Blocked by required conditions
CI / e2e-plano-tests (3.10) (push) Blocked by required conditions
CI / e2e-plano-tests (3.11) (push) Blocked by required conditions
CI / e2e-plano-tests (3.12) (push) Blocked by required conditions
CI / e2e-plano-tests (3.13) (push) Blocked by required conditions
CI / e2e-plano-tests (3.14) (push) Blocked by required conditions
CI / e2e-demo-preference (push) Blocked by required conditions
CI / e2e-demo-currency (push) Blocked by required conditions
Publish docker image (latest) / build-arm64 (push) Waiting to run
Publish docker image (latest) / build-amd64 (push) Waiting to run
Publish docker image (latest) / create-manifest (push) Blocked by required conditions
Build and Deploy Documentation / build (push) Waiting to run
* feat: add initial documentation for Plano Agent Skills * feat: readme with examples * feat: add detailed skills documentation and examples for Plano --------- Co-authored-by: Adil Hafeez <adil.hafeez@gmail.com>
77 lines
2.2 KiB
Markdown
77 lines
2.2 KiB
Markdown
---
|
|
title: Use Model Aliases for Semantic, Stable Model References
|
|
impact: MEDIUM
|
|
impactDescription: Hardcoded model names in client code require code changes when you swap providers; aliases let you update routing in config.yaml alone
|
|
tags: routing, model-aliases, maintainability, client-integration
|
|
---
|
|
|
|
## Use Model Aliases for Semantic, Stable Model References
|
|
|
|
`model_aliases` map human-readable names to specific model identifiers. Client applications reference the alias, not the underlying model. When you want to upgrade from `gpt-4o` to a new model, you change one line in `config.yaml` — not every client calling the API.
|
|
|
|
**Incorrect (clients hardcode specific model names):**
|
|
|
|
```yaml
|
|
# config.yaml — no aliases defined
|
|
version: v0.3.0
|
|
|
|
listeners:
|
|
- type: model
|
|
name: model_listener
|
|
port: 12000
|
|
|
|
model_providers:
|
|
- model: openai/gpt-4o
|
|
access_key: $OPENAI_API_KEY
|
|
default: true
|
|
```
|
|
|
|
```python
|
|
# Client code — brittle, must be updated when model changes
|
|
client.chat.completions.create(model="gpt-4o", ...)
|
|
```
|
|
|
|
**Correct (semantic aliases, stable client contracts):**
|
|
|
|
```yaml
|
|
version: v0.3.0
|
|
|
|
listeners:
|
|
- type: model
|
|
name: model_listener
|
|
port: 12000
|
|
|
|
model_providers:
|
|
- model: openai/gpt-4o-mini
|
|
access_key: $OPENAI_API_KEY
|
|
default: true
|
|
- model: openai/gpt-4o
|
|
access_key: $OPENAI_API_KEY
|
|
- model: anthropic/claude-sonnet-4-20250514
|
|
access_key: $ANTHROPIC_API_KEY
|
|
|
|
model_aliases:
|
|
plano.fast.v1:
|
|
target: gpt-4o-mini # Cheap, fast — for high-volume tasks
|
|
|
|
plano.smart.v1:
|
|
target: gpt-4o # High capability — for complex reasoning
|
|
|
|
plano.creative.v1:
|
|
target: claude-sonnet-4-20250514 # Strong creative writing and analysis
|
|
|
|
plano.v1:
|
|
target: gpt-4o # Default production alias
|
|
```
|
|
|
|
```python
|
|
# Client code — stable, alias is the contract
|
|
client.chat.completions.create(model="plano.smart.v1", ...)
|
|
```
|
|
|
|
**Alias naming conventions:**
|
|
- `<org>.<purpose>.<version>` — e.g., `plano.fast.v1`, `acme.code.v2`
|
|
- Bumping `.v2` → `.v3` lets you run old and new aliases simultaneously during rollouts
|
|
- `plano.v1` as a canonical default gives clients a single stable entry point
|
|
|
|
Reference: https://github.com/katanemo/archgw
|