__init__.py

Go to the documentation of this file.

#!/usr/bin/env python3
# -*- coding: utf-8 -*-
# providers/openai_compat/__init__.py
 
"""
Generic OpenAI-compatible provider bundle — many lanes, one implementation.
 
Purpose
-------
Importing this package validates the lane catalogue and registers ONE
provider instance per catalogue row into
``option_c_agent_contracts.registry``. After ``import
providers.openai_compat`` the registry holds the seven lane names
(``groq``, ``cerebras``, ``nvidia_nim``, ``openrouter``, ``bitdeer``,
``vercel``, ``cheaperinference``) alongside whatever else is registered,
and any of them can be selected with ``OC_CHAT_PROVIDER=<lane>``.
 
The lanes are the OpenAI-dialect subset of the set the OCON benchmark
harness proved end to end. DeepSeek keeps its own richer bundle; the
Anthropic and Gemini dialects are out of scope for this bundle.
 
Responsibilities
----------------
- Validate and self-register every catalogue row on import.
- Re-export the bundle's public surface.
 
Diagnostics
-----------
Domain: OC_CHAT.CLIENT
Levels:
    L2 — lifecycle events
    L3 — semantic details
    L4 — deep tracing
 
Contracts
---------
- Side effect on import: :func:`register_all` runs once. Repeated
  imports are idempotent (Python caches the module; the registry also
  treats a same-class same-name re-registration as a no-op).
- A catalogue row that fails validation raises :exc:`CatalogueError` HERE,
  at import, naming the row — the bundle never registers a partial set of
  lanes and never silently drops one (plan 215 P5).
- The bundle reads no API key and holds no credential; the catalogue
  carries env-var NAMES only (plan 215 P6).
 
Dependencies
------------
- oc_diagnostics (structured debug logging via _dbg)
- providers.openai_compat.catalogue (lane catalogue types, LANES and validation, re-exported)
- providers.openai_compat.client (OpenAICompatClient, re-exported)
- providers.openai_compat.provider (register_all run on import, and the re-exported provider surface)
- providers.openai_compat.usage (normalise_usage, re-exported)
"""
from oc_diagnostics import _dbg
 
from .catalogue import LANES, CatalogueError, Lane, LaneModel, lane_by_name, validate_catalogue
from .client import OpenAICompatClient
from .provider import OpenAICompatProvider, register_all, registered_lanes
from .usage import normalise_usage
 
# Self-register every lane on import (the Phase C.1c bundle contract).
register_all()
 
_dbg("OC_CHAT.CLIENT", "module", "loaded", 4)
 
__all__ = [
    "CatalogueError",
    "LANES",
    "Lane",
    "LaneModel",
    "OpenAICompatClient",
    "OpenAICompatProvider",
    "lane_by_name",
    "normalise_usage",
    "register_all",
    "registered_lanes",
    "validate_catalogue",
]