Skip to content

Shims API

Provider Shim

llm_rosetta.shims.provider_shim.ProviderShim dataclass 

ProviderShim(**kwargs: Any)

Provider identity card with optional transforms.

Attributes:

Name Type Description
name str

Canonical provider identifier (e.g. "deepseek").
base str

API standard this provider follows. Must be one of the converter type strings ("openai_chat", "anthropic", "google", "openai_responses").
default_base_url str | None

Default upstream base URL. Used by the gateway when the provider config does not specify base_url.
default_api_key_env str | None

Default environment variable name for the API key (e.g. "DEEPSEEK_API_KEY").
logo str | None

URL to the provider's logo image (SVG preferred).
model_id_field str | None

JSON field name to use as model identifier when fetching the upstream model list. Defaults to "id" when None. Useful for providers like Argo that place the actual model identifier in a non-standard field.
pre_ir_transforms tuple[Transform, ...]

Body-level transforms applied BEFORE IR conversion (normalise provider dialect → standard). Aliased as from_transforms for backward compatibility.
post_ir_transforms tuple[Transform, ...]

Body-level transforms applied AFTER IR conversion (standard → provider dialect). Aliased as to_transforms for backward compatibility.
reasoning ReasoningCapability | None

Reasoning capability config for this provider. When None, the converter uses its built-in default.
model_reasoning dict[str, ReasoningCapability] | None

Per-model reasoning overrides keyed by upstream model ID (post-alias). Each entry inherits from the provider-level reasoning for unset fields.

Accept both new and legacy kwarg names.

Legacy from_transforms maps to pre_ir_transforms; to_transforms maps to post_ir_transforms. New names take precedence if both are provided.

Source code in src/llm_rosetta/shims/provider_shim.py 
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
def __init__(self, **kwargs: Any) -> None:  # type: ignore[override]
    """Accept both new and legacy kwarg names.

    Legacy ``from_transforms`` maps to ``pre_ir_transforms``;
    ``to_transforms`` maps to ``post_ir_transforms``.
    New names take precedence if both are provided.
    """
    # Map legacy names → new names (new names take precedence)
    if "from_transforms" in kwargs:
        warnings.warn(
            "ProviderShim(from_transforms=...) is deprecated, "
            "use pre_ir_transforms instead",
            DeprecationWarning,
            stacklevel=2,
        )
        if "pre_ir_transforms" not in kwargs:
            kwargs["pre_ir_transforms"] = kwargs.pop("from_transforms")
        else:
            kwargs.pop("from_transforms")
    if "to_transforms" in kwargs:
        warnings.warn(
            "ProviderShim(to_transforms=...) is deprecated, "
            "use post_ir_transforms instead",
            DeprecationWarning,
            stacklevel=2,
        )
        if "post_ir_transforms" not in kwargs:
            kwargs["post_ir_transforms"] = kwargs.pop("to_transforms")
        else:
            kwargs.pop("to_transforms")

    # Apply defaults for fields not in kwargs.
    # Keep in sync with dataclass field defaults above.
    _FIELD_DEFAULTS = {
        "default_base_url": None,
        "default_api_key_env": None,
        "logo": None,
        "model_id_field": None,
        "pre_ir_transforms": (),
        "post_ir_transforms": (),
        "ir_transforms": (),
        "reasoning": None,
        "model_reasoning": None,
    }
    _VALID_FIELDS = {"name", "base"} | _FIELD_DEFAULTS.keys()
    for k, v in _FIELD_DEFAULTS.items():
        kwargs.setdefault(k, v)

    # Reject unknown kwargs (match frozen dataclass behavior)
    unknown = set(kwargs) - _VALID_FIELDS
    if unknown:
        raise TypeError(
            f"ProviderShim.__init__() got unexpected keyword argument(s): "
            f"{', '.join(sorted(unknown))}"
        )

    for k, v in kwargs.items():
        object.__setattr__(self, k, v)

from_transforms property 

from_transforms: tuple[Transform, ...]

Alias for pre_ir_transforms (deprecated).

to_transforms property 

to_transforms: tuple[Transform, ...]

Alias for post_ir_transforms (deprecated).

llm_rosetta.shims.provider_shim.register_shim 

register_shim(shim: ProviderShim) -> None

Register (or replace) a :class:ProviderShim in the global registry.

If a shim with the same name is already registered, it is silently replaced and an INFO-level log is emitted. This allows plugin shims to override built-in defaults without raising errors.

Source code in src/llm_rosetta/shims/provider_shim.py 
222
223
224
225
226
227
228
229
230
231
def register_shim(shim: ProviderShim) -> None:
    """Register (or replace) a :class:`ProviderShim` in the global registry.

    If a shim with the same name is already registered, it is silently
    replaced and an INFO-level log is emitted.  This allows plugin shims
    to override built-in defaults without raising errors.
    """
    if shim.name in _SHIM_REGISTRY:
        logger.info("Shim %r overridden (base: %s)", shim.name, shim.base)
    _SHIM_REGISTRY[shim.name] = shim

