v0.3: model-group aggregation and compatibility hardening

[AviBackToBlack]

Goal

Build v0.3 around safe model-group semantics and the remaining compatibility gaps discovered during v0.1/v0.2 validation.

Proposed order

1. Multi-deployment / model-group aggregation

LiteLLM legitimately supports multiple deployments with the same user-facing model_name. v0.2 rejects duplicates, so the generator cannot currently represent a routed model group.

Research and implement a deterministic aggregation contract instead of selecting an arbitrary deployment.

Questions to settle before implementation:

• how LiteLLM routes capability-constrained requests across deployments in a group
• whether group capability values should be intersection/guarantee semantics, union/routable semantics, or field-specific
• how null vs explicit false propagates across deployments
• context/output token policy when deployments disagree
• canonical/base-model identity when deployments route to different underlying models/providers
• exact Codex template eligibility when only some deployments resolve to the same exact Codex model
• reasoning-effort aggregation and explicit denial precedence
• supported OpenAI parameter aggregation

Relevant upstream evidence:

• LiteLLM has first-class ModelGroupInfo / /model_group/info semantics and supports multiple deployments per model_name.
• Current LiteLLM router tests explicitly construct multiple deployments sharing a model group.
• [Bug]: GET /v1/models pegs proxy CPU for minutes / proxy hangs, health checks fail (v1.92.0 regression: per-model get_model_group_info + deepcopy of full deployment on wildcard routes) BerriAI/litellm#33636 documents multiple deployments sharing one wildcard model_name in production.
• Regression/Fix: model_group_alias entries not exposed in /model/info endpoint BerriAI/litellm#30589 documents model-group aliases and /model/info behavior.

Acceptance criteria:

• duplicate model_name values no longer fail merely because the group has multiple deployments
• aggregation is deterministic and order-independent
• no capability is advertised more strongly than the selected aggregation contract permits
• ambiguous/conflicting exact-template identity fails closed or falls back conservatively; never arbitrarily picks a donor
• explain exposes group size, disagreement notes, and field provenance
• tests cover same-model duplicate deployments, heterogeneous providers, conflicting true/false/null capabilities, reasoning levels, context windows, and order independence

2. Offline bundle version identity

Replace the current caller-trust boundary between --catalog-file, --codex-prompt-file, and --codex-schema-file with a verifiable bundle/manifest contract.

Acceptance criteria:

• one explicit Codex version/ref identity for all offline resources
• digest verification for bundled files
• mixed-version resources fail closed
• exact-only offline generation remains lightweight

3. Per-model overrides and globs

Extend the exact string allowlist without making selection ambiguous.

Acceptance criteria:

• backwards-compatible exact strings
• deterministic glob expansion
• explicit per-model overrides with provenance
• no silent inclusion of non-chat/non-responses models

4. Foreign web-search compatibility

Research before enabling. Do not simply map supports_web_search=true to Codex search support until the wire/tool semantics are proven compatible.

Current reason for caution:

• LiteLLM capability metadata itself has had recent missing supports_web_search flags across current Claude models: supports_web_search flag missing across the current Claude model family, not just claude-sonnet-5 BerriAI/litellm#33919
• Codex custom-provider discovery remains an active compatibility area: support LiteLLM /model/info for provider model discovery openai/codex#30760 and Custom model_providers: /models discovery requires undocumented internal schema; support the standard OpenAI list as a fallback openai/codex#37122

Acceptance criteria:

• identify exact Codex search-tool wire expectations for the matched Codex version
• distinguish provider-native web search from OpenAI-compatible search parameter support
• only enable when the LiteLLM route and Codex protocol are both evidenced compatible
• otherwise retain conservative false/disabled behavior

Non-goals

• no model-specific donor cloning for foreign models
• no weakening of v0.2 schema-drift fail-closed behavior
• no hidden inference from LiteLLM null
• no real/private LiteLLM payloads or infrastructure data in fixtures

[AviBackToBlack]

Foreign web-search research gate is now captured in PR #22.

Key finding: LiteLLM supports_web_search and Codex supports_search_tool are not the same capability. Current Codex uses supports_search_tool for tool-search/deferred tool discovery, while hosted web_search is gated by provider capability + runtime web-search mode and shaped by web_search_tool_type. WebSearchToolType currently has no disabled variant, and configured/custom providers inherit web_search=true from provider capability defaults.

Therefore model_catalog_json alone cannot currently guarantee hosted-search suppression for a foreign model, and a plain LiteLLM supports_web_search=true is not sufficient proof that every routed deployment accepts Codex's exact OpenAI Responses hosted-search wire shape.

PR #22 defines the contract and source index. Immediate follow-up after the design gate: remove the existing supports_web_search -> supports_search_tool exact-template coupling and correct the misleading foreign-search wording. Actual foreign hosted-search enablement remains deferred pending a stronger provider/model capability boundary plus route-level wire proof.

[AviBackToBlack]

v0.3 implementation and release-prep are complete. PR #24 merged to main at 08c0e04eda50172f2e96f980fe12e61352ac9da2, with package/runtime version 0.3.0 and all required CI/security checks green before merge.

Release tag hygiene remains before closing this roadmap issue:

• create v0.3.0 at 08c0e04eda50172f2e96f980fe12e61352ac9da2
• restore missing historical v0.2.1 at 6f66a4394ffe3651d5bd8ca1048cb9bb1e80a872

Both tag refs are currently absent. Keep #5 open until v0.3.0 exists.

[AviBackToBlack]

v0.3.0 release closure verified.

• v0.2.1 is present as a verified annotated SSH-signed tag and dereferences to 6f66a4394ffe3651d5bd8ca1048cb9bb1e80a872.
• v0.3.0 is present as a verified annotated SSH-signed tag and dereferences to 08c0e04eda50172f2e96f980fe12e61352ac9da2.
• main is 08c0e04eda50172f2e96f980fe12e61352ac9da2 from release-prep PR chore: prepare v0.3.0 release #24.

All four v0.3 roadmap items are complete; closing this issue as completed.