Repository navigation
docs(aws-startup-advisor): list the OpenRouter gateway guide in the model-lifecycle mapping-guide rule - #470
Conversation
… in the AI capability catalog Follow-up to aws#450. That PR deliberately marked `google` and `openrouter` as `unknown` in ai-capability-catalog.json because neither had a shared, cross-skill Bedrock-mapping guide under skills/shared/ai/ — the bar the catalog uses for `supported`. Gemini's only guide lived under gcp-to-aws's adapter-local design-refs/, and no gateway-routing guide existed at all. This PR delivers those two shared guides and flips both catalog entries: - skills/shared/ai/ai-gemini-to-bedrock.md — source-cloud-neutral Gemini → Bedrock model-selection guide, modeled on the shared OpenAI/Anthropic guides (same header/vendoring contract). The Bedrock target depends on the Gemini model, not the source cloud, so the guide is canonical here and vendored into gcp-to-aws and azure-to-aws. - skills/shared/ai/ai-openrouter-to-bedrock.md — gateway-routing guide that maps each OpenRouter-fronted upstream model to Bedrock via the per-provider guides, preserving per-upstream associations and BYOK-vs-credits cost provenance. OpenRouter stays a gateway, never a provider or infrastructure source. - catalog: google -> supported, openrouter -> supported, catalog_version 1 -> 2, verified_at refreshed, notes rewritten to cite the new guides. Target-only, matching aws#450/aws#415/aws#416: no phase file reads these; no runtime behavior changes; implemented_adapter/route stay null everywhere (status reflects documentation coverage, not an implemented adapter). The gcp-to-aws adapter-local design-refs/ai-gemini-to-bedrock.md is retained; repointing its runtime routing onto the shared guide is deferred to the extraction stages (aws#389 3a-3e). Gates: vendored-parity (55 files byte-identical), skill-refs (1357 refs, 0 missing), ai-capability-catalog contract tests (13), full plugin suite (444), lint:md (803 files, 0 errors), artifacts/consent-disclosure/model-id all pass.
…pter-local drift Addresses a review flag on this PR: gcp-to-aws now holds two Gemini → Bedrock guides — the new inert shared/vendored copy and the older adapter-local references/design-refs/ one that design-ai.md still loads at runtime — with no gate between them. The vendored-parity check only compares the vendored copy against the shared canonical, never against the adapter-local original, so a one-sided pricing edit could let them silently disagree until the aws#389 3a-3e extraction folds them together. - Make the shared guide's priced body byte-identical to the adapter-local guide's (the two had drifted by a single cosmetic table-separator character; all pricing/mapping rows already matched). Headers stay intentionally different (canonical banner + source-neutral Applies-to). - Add tests/test_gemini_guide_body_parity.py: pins both guides' bodies (from the first `## ` heading down) byte-for-byte, excluding the lead-in. Verified it fails on a one-sided pricing mutation. Delete this test when the extraction stage merges the two guides into one. No runtime routing changes; still target-only. Full `mise run ci` passes (446 tests, +2).
|
Agreed — the description undersold the diff, and I've fixed it. Updated the Scope and Base / stacking sections to explicitly name One clarification on attribution: that regression test is #469's commit ( Good catch on the drift-guard, and thanks for confirming it passes against current |
leon1418
left a comment
leon1418
left a comment
There was a problem hiding this comment.
[🤖 AI review 🤖]
Reviewed the full 16-file diff at 3f58570d91a4a8cf22582982cde5fac99e1132a6, including the stacked guide/catalog changes. Three P2 corrections are needed in skills/shared/ai/ai-openrouter-to-bedrock.md and its GCP/Azure vendored copies:
- Match Discover's actual fields and provenance values; handle uncertain and mixed usage without inventing a funding/token split.
- Keep captured OpenRouter spend as the current-cost baseline, with its existing window and overlap caveats.
- Preserve the endpoint and inference-profile choice made by the provider guide through cutover.
Validation passed: 446 plugin tests, 480 agent-advisor tests, both Heroku suites (13 + 44 tests), Markdown lint, artifact/consent/model checks, 1,357 skill references, and parity for all 55 vendored files. The independent reviewer also passed 15 scoped tests. Findings are supported by source contracts and current provider documentation; no live migration or inference was run.
…er/Estimate contracts Addresses three P2 review findings on the ai-openrouter-to-bedrock.md guide (canonical + both vendored copies): 1. Provenance enum: the guide used invented `byok`/`credits` values and told the reader to derive a BYOK/credits volume split. The producer (discover-openrouter-api.md) actually emits `byok_passthrough`/`no_byok`/`mixed`/`uncertain`/`unknown` with a single `monthly_cost_usd` and no funding/token ratio, and llm-to-bedrock/SKILL.md forbids deriving that split. Rewrote the table to the real enum, added the `uncertain` handling, and state the mixed split is unavailable rather than fabricating one. 2. Cost baseline: the guide told the reader to compare the Bedrock target against the upstream provider's list price instead of the captured OpenRouter spend, which would swap the savings denominator. estimate-ai.md Part 1 prefers measured current_costs/usage-profile dollars and does not fall back to a direct-provider list rate for the OpenRouter portion (no source-side list row in pricing-cache.md). Made the captured spend the baseline and demoted list pricing to a separately labeled reference. 3. Endpoint/migration_path: the Cutover step sent every GPT target to Mantle, but ai-openai-to-bedrock.md can select `runtime_openai_cris` (CRIS) for GPT-5.6/GPT-6. Now carries each target's selected migration_path, endpoint/ profile ID, and matching IAM (bedrock:InvokeModel for Converse/runtime, bedrock-mantle:* for the Mantle GPT path) through cutover. Docs-only, target-only; vendored parity, skill-refs, lint:md green; 446 tests pass.
…odel-lifecycle mapping-guide rule The "Mapping Guides" section of ai-model-lifecycle.md enumerates the mapping guides its lifecycle rules apply to (Best-Bedrock-Match rows must be Active, no exclusion-zone or restricted models as defaults, Legacy only in notes). It listed the OpenAI, Anthropic, and Gemini guides but not the new shared OpenRouter gateway guide (ai-openrouter-to-bedrock.md), whose per-upstream recommendation rows are subject to the same rules. Add it to the heading, flagged as the gateway guide. Docs-only; vendored copies in gcp-to-aws and azure-to-aws synced byte-identical. Builds on the shared OpenRouter guide added in the catalog PR. Full `mise run ci` passes (446 tests; vendored-parity, skill-refs, lint:md all green).
3f58570 to
17120cd
Compare
leon1418
left a comment
leon1418
left a comment
There was a problem hiding this comment.
[🤖 AI review 🤖]
All three prior findings are verified fixed at 17120cdf7b2ee93b1e0cdca0af5b14d1fedc4dcb: the guide now matches Discover's provenance contract, preserves measured OpenRouter costs, and carries the selected Runtime/CRIS or Mantle path through cutover. I replied with the evidence and resolved our three original conversations.
The complete OCR-assisted follow-up and independent review covered all 16 changed files and found no new substantive issues. Validation passed: 446 plugin tests, 480 agent-advisor tests, both Heroku suites, and the required Markdown, model, artifact, consent, reference and vendoring checks. Verification used source contracts and local checks; no live migration or inference was run.
Approval is recommended for the user to submit.
leon1418
left a comment
leon1418
left a comment
There was a problem hiding this comment.
[🤖 AI review 🤖]
Rechecked b327d0b070e80da4e23d707d82f591a5725c6602 against base bc39e268867d23795eb1aa222eda1f510502a50b. All 16 PR files retain the contents reviewed at 17120cdf7b2ee93b1e0cdca0af5b14d1fedc4dcb. The complete OCR-assisted follow-up and fresh independent review found no substantive issues; the earlier fixes remain intact.
Current validation passed: 467 plugin tests, 509 agent-advisor tests, both Heroku suites (13 + 44 tests), all required lint/contract checks, 1,353 skill references, and parity for 55 vendored files. The independent reviewer also passed 15 focused tests. These are source and local-test results, with no live migration or inference run.
Approval is recommended for the user to submit.
Problem
The Mapping Guides section of
skills/shared/ai/ai-model-lifecycle.mdenumerates the mapping guides its lifecycle rules apply to — Best-Bedrock-Match rows must contain only Active models, exclusion-zone andrestrictedmodels must not appear as defaults, and Legacy models may appear only in notes. The heading listed the OpenAI, Anthropic, and Gemini guides but not the shared OpenRouter gateway guide (ai-openrouter-to-bedrock.md), whose per-upstream recommendation rows are subject to the exact same rules.Left unlisted, a future edit to the OpenRouter guide could introduce a Legacy or exclusion-zone model as a default recommendation without the lifecycle rule visibly covering it.
Fix
Add
ai-openrouter-to-bedrock.mdto the Mapping Guides heading, flagged as the gateway guide to distinguish it from the per-provider guides. One-line prose change, applied to the canonicalskills/shared/ai/ai-model-lifecycle.mdand copied byte-identically into the two vendored copies.Scope
This PR's own commit is docs-only: it affects a single sentence in
ai-model-lifecycle.md(canonical + both vendored copies), with no schema, runtime-behavior, model-data, or artifact change. The full diff againstmainalso shows files inherited from #469 (see the stacking note below) — including thetest_gemini_guide_body_parity.pyregression test, which is #469's work, carried in only because this branch is stacked on it. It drops out of this PR's diff after #469 merges and this rebases.Base / stacking note
This branch is stacked on #469 (which introduces
ai-openrouter-to-bedrock.md), so the diff againstmaincurrently also shows #469's files: the two new shared AI guides and their vendored copies, the capability-catalog change, the README tables, and thetest_gemini_guide_body_parity.pyregression test. Only the threeai-model-lifecycle.mdlines are this PR's own commit (0ce4eb7) — everything else belongs to #469 and drops out of the diff once #469 merges and this is rebased ontomain. This PR cannot merge before #469 because the guide it names must exist first; the skill-reference lint would otherwise fail on a missing path.In code, for reviewers
skills/shared/ai/ai-model-lifecycle.mdline 160 — the### Mapping Guides (...)heading gainsthe gateway guide ai-openrouter-to-bedrock.md.skills/gcp-to-aws/references/vendored/ai/ai-model-lifecycle.mdandskills/azure-to-aws/references/vendored/ai/ai-model-lifecycle.md— the same line, synced byte-identical viatools/sync-vendored.py.Validation
Validation recorded for current head `0ce4eb7e15219a2e56307b2cb719aba293db7389`:
The change is a single documentation line; no runtime path is exercised.
Type of Change
Startup Advisor review checklist
By submitting this PR, I confirm that:
By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.