session_models.py

Go to the documentation of this file.

#!/usr/bin/env python3
# -*- coding: utf-8 -*-
# oc_chat/core/session_models.py
 
"""
Pydantic models for the two JSON-sidecar files of a session.
 
Purpose
-------
The session-meta.json and chat-log.json files have grown organically
over the project's lifetime. Until now they were typed only as raw
``dict`` at the persistence boundary, so corrupt or unexpected
payloads (a missing required key, a type mismatch from an external
edit, an old format from a pre-Phase J session) propagated all the
way into the runtime as silent ``KeyError``s or ``AttributeError``s.
 
This module gives those JSON shapes a validated home: every key has
a declared type and a sensible default. ``extra="allow"`` keeps
forward-compat with future keys we have not yet enumerated.
 
Responsibilities
----------------
- :class:`SessionMetadata` — mirror of the dict returned by
  :func:`oc_chat.core.persistence.load_session_metadata`.
- :class:`ChatLog` — mirror of the dict returned by
  :func:`oc_chat.core.persistence.load_chat_log`.
- :class:`UsageBlock` — sub-model for the chat-log ``usage`` block.
 
Diagnostics
-----------
Domain: OC_CHAT.CTX
Levels:
    L2 — validation failures (logged and surfaced as ValidationError)
    L3 — model construction details
    L4 — deep tracing (per-field validation, if ever enabled)
 
Contracts
---------
- Every model is forgiving: all fields have defaults, so an old file
  with missing keys validates cleanly with the defaults applied.
- ``extra="allow"`` means unknown keys are kept on the model (and
  round-tripped through ``model_dump()``) — newer formats never lose
  data when read by older code.
- ``ValidationError`` is only raised on hard type mismatches (e.g.
  a list where a string is expected). Callers should catch it at the
  JSON-load boundary.
 
Dependencies
------------
- oc_diagnostics (structured debug logging via _dbg)
- pydantic (BaseModel, Field, ConfigDict and field_validator, version 2 or later)
- oc_chat.core.event_bootstrap (lazy; _valid_alias to validate the legacy event slugs)
"""
from __future__ import annotations
 
from typing import Any
 
from oc_diagnostics import _dbg
from pydantic import BaseModel, ConfigDict, Field, field_validator
 
_dbg("OC_CHAT.CTX", "module", "loaded", 4)
 
 
class UsageBlock(BaseModel):
    """Per-session aggregated usage counters embedded in the chat log."""
 
    model_config = ConfigDict(extra="allow")
 
    prompt_tokens: int = 0
    completion_tokens: int = 0
    total_tokens: int = 0
    prompt_cache_hit_tokens: int = 0
    prompt_cache_miss_tokens: int = 0
 
 
class SessionMetadata(BaseModel):
    """Validated mirror of the ``*_meta.json`` sidecar."""
 
    model_config = ConfigDict(extra="allow")
 
    session_name: str = ""
    created: str = ""
    last_modified: str = ""
    model: str = ""
    reasoning_effort: str = ""
    system_prompt: str = ""
    stats: dict[str, Any] = Field(default_factory=dict)
    chat_logs: list[str] = Field(default_factory=list)
    ui: dict[str, Any] = Field(default_factory=dict)
    last_turn_max_prompt_tokens: int = 0
    rollover_hint_shown: bool = False
    # OCT-LINT: disable=no_hardcoded_secrets reason="Metadata field defaults and names, not secrets"
    token_profile: str = "balanced"
    max_react_iterations: int | None = None
    cache_turn_snapshots: list[Any] = Field(default_factory=list)
    active_plan_id: str | None = None
    provider_name: str = Field(default="")
    generation_options: dict = Field(default_factory=dict)
    endpoint_name: str = Field(default="")
    sandbox_root_override: str | None = None
 
    # ── Plan 152 D8 — event-dir rename continuity (additive keys) ───────────
    legacy_event_slugs: list[str] = Field(default_factory=list)
    # OCT-LINT: disable=no_hardcoded_secrets reason="Metadata field defaults and names, not secrets"
    """Ordered, validated, deduplicated name-slugs this session wrote events
    under before earlier renames.
 
    CONSTRAINED to the canonical ``event_bootstrap._slug`` grammar by
    :meth:`_validate_legacy_event_slugs` — these are persisted PATH SEGMENTS, so
    an unconstrained value would be untrusted path input.
 
    Declaring it here is necessary but NOT sufficient:
    ``load_session_metadata`` returns the RAW dict when model validation fails,
    so this contract is bypassable. Every consumer re-validates at use — see
    ``event_bootstrap.event_read_dirs`` and ``session._validated_event_slugs``.
    """
 
    superseded_by: str | None = None
    """Set on the OLD record when a rename supersedes it (never deleted).
 
    A rename writes both files under the NEW name while the old record stays on
    disk with the SAME ``session_id``. Marking the old one at rename-commit time
    makes it non-canonical by construction, so the current record can never lose
    its identity — or its event history — to its own stale snapshot by load
    order.
    """
 
    @field_validator("legacy_event_slugs", mode="before")
    @classmethod
    def _validate_legacy_event_slugs(cls, value: Any) -> list[str]:
        """Keep only canonical slugs, in order, deduplicated. Never raises.
 
        Fail-closed by dropping: an invalid alias is ignored rather than
        rejecting the whole record, because a single bad alias must not make a
        user's session unloadable.
        """
        if not isinstance(value, (list, tuple)):
            return []
        from oc_chat.core.event_bootstrap import _valid_alias
        out: list[str] = []
        for item in value:
            if _valid_alias(item) and item not in out:
                out.append(item)
        return out
 
 
class ChatLog(BaseModel):
    """Validated mirror of the ``*_chat_log.json`` sidecar."""
 
    model_config = ConfigDict(extra="allow")
 
    session_name: str = ""
    timestamp: str = ""
    model: str = ""
    reasoning_effort: str = ""
    messages: list[dict[str, Any]] = Field(default_factory=list)
    usage: UsageBlock = Field(default_factory=UsageBlock)
 
 
__all__ = [
    "ChatLog",
    "SessionMetadata",
    "UsageBlock",
]