models.py

Go to the documentation of this file.

#!/usr/bin/env python3
# -*- coding: utf-8 -*-
# providers/example/models.py
 
"""
Example provider model registry — typed.
 
Purpose
-------
:data:`MODELS` is the canonical, single-source-of-truth registry of
example "models" with their capabilities. Each entry is a fake; the
:class:`ExampleClient` does not actually call any of them.
 
:data:`TIER_MAP` records the semantic-tier → model-id mapping that
:meth:`ExampleProvider.tier` returns. ``step_routing.py`` reads it
via ``provider.tier("cheap")`` / ``provider.tier("reasoning")``.
 
When copying this bundle for a real provider, replace the entries
here with the provider's actual models and add any additional
capability flags the provider needs.
 
Responsibilities
----------------
- :data:`MODELS` — minimal ``dict[str, ModelCaps]`` with two
  entries: ``example-echo`` (no thinking) and ``example-reasoning``
  (thinking enabled).
- :data:`TIER_MAP` — semantic-tier lookup for the four tiers
  ``default`` / ``cheap`` / ``reasoning`` / ``summary``.
 
Diagnostics
-----------
Domain: OC_CHAT.CLIENT
Levels:
    L2 — lifecycle events
    L3 — semantic details
    L4 — deep tracing
 
Contracts
---------
- ``MODELS`` keys are arbitrary stub names (no API equivalence).
- ``TIER_MAP`` values must reference keys in ``MODELS``.
- The dataclass is immutable; capability changes mean editing this
  file rather than mutating at runtime.
 
Dependencies
------------
- oc_diagnostics (structured debug logging via _dbg)
- option_c_agent_contracts (ModelCaps capability record for each model)
"""
from __future__ import annotations
 
from oc_diagnostics import _dbg
 
from option_c_agent_contracts import ModelCaps
 
_dbg("OC_CHAT.CLIENT", "module", "loaded", 4)
 
 
MODELS: dict[str, ModelCaps] = {
    "example-echo":      ModelCaps(supports_thinking=False, supports_reasoning=False, supports_tools=True,  max_context_tokens=4096),
    "example-reasoning": ModelCaps(supports_thinking=True,  supports_reasoning=True,  supports_tools=True,  max_context_tokens=4096),
}
 
 
TIER_MAP: dict[str, str] = {
    "default":   "example-echo",
    "cheap":     "example-echo",
    "reasoning": "example-reasoning",
    "summary":   "example-echo",
}
 
 
__all__ = ["MODELS", "TIER_MAP"]