llm_rosetta.shims.provider_shim.unregister_shim 

unregister_shim(name: str) -> ProviderShim | None

Remove and return a shim by name. Returns None if not found.

Source code in src/llm_rosetta/shims/provider_shim.py 
234
235
236
def unregister_shim(name: str) -> ProviderShim | None:
    """Remove and return a shim by name.  Returns ``None`` if not found."""
    return _SHIM_REGISTRY.pop(name, None)

llm_rosetta.shims.provider_shim.get_shim 

get_shim(name: str) -> ProviderShim | None

Look up a registered :class:ProviderShim by name.

Source code in src/llm_rosetta/shims/provider_shim.py 
239
240
241
def get_shim(name: str) -> ProviderShim | None:
    """Look up a registered :class:`ProviderShim` by *name*."""
    return _SHIM_REGISTRY.get(name)

llm_rosetta.shims.provider_shim.list_shims 

list_shims() -> list[ProviderShim]

Return all registered provider shims.

Source code in src/llm_rosetta/shims/provider_shim.py 
257
258
259
def list_shims() -> list[ProviderShim]:
    """Return all registered provider shims."""
    return list(_SHIM_REGISTRY.values())

llm_rosetta.shims.provider_shim.resolve_base 

resolve_base(name: str) -> str

Resolve a provider/shim name to its base converter type.

If name is already a known base type (e.g. "openai_chat"), it is returned unchanged. Otherwise the shim registry is consulted. If the name is not found in either, it is returned as-is (caller decides how to handle unknown names).

Source code in src/llm_rosetta/shims/provider_shim.py 
262
263
264
265
266
267
268
269
270
271
272
273
274
275
def resolve_base(name: str) -> str:
    """Resolve a provider/shim *name* to its base converter type.

    If *name* is already a known base type (e.g. ``"openai_chat"``),
    it is returned unchanged.  Otherwise the shim registry is consulted.
    If the name is not found in either, it is returned as-is (caller
    decides how to handle unknown names).
    """
    if name in _BASE_TYPES:
        return name
    shim = _SHIM_REGISTRY.get(name)
    if shim is not None:
        return shim.base
    return name

Transforms

llm_rosetta.shims.transforms.Transform module-attribute 

Transform = Callable[[dict[str, Any]], dict[str, Any]]

A pure data transformation: receives a provider body dict and returns a (possibly mutated) body dict.

llm_rosetta.shims.transforms.apply_transforms 

apply_transforms(transforms: tuple[Transform, ...], body: dict[str, Any]) -> dict[str, Any]

Apply transforms sequentially to body, returning the result.

Source code in src/llm_rosetta/shims/transforms.py 
196
197
198
199
200
201
202
def apply_transforms(
    transforms: tuple[Transform, ...], body: dict[str, Any]
) -> dict[str, Any]:
    """Apply *transforms* sequentially to *body*, returning the result."""
    for t in transforms:
        body = t(body)
    return body

llm_rosetta.shims.transforms.strip_fields 

strip_fields(*keys: str) -> Transform

Return a transform that removes keys from the body.

No-op for keys that do not exist (idempotent).

Source code in src/llm_rosetta/shims/transforms.py 
56
57
58
59
60
61
62
63
64
65
66
67
def strip_fields(*keys: str) -> Transform:
    """Return a transform that removes *keys* from the body.

    No-op for keys that do not exist (idempotent).
    """

    def _strip(body: dict[str, Any]) -> dict[str, Any]:
        for k in keys:
            body.pop(k, None)
        return body

    return _NamedTransform(_strip, f"strip_fields({', '.join(repr(k) for k in keys)})")

llm_rosetta.shims.transforms.rename_field 

rename_field(old: str, new: str) -> Transform

Return a transform that renames a top-level field.

No-op if old does not exist (idempotent).

Source code in src/llm_rosetta/shims/transforms.py 
70
71
72
73
74
75
76
77
78
79
80
81
def rename_field(old: str, new: str) -> Transform:
    """Return a transform that renames a top-level field.

    No-op if *old* does not exist (idempotent).
    """

    def _rename(body: dict[str, Any]) -> dict[str, Any]:
        if old in body:
            body[new] = body.pop(old)
        return body

    return _NamedTransform(_rename, f"rename_field({old!r}, {new!r})")

llm_rosetta.shims.transforms.set_defaults 

set_defaults(**defaults: Any) -> Transform

Return a transform that sets fields only when they are absent.

Idempotent: existing values are never overwritten.

Source code in src/llm_rosetta/shims/transforms.py 
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
def set_defaults(**defaults: Any) -> Transform:
    """Return a transform that sets fields only when they are absent.

    Idempotent: existing values are never overwritten.
    """

    def _defaults(body: dict[str, Any]) -> dict[str, Any]:
        for k, v in defaults.items():
            body.setdefault(k, v)
        return body

    return _NamedTransform(
        _defaults,
        f"set_defaults({', '.join(f'{k}={v!r}' for k, v in defaults.items())})",
    )