docs: document rich alias object form, routing_info response block, and pricing lookup precedence

[Pratham-Mishra04]

Summary

Documents the rich object form for alias entries, the new routing_info response block, and the pricing lookup precedence that uses canonical model_name to resolve opaque wire identifiers against the catalog.

Changes

• Added a note in the providers config reference pointing readers to the aliasing-models page for the object alias form
• Expanded the aliasing-models page to document the full alias object schema (model_id, model_name, model_family, description, region, and provider-specific overrides for Azure, Vertex, Bedrock, and Replicate), including a field reference table and validation rules for provider mismatch
• Replaced the flat extra_fields response fields (original_model_requested, resolved_model_used, provider) with the structured routing_info block; deprecated fields are noted as still populated for backward compatibility
• Added a lookup precedence section to the custom-pricing page explaining how pricing resolves opaque deployment IDs by trying the alias's canonical model_name before the wire model_id and the caller-sent model

Type of change

• Bug fix
• Feature
• Refactor
• Documentation
• Chore/CI

Affected areas

• Core (Go)
• Transports (HTTP)
• Providers/Integrations
• Plugins
• UI (React)
• Docs

How to test

Review the rendered docs pages for:

• docs/deployment-guides/config-json/providers.mdx — confirm the new <Note> appears after the Azure credential example
• docs/providers/aliasing-models.mdx — confirm the alias object schema table, provider-specific overrides table, updated routing_info response example, and deprecation note all render correctly
• docs/providers/custom-pricing.mdx — confirm the new "Lookup precedence" section appears between the wildcard patterns section and the request type filtering section

Breaking changes

• Yes
• No

The deprecated extra_fields top-level fields (original_model_requested, resolved_model_used, provider) remain populated, so existing consumers are unaffected.

Related issues

Security considerations

None.

Checklist

• I read docs/contributing/README.md and followed the guidelines
• I added/updated tests where appropriate
• I updated documentation where needed
• I verified builds succeed (Go and UI)
• I verified the CI pipeline passes locally if applicable

Summary by CodeRabbit

• Documentation
  • Added support for richer alias objects with per-alias routing/pricing metadata and provider-specific overrides; Azure guidance clarifies object-form aliases are supported.
  • Strengthened alias validation guidance (no empty/whitespace-only names, case-insensitive duplicate prevention, provider-mismatch rejection).
  • Introduced structured routing_info in responses (legacy fields noted for compatibility).
  • Clarified pricing lookup precedence and alias/model matching/fallback behavior.

[coderabbitai]

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

• @coderabbitai resume to resume automatic reviews.
• @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

• ▶️ Resume reviews
• 🔍 Trigger review

📝 Walkthrough

Walkthrough

This PR updates documentation for rich alias objects, extra_fields.routing_info alias-resolution reporting, Azure alias object syntax, and pricing lookup precedence when aliases are involved.

Changes

Alias Schema and Pricing Documentation

Layer / File(s)	Summary
Rich alias format and response tracking docs/providers/aliasing-models.mdx	Static key-level alias docs now describe alias values as either strings or structured objects, document validation and provider-specific override fields, and update response examples to use extra_fields.routing_info with resolved_key_alias.
Provider deployment alias guidance docs/deployment-guides/config-json/providers.mdx	Azure deployment alias docs add a note that aliases may use object values with canonical model metadata and per-alias provider override properties.
Pricing lookup precedence with aliases docs/providers/custom-pricing.mdx	Custom pricing docs define alias-aware catalog lookup order and clarify that pricing overrides match the wire model rather than the catalog lookup candidate.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Suggested reviewers

• akshaydeo
• danpiths

Poem

🐰 I found some aliases dressed up just right,
With routing notes tucked in crisp moonlight.
Pricing now hops in ordered line,
And docs make every path align.
Carrot cheers for schema bright!

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title directly summarizes the three main documentation changes: rich alias object form, routing_info response block, and pricing lookup precedence.
Description check	✅ Passed	The description includes all key sections from the template (Summary, Changes, Type, Affected areas, How to test, Breaking changes, Checklist) with detailed content addressing the documentation updates.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch 06-03-docs_alias_and_pricing_doc_updates

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[Pratham-Mishra04]

• feat: add KeyID filter to ListModelsRequest to scope calls to a single key #4036 : 2 dependent PRs (#4037 , #4038 )
• feat: adds datasheet store to modelcatalog #4035
• feat: add live model cache store and port keyconfig regression tests for alias/model isolation #4034
• feat: add keyconfig.Store for per-key config aggregation with allow/block/alias views #4033
• docs: document rich alias object form, routing_info response block, and pricing lookup precedence #4022 👈 (View in Graphite)
• refactor: replace resolvePricing positional model args with RoutingInfo and add backward-compat fallback for legacy ExtraFields #4021
• feat: add RoutingInfo to response/error extra fields with fallback and key alias signals #4020
• feat: replace flat aliases table with rich deployments table supporting per-deployment model family, canonical name, and provider-specific overrides #4019
• feat: add per-alias Replicate use deployments override and provider-scoped alias sub-config validation #4018
• feat: add per-alias Vertex project/region overrides and context-aware model family resolution #4017
• feat: propagate context into Bedrock region/ARN/model-family resolution for per-alias overrides #4016
• feat: add per-alias Azure endpoint, API version, and Anthropic version overrides with context-aware family resolution #4015
• refactor: promote KeyAliases values from string to AliasConfig with backward-compatible JSON marshaling #4014
• feat: enforce routing allowlist in core and propagate VK provider constraints via context key #3936 : 1 other dependent PR (#3711 )
• docs: document PreRequestHook routing phase, per-request vs per-attempt semantics, and updated plugin sequencing #3935
• refactor: move model-catalog provider resolution into a modelcatalogresolver PreRequestHook plugin #3934
• refactor: migrate governance routing from HTTPTransportPreHook to PreRequestHook #3933
• feat: add PreRequestHook to LLMPlugin interface as a once-per-request routing phase before PreLLMHook #3932
• dev

