Skip to content

refactor(contracts): one home for the extension contracts and a tier table (#1657 C1–C6) - #1659

Open
Oaklight wants to merge 12 commits into
masterfrom
refactor/contracts-home
Open

Oaklight wants to merge 12 commits into
masterfrom
refactor/contracts-home

Conversation

@Oaklight

@Oaklight Oaklight commented Nov 21, 2026 •

Copy link
Copy Markdown
Owner

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__ holds SURFACE_VERSION (moved from api; api re-exports the same object, still level 1), IR_VERSION = 1 (defined in llm_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.
  • Moves, no forwarders (C1): 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.observability shipped in 0.13.0 and holds the alias finder, so the parent stays and its usage names resolve from contracts.usage.
  • contracts.shim (C1/C6): ProviderShim, ConnectionConfig, ToolsConfig, ReasoningCapability, VendorManifest, QuotaDeclaration, BatchDeclaration, SoftErrorPattern, TYPE_PARAM_KEYS, the three literal types, and load_providers_from_dir (the plugin registration call; it delegates to the loader on call). shims/provider_shim.py keeps 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 no ModelShim class 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 / _NamedIRTransform are renamed at their definitions; no shim imports a private name.
  • Facades removed (D3): llm_rosetta.transforms and llm_rosetta.capabilities are gone; core reads llm_rosetta.ir, shims and tests read contracts.transform, the gateway test reads api.
  • Partial initialisation: plugin entry points run during import llm_rosetta. tests/test_contracts_partial_init.py installs 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.
  • Tier table (C3): llm_rosetta/_tiers.py (data only) lists USER, EXTENSION, COMPAT and REMOVED modules; public_api_diff.py builds its core PUBLIC_MODULES from it and keeps comparing the REMOVED tier, so a removal cannot be hidden by dropping it from the list. tests/test_tiers.py checks every listed module imports and every removed one stays absent.
  • Gateway boundary (C4): two prefixes, llm_rosetta.api and llm_rosetta.contracts (contracts.usage package-only). _TESTS_PRIVATE_ALLOWLIST unchanged.
  • Shim boundary (C5): tests/test_shim_sidecar_boundary.py — every .py under shims/providers/<vendor>/, the scaffold templates and the scaffolder's output import core only via llm_rosetta.contracts… (not api: it cannot load while sidecars run). The openai_chatgpt → openai.quota.PROBES import is replaced by a copy of the Codex probe (vendor-specific, so not a contracts helper); a test keeps the two copies AST-identical.
  • AGENTS.md rows that named moved paths follow the tree.

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.py and llm_rosetta/capabilities.py. By maintainer decision both come back as one-minor forwarders (removed in 0.15.0): llm_rosetta.routing forwards ProviderType, ResolvedRoute, Router from contracts.routing; llm_rosetta.capabilities forwards its twelve 0.13.0 names from contracts.shim, converters.base, shims.provider_shim and ir.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 is shims.provider_shim.resolve_base (the #919 P6 removal, newly visible because provider_shim joined the compared modules).

The branch also bumps both distributions to 0.14.0.dev35 (the gateway's llm-rosetta>=0.14.0.dev0,<0.15 range already admits it). No tag, no release.

Verification

  • make lint: passes.
  • Full suite (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 no Traceback on stderr) come from the external llm-rosetta-shim-opendesign plugin installed in the local env, which still imports llm_rosetta.shims.auth_exchange until C7; CI does not install it. An earlier buttercup run (rtest, no plugin) had 8 failures, all in files rtest does 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.routing and llm_rosetta.capabilities diff clean (only optional parameters added).
  • Mutation checks: the partial-init test fails when the plugin's entry point imports llm_rosetta.api and when a contract module imports __version__; the sidecar boundary test fails with the old openai_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.

… 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.
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.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant