"""Versioned token-calibration factors for the reporting layer.

Rows stay RAW: they carry char-based token estimates exactly as measured.

Converting raw char counts into calibrated token estimates is a reporting

concern, and every converted number must cite the calibration version and

method it came from so two reports can never silently disagree about what

"tokens" means.

Factors live in config/token_calibration.json, written by

scripts/token_calibration_campaign.py. The committed file is an honest

uncalibrated placeholder (n=0, null CIs) using documented heuristic

constants: ~4.0 chars/token for prose-like output, ~3.2 for diff-like

output, which BPE-family tokenizers split more finely.

Null means unmeasured (ADR-0002): an unknown style or a style whose factor

is null yields None — never a silent default factor. Optional enhancers

(tiktoken, the Anthropic count-tokens API) are feature-detected and never

required (ADR-0001).

"""

from __future__ import annotations

import importlib.util

import json

import os

from pathlib import Path

from typing import Any, Optional

SCHEMA_VERSION = 1

DEFAULT_CALIBRATION_PATH = Path(__file__).resolve().parents[2] / "config" / "token_calibration.json"

def load_calibration(path: Path | str = DEFAULT_CALIBRATION_PATH) -> dict[str, Any]:

    """Load and validate a calibration factors file.

    Raises ValueError with a clear message on a missing/foreign

    schema_version so a stale or future-format file fails loudly instead of

    mispricing every report.

    """

    data = json.loads(Path(path).read_text())

    if not isinstance(data, dict):

        raise ValueError(f"calibration file {path}: expected a JSON object, got {type(data).__name__}")

    schema_version = data.get("schema_version")

    if schema_version != SCHEMA_VERSION:

        raise ValueError(

            f"calibration file {path}: unsupported schema_version {schema_version!r}; "

            f"this harness understands schema_version {SCHEMA_VERSION}"

        )

    if not isinstance(data.get("factors"), dict):

        raise ValueError(f"calibration file {path}: missing 'factors' object")

    if not isinstance(data.get("calibration_version"), str) or not data["calibration_version"]:

        raise ValueError(f"calibration file {path}: missing non-empty 'calibration_version'")

    return data

def calibrated_tokens(

    char_count: Optional[float], style: str, calibration: dict[str, Any]

) -> Optional[dict[str, Any]]:

    """Convert a raw char count to a calibrated token estimate, citing its source.

    Returns None when char_count is None, the style has no factor entry, or

    the style's factor is null — unmeasured stays unmeasured (ADR-0002);

    there is no silent default factor.

    """

    if char_count is None:

        return None

    factors = calibration.get("factors")

    if not isinstance(factors, dict):

        return None

    entry = factors.get(style)

    if not isinstance(entry, dict):

        return None

    chars_per_token = entry.get("chars_per_token")

    if not isinstance(chars_per_token, (int, float)) or isinstance(chars_per_token, bool) or chars_per_token <= 0:

        return None

    return {

        "tokens_estimated": float(char_count) / float(chars_per_token),

        "calibration_version": str(calibration.get("calibration_version")),

        "method": str(calibration.get("method")),

        "style": style,

    }

def available_token_counters() -> dict[str, bool]:

    """Feature-detect optional token counters without importing or calling them.

    tiktoken: importable module (never required, ADR-0001).

    anthropic_api: ANTHROPIC_API_KEY present in the environment — presence

    only; nothing here performs a network call.

    """

    return {

        "tiktoken": importlib.util.find_spec("tiktoken") is not None,

        "anthropic_api": bool(os.environ.get("ANTHROPIC_API_KEY")),

    }