Repository navigation
Conversation
… and the sidecar hook names llm_rosetta.contracts is the one home for what an outside party implements or receives (#1657). This first step adds the package itself: it holds only constants, so importing it loads no converter and no shim registry. - SURFACE_VERSION moves here from llm_rosetta.api; api re-exports it, so the gateway's startup check reads the same object (still level 1: the paths it covers never shipped in a final release). - IR_VERSION = 1 is defined with the IR data model (llm_rosetta.types.ir.version, exported by llm_rosetta.types.ir) and re-exported from contracts (decision D1, #74). - The sidecar file names and the names the shim loader reads from them (pre_ir_transforms, post_ir_transforms, ir_transforms, response_body_transforms, model_list_transform, PROBES, EXCHANGE) are constants here, and the loader modules and the scaffolder import them instead of restating the strings. A test pins the values and checks that no loader module restates a literal.
…s into llm_rosetta.contracts The four contract modules the gateway and the shims already import move into the contracts package (#1657, C1): - llm_rosetta.shims.auth_exchange -> llm_rosetta.contracts.auth - llm_rosetta.shims.quota_probe -> llm_rosetta.contracts.quota - llm_rosetta.routing (package) -> llm_rosetta.contracts.routing - llm_rosetta.observability.usage -> llm_rosetta.contracts.usage The moves use git mv, so history follows. routing/contract.py becomes the module and takes over the package's __all__ (ProviderType and SoftErrorPattern stay re-exported). usage stays a subpackage: its four submodules are internal, and only the names its __init__ exports are the contract. No forwarder is left at an old path (decided in #1657). None of the four paths exists on v0.13.0 as moved here, with one exception: v0.13.0 had a flat llm_rosetta/routing.py. Its removal is recorded in the public-API allowlist by the tier-table commit, where public_api_diff keeps comparing it. llm_rosetta.observability itself shipped in 0.13.0 and holds the alias finder for the telemetry that moved to the gateway, so the parent stays; its lazy usage names now resolve from llm_rosetta.contracts.usage. Every importer in core, the gateway, the shim sidecars, the scaffold templates and the tests is repointed. The gateway boundary test names the new paths; the next commits collapse it to two prefixes.
The values a shim declares and a host reads move out of shims/provider_shim.py into llm_rosetta.contracts.shim (#1657, C1/C6): ProviderShim, ConnectionConfig, ToolsConfig, ReasoningCapability, VendorManifest, QuotaDeclaration, BatchDeclaration, SoftErrorPattern, TYPE_PARAM_KEYS and the UnsignedBlocks / ReplayMissing / ToolSearchMode literals. The classes are moved verbatim; there is no ModelShim class in the tree, so none moves. shims/provider_shim.py shipped in 0.13.0, so it stays. It keeps the registry (register_shim, get_shim, staging_registry, ...), which is not part of the contract, and re-exports the data classes as the same objects, plus the 0.13.0 re-exports (IREffort, IRMode, Transform, IRTransform). Its docstring names the new home and says that importing the data classes from it is deprecated, with removal in 0.15.0. It now declares __all__. Every core and test import of a data class reads contracts.shim; a test checks that no core module imports one from provider_shim and that the re-exports are identical objects.
…d primitives; NamedTransform is public A shim's transforms.py had no public module to import from: every core and external shim imported the internal llm_rosetta.transforms facade, and four core shims (groq, minimax, openai_chatgpt, openrouter) plus three external repos imported the private _NamedTransform (#1657, C2). llm_rosetta.contracts.transform is that module. It re-exports, from the implementations in llm_rosetta.ir.primitives: - the hook types: Transform, IRTransform, TransformContext, NamedTransform, NamedIRTransform; - the runners a shim's own tests need: apply_transforms, apply_ir_transforms; - the body primitives: backfill_reasoning_content, default_message_field, default_tool_description, flatten_system_content, force_fields, rename_field, replace_message_field, rewrite_harmony_tool_calls, set_defaults, strip_fields, strip_fields_for_model; - the IR primitives: auto_cache_breakpoints, hoist_late_system_messages, truncate_images, unwind_parallel_tool_calls. The list is every public name the facade exported, plus the two label wrappers. The audit's eleven shim imports (core and the four external repos) are all in it. NamedIRTransform is public alongside NamedTransform because a shim that writes its own IR-level transform needs the same label wrapper; nothing in core used either name privately, so both are renamed at their definitions and no underscore alias is kept. The core shim sidecars and shims/__init__ import from the contract; the shim data classes take their Transform types from it too.
…pabilities facades Both packages were compatibility facades over llm_rosetta.ir (the transform primitives and the capability passes). Neither path exists on v0.13.0, which had llm_rosetta/shims/transforms.py and a flat llm_rosetta/capabilities.py instead (see the tier-table commit for how the flat module's removal is recorded). Decision D3 of #1657 removes them before 0.14.0 instead of carrying them for a minor. Every importer is repointed: - core internals read the ir/ home: llm_rosetta.ir.primitives(.body/.ir) and llm_rosetta.ir.passes (and its submodules); - llm_rosetta.api takes flatten_system_content from contracts.transform and ToolNameMap from ir.passes.tool_names; - the tests read contracts.transform for the transform names, ir.passes for the passes, and the gateway test reads ToolNameMap from api. test_ir_import_boundary now checks that both paths stay absent. llm_rosetta.contracts joins PUBLIC_MODULES so the top-level coverage test sees it; the tier-table commit replaces the list.
…osetta initialises Plugin entry points (llm_rosetta.shim_providers) run during `import llm_rosetta`: shims/__init__ loads them. A plugin whose entry point or sidecar imports llm_rosetta.api, or a name llm_rosetta/__init__ defines (__version__), hits a partially initialised package; the loader catches the ImportError and logs it, so the plugin's shims never register while every in-process test stays green (measured by the #1657 C7 work). - contracts.shim.load_providers_from_dir is the registration call a plugin entry point makes. It delegates to the shim loader on call, so contracts.shim stays importable while the loader is starting up. It is the one registry function the contract names; the rest stay behind llm_rosetta.api. - contracts.auth declares a literal __all__ (AuthContext, AuthExchange, AuthExchangeError, BaseAuthExchange, InteractiveSetupRequired, credential_for, the field limits and DEFAULT_CREDENTIAL_ROLE). - tests/test_contracts_partial_init.py installs a real entry point (a .dist-info on sys.path) for a fixture plugin whose entry point and sidecars import every contract module and the names the external shim repos use, and checks in a fresh interpreter that its shim registers with its transforms. Mutations that make the entry point import llm_rosetta.api, or make a contract module import __version__, turn it red. - The entry-point failure warning (already WARNING with a traceback) now names the exception class and message and says the plugin's shims are not registered, so the one-line log is enough to diagnose it.
…setta.contracts Every .py file under shims/providers/<vendor>/ (transforms.py, auth.py, quota.py and their helpers) may now import llm_rosetta only through llm_rosetta.contracts and its submodules, plus relative imports inside its own vendor directory (#1657, C5). Not llm_rosetta.api: sidecars execute while `import llm_rosetta` is still running, and api needs the finished package. Not another vendor: each vendor directory has to stand alone so it can move to the plugin monorepo. The loader's own _*.py modules are internal and out of scope. The scaffold templates (*.py.tmpl) and the files the scaffolder writes for --transform --auth --quota follow the same rule; the package template's entry point now registers through contracts.shim.load_providers_from_dir. The one offender was openai_chatgpt/quota.py, which imported llm_rosetta.shims.providers.openai.quota.PROBES. The Codex usage probe is not generic: its endpoint, the JWT claim it reads, the reply shape and the refusal wording are all ChatGPT-plan facts, so it does not belong in contracts/quota.py. It is also not small (one class, about 150 lines), but it is the same vendor fact in two lanes, and the openai vendor must keep it too (a provider entry may declare quota.probe: openai_codex on an openai shim, and the tests pin that). The smallest correct fix is a copy: openai_chatgpt/quota.py now carries the probe itself, and a test compares the two modules' ASTs (docstrings excluded) so the copies cannot drift. A symlink would keep one file but breaks on checkouts without symlink support and does not survive a move to a separate repository.
…and llm_rosetta.contracts The gateway boundary test checked five paths (api plus the four contract modules). With the contracts in one package it checks two prefixes (#1657, C4): llm_rosetta.api and llm_rosetta.contracts with its submodules. contracts.usage keeps its package-only rule: its submodules are internal, so the gateway reaches it as a package only. The private name rule and _TESTS_PRIVATE_ALLOWLIST are unchanged (still one entry). The docstrings of llm_rosetta.api and llm_rosetta_gateway.surface name the two prefixes and say that SURFACE_VERSION is defined in contracts.
…pi_diff reads it llm_rosetta/_tiers.py lists the public modules by tier (#1657, C3): - USER: the library API (root, auto_detect, tool_ops, converters and the five chat converter packages, the embeddings / rerank / decisions packages and the registry, types, types.ir, shims, pipeline, fidelity, retired_names) -- the core entries PUBLIC_MODULES already had; - EXTENSION: llm_rosetta.api and llm_rosetta.contracts with its six submodules; - COMPAT: llm_rosetta.gateway, llm_rosetta.observability (the alias finder) and llm_rosetta.shims.provider_shim. The deprecated converter alias packages CLAUDE.md still lists are already gone from the tree, so none is listed; - REMOVED: llm_rosetta.routing and llm_rosetta.capabilities, the two v0.13.0 flat modules this branch removes. Everything not listed is internal. The file is data only (no imports), so scripts/dev/public_api_diff.py loads it by path without importing llm_rosetta. The script's PUBLIC_MODULES is now USER + EXTENSION + COMPAT plus its own gateway list, and it also compares the REMOVED tier, so a removal stays visible: dropping a module from the list can no longer hide its break. That makes four removals against v0.13.0 visible, each now acknowledged in public_api_allowlist.json with its reason: llm_rosetta.routing (3 names, moved to llm_rosetta.contracts.routing), llm_rosetta.capabilities (12 inferred names; D3 of #1657) and shims.provider_shim.resolve_base (the #919 P6 removal, seen once provider_shim joined the compared modules). Two older reasons that pointed at the removed facades now name the current homes. tests/test_tiers.py checks that every listed module imports, that every REMOVED module stays absent, that no module has two tiers, that every contracts module is in EXTENSION, that the table has no imports and that the script's list is built from it. tests/test_public_api.py pins the literal __all__ of contracts, contracts.shim, contracts.transform and contracts.auth; llm_rosetta.api stays at 62 names.
AGENTS.md (CLAUDE.md) rows that named moved or deleted paths now follow the tree (#1657): the shim-layer table (contracts/shim.py, auth.py, quota.py, transform.py; the registry stays in shims/provider_shim.py; the ModelShim class it named does not exist), the host-surface paragraphs (two prefixes, the contracts package, the tier table), the IR facade sentence, the core modules table (contracts/, _tiers.py, observability/ as the deprecated alias package; routing/, observability/usage/, transforms/ and capabilities/ removed) and the shim/transform escalation line. No other row changes.
This was referenced Nov 21, 2026
v0.13.0 shipped llm_rosetta/routing.py and llm_rosetta/capabilities.py as flat modules, so removing those import names broke released code. Both come back as deprecated forwarders until 0.15.0 (#1657, maintainer decision): - llm_rosetta.routing forwards its three 0.13.0 names (ProviderType, ResolvedRoute, Router) from llm_rosetta.contracts.routing; - llm_rosetta.capabilities forwards its twelve 0.13.0 names (ConversionContext, ProviderShim, ReasoningCapability, resolve_shim and the eight passes enforce_reasoning, strip_reasoning_for_non_reasoning, enforce_vision, enforce_custom_tools, get_custom_tool_names, restore_custom_tool_calls, unwrap_custom_tool_input, relocate_oversized_tool_descriptions) from contracts.shim, converters.base, shims.provider_shim and ir.passes. Each forwarder has a literal __all__ of exactly the 0.13.0 names, says in its docstring and a comment that it is a deprecated 0.13.0 path removed in 0.15.0 and names the replacement, and warns once on import with stacklevel=2 so the warning points at the importer. Both move from the REMOVED tier to COMPAT (REMOVED is now empty), and the 15 allowlist entries for their removal are dropped: public_api_diff against v0.13.0 is clean for both (only optional parameters were added). test_no_deprecation_bounds lists both as kept deprecations and kept shells. The gateway and shim boundary tests still refuse both paths, and a test checks that core does not import them; tests/test_compat_forwarders.py checks the warning, the names and that every name is the same object as its current home.
Both distributions move to 0.14.0.dev35. The gateway's dependency range (llm-rosetta>=0.14.0.dev0,<0.15) already admits it, and no test pins the version string.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Implements steps C1–C6 of #1657 (one home for the extension contracts, a tree that states each module's tier), extending the gateway rule of #1630 to shims. C7–C10 (external shim repos,
MIGRATE_HINT, docs worktrees, changelog) are not in this PR.What changes
llm_rosetta.contracts(C1):__init__holdsSURFACE_VERSION(moved fromapi;apire-exports the same object, still level 1),IR_VERSION = 1(defined inllm_rosetta.types.ir.version, decision D1) and the sidecar file and hook names the shim loader reads (pre_ir_transforms,post_ir_transforms,ir_transforms,response_body_transforms,model_list_transform,PROBES,EXCHANGE); the loader imports them instead of restating the strings.shims/auth_exchange.py→contracts/auth.py,shims/quota_probe.py→contracts/quota.py,routing/→contracts/routing.py,observability/usage/→contracts/usage/(subpackage; only its__init__names are public).git mv, so history follows.llm_rosetta.observabilityshipped in 0.13.0 and holds the alias finder, so the parent stays and its usage names resolve fromcontracts.usage.contracts.shim(C1/C6):ProviderShim,ConnectionConfig,ToolsConfig,ReasoningCapability,VendorManifest,QuotaDeclaration,BatchDeclaration,SoftErrorPattern,TYPE_PARAM_KEYS, the three literal types, andload_providers_from_dir(the plugin registration call; it delegates to the loader on call).shims/provider_shim.pykeeps the registry and re-exports the data classes as the same objects; its docstring says importing them from there is deprecated, removal in 0.15.0. There is noModelShimclass in the tree.contracts.transform(C2): the hook types (Transform,IRTransform,TransformContext,NamedTransform,NamedIRTransform),apply_transforms/apply_ir_transforms, and every body and IR primitive the removed facade exported._NamedTransform/_NamedIRTransformare renamed at their definitions; no shim imports a private name.llm_rosetta.transformsandllm_rosetta.capabilitiesare gone; core readsllm_rosetta.ir, shims and tests readcontracts.transform, the gateway test readsapi.import llm_rosetta.tests/test_contracts_partial_init.pyinstalls a real entry point (.dist-info) for a fixture plugin whose entry point and sidecars import every contract module, and checks in a fresh interpreter that its shim registers. The entry-point failure warning now names the exception class and says the shims are not registered.llm_rosetta/_tiers.py(data only) lists USER, EXTENSION, COMPAT and REMOVED modules;public_api_diff.pybuilds its corePUBLIC_MODULESfrom it and keeps comparing the REMOVED tier, so a removal cannot be hidden by dropping it from the list.tests/test_tiers.pychecks every listed module imports and every removed one stays absent.llm_rosetta.apiandllm_rosetta.contracts(contracts.usagepackage-only)._TESTS_PRIVATE_ALLOWLISTunchanged.tests/test_shim_sidecar_boundary.py— every.pyundershims/providers/<vendor>/, the scaffold templates and the scaffolder's output import core only viallm_rosetta.contracts…(notapi: it cannot load while sidecars run). Theopenai_chatgpt→openai.quota.PROBESimport is replaced by a copy of the Codex probe (vendor-specific, so not acontractshelper); a test keeps the two copies AST-identical.Compat for the two 0.13.0 flat modules
v0.13.0 had two flat modules with the same import names as removed packages:
llm_rosetta/routing.pyandllm_rosetta/capabilities.py. By maintainer decision both come back as one-minor forwarders (removed in 0.15.0):llm_rosetta.routingforwardsProviderType,ResolvedRoute,Routerfromcontracts.routing;llm_rosetta.capabilitiesforwards its twelve 0.13.0 names fromcontracts.shim,converters.base,shims.provider_shimandir.passes. Each warns once on import (stacklevel points at the importer) and has a literal__all__of exactly the 0.13.0 names. Both are in the COMPAT tier; the gateway and shim boundary tests still refuse them. The only new allowlist entry isshims.provider_shim.resolve_base(the #919 P6 removal, newly visible becauseprovider_shimjoined the compared modules).The branch also bumps both distributions to
0.14.0.dev35(the gateway'sllm-rosetta>=0.14.0.dev0,<0.15range already admits it). No tag, no release.Verification
make lint: passes.pytest tests/ --ignore=tests/integration, final branch, local): 11311 passed, 83 skipped, 2 failed. Both failures (test_retired_config_location,test_usage_cli, which assert noTracebackon stderr) come from the externalllm-rosetta-shim-opendesignplugin installed in the local env, which still importsllm_rosetta.shims.auth_exchangeuntil C7; CI does not install it. An earlier buttercup run (rtest, no plugin) had 8 failures, all in filesrtestdoes not sync or tests that need a non-root user; those pass locally.python scripts/dev/public_api_diff.py(v0.13.0 → this branch): exit 0, 0 unacknowledged breaking changes, 45 acknowledged (44 before this branch +provider_shim.resolve_base);llm_rosetta.routingandllm_rosetta.capabilitiesdiff clean (only optional parameters added).llm_rosetta.apiand when a contract module imports__version__; the sidecar boundary test fails with the oldopenai_chatgpt/quota.py.Related: #1657, #1630. The four external shim repos switch in C7 (draft PRs tested against this branch).
AI disclosure: implemented with Claude Code (Claude) under the maintainer's direction; reviewed by the author before merge.