models.py

Go to the documentation of this file.

#!/usr/bin/env python3
# -*- coding: utf-8 -*-
# providers/deepseek/models.py
 
"""
DeepSeek model registry — typed.
 
Purpose
-------
:data:`MODELS` is the canonical, single-source-of-truth registry of
DeepSeek models with their capabilities. It is consumed by
:meth:`DeepSeekProvider.models` and through that by
:class:`oc_chat.core.models.ModelManager`.
 
:data:`TIER_MAP` records the semantic-tier → model-id mapping that
:meth:`DeepSeekProvider.tier` returns. ``step_routing.py`` reads
from this via ``provider.tier("cheap")`` /
``provider.tier("reasoning")`` to choose the per-iteration model.
 
Responsibilities
----------------
- :data:`MODELS` — typed ``dict[str, ModelCaps]`` covering the only two
  selectable DeepSeek models, ``deepseek-v4-pro`` and ``deepseek-v4-flash``
  (in menu order). ``deepseek-v3`` / ``deepseek-coder`` / ``deepseek-chat`` /
  ``deepseek-reasoner`` are retired aliases that migrate on load.
- :data:`TIER_MAP` — semantic-tier to model-id lookup
  (``default`` / ``cheap`` / ``reasoning`` / ``summary``).
- :data:`RETIRED_ALIASES` — retired model id → replacement id, used to
  filter live discovery and to migrate saved sessions deterministically
  (plan 135 §4.6): ``deepseek-chat`` → ``deepseek-v4-flash`` (keeps the
  cheap/non-thinking-default character), ``deepseek-reasoner`` →
  ``deepseek-v4-pro`` (keeps the thinking/reasoning character). The
  TUI-polish pass further retires the legacy non-V4 ids so only the two
  V4 models are selectable: ``deepseek-v3`` → ``deepseek-v4-flash`` (cheap,
  non-thinking) and ``deepseek-coder`` → ``deepseek-v4-pro`` (the V4 set is
  the coding-capable line now).
 
Diagnostics
-----------
Domain: OC_CHAT.CLIENT
Levels:
    L2 — lifecycle events
    L3 — semantic details
    L4 — deep tracing
 
Contracts
---------
- ``MODELS`` keys are exact DeepSeek API model ids — never aliases.
- Capability flags are immutable: edit this file to update a model's
  capabilities; do not mutate the dataclass at runtime.
- ``TIER_MAP`` values must always reference keys in ``MODELS``.
- ``RETIRED_ALIASES`` keys are NOT in ``MODELS`` (they are retired); each
  value MUST be a key in ``MODELS``. Migration is deterministic per alias
  — never collapse both aliases to one shared target.
 
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)
 
 
# Canonical typed registry for all DeepSeek models. Edit here to add /
# adjust capabilities; nothing in ``oc_chat/core/`` mirrors this anymore.
MODELS: dict[str, ModelCaps] = {
    "deepseek-v4-pro":   ModelCaps(supports_thinking=True,  supports_reasoning=True,  supports_tools=True,  max_context_tokens=1_000_000, max_output_tokens=384_000, reasoning_state="text", cache_strategy="automatic"),
    "deepseek-v4-flash": ModelCaps(supports_thinking=False, supports_reasoning=False, supports_tools=True,  max_context_tokens=1_000_000, max_output_tokens=384_000, cache_strategy="automatic"),
}
 
 
# Semantic tier map — DeepSeek's answer to "give me your cheap/reasoning model".
# Other providers will define their own; the rest of the app talks only via
# ``provider.tier(name)``. ``default`` is the reasoning tier (plan 135 §4.6,
# operator-confirmed): a deliberate capability↑/cost↑/latency↑ change from the
# old ``deepseek-chat`` default.
TIER_MAP: dict[str, str] = {
    "default":   "deepseek-v4-pro",
    "cheap":     "deepseek-v4-flash",
    "reasoning": "deepseek-v4-pro",
    "summary":   "deepseek-v4-flash",
}
 
 
# Retired model ids → replacement id (plan 135 §4.6). Deterministic per alias;
# used both to filter live discovery and to migrate saved sessions on load.
RETIRED_ALIASES: dict[str, str] = {
    "deepseek-chat":     "deepseek-v4-flash",
    "deepseek-reasoner": "deepseek-v4-pro",
    "deepseek-v3":       "deepseek-v4-flash",
    "deepseek-coder":    "deepseek-v4-pro",
}
 
 
__all__ = ["MODELS", "TIER_MAP", "RETIRED_ALIASES"]