config.py

Go to the documentation of this file.

#!/usr/bin/env python3
# -*- coding: utf-8 -*-
# oc_chat/core/config.py
 
# OCT-LINT: disable=no_hardcoded_secrets reason="Docstring title triggers Shannon entropy false positive"
"""
Shared runtime configuration for OC Chat.
 
Purpose
-------
Provider-specific settings (DeepSeek's API key env var, base URL,
model registry, default model, summariser-tier model) used to live
here but moved into ``providers/deepseek/`` during Phase C. This
module now holds only neutral concerns: context-compression
heuristics, ANSI styles, ReAct caps, the ``OC_CHAT_*`` env vars, and
shared default fallbacks.
 
Responsibilities
----------------
- Read environment overrides (``OC_CHAT_CONTEXT_FILE``,
  ``OC_CHAT_PROVIDER``, ``NO_COLOR``) at import time via
  ``python-dotenv`` if available.
- Export the canonical defaults: ``DEFAULT_MAX_REACT_ITERATIONS``,
  ``CONTEXT_COMPRESS_THRESHOLD``, ``CONTEXT_KEEP_RECENT_TURNS``,
  ``REASONING_EFFORT_LEVELS``, ``TOKEN_PROFILES``,
  ``MODEL_MAX_TOKENS``.
- :func:`get_max_context_tokens` — provider-aware lookup with fallback
  to ``MODEL_MAX_TOKENS``.
 
Diagnostics
-----------
Domain: OC_CHAT.MAIN
Levels:
    L2 — lifecycle events
    L3 — semantic details
    L4 — deep tracing
 
Contracts
---------
- All values are module-level constants resolved at import time.
- Missing env vars fall back to the documented defaults; never raise.
- ``python-dotenv`` is an optional dependency; absence is silently
  tolerated.
 
Dependencies
------------
- oc_diagnostics (structured debug logging via _dbg)
- oc_chat._env_guard (load_dotenv_guarded - loads .env at import, refusing the security-authority vars)
- oc_chat.core.defaults (default, ceiling, shipped - the shipped defaults and the lower-only output ceiling)
- oc_chat.core.provider_plugin (lazy; registry - the active provider's model context windows)
"""
import os
 
from oc_diagnostics import _dbg
 
# M8.0 (F33/F72): a workspace .env may NOT set security-authority vars
# (profile, provider *_BASE_URL, allow-remote, proxy/cert, package-index).
from oc_chat._env_guard import load_dotenv_guarded
load_dotenv_guarded()
 
# CONFIG-01 (plan 238): every default and ceiling below is bound at import from
# the shipped, read-only ``oc_chat.defaults.toml``. The names stay; the values
# live in a file the agent filesystem tools are hard-denied from writing.
from oc_chat.core.defaults import ceiling, default, shipped
 
_dbg("OC_CHAT.MAIN", "module", "loaded", 4)
 
# File auto-ingested into the system prompt on new sessions ("" disables).
OC_CHAT_CONTEXT_FILE = os.getenv("OC_CHAT_CONTEXT_FILE", "AGENT_CONTEXT.md")
 
DEFAULT_REASONING_EFFORT = default("reasoning_effort")
REASONING_EFFORT_LEVELS = ["low", "medium", "high"]
 
# Context window compression settings
CONTEXT_COMPRESS_THRESHOLD = default("context_compress_threshold")  # fraction of model max
MODEL_MAX_TOKENS = default("model_max_tokens")   # fallback for unknown models / no provider
# Default context-window token cap used by ``cli.py`` when the operator does
# not pass ``--max-context-size``. Mirrored UI-side by the constant of the same
# name in ``oc_ui.terminal.stats`` (the enhanced meter's fallback) so the two
# agree. Relocated here from the former ``oc_chat.core.stats`` by plan 153,
# which moved the UI-owned StatisticsTracker to ``oc_ui.terminal.stats``.
DEFAULT_CONTEXT_WINDOW_SIZE = default("context_window_size")
CONTEXT_KEEP_RECENT = default("context_keep_recent")  # legacy message-count hint
# Phase 3: keep last N user-rooted conversation turns verbatim; older turns are summarised.
CONTEXT_KEEP_RECENT_TURNS = default("context_keep_recent_turns")
 
# ReAct loop — default max iterations (override per session via ``/react``).
DEFAULT_MAX_REACT_ITERATIONS = default("max_react_iterations")
 