This stack of pull requests is managed by Graphite. Learn more about stacking.

[CLAassistant]

Thank you for your submission! We really appreciate it. Like many open source projects, we ask that you sign our Contributor License Agreement before we can accept your contribution.
_{You have signed the CLA already but the status is still pending? Let us recheck it.}

[greptile-apps]

Confidence Score: 5/5

Documentation-only change; all described fields, types, and resolution logic match the current Go implementation.

The new content is accurate: RoutingInfo, ResolvedKeyAlias, the deprecated-field backfill, the three-step pricing lookup, and the provider-mismatch validation rule all exist exactly as documented. Two minor example inconsistencies exist but neither introduces misinformation that would cause integration bugs.

No files require special attention; the small example inconsistencies in docs/providers/aliasing-models.mdx are cosmetic.

Important Files Changed

Filename	Overview
docs/providers/aliasing-models.mdx	Adds alias object schema table, routing_info response block, and deprecation note; example has two minor issues: Azure-specific fields in an ambiguous provider context, and inconsistent extra_fields wrapping between the two code examples.
docs/providers/custom-pricing.mdx	Adds lookup precedence section; logic matches Go code (model_name → model_id → caller model for catalog, wire model_id for override matching). Accurate and consistent with implementation.
docs/deployment-guides/config-json/providers.mdx	Adds a Note block pointing to the aliasing-models page for the object alias form; accurate and well-placed after the Azure key credential example.

_{Reviews (11): Last reviewed commit: "docs: alias and pricing doc updates" | Re-trigger Greptile}

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@docs/providers/aliasing-models.mdx`:
- Line 100: The docs list for the model_family enum is out of sync with the
config schema: update the enum values in the aliasing-models.mdx documentation
to exactly match the model_family enum in the config.schema.json (or, if the
additional families are intended, add them to the model_family enum in the
schema instead); specifically reconcile/remove the entries `gemma`, `llama`,
`imagen`, `veo` from the docs or add those identifiers to the schema so
model_family is authoritative and both sources match.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro

Run ID: 2c60af91-dbce-4fbd-88f1-4125e5216769

📥 Commits

Reviewing files that changed from the base of the PR and between afd8acd and 51aec53.

📒 Files selected for processing (3)

• docs/deployment-guides/config-json/providers.mdx
• docs/providers/aliasing-models.mdx
• docs/providers/custom-pricing.mdx

[coderabbitai]

♻️ Duplicate comments (1)

docs/providers/aliasing-models.mdx (1)

100-100: ⚠️ Potential issue | 🟠 Major | ⚡ Quick win

model_family enum still out of sync with config schema

This is the same issue flagged in the previous review. Line 100 documents gemma, llama, imagen, veo which are not present in the model_family enum in transports/config.schema.json. Remove these values or add them to the schema if they are intended to be supported.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/providers/aliasing-models.mdx` at line 100, The docs list extra
model_family enum values (gemma, llama, imagen, veo) that are not present in the
config schema; either add those values to the model_family enum in the config
schema (transports/config.schema.json) if they are intended to be supported, or
remove them from the documented enum list in docs/providers/aliasing-models.mdx
so the docs match the model_family enum; update whichever side you choose so the
model_family enum values are consistent across the schema and the docs.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Duplicate comments:
In `@docs/providers/aliasing-models.mdx`:
- Line 100: The docs list extra model_family enum values (gemma, llama, imagen,
veo) that are not present in the config schema; either add those values to the
model_family enum in the config schema (transports/config.schema.json) if they
are intended to be supported, or remove them from the documented enum list in
docs/providers/aliasing-models.mdx so the docs match the model_family enum;
update whichever side you choose so the model_family enum values are consistent
across the schema and the docs.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro

Run ID: 7c047396-2fc8-4f49-869d-4ace6c857318

📥 Commits

Reviewing files that changed from the base of the PR and between 88bcc64 and 586b04f.

📒 Files selected for processing (3)

• docs/deployment-guides/config-json/providers.mdx
• docs/providers/aliasing-models.mdx
• docs/providers/custom-pricing.mdx

[akshaydeo]

Merge activity

• Jun 9, 5:17 AM UTC: A user started a stack merge that includes this pull request via Graphite.
• Jun 9, 5:30 AM UTC: @akshaydeo merged this pull request with Graphite.