model-management

Model management

Use this workflow for every model change. Keep the implementation minimal, preserve the public contract unless the user explicitly approves a change, and prove provider behavior with real requests.

Load context first

1. Read the repository AGENTS.md.
2. Read the live registry entry, runtime config, handler, schemas, and tests. The repository is the source of truth for what Pollinations currently offers.
3. Read the relevant local active plan when present:
   • temp/manage_inference.md
   • temp/manage_inferenceport.md
   • temp/manage_gpus.md
   • temp/manage_azure_limits.md
4. Check GitHub for open or merged PRs that may already implement or conflict with the work.
5. Check current official provider documentation, catalog, pricing, availability, quotas, and deprecation notices. Then probe the exact route; the live response wins over documentation.

The temp plans are ignored operational state, not repository truth. When working in a linked worktree where they are absent, locate the primary checkout with git worktree list and read them there. Never copy balances, prices, PR statuses, quotas, or candidate rankings into this skill.

Read operating-policy.md before recommending a route or model. Read only the other references needed for the task:

Mandatory confirmation gate

Apply this gate only to a proposed tracked model mutation. Do not turn a read-only status confirmation, an approval of an already-documented planning decision, or a correction of an operational fact into a different mutation. Treat a generic “confirm” as approval only for the exact contract just shown.

Do not edit any model until the user confirms its complete business and inference contract. Inspect the code and provider first; do not ask the user to discover values for you.

Show one complete row per model:

Ask:

Please confirm: canonical name X, aliases A/none, price multiplier M, paid-only yes/no, Pollinations GPU yes/no, registry provider P, primary route R, best fallback candidate C/none found, and Pollinations fallback decision use C/none. Are all of these correct?

An answer approves only the values shown. If a value is unknown, inferred, conflicting, or route-dependent, label it UNKNOWN, explain the evidence, and wait for that exact decision. A batch approval is valid only when every row is complete.

Public API changes require separate confirmation

Model approval does not authorize adding, renaming, removing, or changing a public endpoint, method, transport, request or response schema, streaming behavior, or event protocol. Do not propose an API-surface change without a concrete user or developer problem it solves.

Before editing, present:

• the user/developer problem and the current public contract;
• the exact proposed routes, methods, transports, schemas, streaming behavior, and events;
• the compatibility reference, resolved by the order in step 4;
• whether the change is additive, behavioral, deprecating, or breaking, and the affected clients;
• the migration, coexistence, and removal plan, or none.

State plainly: This adds/changes the public API: ... Then ask for explicit confirmation of that exact API change. If the problem, standard, or compatibility impact is unclear, do not edit.

Secrets are a separate approval

Model approval never authorizes adding, rotating, synchronizing, deploying, revoking, or otherwise mutating a credential. Follow the exact approval wording, dedicated-PR requirement, execution order, verification, and rollback rules in AGENTS.md. Do not duplicate or weaken that process here.

Workflow

1. Reconcile current state

• Resolve aliases to the canonical registry entry.
• Before any canonical rename, count production and staging API keys whose permissions.models contains the old canonical ID. Verify the deployed authorization code resolves stored aliases; registry aliases alone cannot protect keys while an old exact-string reader is still running.
• Audit every modality registry and every model change merged to main since the current production revision; production can lag behind main.
• If a model or provider is missing from the registry, check git log --all -- <path> and gh pr list --state merged --search <model> before re-adding it — it may have been removed on purpose, added and reverted, or replaced.
• Trace every reachable runtime route and any configured fallback.
• Distinguish the configured provider from the provider that served an observed request.
• Compare the intended change with open PRs and active plan entries.
• Remove shipped work from active plans after production verification; do not keep a completed archive.

2. Research the exact route

• Use official provider/model sources for release, model identity, pricing, regions, preview status, quotas, rate limits, context, inputs, outputs, tools, caching, and deprecation.
• Deduplicate the canonical model across providers.
• List material route differences. Equal model names do not prove equal capabilities.
• Probe the exact deployment and request shape Pollinations will use.
• For every addition or modification, run a fresh web search across provider catalogs and official documentation to discover viable fallback routes; do not rely only on repository integrations or remembered availability. Verify each serious candidate against its current official model page and pricing, then probe the exact route. Compare checkpoint identity, capabilities, parameters, formats, safety/privacy, availability, latency, price, permissions, and billing. Recommend the best candidate or state none found; never omit the fallback decision because the primary route is healthy.
• Inspect provider-managed routing/fallback defaults and controls. Report identity, capability, pricing, residency, and observability tradeoffs.

3. Confirm the contract

Present the mandatory row and obtain explicit confirmation before editing. If a capability or access change is intentional, state it plainly.

4. Implement the smallest complete change

• Canonical public IDs use <publisher-slug>/<official-model-slug>. Keep both components lowercase, preserve the publisher's model family and version, and follow the publisher's public slug when one exists. Never invent, drop, or silently advance a version.
• publisher is the human-readable publisher (OpenAI, Anthropic, xAI), not the inference provider. Keep provider deployment IDs, casing, punctuation, and revision suffixes internal when they are routing details rather than the publisher's public model identity.
• Never encode an inference provider in a public canonical ID. Deduplicate the same publisher model across providers behind one public identity and declare automatic routing through the registry's ordered fallback relationship.
• Name hidden fallback registry entries <public-canonical-id>:<provider>. The public registry key, catalogs, request model, and permissions remain the public ID. Keep fallback identity separate from priority: never use :fallback, numbered fallback suffixes, or priority labels in these IDs.
• For a pinned OpenRouter endpoint, append a meaningful qualifier from the start: <public-canonical-id>:<provider>:<route-qualifier>, such as google/gemini-2.5-flash-lite:openrouter:vertex-global or google/gemini-2.5-flash-lite:openrouter:ai-studio. Distinguish multiple deployments through the same provider explicitly. Use lowercase labels; never encode priority or the temporary fallback role. Preserve fallback registry IDs when changing their order. For provider-managed routing without a fixed backend, do not invent an endpoint qualifier.
• The provider field and route configuration remain authoritative; the name does not select an upstream endpoint. Keep fallback-only entries hidden, without aliases, and excluded from catalogs and direct model selection. Route-specific cost belongs on the serving definition; callers retain the requested public model's price. Use the existing shared fallback mechanism.
• Preserve existing resolved_model_requested, model_used, x-model-used, provider, per-attempt, community and cache attribution semantics during a canonical rename. Recorded IDs may adopt the new spelling, including hidden fallback registry IDs; do not force primary IDs into execution identifiers. Explicit primary execution IDs and their analytics/header contract are deferred to #14543. Review affected consumers and any public API changes separately; do not silently repurpose x-model-used or rewrite historical events.
• Preserve the complete public canonical ID, including existing suffixes, when

Content truncated.