# Token profile for completion caps (``/budget``) — ``balanced`` is baseline.
TOKEN_PROFILES = ("cheap", "balanced", "deep")
 
# ── Completion (output) token budget ──────────────────────────────────────────
# The per-iteration ``max_tokens`` sent to the provider. It bounds reasoning
# AND answer together on a thinking model, so a value sized for the answer
# alone lets the model burn the whole budget on chain-of-thought and stop
# before writing a word — see the reasoning-only path in ``react_loop``.
#
#: Operator ceiling on any single completion. Providers may declare far more
#: (DeepSeek v4 declares 384_000); this bounds one runaway reply without
#: bounding the model's ability to finish an ordinary one. Raising it above
#: this default is a code edit on purpose: the settings file is a
#: model-reachable write surface and may only LOWER the ceiling, never raise
#: it — the same non-self-raising invariant ``resource_caps`` applies to the
#: per-turn tool-call cap. Since plan 238 that invariant has ONE implementation,
#: :func:`oc_chat.core.defaults.ceiling`, and raising this value is an edit to
#: the shipped, write-denied defaults file rather than to this module.
OUTPUT_TOKENS_CEILING = shipped("output_tokens")
 
#: Used when a provider declares no ``max_output_tokens``. ``ModelCaps``
#: defaults the field to 0 meaning "undeclared" (Ollama's table declares none),
#: and 0 must never reach the wire as a cap. Deliberately conservative:
#: guessing a local model's real ceiling high risks provider-side rejection.
UNDECLARED_OUTPUT_TOKENS = default("undeclared_output_tokens")
 
 
def get_output_tokens_ceiling() -> int:
    """Return the effective completion ceiling.
 
    :data:`OUTPUT_TOKENS_CEILING` unless the workspace settings file specifies
    a smaller ``max_output_tokens``. A settings value at or above the code
    default is ignored, so a model that talks a human into a settings write
    cannot widen its own output budget. Degrades to the code default when
    settings are unavailable or unparseable — the generalised lower-only rule in
    :func:`oc_chat.core.defaults.ceiling` (plan 238), unchanged in behaviour.
    """
    return ceiling("output_tokens")
 
# ── ANSI styles ───────────────────────────────────────────────────────────────
# Honour the standard NO_COLOR (https://no-color.org) and FORCE_COLOR
# environment variables.  Precedence: FORCE_COLOR wins over NO_COLOR if both
# are set, matching the convention used by chalk / clicolors / rich.
#
# When colour is disabled, every STYLE_* constant is the empty string — the
# presenter still emits them, but they're invisible.  This keeps the format
# strings untouched.
 
def _color_enabled() -> bool:
    """Return True iff ANSI styles should be emitted."""
    if os.getenv("FORCE_COLOR"):
        return True
    if os.getenv("NO_COLOR") is not None:
        return False
    return True
 
 
_COLOR = _color_enabled()
 
STYLE_RESET  = "\033[0m"  if _COLOR else ""
STYLE_DIM    = "\033[2m"  if _COLOR else ""
STYLE_ITALIC = "\033[3m"  if _COLOR else ""
STYLE_BOLD   = "\033[1m"  if _COLOR else ""
STYLE_CYAN   = "\033[36m" if _COLOR else ""
STYLE_YELLOW = "\033[33m" if _COLOR else ""
STYLE_GREEN  = "\033[32m" if _COLOR else ""
STYLE_RED    = "\033[31m" if _COLOR else ""
 
 
def get_max_context_tokens(model_name: str) -> int:
    """Return the max context window tokens for *model_name*.
 
    Looks up the active provider's curated model registry. Falls back to
    :data:`MODEL_MAX_TOKENS` for unknown models or when no provider is
    registered yet (rare — only happens in early test setup).
    """
    func = "get_max_context_tokens"
    from oc_chat.core.provider_plugin import registry
 
    provider_name = os.environ.get("OC_CHAT_PROVIDER", "deepseek")
    try:
        caps = registry.get(provider_name).models().get(model_name)
        if caps is not None:
            return caps.max_context_tokens
    except (KeyError, AttributeError) as e:
        # VALIDATION_ERROR — provider not yet registered (early test setup), expected
        _dbg("OC_CHAT.MAIN", func, f"VALIDATION_ERROR: {type(e).__name__}: {e}", 3)
    return MODEL_MAX_TOKENS