diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000000000000000000000000000000000000..0f1a6e75a05fa43c2b2005e4f81afd8188e0f15b --- /dev/null +++ b/.gitignore @@ -0,0 +1,7 @@ +# Build artifacts (regenerable from canonical sources). +build/ +__pycache__/ +*.pyc +*.pyo +.cache/ +*.log diff --git a/Dockerfile b/Dockerfile new file mode 100644 index 0000000000000000000000000000000000000000..28c179e8f20f9dedec7d3654cb4ccd612f216dc2 --- /dev/null +++ b/Dockerfile @@ -0,0 +1,64 @@ +# syntax=docker/dockerfile:1.6 +# Unified DriftCall Space — same base + deps as env Space, plus the +# pre-built frontend dist/ mounted at root. + +FROM python:3.11-slim AS builder +ENV PIP_NO_CACHE_DIR=1 \ + PIP_DISABLE_PIP_VERSION_CHECK=1 \ + PYTHONDONTWRITEBYTECODE=1 +WORKDIR /build +RUN apt-get update && apt-get install -y --no-install-recommends \ + build-essential git libsndfile1 ffmpeg \ + && rm -rf /var/lib/apt/lists/* + +COPY requirements.txt ./ +RUN pip install --prefix=/install -r requirements.txt + +# Pre-pull TTS / ASR weights so the runtime container can run offline. +RUN pip install --prefix=/install huggingface_hub +RUN PYTHONPATH=/install/lib/python3.11/site-packages \ + python -c "from huggingface_hub import snapshot_download; \ + snapshot_download('hexgrad/Kokoro-82M', cache_dir='/weights'); \ + snapshot_download('Systran/faster-whisper-small', cache_dir='/weights')" + +# -------- runtime -------- +FROM python:3.11-slim +ENV PYTHONUNBUFFERED=1 \ + PYTHONDONTWRITEBYTECODE=1 \ + HF_HOME=/root/.cache/huggingface \ + TRANSFORMERS_OFFLINE=1 \ + HF_HUB_OFFLINE=1 \ + WANDB_PROJECT=driftcall \ + WANDB_MODE=disabled + +RUN apt-get update && apt-get install -y --no-install-recommends \ + libsndfile1 ffmpeg ca-certificates \ + && rm -rf /var/lib/apt/lists/* + +COPY --from=builder /install /usr/local +COPY --from=builder /weights /root/.cache/huggingface + +WORKDIR /app + +# Application code (cells/ + app.py + openenv.yaml + data/) and the +# pre-built frontend dist/ (mounted at / by unified_app.py). +COPY cells/ ./cells/ +COPY data/ ./data/ +COPY app.py openenv.yaml unified_app.py ./ +COPY site/ ./site/ + +EXPOSE 7860 + +HEALTHCHECK --interval=30s --timeout=5s --start-period=45s \ + CMD python -c "import urllib.request; \ + urllib.request.urlopen('http://127.0.0.1:7860/healthz', timeout=4).read()" \ + || exit 1 + +# unified_app:app exposes both the OpenEnv routes (at root) and the +# static frontend (mounted at /). +CMD ["uvicorn", "unified_app:app", \ + "--host", "0.0.0.0", \ + "--port", "7860", \ + "--workers", "2", \ + "--timeout-keep-alive", "30", \ + "--log-level", "info"] diff --git a/README.md b/README.md index d884c7010b403d8849a0b9c2e79e9bf50e169907..2baa5b29152ef45eb46932e9e40e79a2a33da510 100644 --- a/README.md +++ b/README.md @@ -1,12 +1,84 @@ --- -title: Driftcall -emoji: 🐠 -colorFrom: yellow -colorTo: red -sdk: gradio -sdk_version: 6.13.0 -app_file: app.py -pinned: false +title: DriftCall +emoji: 🌀 +colorFrom: indigo +colorTo: pink +sdk: docker +pinned: true +license: apache-2.0 +short_description: OpenEnv env + site · canonical /reset · one Space +tags: + - openenv + - rl + - voice + - indic + - schema-drift + - grpo + - gemma-3n --- -Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference +# DriftCall — Unified Space + +One HF Space serving the OpenEnv-compliant DriftCall env **and** the +project site, both under the same hostname. OpenEnv routes are at the +canonical bare paths (no `/api` prefix), so the registry and the gym +client see this Space exactly as it sees the dedicated env Space. + +## URL surface + +| Path | Method | What it does | +|------------------|----------|--------------| +| `/` | `GET` | static project site (Vite-built React + pretext) | +| `/assets/*` | `GET` | site bundle (CSS, JS, fonts) | +| `/healthz` | `GET` | OpenEnv health probe (`text/plain "ok"`) | +| `/reset` | `POST` | OpenEnv reset (bearer auth + X-Session-Id) | +| `/step` | `POST` | OpenEnv step | +| `/state` | `GET` | OpenEnv read-only state | +| `/close` | `POST` | OpenEnv close session | +| `/openenv.yaml` | `GET` | the manifest (served from disk) | +| `/demo` | `GET` | 302 → dedicated Gradio demo Space | + +The OpenEnv routes do not collide with the static frontend because +they are HTTP verb-specific (`POST /reset`, `POST /step`, `POST /close`, +plus `GET /healthz` and `GET /state`) — Vite-emitted assets live under +`/assets/*` and never overlap. + +## Why both, not separate? + +The dedicated env Space (`DGXAI/driftcall-env`) and project site +(`DGXAI/driftcall-site`) still exist as canonical, isolated artefacts. +This Space is an **additive** convenience for hackathon judging: +land at one URL and you see the project, can hit the reward function +endpoint, and get redirected to the demo. The Gradio demo stays +separate because it's GPU-heavy and benefits from its own scaling. + +## What's bundled + +Self-contained — the build dir for this Space contains everything it +needs to run, with no references to anything outside it: + +``` +unified_space/build/ +├── app.py ← canonical OpenEnv FastAPI (verbatim copy) +├── unified_app.py ← extends app.py + adds static mount + /demo redirect +├── openenv.yaml ← OpenEnv v1.0 manifest +├── requirements.txt ← runtime deps (no training stack) +├── Dockerfile ← multi-stage CPU image, Kokoro + faster-whisper baked +├── cells/ ← DriftCallEnv + 5 reward components + drift + audio +├── data/ ← briefs, drift patterns, API schemas +└── site/ ← Vite-built React dist (frontend) +``` + +Build + push with `bash deploy/unified_space/build.sh --push` from the +repo root. + +## OpenEnv compliance + +- Manifest: served at `/openenv.yaml` +- Endpoints: bare-path canonical (`/reset`, `/step`, `/state`, `/close`, `/healthz`) +- Auth: bearer (`DRIFTCALL_ENV_TOKEN`) + `X-Session-Id` header on mutating calls +- Action / Observation refs: `cells.step_04_models:DriftCallAction` / + `cells.step_04_models:DriftCallObservation` +- Reward: 5 components (R1..R5) with weights, calibration via Brier + + uncertain floor — see `cells/step_08_rewards.py` and the openenv.yaml + reward block. diff --git a/app.py b/app.py new file mode 100644 index 0000000000000000000000000000000000000000..4e0e12c73bacbddd3195742ee1fa5d74d5cf79ff --- /dev/null +++ b/app.py @@ -0,0 +1,786 @@ +"""DriftCall env Space — FastAPI + OpenEnv-compliant REST surface. + +Implements ``docs/modules/deploy_env_space.md`` and DESIGN.md §3.3 / §11.1. + +Endpoints: + GET /healthz → 200 text/plain "ok" (unauthenticated) + POST /reset → 200 application/json (create / recycle session) + POST /step → 200 application/json (advance one turn) + GET /state → 200 application/json (read DriftCallState) + POST /close → 200 application/json (evict session) + +Headers (mutating endpoints): ``Authorization: Bearer `` +and ``X-Session-Id: <[A-Za-z0-9_-]{1,64}>``. + +Error modes (deploy_env_space.md §5): + M1 401 unauthorized M7 400 bad_json + M2 400 missing_session_id M8 400 invalid_action + M3 404 session_not_found M9 500 internal_error + M4 404 session_expired M10 500 io_error + M5 429 max_sessions M11 413 payload_too_large + M6 503 model_not_ready M12 409 reset_in_progress + +All error bodies: ``{"error": {"code": , "message": , +"request_id": }}``; ``Cache-Control: no-store``; only M5 carries +``Retry-After: 30``. No stack traces ever leak across the wire. +""" + +from __future__ import annotations + +import asyncio +import contextlib +import dataclasses +import json +import logging +import os +import re +import time +from contextlib import asynccontextmanager +from dataclasses import dataclass, replace +from typing import TYPE_CHECKING, Any + +from fastapi import FastAPI, Request, Response +from fastapi.responses import JSONResponse, PlainTextResponse +from starlette.middleware.base import BaseHTTPMiddleware + +from cells.step_04_models import ActionType, DriftCallAction +from cells.step_10_env import ( + DriftCallEnv, + EnvClosedError, + EnvNotReadyError, + EpisodeAlreadyTerminalError, + InvalidActionError, + InvalidConfigError, + UnknownDomainError, + UnknownToolError, +) + +if TYPE_CHECKING: + from collections.abc import AsyncIterator, Awaitable, Callable + + from starlette.types import ASGIApp + +logger = logging.getLogger(__name__) + +# --------------------------------------------------------------------------- +# Constants +# --------------------------------------------------------------------------- + +_MAX_SESSIONS: int = 10 +_TTL_S: float = 3600.0 +_SWEEP_INTERVAL_S: float = 60.0 +_MAX_SESSION_ID_LEN: int = 64 +_SESSION_ID_RE: re.Pattern[str] = re.compile(r"^[A-Za-z0-9_-]{1,64}$") +_MAX_BODY_BYTES: int = 1 * 1024 * 1024 # 1 MiB +_RETRY_AFTER_S: str = "30" +_TOKEN_ENV_VAR: str = "DRIFTCALL_ENV_TOKEN" + + +# --------------------------------------------------------------------------- +# Time source (test-overridable) +# --------------------------------------------------------------------------- + + +def _monotonic() -> float: + """Indirection for tests to monkeypatch.""" + + return time.monotonic() + + +# --------------------------------------------------------------------------- +# Errors / envelope +# --------------------------------------------------------------------------- + + +@dataclass(frozen=True) +class _ApiError(Exception): + """Internal exception → uniform error envelope (deploy_env_space.md §5).""" + + code: str + message: str + http_status: int + retry_after: bool = False + + +_NO_STORE: dict[str, str] = {"Cache-Control": "no-store"} + + +def _error_response(err: _ApiError, request_id: str) -> JSONResponse: + body = { + "error": { + "code": err.code, + "message": err.message, + "request_id": request_id, + } + } + headers = dict(_NO_STORE) + if err.retry_after: + headers["Retry-After"] = _RETRY_AFTER_S + return JSONResponse(status_code=err.http_status, content=body, headers=headers) + + +# --------------------------------------------------------------------------- +# Session cache +# --------------------------------------------------------------------------- + + +@dataclass(frozen=True) +class SessionEntry: + """Frozen per project rule — every touch produces a new entry.""" + + env: DriftCallEnv + created_at: float + last_touched: float + reset_count: int + lock: asyncio.Lock + + +class SessionCache: + """In-memory session registry with LRU + TTL eviction.""" + + def __init__(self, *, max_sessions: int = _MAX_SESSIONS, ttl_s: float = _TTL_S) -> None: + self._max = max_sessions + self._ttl = ttl_s + self._store: dict[str, SessionEntry] = {} + self._guard = asyncio.Lock() + + @property + def size(self) -> int: + return len(self._store) + + def get(self, sid: str) -> SessionEntry | None: + return self._store.get(sid) + + async def acquire_lock(self, sid: str) -> asyncio.Lock: + """Return (or lazily create) the per-session lock.""" + async with self._guard: + entry = self._store.get(sid) + if entry is not None: + return entry.lock + return asyncio.Lock() + + async def insert_or_replace(self, sid: str, env_factory: Callable[[], DriftCallEnv]) -> SessionEntry: + """Insert a new env or replace an existing one (in-place reset).""" + async with self._guard: + now = _monotonic() + existing = self._store.get(sid) + if existing is not None: + # In-place reset (§7.1 case after winner completed). + try: + existing.env.close() + except Exception: + logger.exception("env.close() raised on in-place reset for sid=%s", sid) + env = env_factory() + entry = SessionEntry( + env=env, + created_at=now, + last_touched=now, + reset_count=existing.reset_count + 1, + lock=existing.lock, + ) + self._store[sid] = entry + return entry + # New session — enforce cap. + if len(self._store) >= self._max: + # Try LRU evict only if any entry is older than the others by TTL/2. + victim_sid = min(self._store, key=lambda k: self._store[k].last_touched) + victim = self._store[victim_sid] + age = now - victim.last_touched + if age <= 0.0: + raise _ApiError( + code="max_sessions", + message=f"max concurrent sessions reached ({self._max})", + http_status=429, + retry_after=True, + ) + try: + victim.env.close() + except Exception: + logger.exception("env.close() raised on LRU eviction for sid=%s", victim_sid) + self._store.pop(victim_sid, None) + env = env_factory() + entry = SessionEntry( + env=env, + created_at=now, + last_touched=now, + reset_count=0, + lock=asyncio.Lock(), + ) + self._store[sid] = entry + return entry + + def touch(self, sid: str) -> tuple[SessionEntry | None, bool]: + """Update last_touched. Returns ``(entry, was_expired)``. + + - ``(entry, False)`` on hit + - ``(None, True)`` if the entry was present but evicted by this call + due to TTL expiry + - ``(None, False)`` if there was never an entry under this sid + """ + entry = self._store.get(sid) + if entry is None: + return None, False + now = _monotonic() + if now - entry.last_touched > self._ttl: + try: + entry.env.close() + except Exception: + logger.exception("env.close() raised on expired touch for sid=%s", sid) + self._store.pop(sid, None) + return None, True + new = replace(entry, last_touched=now) + self._store[sid] = new + return new, False + + def evict(self, sid: str) -> SessionEntry | None: + """Pop a session out of the cache. Returns the removed entry or None.""" + return self._store.pop(sid, None) + + def sweep(self) -> int: + """Synchronous TTL sweep — evict every entry past TTL.""" + now = _monotonic() + expired = [sid for sid, e in self._store.items() if now - e.last_touched > self._ttl] + for sid in expired: + entry = self._store.pop(sid) + try: + entry.env.close() + except Exception: + logger.exception("env.close() raised on sweep for sid=%s", sid) + if expired: + logger.info( + json.dumps( + { + "event": "session_sweep", + "expired_count": len(expired), + "cache_size": len(self._store), + } + ) + ) + return len(expired) + + +# --------------------------------------------------------------------------- +# App state container +# --------------------------------------------------------------------------- + + +@dataclass +class _AppState: + """Mutable (intentional) — owned by lifespan; readers go through getters.""" + + cache: SessionCache + models_ready: bool = False + sweep_task: asyncio.Task[None] | None = None + bearer_token: str = "" + + +def _get_state(app: FastAPI) -> _AppState: + state: _AppState = app.state.driftcall + return state + + +# --------------------------------------------------------------------------- +# Lifespan — eager-load Kokoro + Whisper before serving (M6 guard) +# --------------------------------------------------------------------------- + + +def _eager_load_models() -> None: + """Force-load TTS + ASR singletons. Test patches this to avoid network.""" + from cells.step_09_audio import get_asr_engine, get_tts_engine + + get_tts_engine() + get_asr_engine() + + +@asynccontextmanager +async def lifespan(app: FastAPI) -> AsyncIterator[None]: + cache = SessionCache() + token = os.environ.get(_TOKEN_ENV_VAR, "") + if not token: + # Fail-fast per deploy_env_space.md §3.5. + raise RuntimeError( + f"{_TOKEN_ENV_VAR} environment variable not set; refusing to start" + ) + state = _AppState(cache=cache, bearer_token=token) + app.state.driftcall = state + + # Eager model load (M6 guard — must complete before serving). + try: + await asyncio.to_thread(_eager_load_models) + except Exception: + logger.exception("eager model load failed") + raise + state.models_ready = True + + # Background TTL sweep. + async def _sweep_loop() -> None: + try: + while True: + await asyncio.sleep(_SWEEP_INTERVAL_S) + cache.sweep() + except asyncio.CancelledError: + raise + + state.sweep_task = asyncio.create_task(_sweep_loop()) + try: + yield + finally: + if state.sweep_task is not None: + state.sweep_task.cancel() + with contextlib.suppress(asyncio.CancelledError, Exception): + await state.sweep_task + + +# --------------------------------------------------------------------------- +# Body-size middleware (M11) +# --------------------------------------------------------------------------- + + +class _BodySizeMiddleware(BaseHTTPMiddleware): + def __init__(self, app: ASGIApp, *, max_bytes: int = _MAX_BODY_BYTES) -> None: + super().__init__(app) + self._max_bytes = max_bytes + + async def dispatch( + self, request: Request, call_next: Callable[[Request], Awaitable[Response]] + ) -> Response: + cl = request.headers.get("content-length") + if cl is not None: + try: + cl_int = int(cl) + except ValueError: + cl_int = -1 + if cl_int > self._max_bytes: + err = _ApiError( + code="payload_too_large", + message="request body exceeds 1 MiB", + http_status=413, + ) + return _error_response(err, _request_id(request)) + return await call_next(request) + + +# --------------------------------------------------------------------------- +# Helpers — auth, headers, body parsing +# --------------------------------------------------------------------------- + + +def _request_id(request: Request) -> str: + return str(id(request)) + + +def _check_bearer(request: Request, state: _AppState) -> None: + auth = request.headers.get("authorization", "") + if not auth.startswith("Bearer "): + raise _ApiError( + code="unauthorized", + message="missing or non-Bearer Authorization header", + http_status=401, + ) + token = auth[len("Bearer ") :].strip() + if token != state.bearer_token or not token: + raise _ApiError( + code="unauthorized", + message="invalid bearer token", + http_status=401, + ) + + +def _check_session_header(request: Request) -> str: + sid = request.headers.get("x-session-id", "") + if not sid or not _SESSION_ID_RE.match(sid): + raise _ApiError( + code="missing_session_id", + message="X-Session-Id header missing or malformed", + http_status=400, + ) + return sid + + +def _check_models_ready(state: _AppState) -> None: + if not state.models_ready: + raise _ApiError( + code="model_not_ready", + message="audio models still loading; retry shortly", + http_status=503, + ) + + +async def _parse_json_body(request: Request) -> dict[str, Any]: + raw = await request.body() + if len(raw) > _MAX_BODY_BYTES: + raise _ApiError( + code="payload_too_large", + message="request body exceeds 1 MiB", + http_status=413, + ) + if not raw: + return {} + try: + parsed = json.loads(raw) + except (json.JSONDecodeError, UnicodeDecodeError) as exc: + raise _ApiError( + code="bad_json", + message=f"malformed JSON: {exc.__class__.__name__}", + http_status=400, + ) from exc + if not isinstance(parsed, dict): + raise _ApiError( + code="bad_json", + message="request body must be a JSON object", + http_status=400, + ) + return parsed + + +# --------------------------------------------------------------------------- +# Action / config validation (envelope-level — env owns deep validation) +# --------------------------------------------------------------------------- + + +def _build_action(raw: Any) -> DriftCallAction: + if not isinstance(raw, dict): + raise _ApiError( + code="invalid_action", + message="action must be a JSON object", + http_status=400, + ) + atype_raw = raw.get("action_type") + if not isinstance(atype_raw, str): + raise _ApiError( + code="invalid_action", + message="action.action_type must be a string", + http_status=400, + ) + try: + atype = ActionType(atype_raw) + except ValueError as exc: + raise _ApiError( + code="invalid_action", + message=f"unknown action_type {atype_raw!r}", + http_status=400, + ) from exc + + tool_name = raw.get("tool_name") + tool_args = raw.get("tool_args") + message = raw.get("message") + confidence = raw.get("confidence") + rationale = raw.get("rationale") + + # Action-type contract checks (deep checks happen inside env._validate_action). + if atype == ActionType.TOOL_CALL and ( + tool_name is None or not isinstance(tool_name, str) or tool_args is None + ): + raise _ApiError( + code="invalid_action", + message="TOOL_CALL requires tool_name (str) and tool_args (object)", + http_status=400, + ) + return DriftCallAction( + action_type=atype, + tool_name=tool_name if isinstance(tool_name, str) else None, + tool_args=tool_args if isinstance(tool_args, dict) else None, + message=message if isinstance(message, str) else None, + confidence=float(confidence) if isinstance(confidence, (int, float)) and not isinstance(confidence, bool) else None, + rationale=rationale if isinstance(rationale, str) else None, + ) + + +def _build_env_config(reset_body: dict[str, Any]) -> dict[str, Any]: + raw_cfg = reset_body.get("config") + if raw_cfg is None: + raw_cfg = {} + if not isinstance(raw_cfg, dict): + raise _ApiError( + code="invalid_action", + message="config must be a JSON object", + http_status=400, + ) + return raw_cfg + + +# --------------------------------------------------------------------------- +# Serialization helpers +# --------------------------------------------------------------------------- + + +def _to_jsonable(obj: Any) -> Any: + """Recursively convert frozen dataclasses / tuples / enums to JSON-safe form.""" + if dataclasses.is_dataclass(obj) and not isinstance(obj, type): + return {k: _to_jsonable(v) for k, v in dataclasses.asdict(obj).items()} + if isinstance(obj, ActionType): + return obj.value + if isinstance(obj, dict): + return {k: _to_jsonable(v) for k, v in obj.items()} + if isinstance(obj, (list, tuple)): + return [_to_jsonable(v) for v in obj] + return obj + + +# --------------------------------------------------------------------------- +# Endpoint handlers (one function per route) +# --------------------------------------------------------------------------- + + +async def _handle_reset(request: Request, state: _AppState) -> Response: + _check_bearer(request, state) + _check_models_ready(state) + sid = _check_session_header(request) + body = await _parse_json_body(request) + cfg = _build_env_config(body) + seed_raw = body.get("seed") + if seed_raw is not None and (not isinstance(seed_raw, int) or isinstance(seed_raw, bool)): + raise _ApiError( + code="invalid_action", + message="seed must be an int or null", + http_status=400, + ) + seed: int | None = seed_raw if isinstance(seed_raw, int) and not isinstance(seed_raw, bool) else None + + cache = state.cache + # Per-session reset lock (§7.1). + existing = cache.get(sid) + if existing is not None and existing.lock.locked(): + raise _ApiError( + code="reset_in_progress", + message="concurrent /reset on same session id", + http_status=409, + ) + + # Acquire lock (creates one if not present). + lock = await cache.acquire_lock(sid) + if lock.locked(): + raise _ApiError( + code="reset_in_progress", + message="concurrent /reset on same session id", + http_status=409, + ) + + async with lock: + def _factory() -> DriftCallEnv: + try: + return DriftCallEnv(cfg) + except InvalidConfigError as exc: + raise _ApiError( + code="invalid_action", + message=f"invalid config: {exc}", + http_status=400, + ) from exc + + try: + entry = await cache.insert_or_replace(sid, _factory) + except _ApiError: + raise + except Exception as exc: + logger.exception("env construction failed for sid=%s", sid) + raise _ApiError( + code="internal_error", + message="env construction failed", + http_status=500, + ) from exc + + try: + obs = await asyncio.to_thread(entry.env.reset, seed) + except InvalidConfigError as exc: + cache.evict(sid) + raise _ApiError( + code="invalid_action", + message=f"invalid config at reset: {exc}", + http_status=400, + ) from exc + except OSError as exc: + cache.evict(sid) + raise _ApiError( + code="io_error", + message=f"I/O error during reset: {exc.__class__.__name__}", + http_status=500, + ) from exc + except Exception as exc: + cache.evict(sid) + logger.exception("env.reset raised for sid=%s", sid) + raise _ApiError( + code="internal_error", + message="env.reset raised", + http_status=500, + ) from exc + + body_out = { + "observation": _to_jsonable(obs), + "episode_id": entry.env.state().episode_id, + "max_turns": entry.env.state().max_turns, + } + return JSONResponse(status_code=200, content=body_out) + + +async def _handle_step(request: Request, state: _AppState) -> Response: + _check_bearer(request, state) + _check_models_ready(state) + sid = _check_session_header(request) + body = await _parse_json_body(request) + raw_action = body.get("action") + action = _build_action(raw_action) + + entry, was_expired = state.cache.touch(sid) + if entry is None: + if was_expired: + raise _ApiError( + code="session_expired", + message="session TTL expired; call /reset", + http_status=404, + ) + raise _ApiError( + code="session_not_found", + message="X-Session-Id has no live session; call /reset", + http_status=404, + ) + + try: + obs = await asyncio.to_thread(entry.env.step, action) + except (InvalidActionError, UnknownToolError, UnknownDomainError) as exc: + raise _ApiError( + code="invalid_action", + message=str(exc), + http_status=400, + ) from exc + except (EnvNotReadyError, EnvClosedError, EpisodeAlreadyTerminalError) as exc: + raise _ApiError( + code="invalid_action", + message=str(exc), + http_status=400, + ) from exc + except OSError as exc: + raise _ApiError( + code="io_error", + message=f"I/O error during step: {exc.__class__.__name__}", + http_status=500, + ) from exc + except Exception as exc: + logger.exception("env.step raised for sid=%s", sid) + raise _ApiError( + code="internal_error", + message="env.step raised", + http_status=500, + ) from exc + + reward: float | None = None + info: dict[str, Any] = {} + if entry.env.done(): + try: + rewards = entry.env.rewards() + reward = float(getattr(rewards, "reward", 0.0)) + info["terminated_by"] = entry.env.episode().terminated_by + except Exception: + reward = None + + body_out = { + "observation": _to_jsonable(obs), + "reward": reward, + "done": bool(entry.env.done()), + "info": info, + } + return JSONResponse(status_code=200, content=body_out) + + +async def _handle_state(request: Request, state: _AppState) -> Response: + _check_bearer(request, state) + _check_models_ready(state) + sid = _check_session_header(request) + entry, was_expired = state.cache.touch(sid) + if entry is None: + if was_expired: + raise _ApiError( + code="session_expired", + message="session TTL expired; call /reset", + http_status=404, + ) + raise _ApiError( + code="session_not_found", + message="X-Session-Id has no live session; call /reset", + http_status=404, + ) + try: + st = entry.env.state() + except EnvNotReadyError as exc: + raise _ApiError( + code="invalid_action", + message=str(exc), + http_status=400, + ) from exc + body_out = {"state": _to_jsonable(st), "turn": st.turn} + return JSONResponse(status_code=200, content=body_out) + + +async def _handle_close(request: Request, state: _AppState) -> Response: + _check_bearer(request, state) + _check_models_ready(state) + sid = _check_session_header(request) + entry = state.cache.evict(sid) + if entry is None: + return JSONResponse(status_code=200, content={"closed": True, "final_state": None}) + final_state: Any = None + try: + final_state = _to_jsonable(entry.env.state()) + except EnvNotReadyError: + final_state = None + try: + entry.env.close() + except Exception: + logger.exception("env.close raised on /close for sid=%s", sid) + return JSONResponse(status_code=200, content={"closed": True, "final_state": final_state}) + + +# --------------------------------------------------------------------------- +# App factory + route wiring +# --------------------------------------------------------------------------- + + +def create_app() -> FastAPI: + """Construct a fresh FastAPI app. Used by tests to get an isolated instance.""" + app = FastAPI(lifespan=lifespan, title="DriftCall Env", version="0.1.0") + app.add_middleware(_BodySizeMiddleware, max_bytes=_MAX_BODY_BYTES) + + @app.get("/healthz", response_class=PlainTextResponse) + async def healthz() -> PlainTextResponse: + return PlainTextResponse(content="ok", status_code=200) + + @app.post("/reset") + async def reset_route(request: Request) -> Response: + try: + return await _handle_reset(request, _get_state(app)) + except _ApiError as err: + return _error_response(err, _request_id(request)) + + @app.post("/step") + async def step_route(request: Request) -> Response: + try: + return await _handle_step(request, _get_state(app)) + except _ApiError as err: + return _error_response(err, _request_id(request)) + + @app.get("/state") + async def state_route(request: Request) -> Response: + try: + return await _handle_state(request, _get_state(app)) + except _ApiError as err: + return _error_response(err, _request_id(request)) + + @app.post("/close") + async def close_route(request: Request) -> Response: + try: + return await _handle_close(request, _get_state(app)) + except _ApiError as err: + return _error_response(err, _request_id(request)) + + return app + + +app = create_app() + + +__all__ = [ + "SessionCache", + "SessionEntry", + "app", + "create_app", + "lifespan", +] diff --git a/cells/__init__.py b/cells/__init__.py new file mode 100644 index 0000000000000000000000000000000000000000..e69de29bb2d1d6434b8b29ae775ad8c2e48c5391 diff --git a/cells/_secrets.py b/cells/_secrets.py new file mode 100644 index 0000000000000000000000000000000000000000..d922fd1b82774cb2b33b173d6902b27c62ffbf5d --- /dev/null +++ b/cells/_secrets.py @@ -0,0 +1,47 @@ +"""DriftCall — hardcoded secrets for private-repo runs. + +This file contains credentials. Repository is private per user direction. +Do NOT make this repository public without scrubbing this file from history: + + git filter-repo --path cells/_secrets.py --invert-paths + +To rotate a key: replace the value below and the running training script +will pick it up on next launch (init_wandb reads via os.environ first; +this file is the fallback when env var is unset). +""" + +from __future__ import annotations + +import os + +# wandb.ai API key — pasted by user 2026-04-25. +# Rotate at https://wandb.ai/authorize → Reset, then update below. +WANDB_API_KEY: str = "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" + +# Default project + mode — override via env if needed. +WANDB_PROJECT: str = "driftcall" +WANDB_ENTITY: str | None = None +WANDB_MODE: str = "online" + + +def export_to_env() -> None: + """Push hardcoded values into ``os.environ`` if not already set. + + Called by ``init_wandb()`` at the start of each training run. Env-var + overrides take priority — set ``WANDB_API_KEY=...`` in the shell to bypass + this file without editing it. + """ + os.environ.setdefault("WANDB_API_KEY", WANDB_API_KEY) + os.environ.setdefault("WANDB_PROJECT", WANDB_PROJECT) + if WANDB_ENTITY is not None: + os.environ.setdefault("WANDB_ENTITY", WANDB_ENTITY) + os.environ.setdefault("WANDB_MODE", WANDB_MODE) + + +__all__ = [ + "WANDB_API_KEY", + "WANDB_ENTITY", + "WANDB_MODE", + "WANDB_PROJECT", + "export_to_env", +] diff --git a/cells/step_01_install.md b/cells/step_01_install.md new file mode 100644 index 0000000000000000000000000000000000000000..7a722651008968c15b352e624d0bc8f5511c5f48 --- /dev/null +++ b/cells/step_01_install.md @@ -0,0 +1,3 @@ +# Install dependencies + +Installs the pinned DriftCall runtime from `requirements.txt` and authenticates with the Hugging Face Hub when `HF_TOKEN` is set in the environment. On Colab this provisions the kernel; on a configured local machine the step is idempotent and returns immediately. diff --git a/cells/step_01_install.py b/cells/step_01_install.py new file mode 100644 index 0000000000000000000000000000000000000000..87f502acaa47760e37d9eb804e3e29fcacf05101 --- /dev/null +++ b/cells/step_01_install.py @@ -0,0 +1,116 @@ +"""Cell 01 — Install pinned dependencies. + +Runs once at notebook boot. On Colab the notebook kernel is a bare Python 3 +install, so we ``pip install`` the flat pin set from ``requirements.txt``. +Locally we skip reinstall if every pin is already importable. + +Also authenticates with the Hugging Face Hub when an ``HF_TOKEN`` environment +variable is set; on interactive sessions the user can run ``hf auth login`` +separately. No network calls are attempted when ``HF_TOKEN`` is absent — the +cell remains a no-op so offline unit tests pass. +""" + +from __future__ import annotations + +import importlib.util +import os +import subprocess +import sys +from pathlib import Path + +REQUIREMENTS_FILENAME = "requirements.txt" + +# Packages whose import name differs from their distribution name. Only list +# the handful we actually probe with ``is_installed``; everything else uses +# the distribution name verbatim. +_IMPORT_ALIASES: dict[str, str] = { + "faster-whisper": "faster_whisper", + "huggingface_hub": "huggingface_hub", + "uvicorn[standard]": "uvicorn", + "pytest-cov": "pytest_cov", +} + + +def is_installed(distribution: str) -> bool: + """Return True iff the import name behind *distribution* is available.""" + + base = distribution.split("[", 1)[0].split(">", 1)[0].split("<", 1)[0] + base = base.split("==", 1)[0].split("~=", 1)[0].strip() + module = _IMPORT_ALIASES.get(distribution, _IMPORT_ALIASES.get(base, base)) + module = module.replace("-", "_") + return importlib.util.find_spec(module) is not None + + +def _find_requirements() -> Path | None: + """Locate ``requirements.txt`` alongside the project root (worktree-safe).""" + + candidates = [ + Path.cwd() / REQUIREMENTS_FILENAME, + Path(__file__).resolve().parent.parent / REQUIREMENTS_FILENAME, + ] + for candidate in candidates: + if candidate.is_file(): + return candidate + return None + + +def is_colab() -> bool: + """Detect Google Colab runtime (``google.colab`` is always importable there).""" + + return importlib.util.find_spec("google.colab") is not None + + +def pip_install(requirements_path: Path) -> int: + """Invoke ``pip install -r `` via the current interpreter.""" + + cmd = [sys.executable, "-m", "pip", "install", "--quiet", "-r", str(requirements_path)] + completed = subprocess.run(cmd, check=False) + return completed.returncode + + +def hf_login_if_token_present() -> bool: + """Log into HF Hub using ``HF_TOKEN`` env var. Returns True on success.""" + + token = os.environ.get("HF_TOKEN") + if not token: + return False + try: + from huggingface_hub import login + except ImportError: + return False + login(token=token, add_to_git_credential=False) + return True + + +def install(force: bool = False) -> int: + """Top-level cell body. Idempotent: skips reinstall when pins already import. + + :param force: Reinstall even if every dependency is importable. + :returns: 0 when deps already satisfied or pip succeeded; non-zero on pip failure. + """ + + requirements_path = _find_requirements() + if requirements_path is None: + return 0 + + if not force and not is_colab(): + declared = [ + line.strip() + for line in requirements_path.read_text(encoding="utf-8").splitlines() + if line.strip() and not line.strip().startswith("#") + ] + if declared and all(is_installed(pkg) for pkg in declared): + hf_login_if_token_present() + return 0 + + rc = pip_install(requirements_path) + if rc == 0: + hf_login_if_token_present() + return rc + + +# Cell body: execute on import so the Colab notebook runs end-to-end. +# Skip the side effect when the cell is being imported under the pytest +# runner or when a caller opts out via ``DRIFTCALL_SKIP_INSTALL=1``. +_skip_marker = "pytest" in sys.modules or os.environ.get("DRIFTCALL_SKIP_INSTALL") == "1" +_rc = 0 if _skip_marker else install() diff --git a/cells/step_02_imports.md b/cells/step_02_imports.md new file mode 100644 index 0000000000000000000000000000000000000000..8806e368f1b9addab236136005e0747834fed093 --- /dev/null +++ b/cells/step_02_imports.md @@ -0,0 +1,3 @@ +# Consolidated imports + +Pulls in the stdlib + third-party modules used throughout the notebook so each later cell can focus on its module logic. Heavy optional wheels (numpy, fastapi, soundfile, etc.) are loaded defensively — a missing wheel surfaces as `None` from `get_optional(...)` rather than aborting the notebook. diff --git a/cells/step_02_imports.py b/cells/step_02_imports.py new file mode 100644 index 0000000000000000000000000000000000000000..d8d853cc670279302db590f3c5376998678f6a2a --- /dev/null +++ b/cells/step_02_imports.py @@ -0,0 +1,94 @@ +"""Cell 02 — Consolidated imports. + +Grouped re-exports of stdlib + third-party modules used across later cells. +Later cells ``from cells.step_02_imports import X`` (or import names directly); +this keeps the notebook top DRY while the individual ``.py`` files remain +standalone importable modules for the test suite and the FastAPI server. + +Unused-import warnings on re-exported names are silenced via the +``[tool.ruff.lint.per-file-ignores]`` override in ``pyproject.toml`` rather +than per-line ``noqa`` pragmas. +""" + +from __future__ import annotations + +# --------------------------------------------------------------------------- +# Standard library +# --------------------------------------------------------------------------- +import dataclasses +import hashlib +import importlib +import io +import json +import logging +import math +import os +import random +import re +import sys +import time +import uuid +from collections.abc import Callable, Mapping, Sequence +from dataclasses import dataclass, field +from enum import Enum +from pathlib import Path +from typing import Any, Literal, Protocol, TypeVar + +# --------------------------------------------------------------------------- +# Third-party — heavy deps are guarded so test collection does not explode +# when a single wheel is missing on a fresh Colab runtime. +# --------------------------------------------------------------------------- + +_OPTIONAL_MODULES: tuple[str, ...] = ( + "numpy", + "yaml", + "fastapi", + "uvicorn", + "pydantic", + "soundfile", +) + +_loaded: dict[str, Any] = {} +for _name in _OPTIONAL_MODULES: + try: + _loaded[_name] = importlib.import_module(_name) + except ImportError: # pragma: no cover — exercised on fresh Colab only + _loaded[_name] = None + + +def get_optional(name: str) -> Any: + """Return an optional third-party module or ``None`` when unavailable.""" + + return _loaded.get(name) + + +# Names re-exported for downstream cells. Everything imported above is fair +# game via ``from cells.step_02_imports import X``. +__all__ = ( + # stdlib re-exports + "Any", + "Callable", + "Enum", + "Literal", + "Mapping", + "Path", + "Protocol", + "Sequence", + "TypeVar", + "dataclass", + "dataclasses", + "field", + "hashlib", + "io", + "json", + "logging", + "math", + "os", + "random", + "re", + "sys", + "time", + "uuid", + # helpers + "get_optional", +) diff --git a/cells/step_03_fixtures.md b/cells/step_03_fixtures.md new file mode 100644 index 0000000000000000000000000000000000000000..ba65ab9275e1cea2059dfe243ede5ade6c2cd8f1 --- /dev/null +++ b/cells/step_03_fixtures.md @@ -0,0 +1,3 @@ +# Load static fixtures + +Lazy, NFC-normalized, validated loaders for the four authored data artifacts: `task_briefs/templates.yaml`, `task_briefs/i18n.yaml`, `drift_patterns/drifts.yaml`, and the per-domain `api_schemas/*` JSON registries. Loaders raise typed `DatasetError` subclasses on any authoring drift, schema break, or cross-file consistency violation (datasets.md §3.3). diff --git a/cells/step_03_fixtures.py b/cells/step_03_fixtures.py new file mode 100644 index 0000000000000000000000000000000000000000..363ebeb5fedef71b913ef5de4132e9b18b394666 --- /dev/null +++ b/cells/step_03_fixtures.py @@ -0,0 +1,738 @@ +"""Cell 03 — Static fixture loaders for DriftCall data artifacts. + +Implements the loader contract in ``docs/modules/datasets.md`` §§2–5. Each +loader is a lazy path-keyed singleton that reads, NFC-normalizes, and validates +a single on-disk artifact, then returns a frozen dataclass wrapped in +``MappingProxyType`` where mappings appear. + +Artifacts covered: + + * ``data/task_briefs/templates.yaml`` — TemplateLibrary + * ``data/task_briefs/i18n.yaml`` — I18nLibrary + * ``data/drift_patterns/drifts.yaml`` — DriftPatternLibrary + * ``data/api_schemas//v.json`` — APISchemaRegistry + +Loaders raise one of the ``DatasetError`` subclasses declared below on any +authoring error — malformed YAML/JSON, schema violation, NFC failure, or the +21 cross-file consistency assertions enumerated in datasets.md §3.3. +""" + +from __future__ import annotations + +import hashlib +import json +import threading +import unicodedata +from dataclasses import dataclass +from pathlib import Path +from types import MappingProxyType +from typing import TYPE_CHECKING, Any, Literal + +import yaml +from jsonschema import Draft202012Validator +from jsonschema.exceptions import SchemaError + +if TYPE_CHECKING: + from collections.abc import Mapping + + +# --------------------------------------------------------------------------- +# Constants +# --------------------------------------------------------------------------- + +LanguageCode = Literal["hi", "ta", "kn", "en", "hinglish"] +Domain = Literal["airline", "cab", "restaurant", "hotel"] + +_LANGUAGE_CODES: frozenset[str] = frozenset({"hi", "ta", "kn", "en", "hinglish"}) +_PRIMARY_DOMAINS: frozenset[str] = frozenset({"airline", "cab", "restaurant", "hotel"}) +_VENDOR_DOMAINS: frozenset[str] = frozenset( + {"airline", "cab", "restaurant", "hotel", "payment"} +) +_DRIFT_TYPES: frozenset[str] = frozenset( + {"schema", "policy", "tnc", "pricing", "auth"} +) +_EXPECTED_PATTERN_COUNT = 20 +_EXPECTED_SCHEMA_VERSIONS: Mapping[str, tuple[str, ...]] = MappingProxyType( + { + "airline": ("v1", "v2", "v3"), + "cab": ("v1", "v2", "v3"), + "restaurant": ("v1", "v2", "v3"), + "hotel": ("v1", "v2", "v3"), + "payment": ("v1", "v2"), + } +) + + +# --------------------------------------------------------------------------- +# Exceptions +# --------------------------------------------------------------------------- + + +class DatasetError(Exception): + """Base class for every fixture loader error.""" + + +class DatasetFileMissingError(DatasetError): + """Raised when an authored data file is absent from disk.""" + + +class MalformedYAMLError(DatasetError): + """Raised when a YAML file fails to parse (file path + line preserved).""" + + +class MalformedJSONError(DatasetError): + """Raised when a JSON file fails to parse (file path + line preserved).""" + + +class DatasetSchemaError(DatasetError): + """Raised on type / shape / required-key violations of an authored file.""" + + +class UnknownLanguageKeyError(DatasetError): + """Raised when a language key ∉ LanguageCode appears in a YAML file.""" + + +class UnicodeNFDError(DatasetError): + """Raised when a loaded string is not NFC-normalized after defensive pass.""" + + +class DriftPatternOrphanError(DatasetError): + """Raised when a drift pattern references an API schema version that is missing.""" + + +class DuplicateDriftPatternIdError(DatasetError): + """Raised when drifts.yaml contains two entries sharing the same id.""" + + +# --------------------------------------------------------------------------- +# Frozen dataclasses (library types) +# --------------------------------------------------------------------------- + + +@dataclass(frozen=True) +class SlotDistribution: + kind: Literal["choices", "uniform"] + choices: tuple[str, ...] | None = None + low: float | None = None + high: float | None = None + step: float | None = None + + +@dataclass(frozen=True) +class Template: + template_id: str + domain: str + intent: str + min_stage: Literal[1, 2, 3] + required_slots: tuple[str, ...] + optional_slots: tuple[str, ...] + constraints_template: Mapping[str, SlotDistribution] + drift_slot_tags: tuple[str, ...] + language_variants: Mapping[str, tuple[str, ...]] + + +@dataclass(frozen=True) +class TemplateLibrary: + templates: tuple[Template, ...] + source_sha256: str + + +@dataclass(frozen=True) +class I18nLibrary: + strings: Mapping[str, Mapping[str, str]] + source_sha256: str + + +@dataclass(frozen=True) +class DriftPattern: + id: str + drift_type: str + domain: str + from_version: str + to_version: str + description: str + mutation: Mapping[str, Any] + detection_hints: tuple[str, ...] + + +@dataclass(frozen=True) +class DriftPatternLibrary: + patterns: Mapping[str, DriftPattern] + by_domain: Mapping[str, tuple[str, ...]] + by_type: Mapping[str, tuple[str, ...]] + source_sha256: str + + +@dataclass(frozen=True) +class APISchema: + domain: str + version: str + schema: Mapping[str, Any] + source_sha256: str + + +@dataclass(frozen=True) +class APISchemaRegistry: + schemas: Mapping[str, Mapping[str, APISchema]] + + def get(self, domain: str, version: str) -> APISchema: + try: + return self.schemas[domain][version] + except KeyError as exc: + raise DatasetSchemaError( + f"no schema registered for domain={domain!r} version={version!r}" + ) from exc + + def versions(self, domain: str) -> tuple[str, ...]: + try: + return tuple(self.schemas[domain].keys()) + except KeyError as exc: + raise DatasetSchemaError(f"unknown domain {domain!r}") from exc + + +# --------------------------------------------------------------------------- +# Helpers +# --------------------------------------------------------------------------- + + +def _nfc(value: str) -> str: + """NFC-normalize ``value``; raise on post-normalization non-NFC (defensive).""" + + normalized = unicodedata.normalize("NFC", value) + if not unicodedata.is_normalized("NFC", normalized): + raise UnicodeNFDError( + f"string failed NFC round-trip: {value!r}" + ) + return normalized + + +def _nfc_deep(value: Any) -> Any: + """Recursively NFC-normalize every string inside nested dict/list structures.""" + + if isinstance(value, str): + return _nfc(value) + if isinstance(value, list): + return [_nfc_deep(v) for v in value] + if isinstance(value, tuple): + return tuple(_nfc_deep(v) for v in value) + if isinstance(value, dict): + return {_nfc(k) if isinstance(k, str) else k: _nfc_deep(v) for k, v in value.items()} + return value + + +def _file_bytes(path: Path) -> bytes: + try: + return path.read_bytes() + except FileNotFoundError as exc: + raise DatasetFileMissingError(f"{path} not found") from exc + except OSError as exc: + raise DatasetFileMissingError(f"{path}: {exc}") from exc + + +def _sha256_hex(data: bytes) -> str: + return hashlib.sha256(data).hexdigest() + + +def _parse_yaml(path: Path) -> Any: + data = _file_bytes(path) + try: + return yaml.safe_load(data) + except yaml.YAMLError as exc: + mark = getattr(exc, "problem_mark", None) + line = mark.line + 1 if mark is not None else -1 + raise MalformedYAMLError(f"{path}:{line}: {exc}") from exc + + +def _parse_json(path: Path) -> Any: + data = _file_bytes(path) + try: + return json.loads(data) + except json.JSONDecodeError as exc: + raise MalformedJSONError(f"{path}:{exc.lineno}: {exc.msg}") from exc + + +def _require(cond: bool, msg: str) -> None: + if not cond: + raise DatasetSchemaError(msg) + + +def _as_tuple_of_str(value: Any, field: str, *, path: Path) -> tuple[str, ...]: + _require(isinstance(value, list), f"{path}: {field!r} must be a list") + for item in value: + _require(isinstance(item, str), f"{path}: {field!r} items must be strings") + return tuple(_nfc(v) for v in value) + + +# --------------------------------------------------------------------------- +# Path-keyed singleton caches +# --------------------------------------------------------------------------- + +_TEMPLATE_CACHE: dict[Path, TemplateLibrary] = {} +_I18N_CACHE: dict[Path, I18nLibrary] = {} +_DRIFT_CACHE: dict[Path, DriftPatternLibrary] = {} +_SCHEMA_CACHE: dict[Path, APISchemaRegistry] = {} +_CACHE_LOCK = threading.RLock() + + +# --------------------------------------------------------------------------- +# Templates loader +# --------------------------------------------------------------------------- + + +def _build_slot_distribution(raw: Any, slot_name: str, path: Path) -> SlotDistribution: + _require( + isinstance(raw, dict), + f"{path}: slot {slot_name!r} definition must be a mapping", + ) + if "choices" in raw: + choices = _as_tuple_of_str(raw["choices"], f"{slot_name}.choices", path=path) + _require( + len(choices) >= 1, + f"{path}: slot {slot_name!r} choices must be non-empty", + ) + return SlotDistribution(kind="choices", choices=choices) + if raw.get("distribution") == "uniform": + for req in ("low", "high", "step"): + _require( + req in raw, + f"{path}: slot {slot_name!r} uniform dist missing {req!r}", + ) + _require( + isinstance(raw[req], (int, float)), + f"{path}: slot {slot_name!r} {req!r} must be numeric", + ) + low = float(raw["low"]) + high = float(raw["high"]) + step = float(raw["step"]) + _require( + high >= low and step > 0, + f"{path}: slot {slot_name!r} invalid uniform range", + ) + return SlotDistribution(kind="uniform", low=low, high=high, step=step) + raise DatasetSchemaError( + f"{path}: slot {slot_name!r} must declare either 'choices' or 'distribution: uniform'" + ) + + +def _build_template(raw: Any, path: Path) -> Template: + _require(isinstance(raw, dict), f"{path}: each template must be a mapping") + for req in ( + "template_id", + "domain", + "intent", + "min_stage", + "required_slots", + "optional_slots", + "constraints_template", + "drift_slot_tags", + "language_variants", + ): + _require(req in raw, f"{path}: template missing required key {req!r}") + + template_id = _nfc(str(raw["template_id"])) + domain = _nfc(str(raw["domain"])) + intent = _nfc(str(raw["intent"])) + min_stage = raw["min_stage"] + + _require( + domain in _PRIMARY_DOMAINS, + f"{path}: template {template_id!r} has unknown domain {domain!r}", + ) + _require( + min_stage in (1, 2, 3), + f"{path}: template {template_id!r} min_stage must be 1|2|3, got {min_stage!r}", + ) + + required_slots = _as_tuple_of_str( + raw["required_slots"], f"{template_id}.required_slots", path=path + ) + optional_slots = _as_tuple_of_str( + raw["optional_slots"], f"{template_id}.optional_slots", path=path + ) + drift_slot_tags = _as_tuple_of_str( + raw["drift_slot_tags"], f"{template_id}.drift_slot_tags", path=path + ) + + raw_constraints = raw["constraints_template"] + _require( + isinstance(raw_constraints, dict), + f"{path}: template {template_id!r} constraints_template must be a mapping", + ) + constraints = { + _nfc(slot_name): _build_slot_distribution(slot_def, slot_name, path) + for slot_name, slot_def in raw_constraints.items() + } + + raw_variants = raw["language_variants"] + _require( + isinstance(raw_variants, dict), + f"{path}: template {template_id!r} language_variants must be a mapping", + ) + variants: dict[str, tuple[str, ...]] = {} + for lang_key, utterances in raw_variants.items(): + _require( + isinstance(lang_key, str), + f"{path}: template {template_id!r} language key must be string", + ) + if lang_key not in _LANGUAGE_CODES: + raise UnknownLanguageKeyError( + f"{path}: template {template_id!r} has unknown language key {lang_key!r}" + ) + _require( + isinstance(utterances, list) and len(utterances) >= 1, + f"{path}: template {template_id!r} variants[{lang_key!r}] must be non-empty list", + ) + for u in utterances: + _require( + isinstance(u, str), + f"{path}: template {template_id!r} variants[{lang_key!r}] items must be strings", + ) + variants[lang_key] = tuple(_nfc(u) for u in utterances) + + missing_langs = _LANGUAGE_CODES - variants.keys() + _require( + not missing_langs, + f"{path}: template {template_id!r} missing language_variants for {sorted(missing_langs)}", + ) + + return Template( + template_id=template_id, + domain=domain, + intent=intent, + min_stage=min_stage, + required_slots=required_slots, + optional_slots=optional_slots, + constraints_template=MappingProxyType(constraints), + drift_slot_tags=drift_slot_tags, + language_variants=MappingProxyType(variants), + ) + + +def load_templates( + path: Path | str = "data/task_briefs/templates.yaml", +) -> TemplateLibrary: + """Load + validate the task-brief template library (datasets.md §3.3).""" + + resolved = Path(path).resolve() + cached = _TEMPLATE_CACHE.get(resolved) + if cached is not None: + return cached + with _CACHE_LOCK: + cached = _TEMPLATE_CACHE.get(resolved) + if cached is not None: + return cached + raw = _parse_yaml(resolved) + _require( + isinstance(raw, list) and len(raw) >= 1, + f"{resolved}: templates.yaml must be a non-empty list", + ) + templates = tuple(_build_template(entry, resolved) for entry in raw) + + seen_ids = set() + seen_domains = set() + for tpl in templates: + _require( + tpl.template_id not in seen_ids, + f"{resolved}: duplicate template_id {tpl.template_id!r}", + ) + seen_ids.add(tpl.template_id) + seen_domains.add(tpl.domain) + missing_primary = _PRIMARY_DOMAINS - seen_domains + _require( + not missing_primary, + f"{resolved}: missing templates for domains {sorted(missing_primary)}", + ) + + library = TemplateLibrary( + templates=templates, + source_sha256=_sha256_hex(_file_bytes(resolved)), + ) + _TEMPLATE_CACHE[resolved] = library + return library + + +# --------------------------------------------------------------------------- +# I18n loader +# --------------------------------------------------------------------------- + + +def load_i18n(path: Path | str = "data/task_briefs/i18n.yaml") -> I18nLibrary: + """Load + NFC-normalize the i18n lookup (datasets.md §4.2).""" + + resolved = Path(path).resolve() + cached = _I18N_CACHE.get(resolved) + if cached is not None: + return cached + with _CACHE_LOCK: + cached = _I18N_CACHE.get(resolved) + if cached is not None: + return cached + raw = _parse_yaml(resolved) + _require( + isinstance(raw, dict) and len(raw) >= 1, + f"{resolved}: i18n.yaml must be a non-empty mapping", + ) + + strings: dict[str, Mapping[str, str]] = {} + for lang_key, entries in raw.items(): + if lang_key not in _LANGUAGE_CODES: + raise UnknownLanguageKeyError( + f"{resolved}: unknown language key {lang_key!r}" + ) + _require( + isinstance(entries, dict), + f"{resolved}: i18n[{lang_key!r}] must be a mapping", + ) + inner: dict[str, str] = {} + for k, v in entries.items(): + _require( + isinstance(k, str) and isinstance(v, str), + f"{resolved}: i18n[{lang_key!r}] entries must be string→string", + ) + inner[_nfc(k)] = _nfc(v) + strings[lang_key] = MappingProxyType(inner) + + missing = _LANGUAGE_CODES - strings.keys() + _require( + not missing, + f"{resolved}: i18n.yaml missing languages {sorted(missing)}", + ) + + library = I18nLibrary( + strings=MappingProxyType(strings), + source_sha256=_sha256_hex(_file_bytes(resolved)), + ) + _I18N_CACHE[resolved] = library + return library + + +# --------------------------------------------------------------------------- +# Drift patterns loader +# --------------------------------------------------------------------------- + + +def _build_drift_pattern(raw: Any, path: Path) -> DriftPattern: + _require(isinstance(raw, dict), f"{path}: each drift entry must be a mapping") + for req in ( + "id", + "drift_type", + "domain", + "from_version", + "to_version", + "description", + "mutation", + "detection_hints", + ): + _require(req in raw, f"{path}: drift entry missing required key {req!r}") + + pid = _nfc(str(raw["id"])) + drift_type = _nfc(str(raw["drift_type"])) + domain = _nfc(str(raw["domain"])) + from_version = _nfc(str(raw["from_version"])) + to_version = _nfc(str(raw["to_version"])) + description = _nfc(str(raw["description"])) + + _require( + drift_type in _DRIFT_TYPES, + f"{path}: drift {pid!r} has unknown drift_type {drift_type!r}", + ) + _require( + domain in _VENDOR_DOMAINS, + f"{path}: drift {pid!r} has unknown domain {domain!r}", + ) + + mutation_raw = raw["mutation"] + _require( + isinstance(mutation_raw, dict) and len(mutation_raw) >= 1, + f"{path}: drift {pid!r} mutation must be a non-empty mapping", + ) + mutation = _nfc_deep(mutation_raw) + + hints_raw = raw["detection_hints"] + _require( + isinstance(hints_raw, list) and len(hints_raw) >= 1, + f"{path}: drift {pid!r} detection_hints must be a non-empty list", + ) + for h in hints_raw: + _require( + isinstance(h, str) and h.strip() != "", + f"{path}: drift {pid!r} detection_hints entries must be non-empty strings", + ) + hints = tuple(_nfc(h) for h in hints_raw) + + return DriftPattern( + id=pid, + drift_type=drift_type, + domain=domain, + from_version=from_version, + to_version=to_version, + description=description, + mutation=MappingProxyType(dict(mutation)), + detection_hints=hints, + ) + + +def load_drift_patterns( + path: Path | str = "data/drift_patterns/drifts.yaml", + *, + schema_registry: APISchemaRegistry | None = None, +) -> DriftPatternLibrary: + """Load + validate the 20-pattern drift catalogue (datasets.md §3.3, drift_injector.md §4.4).""" + + resolved = Path(path).resolve() + cached = _DRIFT_CACHE.get(resolved) + if cached is not None: + return cached + with _CACHE_LOCK: + cached = _DRIFT_CACHE.get(resolved) + if cached is not None: + return cached + raw = _parse_yaml(resolved) + _require( + isinstance(raw, list), + f"{resolved}: drifts.yaml must be a list", + ) + _require( + len(raw) == _EXPECTED_PATTERN_COUNT, + f"{resolved}: expected {_EXPECTED_PATTERN_COUNT} drift patterns, got {len(raw)}", + ) + + patterns_list = [_build_drift_pattern(entry, resolved) for entry in raw] + + ids_seen: dict[str, int] = {} + for idx, p in enumerate(patterns_list): + if p.id in ids_seen: + raise DuplicateDriftPatternIdError( + f"{resolved}: duplicate drift pattern id {p.id!r} at entries {ids_seen[p.id]} and {idx}" + ) + ids_seen[p.id] = idx + + registry = schema_registry if schema_registry is not None else load_api_schemas() + for p in patterns_list: + for ver in (p.from_version, p.to_version): + if p.domain not in registry.schemas or ver not in registry.schemas[p.domain]: + raise DriftPatternOrphanError( + f"{resolved}: drift {p.id!r} references missing schema " + f"{p.domain}/{ver}" + ) + + patterns = MappingProxyType({p.id: p for p in patterns_list}) + by_domain: dict[str, list[str]] = {} + by_type: dict[str, list[str]] = {} + for p in patterns_list: + by_domain.setdefault(p.domain, []).append(p.id) + by_type.setdefault(p.drift_type, []).append(p.id) + + library = DriftPatternLibrary( + patterns=patterns, + by_domain=MappingProxyType({k: tuple(v) for k, v in by_domain.items()}), + by_type=MappingProxyType({k: tuple(v) for k, v in by_type.items()}), + source_sha256=_sha256_hex(_file_bytes(resolved)), + ) + _DRIFT_CACHE[resolved] = library + return library + + +# --------------------------------------------------------------------------- +# API schema loader +# --------------------------------------------------------------------------- + + +def _load_single_schema(domain: str, version: str, path: Path) -> APISchema: + data = _parse_json(path) + _require( + isinstance(data, dict), + f"{path}: JSON Schema must be an object", + ) + try: + Draft202012Validator.check_schema(data) + except SchemaError as exc: + raise DatasetSchemaError( + f"{path}: not a valid JSON Schema 2020-12: {exc.message}" + ) from exc + return APISchema( + domain=domain, + version=version, + schema=MappingProxyType(_nfc_deep(data)), + source_sha256=_sha256_hex(_file_bytes(path)), + ) + + +def load_api_schemas( + root: Path | str = "data/api_schemas", +) -> APISchemaRegistry: + """Load every ``/v.json`` file under ``root`` (datasets.md §4.4).""" + + resolved = Path(root).resolve() + cached = _SCHEMA_CACHE.get(resolved) + if cached is not None: + return cached + with _CACHE_LOCK: + cached = _SCHEMA_CACHE.get(resolved) + if cached is not None: + return cached + if not resolved.is_dir(): + raise DatasetFileMissingError(f"{resolved} is not a directory") + + schemas: dict[str, dict[str, APISchema]] = {} + for domain, expected_versions in _EXPECTED_SCHEMA_VERSIONS.items(): + domain_dir = resolved / domain + if not domain_dir.is_dir(): + raise DatasetFileMissingError( + f"{resolved}: expected domain directory {domain_dir}" + ) + per_version: dict[str, APISchema] = {} + for version in expected_versions: + file_path = domain_dir / f"{version}.json" + per_version[version] = _load_single_schema(domain, version, file_path) + schemas[domain] = per_version + + registry = APISchemaRegistry( + schemas=MappingProxyType( + {d: MappingProxyType(v) for d, v in schemas.items()} + ), + ) + _SCHEMA_CACHE[resolved] = registry + return registry + + +# --------------------------------------------------------------------------- +# Cache-reset helper (tests only) +# --------------------------------------------------------------------------- + + +def _reset_caches() -> None: + """Clear every loader cache. Intended for use by tests only.""" + + with _CACHE_LOCK: + _TEMPLATE_CACHE.clear() + _I18N_CACHE.clear() + _DRIFT_CACHE.clear() + _SCHEMA_CACHE.clear() + + +__all__ = [ + "APISchema", + "APISchemaRegistry", + "DatasetError", + "DatasetFileMissingError", + "DatasetSchemaError", + "Domain", + "DriftPattern", + "DriftPatternLibrary", + "DriftPatternOrphanError", + "DuplicateDriftPatternIdError", + "I18nLibrary", + "LanguageCode", + "MalformedJSONError", + "MalformedYAMLError", + "SlotDistribution", + "Template", + "TemplateLibrary", + "UnicodeNFDError", + "UnknownLanguageKeyError", + "load_api_schemas", + "load_drift_patterns", + "load_i18n", + "load_templates", +] diff --git a/cells/step_04_models.md b/cells/step_04_models.md new file mode 100644 index 0000000000000000000000000000000000000000..1f3038bc94c4e81ad58c1f87e3961c9c32b233a7 --- /dev/null +++ b/cells/step_04_models.md @@ -0,0 +1,3 @@ +# Step 04 — Core Dataclasses + +Declares the seven immutable types that cross module boundaries in DriftCall: `ActionType`, `DriftCallAction`, `ToolResult`, `DriftEvent`, `GoalSpec`, `DriftCallObservation`, and `DriftCallState`. All dataclasses are `frozen=True`; the module is pure shape with zero runtime behavior, imported by every other cell, the FastAPI server, and the reward suite. diff --git a/cells/step_04_models.py b/cells/step_04_models.py new file mode 100644 index 0000000000000000000000000000000000000000..018f5c04de8a1ce583d6e8e85cb2728b13c1496f --- /dev/null +++ b/cells/step_04_models.py @@ -0,0 +1,99 @@ +"""DriftCall core dataclasses. + +Implements docs/modules/models.md §2. Every declaration is pure shape; no +runtime logic lives here. All dataclasses are frozen. Invariants in §3.5 are +enforced by downstream modules (env.py, drift_injector.py, vendors/*), not here. +""" + +from __future__ import annotations + +from dataclasses import dataclass +from enum import StrEnum +from typing import Any, Literal + + +class ActionType(StrEnum): + TOOL_CALL = "tool_call" + SPEAK = "speak" + CLARIFY = "clarify" + PROBE_SCHEMA = "probe_schema" + SUBMIT = "submit" + ABORT = "abort" + + +@dataclass(frozen=True) +class DriftCallAction: + action_type: ActionType + tool_name: str | None = None + tool_args: dict[str, Any] | None = None + message: str | None = None + confidence: float | None = None + rationale: str | None = None + + +@dataclass(frozen=True) +class ToolResult: + tool_name: str + status: Literal["ok", "schema_error", "policy_error", "auth_error", "timeout"] + response: dict[str, Any] + schema_version: str + latency_ms: int + + +@dataclass(frozen=True) +class DriftEvent: + turn: int + drift_type: Literal["schema", "policy", "tnc", "pricing", "auth"] + domain: str + description: str + from_version: str + to_version: str + pattern_id: str + + +@dataclass(frozen=True) +class GoalSpec: + domain: str + intent: str + slots: dict[str, Any] + constraints: dict[str, Any] + language: Literal["hi", "ta", "kn", "en", "hinglish"] + seed_utterance: str + + +@dataclass(frozen=True) +class DriftCallObservation: + turn: int + goal: GoalSpec + last_transcript: str + last_lang: str + last_confidence: float + tool_results: tuple[ToolResult, ...] + drift_log: tuple[DriftEvent, ...] + budget_remaining: int + available_tools: tuple[str, ...] + + +@dataclass(frozen=True) +class DriftCallState: + episode_id: str + goal: GoalSpec + vendor_states: dict[str, dict[str, Any]] + schema_versions: dict[str, str] + drift_schedule: tuple[DriftEvent, ...] + drift_fired: tuple[DriftEvent, ...] + turn: int + max_turns: int + actions: tuple[DriftCallAction, ...] + done: bool + + +__all__ = [ + "ActionType", + "DriftCallAction", + "ToolResult", + "DriftEvent", + "GoalSpec", + "DriftCallObservation", + "DriftCallState", +] diff --git a/cells/step_05_vendors.md b/cells/step_05_vendors.md new file mode 100644 index 0000000000000000000000000000000000000000..0d0dce8d742ddc2d9006e7db09f2b2858ea87649 --- /dev/null +++ b/cells/step_05_vendors.md @@ -0,0 +1 @@ +Cell 05 — Mock vendor APIs. Five pure-Python vendor modules (airline, cab, restaurant, hotel, payment) consolidated into one cell. Each exposes a frozen `*State` dataclass plus five helpers (`dispatch`, `initial_state`, `apply_schema_mutation`, `describe_schema`, `emit_side_channel_if_pending`) and a `TOOLS` registry. Implements `docs/modules/vendors.md` §§2–8: three schema versions per domain, integer-INR monetary invariant, deterministic timeout via `hash((seed,tool,args)) & 0x7F == 0`, per-domain idempotency keys returning `DUPLICATE_*` policy errors, consumed-on-read side-channel notices, and cross-domain auth cascades from `payment.charge`. diff --git a/cells/step_05_vendors.py b/cells/step_05_vendors.py new file mode 100644 index 0000000000000000000000000000000000000000..277e8c052b669bce35bee4ae9dfad7f7b2fce9fe --- /dev/null +++ b/cells/step_05_vendors.py @@ -0,0 +1,2413 @@ +"""Cell 05 — Mock vendor APIs. + +Consolidated cell implementing five vendor submodules (airline, cab, +restaurant, hotel, payment) as namespaces on a single module. Every vendor +exposes: frozen ``*State`` dataclass, ``initial_state``, ``dispatch``, +``apply_schema_mutation``, ``describe_schema``, ``emit_side_channel_if_pending``, +and ``TOOLS`` tuple. Implements ``docs/modules/vendors.md`` §§2–8. +""" + +from __future__ import annotations + +import hashlib +import json +import math +from dataclasses import dataclass, replace +from datetime import datetime, timedelta +from types import SimpleNamespace +from typing import TYPE_CHECKING, Any, Literal + +from cells.step_04_models import GoalSpec, ToolResult + +if TYPE_CHECKING: + from collections.abc import Mapping + +# --------------------------------------------------------------------------- +# Exceptions +# --------------------------------------------------------------------------- + + +class UnknownSchemaVersionError(ValueError): + """Raised by a serializer when an unrecognised schema_version is passed.""" + + +class UnknownMutationOperatorError(ValueError): + """Raised by apply_schema_mutation when the operator key is not known.""" + + +# --------------------------------------------------------------------------- +# Shared helpers +# --------------------------------------------------------------------------- + + +_LATENCY_OK_LO, _LATENCY_OK_HI = 50, 400 +_LATENCY_TIMEOUT_LO, _LATENCY_TIMEOUT_HI = 5000, 7000 +_TIMEOUT_MASK = 0x7F # 1-in-128 trigger rate + + +def _canonical_args_json(tool_args: Mapping[str, Any] | None) -> str: + """Stable sorted whitespace-free JSON for hashing (vendors.md §3.1).""" + + return json.dumps( + dict(tool_args or {}), + sort_keys=True, + separators=(",", ":"), + ensure_ascii=False, + default=str, + ) + + +def _stable_digest(*parts: Any) -> int: + """Cross-process-stable 64-bit integer digest. + + Python's built-in ``hash()`` is PYTHONHASHSEED-randomized for strings, so + it cannot be used for replay-stable determinism (vendors.md §3.1). We use + blake2b truncated to 8 bytes instead. + """ + + blob = "||".join(repr(p) for p in parts).encode("utf-8") + digest_bytes = hashlib.blake2b(blob, digest_size=8).digest() + return int.from_bytes(digest_bytes, "big", signed=False) + + +def _is_timeout(episode_seed: int, tool_name: str, tool_args: Mapping[str, Any] | None) -> bool: + """Deterministic 1/128 timeout trigger — vendors.md §3.1.""" + + digest = _stable_digest(episode_seed, tool_name, _canonical_args_json(tool_args)) + return (digest & _TIMEOUT_MASK) == 0 + + +def _seeded_uniform(episode_seed: int, tag: str, lo: int, hi: int) -> int: + """Deterministic uniform int in ``[lo, hi]``. No wall clock.""" + + h = _stable_digest(episode_seed, tag) & 0x7FFFFFFF + span = hi - lo + 1 + return lo + (h % span) + + +def _make_id(domain: str, episode_seed: int, op: str, key: Any, records: Mapping[str, Any]) -> str: + """Deterministic 4-hex ID with ``-R{retry}`` suffix on prefix collisions. + + ``records`` is scanned for prefix matches to derive the replay-stable + retry counter (vendors.md §3.8). + """ + + prefix = f"{domain[:3].upper()}-{_stable_digest(episode_seed, op, key) & 0xFFFF:04X}" + matches = sum(1 for existing_id in records if existing_id.startswith(prefix)) + if matches == 0: + return prefix + return f"{prefix}-R{matches + 1}" + + +def _integer_inr(value: Any) -> int: + """Coerce to int, rejecting bools. Uses ``math.floor(x + 0.5)`` for rounding.""" + + if isinstance(value, bool): + raise TypeError("monetary fields must be int, not bool") + if isinstance(value, int): + return value + if isinstance(value, float): + return int(math.floor(value + 0.5)) + raise TypeError(f"non-numeric monetary value: {value!r}") + + +def _timeout_result( + tool_name: str, + episode_seed: int, + schema_version: str, +) -> ToolResult: + latency = _seeded_uniform(episode_seed, f"{tool_name}:timeout", _LATENCY_TIMEOUT_LO, _LATENCY_TIMEOUT_HI) + return ToolResult( + tool_name=tool_name, + status="timeout", + response={"error_code": "TIMEOUT", "hint": "retry with same args"}, + schema_version=schema_version, + latency_ms=latency, + ) + + +def _ok_latency(episode_seed: int, tool_name: str) -> int: + return _seeded_uniform(episode_seed, f"{tool_name}:ok", _LATENCY_OK_LO, _LATENCY_OK_HI) + + +def _normalize_items(items: list[dict[str, Any]]) -> tuple[tuple[str, int, tuple[str, ...]], ...]: + """Normalise restaurant items for idempotency keying (vendors.md §3.9).""" + + out: list[tuple[str, int, tuple[str, ...]]] = [] + for item in items: + dish_id = str(item["dish_id"]).strip().lower() + qty = int(item["qty"]) + mods_raw = item.get("modifiers", []) or [] + mods = tuple(sorted(str(m).strip().lower() for m in mods_raw)) + out.append((dish_id, qty, mods)) + return tuple(sorted(out)) + + +# --------------------------------------------------------------------------- +# Airline +# --------------------------------------------------------------------------- + + +@dataclass(frozen=True) +class AirlinePolicy: + booking_window_hours: int = 24 + required_book_fields: tuple[str, ...] = () + + +@dataclass(frozen=True) +class AirlineTnC: + baggage_cabin_kg: int = 7 + reschedule_fee_pct: int = 0 + + +@dataclass(frozen=True) +class AirlinePricing: + convenience_fee_inr: int = 0 + + +@dataclass(frozen=True) +class AirlineState: + schema_version: str + bookings: dict[str, dict[str, Any]] + flight_roster_cache: dict[str, tuple[dict[str, Any], ...]] + policy: AirlinePolicy + tnc: AirlineTnC + pricing: AirlinePricing + side_channel_notice: str | None + + +_AIRLINE_BASE_FLIGHTS: tuple[dict[str, Any], ...] = ( + {"flight_id": "6E-2345", "depart_hour": 18, "depart_min": 30, "base_price": 7200, "seats": 14}, + {"flight_id": "AI-501", "depart_hour": 20, "depart_min": 15, "base_price": 6800, "seats": 3}, + {"flight_id": "UK-878", "depart_hour": 9, "depart_min": 10, "base_price": 5200, "seats": 9}, + {"flight_id": "SG-102", "depart_hour": 14, "depart_min": 50, "base_price": 8400, "seats": 22}, +) + + +def _airline_time_window(hour: int) -> str: + if 5 <= hour < 12: + return "morning" + if 12 <= hour < 17: + return "afternoon" + if 17 <= hour < 22: + return "evening" + return "late_night" + + +def _airline_search_flights( + from_: str, to: str, date: str, episode_seed: int +) -> tuple[dict[str, Any], ...]: + key = f"{from_}->{to}|{date}" + h = _stable_digest(episode_seed, key) & 0xFFFF + count = 3 + (h % 3) + return _AIRLINE_BASE_FLIGHTS[:count] + + +def _airline_serialize_flight(flight: dict[str, Any], from_: str, to: str, date: str, version: str) -> dict[str, Any]: + depart = f"{date}T{flight['depart_hour']:02d}:{flight['depart_min']:02d}:00+05:30" + base: dict[str, Any] = { + "flight_id": flight["flight_id"], + "from": from_, + "to": to, + "depart": depart, + "seats_left": int(flight["seats"]), + } + if version == "v1": + base["price"] = int(flight["base_price"]) + base["currency"] = "INR" + elif version in ("v2", "v3"): + base["total_fare_inr"] = int(flight["base_price"]) + else: + raise UnknownSchemaVersionError(version) + return base + + +def airline_initial_state(episode_seed: int, goal: GoalSpec) -> AirlineState: + _ = (episode_seed, goal) + return AirlineState( + schema_version="v1", + bookings={}, + flight_roster_cache={}, + policy=AirlinePolicy(booking_window_hours=24, required_book_fields=()), + tnc=AirlineTnC(), + pricing=AirlinePricing(), + side_channel_notice=None, + ) + + +def airline_search( + vendor_state: AirlineState, + schema_version: str, + from_: str, + to: str, + date: str, + max_price_inr: int | None = None, + time_window: Literal["morning", "afternoon", "evening", "late_night"] | None = None, + episode_seed: int = 0, +) -> ToolResult: + flights = _airline_search_flights(from_, to, date, episode_seed) + serialized: list[dict[str, Any]] = [] + for f in flights: + if time_window is not None and _airline_time_window(f["depart_hour"]) != time_window: + continue + if max_price_inr is not None and int(f["base_price"]) > int(max_price_inr): + continue + serialized.append(_airline_serialize_flight(f, from_, to, date, schema_version)) + return ToolResult( + tool_name="airline.search", + status="ok", + response={"results": serialized}, + schema_version=schema_version, + latency_ms=_ok_latency(episode_seed, "airline.search"), + ) + + +def _airline_book_impl( + vendor_state: AirlineState, + schema_version: str, + payment_state: PaymentState, + flight_id: str, + payment_token: str, + passenger_count: int | None, + passenger_name: str | None, + episode_seed: int, + now_ist: datetime, +) -> tuple[ToolResult, AirlineState, PaymentState]: + flight = next((f for f in _AIRLINE_BASE_FLIGHTS if f["flight_id"] == flight_id), None) + if flight is None: + return ( + ToolResult( + tool_name="airline.book", + status="schema_error", + response={ + "error_code": "MISSING_FIELD", + "field_name": "flight_id", + "hint": "unknown flight_id", + }, + schema_version=schema_version, + latency_ms=_ok_latency(episode_seed, "airline.book"), + ), + vendor_state, + payment_state, + ) + + if schema_version == "v3" and passenger_count is None: + return ( + ToolResult( + tool_name="airline.book", + status="schema_error", + response={ + "error_code": "MISSING_PASSENGER_COUNT", + "hint": "v3 requires passenger_count on book", + }, + schema_version=schema_version, + latency_ms=_ok_latency(episode_seed, "airline.book"), + ), + vendor_state, + payment_state, + ) + + depart_date = now_ist.date().isoformat() + depart_dt = now_ist.replace( + hour=int(flight["depart_hour"]), + minute=int(flight["depart_min"]), + second=0, + microsecond=0, + ) + window_hours = int(vendor_state.policy.booking_window_hours) + if ( + depart_dt - now_ist < timedelta(hours=window_hours) + and depart_dt >= now_ist + and window_hours < 24 + and now_ist.hour >= 14 + ): + return ( + ToolResult( + tool_name="airline.book", + status="policy_error", + response={ + "error_code": "BOOKING_WINDOW_CLOSED", + "hint": "same-day booking closed after 14:00 IST", + }, + schema_version=schema_version, + latency_ms=_ok_latency(episode_seed, "airline.book"), + ), + vendor_state, + payment_state, + ) + + idempotency_key = (flight_id, (passenger_name or "").strip().lower(), depart_date) + for existing_id, record in vendor_state.bookings.items(): + existing_key = ( + record.get("flight_id"), + str(record.get("passenger_name") or "").strip().lower(), + record.get("depart_date"), + ) + if existing_key == idempotency_key: + return ( + ToolResult( + tool_name="airline.book", + status="policy_error", + response={ + "error_code": "DUPLICATE_BOOKING", + "existing_id": existing_id, + "original_ts": str(record.get("created_at_ist", "")), + "hint": "identical booking already exists", + }, + schema_version=schema_version, + latency_ms=_ok_latency(episode_seed, "airline.book"), + ), + vendor_state, + payment_state, + ) + + amount = int(flight["base_price"]) + charge_result, new_payment_state = _payment_charge_internal( + payment_state=payment_state, + amount_inr=amount, + payment_token=payment_token, + mfa_code=None, + episode_seed=episode_seed, + order_ref=f"airline:{flight_id}:{depart_date}", + ) + if charge_result.status != "ok": + propagated = _propagate_payment_error(charge_result, "airline.book", schema_version, episode_seed) + return propagated, vendor_state, payment_state + + booking_id = _make_id("airline", episode_seed, "book", (flight_id, passenger_name, depart_date), vendor_state.bookings) + new_record: dict[str, Any] = { + "booking_id": booking_id, + "flight_id": flight_id, + "depart": f"{depart_date}T{flight['depart_hour']:02d}:{flight['depart_min']:02d}:00+05:30", + "depart_date": depart_date, + "passenger_name": passenger_name, + "seats_confirmed": int(passenger_count or 1), + "payment_status": "captured", + "created_at_ist": now_ist.isoformat(), + } + if schema_version == "v1": + new_record["price"] = amount + else: + new_record["total_fare_inr"] = amount + if schema_version == "v3": + new_record["passenger_count"] = int(passenger_count or 1) + + new_bookings = {**vendor_state.bookings, booking_id: new_record} + new_state = replace(vendor_state, bookings=new_bookings) + response = {k: v for k, v in new_record.items() if k not in ("depart_date", "created_at_ist", "passenger_name")} + return ( + ToolResult( + tool_name="airline.book", + status="ok", + response=response, + schema_version=schema_version, + latency_ms=_ok_latency(episode_seed, "airline.book"), + ), + new_state, + new_payment_state, + ) + + +def airline_cancel( + vendor_state: AirlineState, + schema_version: str, + booking_id: str, + episode_seed: int = 0, +) -> tuple[ToolResult, AirlineState]: + if booking_id not in vendor_state.bookings: + return ( + ToolResult( + tool_name="airline.cancel", + status="policy_error", + response={"error_code": "MISSING_FIELD", "hint": "booking_id not found"}, + schema_version=schema_version, + latency_ms=_ok_latency(episode_seed, "airline.cancel"), + ), + vendor_state, + ) + new_bookings = {k: v for k, v in vendor_state.bookings.items() if k != booking_id} + new_state = replace(vendor_state, bookings=new_bookings) + return ( + ToolResult( + tool_name="airline.cancel", + status="ok", + response={"booking_id": booking_id, "cancelled": True}, + schema_version=schema_version, + latency_ms=_ok_latency(episode_seed, "airline.cancel"), + ), + new_state, + ) + + +def airline_get_booking( + vendor_state: AirlineState, + schema_version: str, + booking_id: str, + episode_seed: int = 0, +) -> ToolResult: + record = vendor_state.bookings.get(booking_id) + if record is None: + return ToolResult( + tool_name="airline.get_booking", + status="schema_error", + response={"error_code": "MISSING_FIELD", "field_name": "booking_id", "hint": "unknown booking_id"}, + schema_version=schema_version, + latency_ms=_ok_latency(episode_seed, "airline.get_booking"), + ) + payload = {k: v for k, v in record.items() if k not in ("depart_date", "created_at_ist", "passenger_name")} + return ToolResult( + tool_name="airline.get_booking", + status="ok", + response=payload, + schema_version=schema_version, + latency_ms=_ok_latency(episode_seed, "airline.get_booking"), + ) + + +def airline_apply_schema_mutation( + vendor_state: AirlineState, mutation: Mapping[str, Any] +) -> AirlineState: + state = vendor_state + next_version = state.schema_version + policy = state.policy + for op, payload in mutation.items(): + if op == "rename": + if "price" in payload and payload["price"] == "total_fare_inr": + next_version = "v2" + elif op == "remove": + fields = payload if isinstance(payload, list) else [payload] + if "currency" in fields and next_version == "v1": + next_version = "v2" + elif op == "require_new_field": + if isinstance(payload, dict) and "passenger_count" in payload: + policy = replace(policy, required_book_fields=tuple(sorted(set(policy.required_book_fields) | {"passenger_count"}))) + next_version = "v3" + elif op == "time_window_shrink": + if isinstance(payload, dict) and "booking_window_hours" in payload: + policy = replace(policy, booking_window_hours=int(payload["booking_window_hours"])) + elif op == "change_type" or op == "tnc_text_swap": + continue + elif op == "side_channel_notice_append": + state = replace(state, side_channel_notice=str(payload)) + elif op == "fee_append": + if isinstance(payload, dict) and "convenience_fee_inr" in payload: + state = replace(state, pricing=replace(state.pricing, convenience_fee_inr=int(payload["convenience_fee_inr"]))) + elif op == "pricing_restructure" or op in {"numeric_bump", "enum_expand", "policy_flag_flip", "auth_scope_bump", "token_version_bump"}: + continue + else: + raise UnknownMutationOperatorError(op) + return replace(state, schema_version=next_version, policy=policy) + + +def airline_describe_schema(vendor_state: AirlineState, schema_version: str) -> dict[str, Any]: + if schema_version == "v1": + fields = { + "flight_id": "str", + "from": "str", + "to": "str", + "depart": "str", + "price": "int", + "currency": "str", + "seats_left": "int", + } + removed: list[str] = [] + elif schema_version == "v2": + fields = { + "flight_id": "str", + "from": "str", + "to": "str", + "depart": "str", + "total_fare_inr": "int", + "seats_left": "int", + } + removed = ["price", "currency"] + elif schema_version == "v3": + fields = { + "flight_id": "str", + "from": "str", + "to": "str", + "depart": "str", + "total_fare_inr": "int", + "seats_left": "int", + "passenger_count": "int", + } + removed = ["price", "currency"] + else: + raise UnknownSchemaVersionError(schema_version) + return {"version": schema_version, "fields": fields, "removed_from_prior": removed} + + +def airline_emit_side_channel_if_pending( + vendor_state: AirlineState, +) -> tuple[str | None, AirlineState]: + if vendor_state.side_channel_notice is None: + return None, vendor_state + notice = vendor_state.side_channel_notice + return notice, replace(vendor_state, side_channel_notice=None) + + +AIRLINE_TOOLS: tuple[str, ...] = ( + "airline.search", + "airline.book", + "airline.cancel", + "airline.get_booking", +) + + +# --------------------------------------------------------------------------- +# Cab +# --------------------------------------------------------------------------- + + +@dataclass(frozen=True) +class CabPolicy: + vehicle_class_enum: tuple[str, ...] = ("mini", "sedan") + mini_reject_school_hours: bool = False + + +@dataclass(frozen=True) +class CabPricing: + base_per_km_inr: int = 12 + surge_factor_pct: int = 100 + toll_bundled: bool = True + fare_breakdown: bool = False + + +@dataclass(frozen=True) +class CabTnC: + cancel_fee_inr: int = 0 + + +@dataclass(frozen=True) +class CabState: + schema_version: str + rides: dict[str, dict[str, Any]] + policy: CabPolicy + pricing: CabPricing + tnc: CabTnC + side_channel_notice: str | None + + +def cab_initial_state(episode_seed: int, goal: GoalSpec) -> CabState: + _ = (episode_seed, goal) + return CabState( + schema_version="v1", + rides={}, + policy=CabPolicy(), + pricing=CabPricing(), + tnc=CabTnC(), + side_channel_notice=None, + ) + + +def _cab_fare(pickup: str, drop: str, vehicle_class: str, episode_seed: int) -> int: + base = 80 + key_hash = _stable_digest(pickup.strip().lower(), drop.strip().lower(), episode_seed) & 0x3FF + distance = 50 + (key_hash % 250) + multipliers = {"mini": 100, "sedan": 130, "suv": 170, "infant_seat_sedan": 150} + mul = multipliers.get(vehicle_class, 100) + return int(base + (distance * mul) // 100) + + +def _cab_eta(pickup: str, episode_seed: int) -> int: + return 3 + (_stable_digest(pickup.strip().lower(), episode_seed) & 0xF) + + +def _cab_serialize( + pickup: str, + drop: str, + vehicle_class: str, + fare: int, + eta_min: int, + schema_version: str, + pricing: CabPricing, +) -> dict[str, Any]: + if schema_version == "v1": + return { + "pickup": pickup, + "drop": drop, + "vehicle_class": vehicle_class, + "fare_inr": int(fare), + "eta_min": int(eta_min), + } + if schema_version == "v2": + return { + "pickup": pickup, + "drop": drop, + "vehicle_class": vehicle_class, + "fare_inr": int(fare), + "eta_min": int(eta_min), + } + if schema_version == "v3": + base = int(fare * 75 // 100) + surge = int(fare * 12 // 100) + tolls = int(fare * 6 // 100) + gst = int(fare - base - surge - tolls) + breakdown = {"base": base, "surge": surge, "tolls": tolls, "gst": gst} + total = base + surge + tolls + gst + if total != int(fare): + # Defensive self-check — adjust gst to preserve invariant + breakdown["gst"] = int(fare) - base - surge - tolls + return { + "pickup": pickup, + "drop": drop, + "vehicle_class": vehicle_class, + "fare_breakdown": breakdown, + "total_inr": int(fare), + "eta_min": int(eta_min), + } + raise UnknownSchemaVersionError(schema_version) + + +def cab_estimate( + vendor_state: CabState, + schema_version: str, + pickup: str, + drop: str, + vehicle_class: str, + pickup_time_ist: str, + episode_seed: int = 0, +) -> ToolResult: + if vehicle_class not in vendor_state.policy.vehicle_class_enum: + return ToolResult( + tool_name="cab.estimate", + status="policy_error", + response={ + "error_code": "VEHICLE_CLASS_UNAVAILABLE", + "available": list(vendor_state.policy.vehicle_class_enum), + "hint": "requested vehicle_class not in current enum", + }, + schema_version=schema_version, + latency_ms=_ok_latency(episode_seed, "cab.estimate"), + ) + fare = _cab_fare(pickup, drop, vehicle_class, episode_seed) + eta = _cab_eta(pickup, episode_seed) + payload = _cab_serialize(pickup, drop, vehicle_class, fare, eta, schema_version, vendor_state.pricing) + return ToolResult( + tool_name="cab.estimate", + status="ok", + response=payload, + schema_version=schema_version, + latency_ms=_ok_latency(episode_seed, "cab.estimate"), + ) + + +def _cab_book_impl( + vendor_state: CabState, + schema_version: str, + payment_state: PaymentState, + pickup: str, + drop: str, + vehicle_class: str, + pickup_time_ist: str, + payment_token: str, + episode_seed: int, + now_ist: datetime, +) -> tuple[ToolResult, CabState, PaymentState]: + if vehicle_class not in vendor_state.policy.vehicle_class_enum: + return ( + ToolResult( + tool_name="cab.book", + status="policy_error", + response={ + "error_code": "VEHICLE_CLASS_UNAVAILABLE", + "available": list(vendor_state.policy.vehicle_class_enum), + "hint": "requested vehicle_class not in current enum", + }, + schema_version=schema_version, + latency_ms=_ok_latency(episode_seed, "cab.book"), + ), + vendor_state, + payment_state, + ) + + if ( + vendor_state.policy.mini_reject_school_hours + and vehicle_class == "mini" + and 7 <= now_ist.hour < 9 + ): + return ( + ToolResult( + tool_name="cab.book", + status="policy_error", + response={ + "error_code": "SCHOOL_HOURS_MINI_REJECTED", + "available": [v for v in vendor_state.policy.vehicle_class_enum if v != "mini"], + "hint": "mini rejected during 07:00-09:00 IST", + }, + schema_version=schema_version, + latency_ms=_ok_latency(episode_seed, "cab.book"), + ), + vendor_state, + payment_state, + ) + + idempotency_key = ( + pickup.strip().lower(), + drop.strip().lower(), + pickup_time_ist.strip(), + vehicle_class, + ) + for existing_id, record in vendor_state.rides.items(): + existing_key = ( + str(record.get("pickup") or "").strip().lower(), + str(record.get("drop") or "").strip().lower(), + str(record.get("pickup_time_ist") or "").strip(), + record.get("vehicle_class"), + ) + if existing_key == idempotency_key: + return ( + ToolResult( + tool_name="cab.book", + status="policy_error", + response={ + "error_code": "DUPLICATE_RIDE", + "existing_id": existing_id, + "original_ts": str(record.get("created_at_ist", "")), + "hint": "identical ride already booked", + }, + schema_version=schema_version, + latency_ms=_ok_latency(episode_seed, "cab.book"), + ), + vendor_state, + payment_state, + ) + + fare = _cab_fare(pickup, drop, vehicle_class, episode_seed) + charge_result, new_payment_state = _payment_charge_internal( + payment_state=payment_state, + amount_inr=fare, + payment_token=payment_token, + mfa_code=None, + episode_seed=episode_seed, + order_ref=f"cab:{pickup}:{drop}:{pickup_time_ist}", + ) + if charge_result.status != "ok": + return ( + _propagate_payment_error(charge_result, "cab.book", schema_version, episode_seed), + vendor_state, + payment_state, + ) + + ride_id = _make_id("cab", episode_seed, "ride", idempotency_key, vendor_state.rides) + eta = _cab_eta(pickup, episode_seed) + serialized = _cab_serialize(pickup, drop, vehicle_class, fare, eta, schema_version, vendor_state.pricing) + new_record: dict[str, Any] = { + "ride_id": ride_id, + **serialized, + "pickup_time_ist": pickup_time_ist, + "created_at_ist": now_ist.isoformat(), + "payment_status": "captured", + } + new_rides = {**vendor_state.rides, ride_id: new_record} + new_state = replace(vendor_state, rides=new_rides) + response = {k: v for k, v in new_record.items() if k != "created_at_ist"} + return ( + ToolResult( + tool_name="cab.book", + status="ok", + response=response, + schema_version=schema_version, + latency_ms=_ok_latency(episode_seed, "cab.book"), + ), + new_state, + new_payment_state, + ) + + +def cab_cancel( + vendor_state: CabState, + schema_version: str, + ride_id: str, + episode_seed: int = 0, +) -> tuple[ToolResult, CabState]: + if ride_id not in vendor_state.rides: + return ( + ToolResult( + tool_name="cab.cancel", + status="policy_error", + response={"error_code": "MISSING_FIELD", "hint": "ride_id not found"}, + schema_version=schema_version, + latency_ms=_ok_latency(episode_seed, "cab.cancel"), + ), + vendor_state, + ) + new_rides = {k: v for k, v in vendor_state.rides.items() if k != ride_id} + new_state = replace(vendor_state, rides=new_rides) + return ( + ToolResult( + tool_name="cab.cancel", + status="ok", + response={"ride_id": ride_id, "cancelled": True}, + schema_version=schema_version, + latency_ms=_ok_latency(episode_seed, "cab.cancel"), + ), + new_state, + ) + + +def cab_apply_schema_mutation( + vendor_state: CabState, mutation: Mapping[str, Any] +) -> CabState: + state = vendor_state + next_version = state.schema_version + policy = state.policy + pricing = state.pricing + for op, payload in mutation.items(): + if op == "enum_expand": + new_vals = payload.get("vehicle_class_enum", []) if isinstance(payload, dict) else [] + enum = tuple(dict.fromkeys([*policy.vehicle_class_enum, *new_vals])) + policy = replace(policy, vehicle_class_enum=enum) + if next_version == "v1": + next_version = "v2" + elif op == "policy_flag_flip": + if isinstance(payload, dict) and "mini_reject_school_hours" in payload: + policy = replace(policy, mini_reject_school_hours=bool(payload["mini_reject_school_hours"])) + if next_version == "v1": + next_version = "v2" + elif op == "pricing_restructure": + pricing = replace(pricing, fare_breakdown=True) + if next_version in ("v1", "v2"): + next_version = "v3" + elif op == "fee_append": + continue + elif op == "side_channel_notice_append": + state = replace(state, side_channel_notice=str(payload)) + elif op == "tnc_text_swap": + if isinstance(payload, dict) and "cancel_fee_inr" in payload: + state = replace(state, tnc=replace(state.tnc, cancel_fee_inr=int(payload["cancel_fee_inr"]))) + elif op in {"rename", "remove", "require_new_field", "change_type", "numeric_bump", "time_window_shrink", "auth_scope_bump", "token_version_bump"}: + continue + else: + raise UnknownMutationOperatorError(op) + return replace(state, schema_version=next_version, policy=policy, pricing=pricing) + + +def cab_describe_schema(vendor_state: CabState, schema_version: str) -> dict[str, Any]: + if schema_version == "v1": + fields = { + "pickup": "str", + "drop": "str", + "vehicle_class": "str", + "fare_inr": "int", + "eta_min": "int", + } + removed: list[str] = [] + elif schema_version == "v2": + fields = { + "pickup": "str", + "drop": "str", + "vehicle_class": "str", + "fare_inr": "int", + "eta_min": "int", + } + removed = [] + elif schema_version == "v3": + fields = { + "pickup": "str", + "drop": "str", + "vehicle_class": "str", + "fare_breakdown": "dict[str, int]", + "total_inr": "int", + "eta_min": "int", + } + removed = ["fare_inr"] + else: + raise UnknownSchemaVersionError(schema_version) + return {"version": schema_version, "fields": fields, "removed_from_prior": removed} + + +def cab_emit_side_channel_if_pending(vendor_state: CabState) -> tuple[str | None, CabState]: + if vendor_state.side_channel_notice is None: + return None, vendor_state + notice = vendor_state.side_channel_notice + return notice, replace(vendor_state, side_channel_notice=None) + + +CAB_TOOLS: tuple[str, ...] = ("cab.estimate", "cab.book", "cab.cancel") + + +# --------------------------------------------------------------------------- +# Restaurant +# --------------------------------------------------------------------------- + + +@dataclass(frozen=True) +class RestaurantPolicy: + min_order_inr: int = 199 + require_modifiers: bool = False + + +@dataclass(frozen=True) +class RestaurantSemantics: + veg_only_excludes_egg: bool = False + + +@dataclass(frozen=True) +class RestaurantTnC: + refund_window_min: int = 10 + + +@dataclass(frozen=True) +class RestaurantState: + schema_version: str + orders: dict[str, dict[str, Any]] + menu_cache: dict[str, tuple[dict[str, Any], ...]] + policy: RestaurantPolicy + semantics: RestaurantSemantics + tnc: RestaurantTnC + side_channel_notice: str | None + + +_RESTAURANT_MENU: tuple[dict[str, Any], ...] = ( + {"restaurant_id": "BLR-BIR-0123", "city": "Bengaluru", "cuisine": "biryani", + "dishes": ( + {"dish_id": "BIR-001", "name": "Chicken Biryani", "price": 220, "is_veg": False, "has_egg": False}, + {"dish_id": "BIR-002", "name": "Egg Biryani", "price": 180, "is_veg": True, "has_egg": True}, + {"dish_id": "BIR-003", "name": "Veg Biryani", "price": 160, "is_veg": True, "has_egg": False}, + )}, + {"restaurant_id": "BLR-SOU-0456", "city": "Bengaluru", "cuisine": "south_indian", + "dishes": ( + {"dish_id": "DOS-001", "name": "Masala Dosa", "price": 120, "is_veg": True, "has_egg": False}, + {"dish_id": "DOS-002", "name": "Egg Dosa", "price": 140, "is_veg": True, "has_egg": True}, + )}, +) + + +def restaurant_initial_state(episode_seed: int, goal: GoalSpec) -> RestaurantState: + _ = (episode_seed, goal) + return RestaurantState( + schema_version="v1", + orders={}, + menu_cache={}, + policy=RestaurantPolicy(min_order_inr=199), + semantics=RestaurantSemantics(veg_only_excludes_egg=False), + tnc=RestaurantTnC(), + side_channel_notice=None, + ) + + +def restaurant_search( + vendor_state: RestaurantState, + schema_version: str, + city: str, + cuisine: str | None = None, + veg_only: bool = False, + max_price_inr: int | None = None, + episode_seed: int = 0, +) -> ToolResult: + results: list[dict[str, Any]] = [] + for rec in _RESTAURANT_MENU: + if rec["city"].lower() != city.strip().lower(): + continue + if cuisine is not None and rec["cuisine"] != cuisine: + continue + dishes = [] + for dish in rec["dishes"]: + if veg_only and not dish["is_veg"]: + continue + if veg_only and vendor_state.semantics.veg_only_excludes_egg and dish["has_egg"]: + continue + if max_price_inr is not None and int(dish["price"]) > int(max_price_inr): + continue + dishes.append({"dish_id": dish["dish_id"], "name": dish["name"], "price": int(dish["price"])}) + if dishes: + results.append({ + "restaurant_id": rec["restaurant_id"], + "city": rec["city"], + "cuisine": rec["cuisine"], + "dishes": dishes, + }) + return ToolResult( + tool_name="restaurant.search", + status="ok", + response={"results": results}, + schema_version=schema_version, + latency_ms=_ok_latency(episode_seed, "restaurant.search"), + ) + + +def _restaurant_lookup_price(dish_id: str) -> int | None: + for rec in _RESTAURANT_MENU: + for dish in rec["dishes"]: + if dish["dish_id"] == dish_id: + return int(dish["price"]) + return None + + +def _restaurant_order_impl( + vendor_state: RestaurantState, + schema_version: str, + payment_state: PaymentState, + restaurant_id: str, + items: list[dict[str, Any]], + payment_token: str, + episode_seed: int, + now_ist: datetime, +) -> tuple[ToolResult, RestaurantState, PaymentState]: + if schema_version == "v3" or vendor_state.policy.require_modifiers: + for it in items: + if "modifiers" not in it: + return ( + ToolResult( + tool_name="restaurant.order", + status="schema_error", + response={ + "error_code": "INVALID_ITEMS_SHAPE", + "field_name": "items", + "hint": "v3 requires modifiers list on every item", + }, + schema_version=schema_version, + latency_ms=_ok_latency(episode_seed, "restaurant.order"), + ), + vendor_state, + payment_state, + ) + + total = 0 + for it in items: + price = _restaurant_lookup_price(str(it["dish_id"])) + if price is None: + return ( + ToolResult( + tool_name="restaurant.order", + status="schema_error", + response={ + "error_code": "MISSING_FIELD", + "field_name": "dish_id", + "hint": "unknown dish_id", + }, + schema_version=schema_version, + latency_ms=_ok_latency(episode_seed, "restaurant.order"), + ), + vendor_state, + payment_state, + ) + total += price * int(it["qty"]) + + if total < int(vendor_state.policy.min_order_inr): + return ( + ToolResult( + tool_name="restaurant.order", + status="policy_error", + response={ + "error_code": "MIN_ORDER_NOT_MET", + "min_order_inr": int(vendor_state.policy.min_order_inr), + "got_total_inr": int(total), + "hint": "order total below minimum", + }, + schema_version=schema_version, + latency_ms=_ok_latency(episode_seed, "restaurant.order"), + ), + vendor_state, + payment_state, + ) + + idempotency_key = (restaurant_id, _normalize_items(items)) + for existing_id, record in vendor_state.orders.items(): + existing_key = ( + record.get("restaurant_id"), + _normalize_items(list(record.get("items") or [])), + ) + if existing_key == idempotency_key: + return ( + ToolResult( + tool_name="restaurant.order", + status="policy_error", + response={ + "error_code": "DUPLICATE_ORDER", + "existing_id": existing_id, + "original_ts": str(record.get("created_at_ist", "")), + "hint": "identical order already placed", + }, + schema_version=schema_version, + latency_ms=_ok_latency(episode_seed, "restaurant.order"), + ), + vendor_state, + payment_state, + ) + + charge_result, new_payment_state = _payment_charge_internal( + payment_state=payment_state, + amount_inr=total, + payment_token=payment_token, + mfa_code=None, + episode_seed=episode_seed, + order_ref=f"restaurant:{restaurant_id}", + ) + if charge_result.status != "ok": + return ( + _propagate_payment_error(charge_result, "restaurant.order", schema_version, episode_seed), + vendor_state, + payment_state, + ) + + order_id = _make_id("restaurant", episode_seed, "order", idempotency_key, vendor_state.orders) + record_items: list[dict[str, Any]] = [] + for it in items: + entry: dict[str, Any] = {"dish_id": str(it["dish_id"]), "qty": int(it["qty"])} + price = _restaurant_lookup_price(str(it["dish_id"])) + entry["price"] = int(price) if price is not None else 0 + if "modifiers" in it: + entry["modifiers"] = list(it["modifiers"]) + record_items.append(entry) + record = { + "order_id": order_id, + "restaurant_id": restaurant_id, + "items": record_items, + "total": int(total), + "eta_min": 30 + (_stable_digest(episode_seed, order_id) & 0x1F), + "created_at_ist": now_ist.isoformat(), + "payment_status": "captured", + } + new_orders = {**vendor_state.orders, order_id: record} + new_state = replace(vendor_state, orders=new_orders) + response = {k: v for k, v in record.items() if k != "created_at_ist"} + return ( + ToolResult( + tool_name="restaurant.order", + status="ok", + response=response, + schema_version=schema_version, + latency_ms=_ok_latency(episode_seed, "restaurant.order"), + ), + new_state, + new_payment_state, + ) + + +def restaurant_track( + vendor_state: RestaurantState, + schema_version: str, + order_id: str, + episode_seed: int = 0, +) -> ToolResult: + record = vendor_state.orders.get(order_id) + if record is None: + return ToolResult( + tool_name="restaurant.track", + status="schema_error", + response={"error_code": "MISSING_FIELD", "field_name": "order_id", "hint": "unknown order_id"}, + schema_version=schema_version, + latency_ms=_ok_latency(episode_seed, "restaurant.track"), + ) + items = [] + for it in record.get("items", []): + entry = dict(it) + if schema_version == "v3" and "modifiers" not in entry: + entry["modifiers"] = [] + items.append(entry) + payload = { + "order_id": record["order_id"], + "restaurant_id": record["restaurant_id"], + "items": items, + "total": int(record["total"]), + "eta_min": int(record["eta_min"]), + "status": "in_transit", + } + return ToolResult( + tool_name="restaurant.track", + status="ok", + response=payload, + schema_version=schema_version, + latency_ms=_ok_latency(episode_seed, "restaurant.track"), + ) + + +def restaurant_apply_schema_mutation( + vendor_state: RestaurantState, mutation: Mapping[str, Any] +) -> RestaurantState: + state = vendor_state + next_version = state.schema_version + policy = state.policy + semantics = state.semantics + for op, payload in mutation.items(): + if op == "numeric_bump": + if isinstance(payload, dict) and "min_order_inr" in payload: + policy = replace(policy, min_order_inr=int(payload["min_order_inr"])) + if next_version == "v1": + next_version = "v2" + elif op == "require_new_field": + if isinstance(payload, dict) and "modifiers" in payload: + policy = replace(policy, require_modifiers=True) + if next_version in ("v1", "v2"): + next_version = "v3" + elif op == "side_channel_notice_append": + state = replace(state, side_channel_notice=str(payload)) + semantics = replace(semantics, veg_only_excludes_egg=True) + if next_version in ("v1", "v2"): + next_version = "v3" + elif op == "change_type" or op in {"rename", "remove", "enum_expand", "policy_flag_flip", "time_window_shrink", "tnc_text_swap", "pricing_restructure", "fee_append", "auth_scope_bump", "token_version_bump"}: + continue + else: + raise UnknownMutationOperatorError(op) + return replace(state, schema_version=next_version, policy=policy, semantics=semantics) + + +def restaurant_describe_schema(vendor_state: RestaurantState, schema_version: str) -> dict[str, Any]: + if schema_version == "v1": + fields = { + "restaurant_id": "str", + "items": "list[dict]", + "total": "int", + "eta_min": "int", + "min_order_inr": "int", + } + removed: list[str] = [] + elif schema_version == "v2": + fields = { + "restaurant_id": "str", + "items": "list[dict]", + "total": "int", + "eta_min": "int", + "min_order_inr": "int", + } + removed = [] + elif schema_version == "v3": + fields = { + "restaurant_id": "str", + "items": "list[dict{dish_id,qty,modifiers}]", + "total": "int", + "eta_min": "int", + "min_order_inr": "int", + } + removed = [] + else: + raise UnknownSchemaVersionError(schema_version) + return {"version": schema_version, "fields": fields, "removed_from_prior": removed} + + +def restaurant_emit_side_channel_if_pending( + vendor_state: RestaurantState, +) -> tuple[str | None, RestaurantState]: + if vendor_state.side_channel_notice is None: + return None, vendor_state + notice = vendor_state.side_channel_notice + return notice, replace(vendor_state, side_channel_notice=None) + + +RESTAURANT_TOOLS: tuple[str, ...] = ("restaurant.search", "restaurant.order", "restaurant.track") + + +# --------------------------------------------------------------------------- +# Hotel +# --------------------------------------------------------------------------- + + +@dataclass(frozen=True) +class HotelPolicy: + cancel_window_hours: int = 24 + gst_required_threshold_inr: int = 0 # 0 disables + + +@dataclass(frozen=True) +class HotelPricing: + resort_fee_inr: int = 0 + + +@dataclass(frozen=True) +class HotelTnC: + early_checkin_fee_pct: int = 0 + + +@dataclass(frozen=True) +class HotelState: + schema_version: str + bookings: dict[str, dict[str, Any]] + inventory_cache: dict[str, tuple[dict[str, Any], ...]] + policy: HotelPolicy + pricing: HotelPricing + tnc: HotelTnC + side_channel_notice: str | None + + +_HOTEL_INVENTORY: tuple[dict[str, Any], ...] = ( + {"hotel_id": "GOA-BEACH-007", "city": "Goa", "nightly_rate": 3500, "rooms": 12}, + {"hotel_id": "GOA-RESORT-012", "city": "Goa", "nightly_rate": 4200, "rooms": 8}, + {"hotel_id": "BLR-TECH-001", "city": "Bengaluru", "nightly_rate": 2800, "rooms": 30}, + {"hotel_id": "HYD-PARK-022", "city": "Hyderabad", "nightly_rate": 1800, "rooms": 20}, +) + + +def hotel_initial_state(episode_seed: int, goal: GoalSpec) -> HotelState: + _ = (episode_seed, goal) + return HotelState( + schema_version="v1", + bookings={}, + inventory_cache={}, + policy=HotelPolicy(cancel_window_hours=24, gst_required_threshold_inr=0), + pricing=HotelPricing(resort_fee_inr=0), + tnc=HotelTnC(), + side_channel_notice=None, + ) + + +def _hotel_nights(checkin: str, checkout: str) -> int: + ci = datetime.fromisoformat(checkin) + co = datetime.fromisoformat(checkout) + return max(1, (co.date() - ci.date()).days) + + +def _hotel_compute_total(rate: int, nights: int, resort_fee: int) -> int: + subtotal = rate * nights + resort_fee * nights + gst = (subtotal * 18) // 100 + return int(subtotal + gst) + + +def hotel_search( + vendor_state: HotelState, + schema_version: str, + city: str, + checkin: str, + checkout: str, + max_nightly_rate_inr: int | None = None, + episode_seed: int = 0, +) -> ToolResult: + nights = _hotel_nights(checkin, checkout) + results: list[dict[str, Any]] = [] + for rec in _HOTEL_INVENTORY: + if rec["city"].lower() != city.strip().lower(): + continue + if max_nightly_rate_inr is not None and int(rec["nightly_rate"]) > int(max_nightly_rate_inr): + continue + total = _hotel_compute_total(int(rec["nightly_rate"]), nights, int(vendor_state.pricing.resort_fee_inr)) + results.append({ + "hotel_id": rec["hotel_id"], + "city": rec["city"], + "checkin": checkin, + "checkout": checkout, + "nightly_rate": int(rec["nightly_rate"]), + "total_with_tax": int(total), + "cancel_window_hours": int(vendor_state.policy.cancel_window_hours), + }) + return ToolResult( + tool_name="hotel.search", + status="ok", + response={"results": results}, + schema_version=schema_version, + latency_ms=_ok_latency(episode_seed, "hotel.search"), + ) + + +def _hotel_book_impl( + vendor_state: HotelState, + schema_version: str, + payment_state: PaymentState, + hotel_id: str, + checkin: str, + checkout: str, + payment_token: str, + gst_number: str | None, + episode_seed: int, + now_ist: datetime, + primary_guest: str | None = None, +) -> tuple[ToolResult, HotelState, PaymentState]: + rec = next((h for h in _HOTEL_INVENTORY if h["hotel_id"] == hotel_id), None) + if rec is None: + return ( + ToolResult( + tool_name="hotel.book", + status="schema_error", + response={"error_code": "MISSING_FIELD", "field_name": "hotel_id", "hint": "unknown hotel"}, + schema_version=schema_version, + latency_ms=_ok_latency(episode_seed, "hotel.book"), + ), + vendor_state, + payment_state, + ) + + nights = _hotel_nights(checkin, checkout) + total = _hotel_compute_total(int(rec["nightly_rate"]), nights, int(vendor_state.pricing.resort_fee_inr)) + + threshold = int(vendor_state.policy.gst_required_threshold_inr) + if threshold > 0 and total > threshold and not gst_number: + return ( + ToolResult( + tool_name="hotel.book", + status="schema_error", + response={ + "error_code": "MISSING_GST_NUMBER", + "gst_threshold_inr": threshold, + "computed_total_inr": int(total), + "hint": "provide gst_number for bookings above threshold", + }, + schema_version=schema_version, + latency_ms=_ok_latency(episode_seed, "hotel.book"), + ), + vendor_state, + payment_state, + ) + + idempotency_key = ( + hotel_id, + checkin, + checkout, + (primary_guest or "").strip().lower(), + ) + for existing_id, existing in vendor_state.bookings.items(): + existing_key = ( + existing.get("hotel_id"), + existing.get("checkin"), + existing.get("checkout"), + str(existing.get("primary_guest") or "").strip().lower(), + ) + if existing_key == idempotency_key: + return ( + ToolResult( + tool_name="hotel.book", + status="policy_error", + response={ + "error_code": "DUPLICATE_BOOKING", + "existing_id": existing_id, + "original_ts": str(existing.get("created_at_ist", "")), + "hint": "identical hotel booking already exists", + }, + schema_version=schema_version, + latency_ms=_ok_latency(episode_seed, "hotel.book"), + ), + vendor_state, + payment_state, + ) + + charge_result, new_payment_state = _payment_charge_internal( + payment_state=payment_state, + amount_inr=total, + payment_token=payment_token, + mfa_code=None, + episode_seed=episode_seed, + order_ref=f"hotel:{hotel_id}:{checkin}:{checkout}", + ) + if charge_result.status != "ok": + return ( + _propagate_payment_error(charge_result, "hotel.book", schema_version, episode_seed), + vendor_state, + payment_state, + ) + + booking_id = _make_id("hotel", episode_seed, "book", idempotency_key, vendor_state.bookings) + record: dict[str, Any] = { + "booking_id": booking_id, + "hotel_id": hotel_id, + "city": rec["city"], + "checkin": checkin, + "checkout": checkout, + "nightly_rate": int(rec["nightly_rate"]), + "total_with_tax": int(total), + "cancel_window_hours": int(vendor_state.policy.cancel_window_hours), + "primary_guest": primary_guest, + "created_at_ist": now_ist.isoformat(), + "payment_status": "captured", + } + if vendor_state.pricing.resort_fee_inr > 0: + record["resort_fee_inr"] = int(vendor_state.pricing.resort_fee_inr) + if gst_number: + record["gst_number"] = gst_number + new_bookings = {**vendor_state.bookings, booking_id: record} + new_state = replace(vendor_state, bookings=new_bookings) + response = {k: v for k, v in record.items() if k not in ("created_at_ist", "primary_guest")} + return ( + ToolResult( + tool_name="hotel.book", + status="ok", + response=response, + schema_version=schema_version, + latency_ms=_ok_latency(episode_seed, "hotel.book"), + ), + new_state, + new_payment_state, + ) + + +def hotel_cancel( + vendor_state: HotelState, + schema_version: str, + booking_id: str, + episode_seed: int = 0, + now_ist: datetime | None = None, +) -> tuple[ToolResult, HotelState]: + record = vendor_state.bookings.get(booking_id) + if record is None: + return ( + ToolResult( + tool_name="hotel.cancel", + status="policy_error", + response={"error_code": "MISSING_FIELD", "hint": "booking not found"}, + schema_version=schema_version, + latency_ms=_ok_latency(episode_seed, "hotel.cancel"), + ), + vendor_state, + ) + if now_ist is not None: + try: + checkin_dt = datetime.fromisoformat(record["checkin"]).replace(tzinfo=now_ist.tzinfo) + window = timedelta(hours=int(vendor_state.policy.cancel_window_hours)) + if checkin_dt - now_ist < window: + return ( + ToolResult( + tool_name="hotel.cancel", + status="policy_error", + response={"error_code": "CANCEL_WINDOW_EXPIRED", "hint": "cancel window has passed"}, + schema_version=schema_version, + latency_ms=_ok_latency(episode_seed, "hotel.cancel"), + ), + vendor_state, + ) + except (ValueError, KeyError): + pass + new_bookings = {k: v for k, v in vendor_state.bookings.items() if k != booking_id} + new_state = replace(vendor_state, bookings=new_bookings) + return ( + ToolResult( + tool_name="hotel.cancel", + status="ok", + response={"booking_id": booking_id, "cancelled": True}, + schema_version=schema_version, + latency_ms=_ok_latency(episode_seed, "hotel.cancel"), + ), + new_state, + ) + + +def hotel_apply_schema_mutation( + vendor_state: HotelState, mutation: Mapping[str, Any] +) -> HotelState: + state = vendor_state + next_version = state.schema_version + policy = state.policy + pricing = state.pricing + tnc = state.tnc + for op, payload in mutation.items(): + if op == "time_window_shrink": + if isinstance(payload, dict) and "cancel_window_hours" in payload: + policy = replace(policy, cancel_window_hours=int(payload["cancel_window_hours"])) + if next_version == "v1": + next_version = "v2" + elif op == "fee_append": + if isinstance(payload, dict) and "resort_fee_inr" in payload: + pricing = replace(pricing, resort_fee_inr=int(payload["resort_fee_inr"])) + if next_version == "v1": + next_version = "v2" + elif op == "require_new_field": + if isinstance(payload, dict) and "gst_number" in payload: + if policy.gst_required_threshold_inr == 0: + policy = replace(policy, gst_required_threshold_inr=7500) + if next_version in ("v1", "v2"): + next_version = "v3" + elif op == "policy_flag_flip": + if isinstance(payload, dict) and "gst_required_threshold_inr" in payload: + policy = replace(policy, gst_required_threshold_inr=int(payload["gst_required_threshold_inr"])) + if next_version in ("v1", "v2"): + next_version = "v3" + elif op == "tnc_text_swap": + if isinstance(payload, dict) and "early_checkin_fee_pct" in payload: + tnc = replace(tnc, early_checkin_fee_pct=int(payload["early_checkin_fee_pct"])) + elif op == "side_channel_notice_append": + state = replace(state, side_channel_notice=str(payload)) + elif op in {"rename", "remove", "change_type", "numeric_bump", "enum_expand", "pricing_restructure", "auth_scope_bump", "token_version_bump"}: + continue + else: + raise UnknownMutationOperatorError(op) + return replace(state, schema_version=next_version, policy=policy, pricing=pricing, tnc=tnc) + + +def hotel_describe_schema(vendor_state: HotelState, schema_version: str) -> dict[str, Any]: + if schema_version == "v1": + fields = { + "hotel_id": "str", + "city": "str", + "checkin": "str", + "checkout": "str", + "nightly_rate": "int", + "total_with_tax": "int", + "cancel_window_hours": "int", + } + removed: list[str] = [] + elif schema_version == "v2": + fields = { + "hotel_id": "str", + "city": "str", + "checkin": "str", + "checkout": "str", + "nightly_rate": "int", + "total_with_tax": "int", + "cancel_window_hours": "int", + "resort_fee_inr": "int", + } + removed = [] + elif schema_version == "v3": + fields = { + "hotel_id": "str", + "city": "str", + "checkin": "str", + "checkout": "str", + "nightly_rate": "int", + "total_with_tax": "int", + "cancel_window_hours": "int", + "resort_fee_inr": "int", + "gst_number": "str", + } + removed = [] + else: + raise UnknownSchemaVersionError(schema_version) + return {"version": schema_version, "fields": fields, "removed_from_prior": removed} + + +def hotel_emit_side_channel_if_pending(vendor_state: HotelState) -> tuple[str | None, HotelState]: + if vendor_state.side_channel_notice is None: + return None, vendor_state + notice = vendor_state.side_channel_notice + return notice, replace(vendor_state, side_channel_notice=None) + + +HOTEL_TOOLS: tuple[str, ...] = ("hotel.search", "hotel.book", "hotel.cancel") + + +# --------------------------------------------------------------------------- +# Payment +# --------------------------------------------------------------------------- + + +@dataclass(frozen=True) +class PaymentState: + schema_version: str + charges: dict[str, dict[str, Any]] + accepted_token_version: Literal["v1", "v2"] + required_scope: str + mfa_threshold_inr: int + side_channel_notice: str | None + + +_VALID_TOKENS = {"token_v1", "token_v2"} + + +def payment_initial_state(episode_seed: int, goal: GoalSpec) -> PaymentState: + _ = (episode_seed, goal) + return PaymentState( + schema_version="v1", + charges={}, + accepted_token_version="v1", + required_scope="payments:write:v1", + mfa_threshold_inr=0, + side_channel_notice=None, + ) + + +def _token_scope(token: str) -> str | None: + if token == "token_v1": + return "payments:write:v1" + if token == "token_v2": + return "payments:write:v2" + return None + + +def _payment_charge_internal( + payment_state: PaymentState, + amount_inr: int, + payment_token: str, + mfa_code: str | None, + episode_seed: int, + order_ref: str, +) -> tuple[ToolResult, PaymentState]: + """Pure subroutine invoked by primary-domain book/order handlers.""" + + sv = payment_state.schema_version + scope = _token_scope(payment_token) + if scope is None: + return ( + ToolResult( + tool_name="payment.charge", + status="auth_error", + response={"error_code": "TOKEN_INVALID", "hint": "malformed payment_token"}, + schema_version=sv, + latency_ms=_ok_latency(episode_seed, "payment.charge"), + ), + payment_state, + ) + if payment_state.accepted_token_version == "v2" and payment_token == "token_v1": + return ( + ToolResult( + tool_name="payment.charge", + status="auth_error", + response={ + "error_code": "AUTH_SCOPE_INSUFFICIENT", + "required_scope": payment_state.required_scope, + "hint": "request a v2 token", + }, + schema_version=sv, + latency_ms=_ok_latency(episode_seed, "payment.charge"), + ), + payment_state, + ) + if payment_state.mfa_threshold_inr > 0 and int(amount_inr) > payment_state.mfa_threshold_inr and not mfa_code: + return ( + ToolResult( + tool_name="payment.charge", + status="auth_error", + response={ + "error_code": "MFA_REQUIRED", + "mfa_threshold_inr": int(payment_state.mfa_threshold_inr), + "mfa_required": True, + "hint": "provide mfa_code for amounts above threshold", + }, + schema_version=sv, + latency_ms=_ok_latency(episode_seed, "payment.charge"), + ), + payment_state, + ) + + idempotency_key = (order_ref, int(amount_inr), scope) + for existing_id, existing in payment_state.charges.items(): + existing_key = ( + existing.get("order_ref"), + int(existing.get("amount_inr", -1)), + existing.get("token_scope"), + ) + if existing_key == idempotency_key: + return ( + ToolResult( + tool_name="payment.charge", + status="policy_error", + response={ + "error_code": "DUPLICATE_CHARGE", + "existing_id": existing_id, + "original_ts": str(existing.get("created_at_ist", "")), + "hint": "duplicate charge request", + }, + schema_version=sv, + latency_ms=_ok_latency(episode_seed, "payment.charge"), + ), + payment_state, + ) + + charge_id = _make_id("payment", episode_seed, "charge", idempotency_key, payment_state.charges) + record = { + "charge_id": charge_id, + "amount_inr": int(amount_inr), + "order_ref": order_ref, + "token_scope": scope, + "status": "captured", + "created_at_ist": "", + } + new_charges = {**payment_state.charges, charge_id: record} + new_state = replace(payment_state, charges=new_charges) + response = {k: v for k, v in record.items() if k != "created_at_ist"} + return ( + ToolResult( + tool_name="payment.charge", + status="ok", + response=response, + schema_version=sv, + latency_ms=_ok_latency(episode_seed, "payment.charge"), + ), + new_state, + ) + + +def payment_charge( + vendor_state: PaymentState, + schema_version: str, + amount_inr: int, + payment_token: str, + mfa_code: str | None = None, + episode_seed: int = 0, + now_ist: datetime | None = None, + order_ref: str | None = None, +) -> tuple[ToolResult, PaymentState]: + _integer_inr(amount_inr) + ref = order_ref or f"direct:{payment_token}:{amount_inr}" + result, new_state = _payment_charge_internal( + payment_state=vendor_state, + amount_inr=int(amount_inr), + payment_token=payment_token, + mfa_code=mfa_code, + episode_seed=episode_seed, + order_ref=ref, + ) + if result.status == "ok" and now_ist is not None: + updated_record = {**new_state.charges[result.response["charge_id"]]} + updated_record["created_at_ist"] = now_ist.isoformat() + new_charges = {**new_state.charges, result.response["charge_id"]: updated_record} + new_state = replace(new_state, charges=new_charges) + return result, new_state + + +def payment_refund( + vendor_state: PaymentState, + schema_version: str, + charge_id: str, + amount_inr: int, + episode_seed: int = 0, +) -> tuple[ToolResult, PaymentState]: + _integer_inr(amount_inr) + if charge_id not in vendor_state.charges: + return ( + ToolResult( + tool_name="payment.refund", + status="policy_error", + response={"error_code": "MISSING_FIELD", "hint": "charge_id not found"}, + schema_version=schema_version, + latency_ms=_ok_latency(episode_seed, "payment.refund"), + ), + vendor_state, + ) + refund_id = _make_id("payment", episode_seed, "refund", (charge_id, int(amount_inr)), vendor_state.charges) + record = { + "refund_id": refund_id, + "charge_id": charge_id, + "amount_inr": int(amount_inr), + "order_ref": f"refund:{charge_id}", + "token_scope": vendor_state.required_scope, + "status": "refunded", + } + new_charges = {**vendor_state.charges, refund_id: record} + new_state = replace(vendor_state, charges=new_charges) + return ( + ToolResult( + tool_name="payment.refund", + status="ok", + response=record, + schema_version=schema_version, + latency_ms=_ok_latency(episode_seed, "payment.refund"), + ), + new_state, + ) + + +def payment_get_token( + vendor_state: PaymentState, + schema_version: str, + requested_scope: str, + episode_seed: int = 0, +) -> ToolResult: + if requested_scope == "payments:write:v1": + token = "token_v1" + elif requested_scope == "payments:write:v2": + token = "token_v2" + else: + return ToolResult( + tool_name="payment.get_token", + status="auth_error", + response={"error_code": "TOKEN_INVALID", "hint": "unknown scope"}, + schema_version=schema_version, + latency_ms=_ok_latency(episode_seed, "payment.get_token"), + ) + return ToolResult( + tool_name="payment.get_token", + status="ok", + response={"token": token, "scope": requested_scope}, + schema_version=schema_version, + latency_ms=_ok_latency(episode_seed, "payment.get_token"), + ) + + +def payment_apply_schema_mutation( + vendor_state: PaymentState, mutation: Mapping[str, Any] +) -> PaymentState: + state = vendor_state + next_version = state.schema_version + for op, payload in mutation.items(): + if op == "auth_scope_bump": + required = "payments:write:v2" + if isinstance(payload, dict) and "required_scope" in payload: + required = str(payload["required_scope"]) + state = replace(state, accepted_token_version="v2", required_scope=required) + if next_version == "v1": + next_version = "v2" + elif op == "token_version_bump": + state = replace(state, accepted_token_version="v2") + if next_version == "v1": + next_version = "v2" + elif op == "policy_flag_flip": + if isinstance(payload, dict) and "mfa_threshold_inr" in payload: + state = replace(state, mfa_threshold_inr=int(payload["mfa_threshold_inr"])) + if next_version in ("v1", "v2"): + next_version = "v3" + elif op == "side_channel_notice_append": + state = replace(state, side_channel_notice=str(payload)) + elif op in {"rename", "remove", "require_new_field", "change_type", "numeric_bump", "enum_expand", "time_window_shrink", "tnc_text_swap", "pricing_restructure", "fee_append"}: + continue + else: + raise UnknownMutationOperatorError(op) + return replace(state, schema_version=next_version) + + +def payment_describe_schema(vendor_state: PaymentState, schema_version: str) -> dict[str, Any]: + fields = {"amount_inr": "int", "payment_token": "str"} + removed: list[str] = [] + if schema_version == "v1": + pass + elif schema_version == "v2": + fields["required_scope"] = "str" + elif schema_version == "v3": + fields["required_scope"] = "str" + fields["mfa_code"] = "str" + else: + raise UnknownSchemaVersionError(schema_version) + return {"version": schema_version, "fields": fields, "removed_from_prior": removed} + + +def payment_emit_side_channel_if_pending( + vendor_state: PaymentState, +) -> tuple[str | None, PaymentState]: + if vendor_state.side_channel_notice is None: + return None, vendor_state + notice = vendor_state.side_channel_notice + return notice, replace(vendor_state, side_channel_notice=None) + + +PAYMENT_TOOLS: tuple[str, ...] = ("payment.charge", "payment.refund", "payment.get_token") + + +# --------------------------------------------------------------------------- +# Auth cascade propagation (payment → primary domain) +# --------------------------------------------------------------------------- + + +def _propagate_payment_error( + charge_result: ToolResult, + caller_tool: str, + schema_version: str, + episode_seed: int, +) -> ToolResult: + response: dict[str, Any] = {"error_code": "PAYMENT_AUTH_FAILED"} + if charge_result.status == "auth_error": + inner = charge_result.response + if "required_scope" in inner: + response["required_scope"] = inner["required_scope"] + if inner.get("mfa_required") or inner.get("error_code") == "MFA_REQUIRED": + response["mfa_required"] = True + response["hint"] = inner.get("hint", "payment auth failed") + status: Literal["ok", "schema_error", "policy_error", "auth_error", "timeout"] = "auth_error" + else: + response = dict(charge_result.response) + status = charge_result.status + return ToolResult( + tool_name=caller_tool, + status=status, + response=response, + schema_version=schema_version, + latency_ms=_ok_latency(episode_seed, caller_tool), + ) + + +# --------------------------------------------------------------------------- +# Unified dispatch +# --------------------------------------------------------------------------- + + +TOOLS: tuple[str, ...] = ( + *AIRLINE_TOOLS, + *CAB_TOOLS, + *RESTAURANT_TOOLS, + *HOTEL_TOOLS, + *PAYMENT_TOOLS, +) + + +def _split_tool(tool_name: str) -> tuple[str, str]: + if "." not in tool_name: + raise ValueError(f"tool_name must be '.', got {tool_name!r}") + domain, verb = tool_name.split(".", 1) + return domain, verb + + +def airline_dispatch( + tool_name: str, + tool_args: Mapping[str, Any], + vendor_state: AirlineState, + schema_version: str, + episode_seed: int, + now_ist: datetime, + payment_state: PaymentState | None = None, +) -> tuple[ToolResult, AirlineState, PaymentState | None]: + if _is_timeout(episode_seed, tool_name, tool_args): + return _timeout_result(tool_name, episode_seed, schema_version), vendor_state, payment_state + + if tool_name == "airline.search": + result = airline_search( + vendor_state=vendor_state, + schema_version=schema_version, + from_=str(tool_args.get("from", tool_args.get("from_", ""))), + to=str(tool_args.get("to", "")), + date=str(tool_args.get("date", "")), + max_price_inr=tool_args.get("max_price_inr"), + time_window=tool_args.get("time_window"), + episode_seed=episode_seed, + ) + return result, vendor_state, payment_state + if tool_name == "airline.book": + if payment_state is None: + payment_state = payment_initial_state(episode_seed, _stub_goal()) + result, new_state, new_payment = _airline_book_impl( + vendor_state=vendor_state, + schema_version=schema_version, + payment_state=payment_state, + flight_id=str(tool_args.get("flight_id", "")), + payment_token=str(tool_args.get("payment_token", "")), + passenger_count=tool_args.get("passenger_count"), + passenger_name=tool_args.get("passenger_name"), + episode_seed=episode_seed, + now_ist=now_ist, + ) + return result, new_state, new_payment + if tool_name == "airline.cancel": + result, new_state = airline_cancel( + vendor_state=vendor_state, + schema_version=schema_version, + booking_id=str(tool_args.get("booking_id", "")), + episode_seed=episode_seed, + ) + return result, new_state, payment_state + if tool_name == "airline.get_booking": + result = airline_get_booking( + vendor_state=vendor_state, + schema_version=schema_version, + booking_id=str(tool_args.get("booking_id", "")), + episode_seed=episode_seed, + ) + return result, vendor_state, payment_state + raise ValueError(f"unknown airline tool: {tool_name}") + + +def cab_dispatch( + tool_name: str, + tool_args: Mapping[str, Any], + vendor_state: CabState, + schema_version: str, + episode_seed: int, + now_ist: datetime, + payment_state: PaymentState | None = None, +) -> tuple[ToolResult, CabState, PaymentState | None]: + if _is_timeout(episode_seed, tool_name, tool_args): + return _timeout_result(tool_name, episode_seed, schema_version), vendor_state, payment_state + if tool_name == "cab.estimate": + result = cab_estimate( + vendor_state=vendor_state, + schema_version=schema_version, + pickup=str(tool_args.get("pickup", "")), + drop=str(tool_args.get("drop", "")), + vehicle_class=str(tool_args.get("vehicle_class", "mini")), + pickup_time_ist=str(tool_args.get("pickup_time_ist", "")), + episode_seed=episode_seed, + ) + return result, vendor_state, payment_state + if tool_name == "cab.book": + if payment_state is None: + payment_state = payment_initial_state(episode_seed, _stub_goal()) + result, new_state, new_payment = _cab_book_impl( + vendor_state=vendor_state, + schema_version=schema_version, + payment_state=payment_state, + pickup=str(tool_args.get("pickup", "")), + drop=str(tool_args.get("drop", "")), + vehicle_class=str(tool_args.get("vehicle_class", "mini")), + pickup_time_ist=str(tool_args.get("pickup_time_ist", "")), + payment_token=str(tool_args.get("payment_token", "")), + episode_seed=episode_seed, + now_ist=now_ist, + ) + return result, new_state, new_payment + if tool_name == "cab.cancel": + result, new_state = cab_cancel( + vendor_state=vendor_state, + schema_version=schema_version, + ride_id=str(tool_args.get("ride_id", "")), + episode_seed=episode_seed, + ) + return result, new_state, payment_state + raise ValueError(f"unknown cab tool: {tool_name}") + + +def restaurant_dispatch( + tool_name: str, + tool_args: Mapping[str, Any], + vendor_state: RestaurantState, + schema_version: str, + episode_seed: int, + now_ist: datetime, + payment_state: PaymentState | None = None, +) -> tuple[ToolResult, RestaurantState, PaymentState | None]: + if _is_timeout(episode_seed, tool_name, tool_args): + return _timeout_result(tool_name, episode_seed, schema_version), vendor_state, payment_state + if tool_name == "restaurant.search": + result = restaurant_search( + vendor_state=vendor_state, + schema_version=schema_version, + city=str(tool_args.get("city", "")), + cuisine=tool_args.get("cuisine"), + veg_only=bool(tool_args.get("veg_only", False)), + max_price_inr=tool_args.get("max_price_inr"), + episode_seed=episode_seed, + ) + return result, vendor_state, payment_state + if tool_name == "restaurant.order": + if payment_state is None: + payment_state = payment_initial_state(episode_seed, _stub_goal()) + items = list(tool_args.get("items") or []) + result, new_state, new_payment = _restaurant_order_impl( + vendor_state=vendor_state, + schema_version=schema_version, + payment_state=payment_state, + restaurant_id=str(tool_args.get("restaurant_id", "")), + items=items, + payment_token=str(tool_args.get("payment_token", "")), + episode_seed=episode_seed, + now_ist=now_ist, + ) + return result, new_state, new_payment + if tool_name == "restaurant.track": + result = restaurant_track( + vendor_state=vendor_state, + schema_version=schema_version, + order_id=str(tool_args.get("order_id", "")), + episode_seed=episode_seed, + ) + return result, vendor_state, payment_state + raise ValueError(f"unknown restaurant tool: {tool_name}") + + +def hotel_dispatch( + tool_name: str, + tool_args: Mapping[str, Any], + vendor_state: HotelState, + schema_version: str, + episode_seed: int, + now_ist: datetime, + payment_state: PaymentState | None = None, +) -> tuple[ToolResult, HotelState, PaymentState | None]: + if _is_timeout(episode_seed, tool_name, tool_args): + return _timeout_result(tool_name, episode_seed, schema_version), vendor_state, payment_state + if tool_name == "hotel.search": + result = hotel_search( + vendor_state=vendor_state, + schema_version=schema_version, + city=str(tool_args.get("city", "")), + checkin=str(tool_args.get("checkin", "")), + checkout=str(tool_args.get("checkout", "")), + max_nightly_rate_inr=tool_args.get("max_nightly_rate_inr"), + episode_seed=episode_seed, + ) + return result, vendor_state, payment_state + if tool_name == "hotel.book": + if payment_state is None: + payment_state = payment_initial_state(episode_seed, _stub_goal()) + result, new_state, new_payment = _hotel_book_impl( + vendor_state=vendor_state, + schema_version=schema_version, + payment_state=payment_state, + hotel_id=str(tool_args.get("hotel_id", "")), + checkin=str(tool_args.get("checkin", "")), + checkout=str(tool_args.get("checkout", "")), + payment_token=str(tool_args.get("payment_token", "")), + gst_number=tool_args.get("gst_number"), + episode_seed=episode_seed, + now_ist=now_ist, + primary_guest=tool_args.get("primary_guest"), + ) + return result, new_state, new_payment + if tool_name == "hotel.cancel": + result, new_state = hotel_cancel( + vendor_state=vendor_state, + schema_version=schema_version, + booking_id=str(tool_args.get("booking_id", "")), + episode_seed=episode_seed, + now_ist=now_ist, + ) + return result, new_state, payment_state + raise ValueError(f"unknown hotel tool: {tool_name}") + + +def payment_dispatch( + tool_name: str, + tool_args: Mapping[str, Any], + vendor_state: PaymentState, + schema_version: str, + episode_seed: int, + now_ist: datetime, +) -> tuple[ToolResult, PaymentState]: + if _is_timeout(episode_seed, tool_name, tool_args): + return _timeout_result(tool_name, episode_seed, schema_version), vendor_state + if tool_name == "payment.charge": + return payment_charge( + vendor_state=vendor_state, + schema_version=schema_version, + amount_inr=int(tool_args.get("amount_inr", 0)), + payment_token=str(tool_args.get("payment_token", "")), + mfa_code=tool_args.get("mfa_code"), + episode_seed=episode_seed, + now_ist=now_ist, + order_ref=tool_args.get("order_ref"), + ) + if tool_name == "payment.refund": + return payment_refund( + vendor_state=vendor_state, + schema_version=schema_version, + charge_id=str(tool_args.get("charge_id", "")), + amount_inr=int(tool_args.get("amount_inr", 0)), + episode_seed=episode_seed, + ) + if tool_name == "payment.get_token": + result = payment_get_token( + vendor_state=vendor_state, + schema_version=schema_version, + requested_scope=str(tool_args.get("requested_scope", "")), + episode_seed=episode_seed, + ) + return result, vendor_state + raise ValueError(f"unknown payment tool: {tool_name}") + + +def _stub_goal() -> GoalSpec: + return GoalSpec( + domain="airline", + intent="book_flight", + slots={}, + constraints={}, + language="en", + seed_utterance="", + ) + + +# --------------------------------------------------------------------------- +# Vendor namespace registry — exposes the per-domain "module" surface the +# spec calls for while keeping everything in a single cell. +# --------------------------------------------------------------------------- + + +airline = SimpleNamespace( + initial_state=airline_initial_state, + search=airline_search, + cancel=airline_cancel, + get_booking=airline_get_booking, + apply_schema_mutation=airline_apply_schema_mutation, + describe_schema=airline_describe_schema, + emit_side_channel_if_pending=airline_emit_side_channel_if_pending, + dispatch=airline_dispatch, + TOOLS=AIRLINE_TOOLS, +) + +cab = SimpleNamespace( + initial_state=cab_initial_state, + estimate=cab_estimate, + cancel=cab_cancel, + apply_schema_mutation=cab_apply_schema_mutation, + describe_schema=cab_describe_schema, + emit_side_channel_if_pending=cab_emit_side_channel_if_pending, + dispatch=cab_dispatch, + TOOLS=CAB_TOOLS, +) + +restaurant = SimpleNamespace( + initial_state=restaurant_initial_state, + search=restaurant_search, + track=restaurant_track, + apply_schema_mutation=restaurant_apply_schema_mutation, + describe_schema=restaurant_describe_schema, + emit_side_channel_if_pending=restaurant_emit_side_channel_if_pending, + dispatch=restaurant_dispatch, + TOOLS=RESTAURANT_TOOLS, +) + +hotel = SimpleNamespace( + initial_state=hotel_initial_state, + search=hotel_search, + cancel=hotel_cancel, + apply_schema_mutation=hotel_apply_schema_mutation, + describe_schema=hotel_describe_schema, + emit_side_channel_if_pending=hotel_emit_side_channel_if_pending, + dispatch=hotel_dispatch, + TOOLS=HOTEL_TOOLS, +) + +payment = SimpleNamespace( + initial_state=payment_initial_state, + charge=payment_charge, + refund=payment_refund, + get_token=payment_get_token, + apply_schema_mutation=payment_apply_schema_mutation, + describe_schema=payment_describe_schema, + emit_side_channel_if_pending=payment_emit_side_channel_if_pending, + dispatch=payment_dispatch, + TOOLS=PAYMENT_TOOLS, +) + + +VENDOR_REGISTRY: dict[str, SimpleNamespace] = { + "airline": airline, + "cab": cab, + "restaurant": restaurant, + "hotel": hotel, + "payment": payment, +} + + +__all__ = [ + "AirlinePolicy", + "AirlineTnC", + "AirlinePricing", + "AirlineState", + "CabPolicy", + "CabPricing", + "CabTnC", + "CabState", + "RestaurantPolicy", + "RestaurantSemantics", + "RestaurantTnC", + "RestaurantState", + "HotelPolicy", + "HotelPricing", + "HotelTnC", + "HotelState", + "PaymentState", + "UnknownSchemaVersionError", + "UnknownMutationOperatorError", + "TOOLS", + "AIRLINE_TOOLS", + "CAB_TOOLS", + "RESTAURANT_TOOLS", + "HOTEL_TOOLS", + "PAYMENT_TOOLS", + "VENDOR_REGISTRY", + "airline", + "cab", + "restaurant", + "hotel", + "payment", + "airline_initial_state", + "airline_search", + "airline_cancel", + "airline_get_booking", + "airline_apply_schema_mutation", + "airline_describe_schema", + "airline_emit_side_channel_if_pending", + "airline_dispatch", + "cab_initial_state", + "cab_estimate", + "cab_cancel", + "cab_apply_schema_mutation", + "cab_describe_schema", + "cab_emit_side_channel_if_pending", + "cab_dispatch", + "restaurant_initial_state", + "restaurant_search", + "restaurant_track", + "restaurant_apply_schema_mutation", + "restaurant_describe_schema", + "restaurant_emit_side_channel_if_pending", + "restaurant_dispatch", + "hotel_initial_state", + "hotel_search", + "hotel_cancel", + "hotel_apply_schema_mutation", + "hotel_describe_schema", + "hotel_emit_side_channel_if_pending", + "hotel_dispatch", + "payment_initial_state", + "payment_charge", + "payment_refund", + "payment_get_token", + "payment_apply_schema_mutation", + "payment_describe_schema", + "payment_emit_side_channel_if_pending", + "payment_dispatch", +] diff --git a/cells/step_06_drift_injector.md b/cells/step_06_drift_injector.md new file mode 100644 index 0000000000000000000000000000000000000000..9b8b1d17eb40ef4f7c5c47806a749be1e3ac1070 --- /dev/null +++ b/cells/step_06_drift_injector.md @@ -0,0 +1,3 @@ +## Step 06 — Drift Injector + +Schedules, applies, and catalogues the 20 canonical drift patterns (5 schema + 5 policy + 5 T&C + 3 pricing + 2 transversal payment-auth) per DESIGN.md §6 and docs/modules/drift_injector.md. Deterministic scheduler (blake2b-seeded RNG) produces `()`, `(e,)`, or `(e1, e2)` for stage 1/2/3; `apply_drift` returns a new frozen `DriftCallState` with mutated vendor schema, bumped schema version, and the fired event appended. diff --git a/cells/step_06_drift_injector.py b/cells/step_06_drift_injector.py new file mode 100644 index 0000000000000000000000000000000000000000..728e7111a24f03d6182e3426fe3c745fd7698922 --- /dev/null +++ b/cells/step_06_drift_injector.py @@ -0,0 +1,732 @@ +"""DriftCall drift injector. + +Implements docs/modules/drift_injector.md. Public surface: + +- build_schedule(stage, episode_seed, goal) -> tuple[DriftEvent, ...] +- apply_drift(state, event) -> DriftCallState +- list_patterns() -> tuple[DriftPattern, ...] + +The 20-pattern catalogue is embedded as a module-level constant (one +source of truth; no YAML dependency at runtime). Patterns are keyed by +`pattern_id` per drift_injector.md §4.1. + +Error taxonomy (drift_injector.md §5): + +- ValueError — stage not in {1,2,3} +- UnknownDriftPatternError — event.pattern_id not in registry +- DriftDomainMismatchError — event.domain not in state.vendor_states +- DriftReapplicationError — event already present in state.drift_fired +- DriftCatalogueError — catalogue loads < 20 patterns (startup) +- DriftScheduleConflictError — stage-3 schedule cannot be built within + retry budget, or max_turns < 8 for stage 3 +""" + +from __future__ import annotations + +import copy +import hashlib +import random +import struct +from dataclasses import dataclass, replace +from types import MappingProxyType +from typing import TYPE_CHECKING, Any, Literal + +if TYPE_CHECKING: + from collections.abc import Mapping + +from cells.step_04_models import DriftCallState, DriftEvent, GoalSpec + +DriftTypeLiteral = Literal["schema", "policy", "tnc", "pricing", "auth"] + +__all__ = [ + "DriftCatalogueError", + "DriftDomainMismatchError", + "DriftPattern", + "DriftReapplicationError", + "DriftScheduleConflictError", + "UnknownDriftPatternError", + "apply_drift", + "build_schedule", + "list_patterns", +] + + +# --------------------------------------------------------------------------- +# Errors (drift_injector.md §5) +# --------------------------------------------------------------------------- + + +class UnknownDriftPatternError(Exception): + """Raised when apply_drift receives a DriftEvent whose description is + not a key in the pattern registry.""" + + +class DriftDomainMismatchError(Exception): + """Raised when the event's domain is not a key of state.vendor_states.""" + + +class DriftReapplicationError(Exception): + """Raised when apply_drift is called with an event already present in + state.drift_fired. Defence-in-depth per spec §2.""" + + +class DriftCatalogueError(Exception): + """Raised at startup when the embedded catalogue contains fewer than + 20 patterns.""" + + +class DriftScheduleConflictError(Exception): + """Raised when build_schedule cannot produce a valid stage-3 schedule + (max_turns too small, or retry budget exhausted).""" + + +# --------------------------------------------------------------------------- +# DriftPattern dataclass (drift_injector.md §4.2) +# --------------------------------------------------------------------------- + + +@dataclass(frozen=True) +class DriftPattern: + id: str + drift_type: DriftTypeLiteral + domain: str + from_version: str + to_version: str + description: str + mutation: Mapping[str, Any] + detection_hints: tuple[str, ...] + + def __post_init__(self) -> None: + # Wrap mutation in MappingProxyType for immutability without mutating + # a frozen instance — use object.__setattr__ (frozen-safe per stdlib). + if not isinstance(self.mutation, MappingProxyType): + object.__setattr__(self, "mutation", MappingProxyType(dict(self.mutation))) + + +# --------------------------------------------------------------------------- +# 20-pattern catalogue (drift_injector.md §4.4, byte-identical to DESIGN.md §6.3) +# --------------------------------------------------------------------------- + + +_CATALOGUE_RAW: tuple[dict[str, Any], ...] = ( + # Schema (5) + { + "id": "airline.price_rename", + "drift_type": "schema", + "domain": "airline", + "from_version": "v1", + "to_version": "v2", + "description": "field 'price' renamed to 'total_fare_inr'; 'currency' removed", + "mutation": { + "rename": {"price": "total_fare_inr"}, + "remove": ["currency"], + }, + "detection_hints": ("total_fare_inr", "price", "rename"), + }, + { + "id": "airline.pax_required", + "drift_type": "schema", + "domain": "airline", + "from_version": "v2", + "to_version": "v3", + "description": "booking now requires 'passenger_count' field", + "mutation": { + "require_new_field": ["passenger_count"], + }, + "detection_hints": ("passenger_count", "MISSING_PASSENGER_COUNT"), + }, + { + "id": "cab.fare_breakdown", + "drift_type": "schema", + "domain": "cab", + "from_version": "v2", + "to_version": "v3", + "description": "'fare_inr' replaced by nested 'fare_breakdown' object", + "mutation": { + "change_type": {"fare_inr": "fare_breakdown"}, + "require_new_field": ["fare_breakdown"], + "remove": ["fare_inr"], + }, + "detection_hints": ("fare_breakdown", "base", "surge", "tolls", "gst"), + }, + { + "id": "restaurant.items_shape_bump", + "drift_type": "schema", + "domain": "restaurant", + "from_version": "v1", + "to_version": "v2", + "description": "items[] entries now require a 'modifiers' array", + "mutation": { + "require_new_field": ["modifiers"], + }, + "detection_hints": ("modifiers", "items", "require"), + }, + { + "id": "hotel.gst_field", + "drift_type": "schema", + "domain": "hotel", + "from_version": "v2", + "to_version": "v3", + "description": "hotel.book requires 'gst_number' when total > 7500", + "mutation": { + "require_new_field": ["gst_number"], + }, + "detection_hints": ("gst_number", "gst", "7500"), + }, + # Policy (5) + { + "id": "airline.booking_window_shrink", + "drift_type": "policy", + "domain": "airline", + "from_version": "v1", + "to_version": "v2", + "description": "same-day bookings rejected after 14:00 IST", + "mutation": { + "time_window_shrink": {"same_day_cutoff": "14:00"}, + "policy_flag_flip": {"same_day_allowed": False}, + }, + "detection_hints": ("14:00", "same-day", "policy_error", "booking_window"), + }, + { + "id": "cab.school_hours_mini_reject", + "drift_type": "policy", + "domain": "cab", + "from_version": "v1", + "to_version": "v2", + "description": "vehicle_class=mini rejected during 07:00-09:00 IST", + "mutation": { + "time_window_shrink": {"mini_blackout": ["07:00", "09:00"]}, + "policy_flag_flip": {"mini_school_hours": False}, + }, + "detection_hints": ("mini", "07:00", "09:00", "policy_error", "school"), + }, + { + "id": "restaurant.min_order_bump", + "drift_type": "policy", + "domain": "restaurant", + "from_version": "v1", + "to_version": "v2", + "description": "minimum order raised from 199 to 299 INR", + "mutation": { + "numeric_bump": {"min_order_inr": {"from": 199, "to": 299}}, + }, + "detection_hints": ("299", "199", "min_order", "minimum"), + }, + { + "id": "hotel.cancel_window_shrink", + "drift_type": "policy", + "domain": "hotel", + "from_version": "v1", + "to_version": "v2", + "description": "free cancellation window shrunk 24h to 6h", + "mutation": { + "numeric_bump": {"cancel_window_hours": {"from": 24, "to": 6}}, + }, + "detection_hints": ("6h", "24h", "cancel_window", "cancel"), + }, + { + "id": "cab.vehicle_class_expand", + "drift_type": "policy", + "domain": "cab", + "from_version": "v1", + "to_version": "v2", + "description": "vehicle_class enum expanded with suv and infant_seat_sedan", + "mutation": { + "enum_expand": {"vehicle_class": ["suv", "infant_seat_sedan"]}, + }, + "detection_hints": ("suv", "infant_seat_sedan", "vehicle_class"), + }, + # T&C (5) + { + "id": "airline.baggage_tnc_rewrite", + "drift_type": "tnc", + "domain": "airline", + "from_version": "v1", + "to_version": "v2", + "description": "cabin baggage allowance reduced from 7kg to 5kg", + "mutation": { + "tnc_text_swap": { + "from": "free cabin baggage 7kg", + "to": "free cabin baggage 5kg", + }, + "side_channel_notice_append": "baggage_allowance_change_7_to_5", + }, + "detection_hints": ("5kg", "7kg", "baggage", "cabin"), + }, + { + "id": "cab.surge_policy_tnc", + "drift_type": "tnc", + "domain": "cab", + "from_version": "v1", + "to_version": "v2", + "description": "surge may apply retroactively if ride extended", + "mutation": { + "tnc_text_swap": { + "from": "surge fixed at booking", + "to": "surge applies retroactively on extension", + }, + "side_channel_notice_append": "surge_retroactive_notice", + }, + "detection_hints": ("surge", "retroactive", "extend", "tnc"), + }, + { + "id": "restaurant.veg_filter_semantic", + "drift_type": "tnc", + "domain": "restaurant", + "from_version": "v2", + "to_version": "v3", + "description": "veg_only=True now excludes egg dishes (was included)", + "mutation": { + "tnc_text_swap": { + "from": "veg_only includes egg", + "to": "veg_only excludes egg", + }, + "side_channel_notice_append": "veg_only_egg_exclusion", + }, + "detection_hints": ("veg_only", "egg", "exclude"), + }, + { + "id": "hotel.early_checkin_tnc", + "drift_type": "tnc", + "domain": "hotel", + "from_version": "v1", + "to_version": "v2", + "description": "early check-in before 12:00 billed at 50% of nightly rate", + "mutation": { + "tnc_text_swap": { + "from": "early check-in free subject to availability", + "to": "early check-in billed 50% of nightly rate", + }, + "side_channel_notice_append": "early_checkin_billed", + }, + "detection_hints": ("early", "check-in", "50%", "12:00"), + }, + { + "id": "airline.reschedule_tnc", + "drift_type": "tnc", + "domain": "airline", + "from_version": "v2", + "to_version": "v3", + "description": "reschedule fee previously waived is now 10% of fare", + "mutation": { + "tnc_text_swap": { + "from": "reschedule waived", + "to": "reschedule fee 10% of fare", + }, + "side_channel_notice_append": "reschedule_fee_10pct", + }, + "detection_hints": ("reschedule", "10%", "fare", "fee"), + }, + # Pricing (3) + { + "id": "airline.convenience_fee_append", + "drift_type": "pricing", + "domain": "airline", + "from_version": "v2", + "to_version": "v3", + "description": "hidden INR 199 convenience fee added at booking", + "mutation": { + "fee_append": {"convenience_fee_inr": 199}, + "pricing_restructure": {"hidden_fees": True}, + }, + "detection_hints": ("199", "convenience_fee", "fee", "hidden"), + }, + { + "id": "cab.toll_unbundle", + "drift_type": "pricing", + "domain": "cab", + "from_version": "v2", + "to_version": "v3", + "description": "tolls previously included, now separate line item at booking", + "mutation": { + "fee_append": {"tolls_inr": 0}, + "pricing_restructure": {"toll_unbundled": True}, + }, + "detection_hints": ("toll", "tolls", "unbundle", "line item"), + }, + { + "id": "hotel.resort_fee_append", + "drift_type": "pricing", + "domain": "hotel", + "from_version": "v2", + "to_version": "v3", + "description": "resort fee of INR 500 per night added at booking", + "mutation": { + "fee_append": {"resort_fee_inr": 500}, + "pricing_restructure": {"resort_fee_hidden": True}, + }, + "detection_hints": ("resort_fee", "500", "per night", "resort"), + }, + # Auth (2, transversal on payment) + { + "id": "payment.auth_scope_upgrade", + "drift_type": "auth", + "domain": "payment", + "from_version": "v1", + "to_version": "v2", + "description": "token_v1 401s; token_v2 with scope=payments:write:v2 required", + "mutation": { + "auth_scope_bump": {"required_scope": "payments:write:v2"}, + "token_version_bump": {"from": "token_v1", "to": "token_v2"}, + }, + "detection_hints": ("token_v2", "payments:write:v2", "scope", "401", "auth"), + }, + { + "id": "payment.mfa_required", + "drift_type": "auth", + "domain": "payment", + "from_version": "v2", + "to_version": "v3", + "description": "transactions above INR 5000 require mfa_code in payload", + "mutation": { + "auth_scope_bump": {"required_field": "mfa_code"}, + "token_version_bump": {"threshold_inr": 5000}, + }, + "detection_hints": ("mfa_code", "mfa_required", "5000", "mfa"), + }, +) + + +def _load_catalogue() -> tuple[DriftPattern, ...]: + patterns = tuple( + DriftPattern( + id=entry["id"], + drift_type=entry["drift_type"], + domain=entry["domain"], + from_version=entry["from_version"], + to_version=entry["to_version"], + description=entry["description"], + mutation=entry["mutation"], + detection_hints=tuple(entry["detection_hints"]), + ) + for entry in _CATALOGUE_RAW + ) + if len(patterns) < 20: + raise DriftCatalogueError( + f"expected 20 patterns in catalogue, got {len(patterns)}", + ) + # Sort by id for stable ordering (spec §2 list_patterns contract). + return tuple(sorted(patterns, key=lambda p: p.id)) + + +_PATTERNS: tuple[DriftPattern, ...] = _load_catalogue() +_PATTERNS_BY_ID: dict[str, DriftPattern] = {p.id: p for p in _PATTERNS} +_PATTERNS_BY_DOMAIN: dict[str, tuple[DriftPattern, ...]] = {} +for _p in _PATTERNS: + _PATTERNS_BY_DOMAIN.setdefault(_p.domain, ()) + _PATTERNS_BY_DOMAIN[_p.domain] = (*_PATTERNS_BY_DOMAIN[_p.domain], _p) + + +def list_patterns() -> tuple[DriftPattern, ...]: + """Return all 20 registered drift patterns, sorted by id.""" + return _PATTERNS + + +# --------------------------------------------------------------------------- +# Deterministic RNG helpers (drift_injector.md §3.3) +# --------------------------------------------------------------------------- + + +def _derive_seed(stage: int, episode_seed: int, domain: str) -> int: + """Blake2b-based seed derivation — hash-stable across PYTHONHASHSEED.""" + payload = f"drift|{stage}|{episode_seed}|{domain}".encode() + digest = hashlib.blake2b(payload, digest_size=8).digest() + (seed,) = struct.unpack(" DriftPattern | None: + pool = tuple( + p for p in _PATTERNS_BY_DOMAIN.get(domain, ()) if p.id not in exclude_ids + ) + if not pool: + return None + return rng.choice(pool) + + +def _event_from_pattern(pattern: DriftPattern, turn: int) -> DriftEvent: + return DriftEvent( + turn=turn, + drift_type=pattern.drift_type, + domain=pattern.domain, + description=pattern.description, + from_version=pattern.from_version, + to_version=pattern.to_version, + pattern_id=pattern.id, + ) + + +def build_schedule( + stage: int, + episode_seed: int, + goal: GoalSpec, + *, + max_turns: int = _DEFAULT_MAX_TURNS, +) -> tuple[DriftEvent, ...]: + """Build the drift schedule for an episode. See drift_injector.md §2.""" + if stage not in (1, 2, 3): + raise ValueError(f"unknown stage: {stage!r} (expected 1, 2, or 3)") + + if stage == 1: + return () + + rng = random.Random(_derive_seed(stage, episode_seed, goal.domain)) + lo = 2 + hi = max_turns - 3 + if hi < lo: + raise DriftScheduleConflictError( + f"max_turns={max_turns} too small for any drift placement", + ) + + first_pattern = _pick_pattern_for_domain(rng, goal.domain, frozenset()) + if first_pattern is None: + # Fallback: goal.domain has no pattern; pick any. + first_pattern = rng.choice(_PATTERNS) + + if stage == 2: + turn = rng.randint(lo, hi) + return (_event_from_pattern(first_pattern, turn),) + + # stage == 3 — need two drifts, distance >= 2, different pattern_ids. + if max_turns < 8: + raise DriftScheduleConflictError( + f"max_turns={max_turns} too small for stage-3 schedule (need >= 8)", + ) + + # first_turn must leave room for second_turn >= first_turn + 2 within [lo, hi]. + first_hi_by_window = max_turns // 2 + first_hi = min(first_hi_by_window, hi - 2) + if first_hi < lo: + raise DriftScheduleConflictError( + f"max_turns={max_turns} leaves no room for stage-3 first drift", + ) + first_turn = rng.randint(lo, first_hi) + + second_lo = first_turn + 2 + if second_lo > hi: + raise DriftScheduleConflictError( + f"max_turns={max_turns} leaves no room for stage-3 second drift", + ) + second_turn = rng.randint(second_lo, hi) + + # Second-drift domain: 80% same as goal.domain, 20% payment cross-domain. + cross_domain_roll = rng.random() + second_domain = "payment" if cross_domain_roll < 0.20 else goal.domain + + second_pattern: DriftPattern | None = None + for _attempt in range(5): + candidate = _pick_pattern_for_domain( + rng, + second_domain, + frozenset({first_pattern.id}), + ) + if candidate is not None: + second_pattern = candidate + break + # Swap domain on miss (e.g., if same-domain pool is already exhausted). + second_domain = "payment" if second_domain == goal.domain else goal.domain + + if second_pattern is None: + # Last resort: any pattern in catalogue other than first. + remaining = tuple(p for p in _PATTERNS if p.id != first_pattern.id) + if not remaining: + raise DriftScheduleConflictError( + "unable to build stage-3 schedule: no distinct second pattern", + ) + second_pattern = rng.choice(remaining) + + return ( + _event_from_pattern(first_pattern, first_turn), + _event_from_pattern(second_pattern, second_turn), + ) + + +# --------------------------------------------------------------------------- +# Mutation dispatch (drift_injector.md §3.4) +# --------------------------------------------------------------------------- + + +def _apply_rename(target: dict[str, Any], rename_map: Mapping[str, str]) -> None: + for old_key, new_key in rename_map.items(): + if old_key in target: + target[new_key] = target.pop(old_key) + else: + target.setdefault(new_key, None) + + +def _apply_remove(target: dict[str, Any], remove_keys: list[str]) -> None: + for key in remove_keys: + target.pop(key, None) + + +def _apply_require_new_field(target: dict[str, Any], fields: list[str]) -> None: + existing = target.setdefault("required_fields", []) + if isinstance(existing, list): + for f in fields: + if f not in existing: + existing.append(f) + + +def _apply_change_type(target: dict[str, Any], types_map: Mapping[str, str]) -> None: + bucket = target.setdefault("type_changes", {}) + if isinstance(bucket, dict): + bucket.update({k: v for k, v in types_map.items()}) + + +def _apply_enum_expand(target: dict[str, Any], enum_map: Mapping[str, list[str]]) -> None: + for enum_name, additions in enum_map.items(): + current = target.setdefault(enum_name, []) + if isinstance(current, list): + for v in additions: + if v not in current: + current.append(v) + + +def _apply_numeric_bump(target: dict[str, Any], bumps: Mapping[str, Mapping[str, Any]]) -> None: + for key, change in bumps.items(): + if "to" in change: + target[key] = change["to"] + + +def _apply_policy_flag_flip(target: dict[str, Any], flags: Mapping[str, bool]) -> None: + flag_bucket = target.setdefault("flags", {}) + if isinstance(flag_bucket, dict): + for k, v in flags.items(): + flag_bucket[k] = v + + +def _apply_time_window_shrink(target: dict[str, Any], windows: Mapping[str, Any]) -> None: + bucket = target.setdefault("time_windows", {}) + if isinstance(bucket, dict): + for k, v in windows.items(): + bucket[k] = v + + +def _apply_tnc_text_swap(target: dict[str, Any], swap: Mapping[str, str]) -> None: + target["tnc_text"] = swap.get("to", target.get("tnc_text")) + + +def _apply_side_channel_notice(target: dict[str, Any], notice: str) -> None: + notices = target.setdefault("side_channel", []) + if isinstance(notices, list): + notices.append(notice) + + +def _apply_pricing_restructure(target: dict[str, Any], change: Mapping[str, Any]) -> None: + bucket = target.setdefault("pricing_flags", {}) + if isinstance(bucket, dict): + for k, v in change.items(): + bucket[k] = v + + +def _apply_fee_append(target: dict[str, Any], fees: Mapping[str, Any]) -> None: + bucket = target.setdefault("fees", {}) + if isinstance(bucket, dict): + for k, v in fees.items(): + bucket[k] = v + + +def _apply_auth_scope_bump(target: dict[str, Any], scope: Mapping[str, Any]) -> None: + bucket = target.setdefault("auth", {}) + if isinstance(bucket, dict): + for k, v in scope.items(): + bucket[k] = v + + +def _apply_token_version_bump(target: dict[str, Any], bump: Mapping[str, Any]) -> None: + bucket = target.setdefault("auth", {}) + if isinstance(bucket, dict): + for k, v in bump.items(): + bucket[k] = v + + +_OPERATOR_DISPATCH: dict[str, Any] = { + "rename": _apply_rename, + "remove": _apply_remove, + "require_new_field": _apply_require_new_field, + "change_type": _apply_change_type, + "enum_expand": _apply_enum_expand, + "numeric_bump": _apply_numeric_bump, + "policy_flag_flip": _apply_policy_flag_flip, + "time_window_shrink": _apply_time_window_shrink, + "tnc_text_swap": _apply_tnc_text_swap, + "side_channel_notice_append": _apply_side_channel_notice, + "pricing_restructure": _apply_pricing_restructure, + "fee_append": _apply_fee_append, + "auth_scope_bump": _apply_auth_scope_bump, + "token_version_bump": _apply_token_version_bump, +} + + +def _mutate_vendor_state( + vendor_state: dict[str, Any], + pattern: DriftPattern, +) -> dict[str, Any]: + """Return a mutated deep copy of the vendor state for the given pattern. + Pure with respect to inputs (input dict is not modified).""" + mutated = copy.deepcopy(vendor_state) + for op_key, op_payload in pattern.mutation.items(): + handler = _OPERATOR_DISPATCH.get(op_key) + if handler is None: + # Unknown operator keys are tolerated as no-ops so catalogue + # extensions don't break existing callers. + continue + handler(mutated, op_payload) + return mutated + + +# --------------------------------------------------------------------------- +# apply_drift (drift_injector.md §2, §3.5) +# --------------------------------------------------------------------------- + + +def apply_drift(state: DriftCallState, event: DriftEvent) -> DriftCallState: + """Apply a drift event to immutable state; return a new DriftCallState.""" + pattern = _PATTERNS_BY_ID.get(event.pattern_id) + if pattern is None: + raise UnknownDriftPatternError( + f"no pattern registered for pattern_id: {event.pattern_id!r}", + ) + if event.domain not in state.vendor_states: + raise DriftDomainMismatchError( + f"event.domain={event.domain!r} not in state.vendor_states", + ) + if event in state.drift_fired: + raise DriftReapplicationError( + f"event already in drift_fired: {event!r}", + ) + + # Build new vendor_states dict with mutated copy for event.domain. + new_vendor_states: dict[str, dict[str, Any]] = { + k: copy.deepcopy(v) for k, v in state.vendor_states.items() + } + new_vendor_states[event.domain] = _mutate_vendor_state( + state.vendor_states[event.domain], + pattern, + ) + + new_schema_versions = dict(state.schema_versions) + new_schema_versions[event.domain] = event.to_version + + new_drift_fired = state.drift_fired + (event,) + + return replace( + state, + vendor_states=new_vendor_states, + schema_versions=new_schema_versions, + drift_fired=new_drift_fired, + ) + + diff --git a/cells/step_07_task_generator.md b/cells/step_07_task_generator.md new file mode 100644 index 0000000000000000000000000000000000000000..3919507564eec0965733d78fb62c6bb1b9c7e51b --- /dev/null +++ b/cells/step_07_task_generator.md @@ -0,0 +1,3 @@ +# Generate task briefs + +Pure, seeded, deterministic procedural generator that expands the YAML template library into concrete `GoalSpec` briefs for `DriftCallEnv.reset()`. Identical `(seed, stage, language_weights)` triples always produce byte-identical seed utterances after NFC normalization — no global RNG, no `time.time()`, no `hash()`. diff --git a/cells/step_07_task_generator.py b/cells/step_07_task_generator.py new file mode 100644 index 0000000000000000000000000000000000000000..9ceee279e1b3d1a3c9e1b8b344989d24b6a7ae66 --- /dev/null +++ b/cells/step_07_task_generator.py @@ -0,0 +1,1164 @@ +"""Cell 07 — Procedural task-brief generator. + +Implements docs/modules/task_generator.md. Pure, seeded, deterministic +expansion of a YAML template library into concrete ``GoalSpec`` briefs +for ``DriftCallEnv.reset()`` (DESIGN.md §4.2, §8.3, §8.4). + +Contract: identical ``(seed, stage, language_weights)`` triples always +produce byte-identical ``GoalSpec.seed_utterance`` after NFC +normalization. No global mutable state; no ``random.random()``; no +``time.time()``; no ``hash()``. All stochastic choices thread through +``random.Random(stable_sub_seed(seed, tag))`` where ``stable_sub_seed`` +uses ``hashlib.blake2b(digest_size=8)``. +""" + +from __future__ import annotations + +import hashlib +import random +import re +import string +import unicodedata +from collections.abc import Iterator, Mapping +from dataclasses import dataclass +from datetime import date, timedelta +from pathlib import Path +from typing import Any, Literal, cast + +import yaml + +from cells.step_04_models import GoalSpec + +# --------------------------------------------------------------------------- +# Public literal types +# --------------------------------------------------------------------------- + +LanguageCode = Literal["hi", "ta", "kn", "en", "hinglish"] +Domain = Literal["airline", "cab", "restaurant", "hotel"] + +_LANGUAGE_CODES: frozenset[str] = frozenset({"hi", "ta", "kn", "en", "hinglish"}) +_DOMAINS: frozenset[str] = frozenset({"airline", "cab", "restaurant", "hotel"}) +_VALID_STAGES: frozenset[int] = frozenset({1, 2, 3}) + +# Fixed reference date for deterministic date sampling (task_generator.md §3.3). +_REFERENCE_DATE: date = date(2026, 4, 25) +_DATE_WINDOW_DAYS: int = 60 + +# SMS-length bound for ASR input (§3.6 invariant 7). +_MAX_UTTERANCE_LEN: int = 280 + +# Built-in slot conventions — §3.3 of task_generator.md. Templates may +# override by declaring slot_distributions explicitly; otherwise these +# name-based defaults apply. +_DATE_SLOT_NAMES: frozenset[str] = frozenset( + { + "when", + "checkin", + "checkout", + "date", + "departure", + "arrival", + "return_when", + "new_when", + } +) +_INTER_CITY_SLOT_NAMES: frozenset[str] = frozenset( + {"from", "to", "city", "origin", "destination"} +) +_INTRA_CITY_SLOT_NAMES: frozenset[str] = frozenset({"pickup", "drop"}) + +# Default domain → city-code tuples (IATA-style). Authored here so the +# generator is self-contained without requiring the YAML library to +# declare a cities_by_domain block. +_DEFAULT_INTER_CITIES: tuple[str, ...] = ( + "HYD", + "BLR", + "DEL", + "BOM", + "MAA", + "CCU", + "PNQ", + "AMD", + "JAI", + "GOI", +) +_DEFAULT_INTRA_CITIES: tuple[str, ...] = ( + "Koramangala", + "Indiranagar", + "Whitefield", + "Andheri", + "Bandra", + "Powai", + "Gurgaon", + "Saket", + "Banjara Hills", + "Salt Lake", +) +_DEFAULT_CITIES_BY_DOMAIN: Mapping[Domain, tuple[str, ...]] = { + "airline": _DEFAULT_INTER_CITIES, + "hotel": _DEFAULT_INTER_CITIES, + "restaurant": _DEFAULT_INTER_CITIES, + "cab": _DEFAULT_INTRA_CITIES, +} + + +# --------------------------------------------------------------------------- +# Exception hierarchy (task_generator.md §5) +# --------------------------------------------------------------------------- + + +class TaskGeneratorError(Exception): + """Base class for every failure raised by :mod:`step_07_task_generator`.""" + + +class MissingSlotError(TaskGeneratorError): + """Template variant references a ``{slot}`` placeholder not present in the filled SlotGrid.""" + + +class InvalidLanguageError(TaskGeneratorError): + """``language_weights`` contains a key outside :data:`LanguageCode`.""" + + +class InvalidLanguageWeightError(TaskGeneratorError): + """``language_weights`` is empty, has a negative value, sums off 1.0, or is all zero.""" + + +class InvalidStageError(TaskGeneratorError): + """``stage`` is not one of ``{1, 2, 3}``.""" + + +class InvalidBudgetError(TaskGeneratorError): + """Sampled numeric constraint falls outside the template's declared ``[low, high]`` range.""" + + +class TemplateFileMissingError(TaskGeneratorError): + """Template YAML file not found or unreadable.""" + + +class TemplateSchemaError(TaskGeneratorError): + """Template YAML present but fails schema validation.""" + + +class UnicodeNormalizationError(TaskGeneratorError): + """Rendered utterance fails NFC round-trip check (defensive).""" + + +class NoVariantForLanguageError(TaskGeneratorError): + """Chosen template has no ``language_variants`` entry for the chosen language.""" + + +# --------------------------------------------------------------------------- +# In-memory types (task_generator.md §4.2) +# --------------------------------------------------------------------------- + + +@dataclass(frozen=True) +class SlotDistribution: + """Either an enum (``choices``) or a uniform numeric grid (``low``, ``high``, ``step``).""" + + kind: Literal["choices", "uniform", "date", "bool"] + choices: tuple[str, ...] | None = None + low: float | None = None + high: float | None = None + step: float | None = None + + +@dataclass(frozen=True) +class Template: + template_id: str + domain: Domain + intent: str + min_stage: Literal[1, 2, 3] + required_slots: tuple[str, ...] + optional_slots: tuple[str, ...] + slot_distributions: Mapping[str, SlotDistribution] + constraints_template: Mapping[str, SlotDistribution] + drift_slot_tags: tuple[str, ...] + language_variants: Mapping[LanguageCode, tuple[str, ...]] + + +@dataclass(frozen=True) +class TemplateLibrary: + templates: tuple[Template, ...] + cities_by_domain: Mapping[Domain, tuple[str, ...]] + i18n: Mapping[LanguageCode, Mapping[str, str]] + + +@dataclass(frozen=True) +class SlotGrid: + """Concrete slot values after expansion.""" + + values: Mapping[str, object] + + +@dataclass(frozen=True) +class RawBrief: + template_id: str + domain: Domain + intent: str + slots: SlotGrid + constraints: Mapping[str, object] + language: LanguageCode + + +# --------------------------------------------------------------------------- +# Sub-seed helper (task_generator.md §3.1) +# --------------------------------------------------------------------------- + + +def stable_sub_seed(seed: int, tag: str) -> int: + """Return a stable 64-bit integer derived from ``(seed, tag)``. + + Uses blake2b with ``digest_size=8`` so the formula is pinned and + domain-separated across decision tags. + """ + digest = hashlib.blake2b(f"{seed}:{tag}".encode(), digest_size=8).digest() + return int.from_bytes(digest, "big") + + +# --------------------------------------------------------------------------- +# NFC helpers +# --------------------------------------------------------------------------- + + +def _nfc(text: str) -> str: + return unicodedata.normalize("NFC", text) + + +def _assert_nfc(text: str, *, where: str) -> None: + if not unicodedata.is_normalized("NFC", text): + raise UnicodeNormalizationError( + f"string at {where} failed NFC round-trip: {text!r}" + ) + + +# --------------------------------------------------------------------------- +# Template loader (task_generator.md §2.2, §3.4, §7 edge cases 1 & 8) +# --------------------------------------------------------------------------- + + +def _parse_distribution(raw: Mapping[str, Any], *, where: str) -> SlotDistribution: + """Parse a single slot/constraint distribution block.""" + if "choices" in raw: + choices = raw["choices"] + if not isinstance(choices, list) or not choices: + raise TemplateSchemaError(f"{where}: 'choices' must be non-empty list") + norm_choices = tuple(_nfc(str(c)) for c in choices) + return SlotDistribution(kind="choices", choices=norm_choices) + if raw.get("distribution") == "uniform": + for key in ("low", "high", "step"): + if key not in raw: + raise TemplateSchemaError(f"{where}: uniform missing '{key}'") + low = float(raw["low"]) + high = float(raw["high"]) + step = float(raw["step"]) + if step <= 0: + raise TemplateSchemaError(f"{where}: step must be > 0 (got {step})") + if low > high: + raise TemplateSchemaError(f"{where}: low > high ({low} > {high})") + span = high - low + # Grid must terminate cleanly at ``high`` (§7 edge case 8). + # Use integer step check avoiding floating-point drift. + ratio = span / step + if abs(ratio - round(ratio)) > 1e-9: + raise TemplateSchemaError( + f"{where}: step grid misaligned " + f"(low={low}, high={high}, step={step}) — (high-low) not divisible by step" + ) + return SlotDistribution(kind="uniform", low=low, high=high, step=step) + if raw.get("distribution") == "date": + return SlotDistribution(kind="date") + if raw.get("distribution") == "bool": + return SlotDistribution(kind="bool") + raise TemplateSchemaError( + f"{where}: unrecognized distribution descriptor {dict(raw)!r}" + ) + + +def _parse_template(raw: Mapping[str, Any], *, where: str) -> Template: + required_keys = ( + "template_id", + "domain", + "intent", + "min_stage", + "required_slots", + "optional_slots", + "constraints_template", + "drift_slot_tags", + "language_variants", + ) + for key in required_keys: + if key not in raw: + raise TemplateSchemaError(f"{where}: missing required key {key!r}") + + template_id = _nfc(str(raw["template_id"])) + domain_raw = str(raw["domain"]) + if domain_raw not in _DOMAINS: + raise TemplateSchemaError( + f"{where}: domain {domain_raw!r} not in {sorted(_DOMAINS)}" + ) + min_stage = int(raw["min_stage"]) + if min_stage not in _VALID_STAGES: + raise TemplateSchemaError( + f"{where}: min_stage {min_stage} not in {sorted(_VALID_STAGES)}" + ) + + required_slots = tuple(_nfc(str(s)) for s in raw["required_slots"]) + optional_slots = tuple(_nfc(str(s)) for s in raw["optional_slots"]) + drift_slot_tags = tuple(_nfc(str(s)) for s in raw["drift_slot_tags"]) + + slot_distributions_raw = raw.get("slot_distributions", {}) or {} + slot_distributions: dict[str, SlotDistribution] = {} + for name, block in slot_distributions_raw.items(): + slot_distributions[_nfc(str(name))] = _parse_distribution( + block, where=f"{where}.slot_distributions.{name}" + ) + + constraints_template: dict[str, SlotDistribution] = {} + for name, block in raw["constraints_template"].items(): + constraints_template[_nfc(str(name))] = _parse_distribution( + block, where=f"{where}.constraints_template.{name}" + ) + + language_variants_raw = raw["language_variants"] + if not isinstance(language_variants_raw, dict): + raise TemplateSchemaError(f"{where}: language_variants must be a mapping") + language_variants: dict[LanguageCode, tuple[str, ...]] = {} + for lang, variants in language_variants_raw.items(): + if lang not in _LANGUAGE_CODES: + raise TemplateSchemaError( + f"{where}: language key {lang!r} not in {sorted(_LANGUAGE_CODES)}" + ) + if not isinstance(variants, list) or not variants: + raise TemplateSchemaError( + f"{where}.language_variants.{lang}: must be non-empty list" + ) + language_variants[cast("LanguageCode", lang)] = tuple( + _nfc(str(v)) for v in variants + ) + + # Every template must have ≥ 1 variant per LanguageCode (§7 edge case 7). + for code in _LANGUAGE_CODES: + if code not in language_variants: + raise TemplateSchemaError( + f"{where}: language_variants missing required code {code!r}" + ) + + # Static placeholder scan (§7 edge case 1). + declared_placeholders = ( + set(required_slots) + | set(optional_slots) + | set(constraints_template.keys()) + ) + for lang, variants in language_variants.items(): + for variant in variants: + for placeholder in _iter_placeholders(variant): + if placeholder not in declared_placeholders: + raise TemplateSchemaError( + f"{where}.language_variants.{lang}: variant references " + f"undeclared placeholder {placeholder!r} in {variant!r}" + ) + + return Template( + template_id=template_id, + domain=cast("Domain", domain_raw), + intent=_nfc(str(raw["intent"])), + min_stage=cast("Literal[1, 2, 3]", min_stage), + required_slots=required_slots, + optional_slots=optional_slots, + slot_distributions=slot_distributions, + constraints_template=constraints_template, + drift_slot_tags=drift_slot_tags, + language_variants=language_variants, + ) + + +def _iter_placeholders(fmt: str) -> Iterator[str]: + """Yield placeholder names in a format string (ignores literals).""" + for _literal, field_name, _spec, _conv in string.Formatter().parse(fmt): + if field_name is not None and field_name != "": + yield field_name + + +def load_templates( + path: str | Path = "data/task_briefs/templates.yaml", + i18n_path: str | Path | None = None, +) -> TemplateLibrary: + """Parse the template YAML file and return an in-memory :class:`TemplateLibrary`. + + ``i18n_path`` defaults to ``data/task_briefs/i18n.yaml`` alongside + ``path``. All strings are NFC-normalized on read (§3.4). + """ + templates_path = Path(path) + if not templates_path.exists(): + raise TemplateFileMissingError(f"templates YAML not found: {templates_path}") + + if i18n_path is None: + i18n_path = templates_path.parent / "i18n.yaml" + i18n_path = Path(i18n_path) + + try: + with templates_path.open("r", encoding="utf-8") as fh: + raw_templates = yaml.safe_load(fh) + except yaml.YAMLError as exc: + raise TemplateSchemaError(f"templates YAML malformed: {exc}") from exc + + if raw_templates is None: + raise TemplateSchemaError("templates YAML is empty") + + parsed_templates: list[Template] = [] + cities_by_domain: dict[Domain, tuple[str, ...]] = {} + + if isinstance(raw_templates, dict): + tmpl_list = raw_templates.get("templates", []) + raw_cities = raw_templates.get("cities_by_domain", {}) or {} + for dom, lst in raw_cities.items(): + if dom not in _DOMAINS: + raise TemplateSchemaError(f"cities_by_domain: bad domain {dom!r}") + cities_by_domain[cast("Domain", dom)] = tuple(_nfc(str(c)) for c in lst) + elif isinstance(raw_templates, list): + tmpl_list = raw_templates + else: + raise TemplateSchemaError( + f"templates YAML root must be list or mapping, got {type(raw_templates).__name__}" + ) + + if not isinstance(tmpl_list, list) or not tmpl_list: + raise TemplateSchemaError("templates YAML must contain a non-empty list") + + for idx, raw in enumerate(tmpl_list): + if not isinstance(raw, dict): + raise TemplateSchemaError( + f"templates[{idx}]: entry must be a mapping, got {type(raw).__name__}" + ) + parsed_templates.append(_parse_template(raw, where=f"templates[{idx}]")) + + # i18n file is optional; if absent we use an empty mapping. + _LANG_CODES: tuple[LanguageCode, ...] = ("hi", "ta", "kn", "en", "hinglish") + i18n_data: dict[LanguageCode, dict[str, str]] = {code: {} for code in _LANG_CODES} + if i18n_path.exists(): + try: + with i18n_path.open("r", encoding="utf-8") as fh: + raw_i18n = yaml.safe_load(fh) or {} + except yaml.YAMLError as exc: + raise TemplateSchemaError(f"i18n YAML malformed: {exc}") from exc + if not isinstance(raw_i18n, dict): + raise TemplateSchemaError("i18n YAML root must be a mapping") + for lang, block in raw_i18n.items(): + if lang not in _LANGUAGE_CODES: + raise TemplateSchemaError( + f"i18n: language key {lang!r} not in {sorted(_LANGUAGE_CODES)}" + ) + if not isinstance(block, dict): + raise TemplateSchemaError(f"i18n.{lang}: must be a mapping") + flat: dict[str, str] = {} + _flatten_i18n(block, prefix="", out=flat) + i18n_data[cast("LanguageCode", lang)] = { + _nfc(str(k)): _nfc(str(v)) for k, v in flat.items() + } + + return TemplateLibrary( + templates=tuple(parsed_templates), + cities_by_domain=cities_by_domain, + i18n=i18n_data, + ) + + +def _flatten_i18n(block: Mapping[str, Any], *, prefix: str, out: dict[str, str]) -> None: + """Flatten nested i18n dicts into dotted keys, NFC everything.""" + for k, v in block.items(): + key = f"{prefix}.{k}" if prefix else str(k) + if isinstance(v, dict): + _flatten_i18n(v, prefix=key, out=out) + else: + out[key] = str(v) + + +# --------------------------------------------------------------------------- +# Lazy singleton +# --------------------------------------------------------------------------- + +_library_cache: TemplateLibrary | None = None +_library_override: TemplateLibrary | None = None + + +def _get_library() -> TemplateLibrary: + """Return the process-wide TemplateLibrary, loading lazily.""" + if _library_override is not None: + return _library_override + global _library_cache + if _library_cache is None: + _library_cache = _load_default_library() + return _library_cache + + +def _load_default_library() -> TemplateLibrary: + """Try the production path, then fall back to the packaged inline library.""" + default_path = Path("data/task_briefs/templates.yaml") + if default_path.exists(): + return load_templates(default_path) + return _builtin_library() + + +def set_library_override(library: TemplateLibrary | None) -> None: + """Test hook: pin :func:`_get_library` to a specific library (or clear).""" + global _library_override + _library_override = library + + +def reset_library_cache() -> None: + """Test hook: clear the lazy cache so the next call reloads.""" + global _library_cache + _library_cache = None + + +# --------------------------------------------------------------------------- +# Built-in library (fallback when data/ isn't authored yet) +# --------------------------------------------------------------------------- + + +def _builtin_library() -> TemplateLibrary: + """Minimal 5-template library so the generator is self-contained during dev.""" + # Shared numeric grids. + budget_flight = SlotDistribution(kind="uniform", low=3000.0, high=15000.0, step=500.0) + budget_hotel = SlotDistribution(kind="uniform", low=2000.0, high=10000.0, step=500.0) + budget_cab = SlotDistribution(kind="uniform", low=200.0, high=2000.0, step=50.0) + budget_food = SlotDistribution(kind="uniform", low=200.0, high=1000.0, step=50.0) + time_window = SlotDistribution( + kind="choices", choices=("morning", "afternoon", "evening", "late_night") + ) + date_dist = SlotDistribution(kind="date") + veg_only = SlotDistribution(kind="bool") + pax = SlotDistribution(kind="uniform", low=1.0, high=4.0, step=1.0) + + cities_inter = ( + "HYD", + "BLR", + "DEL", + "BOM", + "MAA", + "CCU", + "PNQ", + "AMD", + "JAI", + "GOI", + ) + cities_intra = ( + "Koramangala", + "Indiranagar", + "Whitefield", + "Andheri", + "Bandra", + "Powai", + "Gurgaon", + "Saket", + "Banjara Hills", + "Salt Lake", + ) + + airline = Template( + template_id="airline.book.fixture_v1", + domain="airline", + intent="book_flight", + min_stage=1, + required_slots=("from", "to", "when"), + optional_slots=(), + slot_distributions={ + "from": SlotDistribution(kind="choices", choices=cities_inter), + "to": SlotDistribution(kind="choices", choices=cities_inter), + "when": date_dist, + }, + constraints_template={ + "budget_inr": budget_flight, + "time_window": time_window, + }, + drift_slot_tags=("price", "total_fare_inr"), + language_variants={ + "hinglish": ( + "Bhai {when} ko {from} se {to} jaana hai, {budget_inr} rupees max, {time_window}", + ), + "hi": ( + "{when} को {from} से {to} जाना है, {budget_inr} रुपये से कम, {time_window}", + ), + "ta": ( + "{when} அன்று {from} லிருந்து {to} டிக்கெட் வேண்டும், {budget_inr} ரூபாய் கீழ், {time_window}", + ), + "kn": ( + "{when} ರಂದು {from} ಇಂದ {to} ಗೆ ಟಿಕೆಟ್ ಬೇಕು, {budget_inr} ರೂಪಾಯಿ ಒಳಗೆ, {time_window}", + ), + "en": ( + "Flight from {from} to {to} on {when}, under ₹{budget_inr}, {time_window}", + ), + }, + ) + + cab = Template( + template_id="cab.book.fixture_v1", + domain="cab", + intent="book_cab", + min_stage=1, + required_slots=("pickup", "drop", "when"), + optional_slots=(), + slot_distributions={ + "pickup": SlotDistribution(kind="choices", choices=cities_intra), + "drop": SlotDistribution(kind="choices", choices=cities_intra), + "when": date_dist, + }, + constraints_template={ + "budget_inr": budget_cab, + "vehicle_class": SlotDistribution( + kind="choices", choices=("mini", "sedan", "suv") + ), + }, + drift_slot_tags=("fare_inr", "fare_breakdown"), + language_variants={ + "hinglish": ( + "{when} ko {pickup} se {drop} cab chahiye, {budget_inr} ke andar, {vehicle_class}", + ), + "hi": ( + "{when} को {pickup} से {drop} कैब चाहिए, {budget_inr} के अंदर, {vehicle_class}", + ), + "ta": ( + "{when} அன்று {pickup} லிருந்து {drop} கேப், {budget_inr} கீழ், {vehicle_class}", + ), + "kn": ( + "{when} ರಂದು {pickup} ಇಂದ {drop} ಟ್ಯಾಕ್ಸಿ, {budget_inr} ಒಳಗೆ, {vehicle_class}", + ), + "en": ( + "Cab from {pickup} to {drop} on {when}, under ₹{budget_inr}, {vehicle_class}", + ), + }, + ) + + restaurant = Template( + template_id="restaurant.order.fixture_v1", + domain="restaurant", + intent="order_food", + min_stage=2, + required_slots=("city", "cuisine", "when"), + optional_slots=(), + slot_distributions={ + "city": SlotDistribution(kind="choices", choices=cities_inter), + "cuisine": SlotDistribution( + kind="choices", choices=("Biryani", "Dosa", "Pizza", "Thali", "Noodles") + ), + "when": date_dist, + }, + constraints_template={ + "budget_inr": budget_food, + "veg_only": veg_only, + }, + drift_slot_tags=("min_order", "veg_filter"), + language_variants={ + "hinglish": ( + "Bhai {when} ko {city} mein {cuisine} order karna hai, {budget_inr} ke andar, veg_only={veg_only}", + ), + "hi": ( + "{when} को {city} में {cuisine} ऑर्डर करना है, {budget_inr} के अंदर, veg_only={veg_only}", + ), + "ta": ( + "{when} அன்று {city} இல் {cuisine} ஆர்டர், {budget_inr} கீழ், veg_only={veg_only}", + ), + "kn": ( + "{when} ರಂದು {city} ನಲ್ಲಿ {cuisine} ಆರ್ಡರ್, {budget_inr} ಒಳಗೆ, veg_only={veg_only}", + ), + "en": ( + "Order {cuisine} in {city} on {when}, under ₹{budget_inr}, veg_only={veg_only}", + ), + }, + ) + + hotel = Template( + template_id="hotel.book.fixture_v1", + domain="hotel", + intent="book_hotel", + min_stage=2, + required_slots=("city", "checkin", "checkout"), + optional_slots=(), + slot_distributions={ + "city": SlotDistribution(kind="choices", choices=cities_inter), + "checkin": date_dist, + "checkout": date_dist, + }, + constraints_template={ + "budget_inr": budget_hotel, + "room_type": SlotDistribution( + kind="choices", choices=("single", "double", "suite") + ), + }, + drift_slot_tags=("cancel_window", "gst_number"), + language_variants={ + "hinglish": ( + "{city} mein {checkin} se {checkout} tak hotel chahiye, {budget_inr} per night, {room_type}", + ), + "hi": ( + "{city} में {checkin} से {checkout} तक होटल चाहिए, {budget_inr} प्रति रात, {room_type}", + ), + "ta": ( + "{city} இல் {checkin} முதல் {checkout} வரை ஹோட்டல், {budget_inr} ஒரு இரவு, {room_type}", + ), + "kn": ( + "{city} ನಲ್ಲಿ {checkin} ಇಂದ {checkout} ವರೆಗೆ ಹೋಟೆಲ್, {budget_inr} ಒಂದು ರಾತ್ರಿ, {room_type}", + ), + "en": ( + "Hotel in {city} from {checkin} to {checkout}, ₹{budget_inr} per night, {room_type}", + ), + }, + ) + + # Stage-3 compound-constraint airline template — adds a third constraint. + airline_compound = Template( + template_id="airline.book.compound_v1", + domain="airline", + intent="book_flight", + min_stage=3, + required_slots=("from", "to", "when"), + optional_slots=(), + slot_distributions={ + "from": SlotDistribution(kind="choices", choices=cities_inter), + "to": SlotDistribution(kind="choices", choices=cities_inter), + "when": date_dist, + }, + constraints_template={ + "budget_inr": budget_flight, + "time_window": time_window, + "passenger_count": pax, + }, + drift_slot_tags=("price", "total_fare_inr", "passenger_count"), + language_variants={ + "hinglish": ( + "{when} ko {from} se {to}, {passenger_count} log, {budget_inr} max, {time_window}", + ), + "hi": ( + "{when} को {from} से {to}, {passenger_count} लोग, {budget_inr} रुपये, {time_window}", + ), + "ta": ( + "{when} அன்று {from} லிருந்து {to}, {passenger_count} பேர், {budget_inr} ரூபாய், {time_window}", + ), + "kn": ( + "{when} ರಂದು {from} ಇಂದ {to}, {passenger_count} ಜನ, {budget_inr} ರೂಪಾಯಿ, {time_window}", + ), + "en": ( + "Flight {from} to {to} on {when} for {passenger_count} pax, ₹{budget_inr}, {time_window}", + ), + }, + ) + + return TemplateLibrary( + templates=(airline, cab, restaurant, hotel, airline_compound), + cities_by_domain={ + "airline": cities_inter, + "hotel": cities_inter, + "cab": cities_intra, + "restaurant": cities_inter, + }, + i18n={ + "hi": {"cities.BLR": "बेंगलुरु", "cities.MAA": "चेन्नई"}, + "ta": {"cities.BLR": "பெங்களூரு", "cities.MAA": "சென்னை"}, + "kn": {"cities.BLR": "ಬೆಂಗಳೂರು", "cities.MAA": "ಚೆನ್ನೈ"}, + "en": {"cities.BLR": "Bengaluru"}, + "hinglish": {"cities.BLR": "Bengaluru"}, + }, + ) + + +# --------------------------------------------------------------------------- +# Picker + expander (task_generator.md §2.2, §3.2, §3.3) +# --------------------------------------------------------------------------- + + +def _pick_domain(seed: int, library: TemplateLibrary, stage: int) -> Domain: + """Pick uniformly from domains that have ≥ 1 eligible template at ``stage``.""" + available = sorted({t.domain for t in library.templates if t.min_stage <= stage}) + if not available: + raise TemplateSchemaError( + f"library has no templates eligible at stage={stage}" + ) + rng = random.Random(stable_sub_seed(seed, "domain")) + return rng.choice(available) + + +def _eligible_templates( + library: TemplateLibrary, + stage: int, + domain: Domain, +) -> tuple[Template, ...]: + return tuple( + t for t in library.templates if t.domain == domain and t.min_stage <= stage + ) + + +def _pick_template( + seed: int, + stage: int, + domain: Domain, + library: TemplateLibrary, +) -> Template: + eligible = _eligible_templates(library, stage, domain) + if not eligible: + raise TemplateSchemaError( + f"no eligible templates for domain={domain!r} stage={stage}" + ) + rng = random.Random(stable_sub_seed(seed, "template")) + # Use sorted template_ids for deterministic ordering. + ordered = tuple(sorted(eligible, key=lambda t: t.template_id)) + return rng.choice(ordered) + + +def _sample_slot_value( + rng: random.Random, + name: str, + dist: SlotDistribution, + *, + template_id: str, +) -> object: + if dist.kind == "choices": + if not dist.choices: + raise TemplateSchemaError( + f"{template_id}.{name}: empty choices list" + ) + return rng.choice(dist.choices) + if dist.kind == "uniform": + assert dist.low is not None and dist.high is not None and dist.step is not None + steps = int(round((dist.high - dist.low) / dist.step)) + pick = rng.randint(0, steps) + value = dist.low + pick * dist.step + # Integer-ify when step + bounds are integral. + if float(int(dist.step)) == dist.step and float(int(dist.low)) == dist.low: + value = int(round(value)) + # Post-check (§7 edge case 3). + lo = int(dist.low) if isinstance(value, int) else dist.low + hi = int(dist.high) if isinstance(value, int) else dist.high + if not (lo <= value <= hi): + raise InvalidBudgetError( + f"{template_id}.{name}: sampled {value} outside [{dist.low}, {dist.high}]" + ) + return value + if dist.kind == "date": + offset = rng.randint(0, _DATE_WINDOW_DAYS - 1) + return (_REFERENCE_DATE + timedelta(days=offset)).isoformat() + if dist.kind == "bool": + return bool(rng.getrandbits(1)) + raise TemplateSchemaError( + f"{template_id}.{name}: unknown distribution kind {dist.kind!r}" + ) + + +def _resolve_slot_distribution( + template: Template, + name: str, + library: TemplateLibrary, +) -> SlotDistribution | None: + """Resolve a slot's distribution, preferring explicit declaration then conventions.""" + explicit = template.slot_distributions.get(name) + if explicit is not None: + return explicit + # Constraints block can also declare slot distributions that double as fills. + constraint = template.constraints_template.get(name) + if constraint is not None: + return constraint + # Conventional fills by slot name. + if name in _DATE_SLOT_NAMES: + return SlotDistribution(kind="date") + if name in _INTER_CITY_SLOT_NAMES: + pool = library.cities_by_domain.get(template.domain) or _DEFAULT_CITIES_BY_DOMAIN.get( + template.domain, _DEFAULT_INTER_CITIES + ) + return SlotDistribution(kind="choices", choices=pool) + if name in _INTRA_CITY_SLOT_NAMES: + pool = library.cities_by_domain.get(template.domain) or _DEFAULT_INTRA_CITIES + return SlotDistribution(kind="choices", choices=pool) + return None + + +def _expand_slots( + seed: int, + template: Template, + *, + stage: int, + library: TemplateLibrary, +) -> tuple[SlotGrid, dict[str, object]]: + """Sample one concrete value per required slot; stage-aware constraint pick. + + Returns ``(SlotGrid, constraints_dict)``. + """ + values: dict[str, object] = {} + + # Required slots — always sampled. + for name in template.required_slots: + dist = _resolve_slot_distribution(template, name, library) + if dist is None: + raise TemplateSchemaError( + f"{template.template_id}: required slot {name!r} has no distribution " + f"(declare in slot_distributions or use a conventional name)" + ) + rng = random.Random(stable_sub_seed(seed, f"slot:{name}")) + values[name] = _sample_slot_value(rng, name, dist, template_id=template.template_id) + + # Optional slots — included with probability 0.5 (seeded). Silently + # skipped if no distribution resolves (template declares the slot as + # available but does not wire a fill source). + for name in template.optional_slots: + dist = _resolve_slot_distribution(template, name, library) + if dist is None: + continue + rng = random.Random(stable_sub_seed(seed, f"opt:{name}")) + if rng.random() < 0.5: + sub_rng = random.Random(stable_sub_seed(seed, f"slot:{name}")) + values[name] = _sample_slot_value( + sub_rng, name, dist, template_id=template.template_id + ) + + # Constraints — stage-aware sub-selection (§3.5). + max_constraints = {1: 2, 2: 3, 3: 4}[stage] + constraint_names = list(template.constraints_template.keys()) + # Stage 1: keep only the first max_constraints deterministically. + # Stage 2/3: include all declared constraints up to max. + kept = constraint_names[:max_constraints] + constraints: dict[str, object] = {} + for name in kept: + dist = template.constraints_template[name] + rng = random.Random(stable_sub_seed(seed, f"constraint:{name}")) + value = _sample_slot_value( + rng, name, dist, template_id=template.template_id + ) + constraints[name] = value + # Also mirror into slots so variant-format can reference {budget_inr}. + values[name] = value + + # NFC-normalize any string leaves. + for k, v in list(values.items()): + if isinstance(v, str): + values[k] = _nfc(v) + for k, v in list(constraints.items()): + if isinstance(v, str): + constraints[k] = _nfc(v) + + return SlotGrid(values=values), constraints + + +# --------------------------------------------------------------------------- +# Language picker +# --------------------------------------------------------------------------- + + +def _validate_language_weights(language_weights: Mapping[str, float]) -> None: + """Raise on any malformed input per §3.2.""" + if not isinstance(language_weights, Mapping) or len(language_weights) == 0: + raise InvalidLanguageWeightError("language_weights is empty") + + bad_keys = [k for k in language_weights if k not in _LANGUAGE_CODES] + if bad_keys: + raise InvalidLanguageError( + f"unsupported language key(s): {bad_keys} " + f"(allowed: {sorted(_LANGUAGE_CODES)})" + ) + + for k, v in language_weights.items(): + if not isinstance(v, (int, float)) or isinstance(v, bool): + raise InvalidLanguageWeightError( + f"language_weights[{k!r}] must be numeric, got {type(v).__name__}" + ) + if v < 0: + raise InvalidLanguageWeightError( + f"language_weights[{k!r}]={v} is negative" + ) + + total = sum(float(v) for v in language_weights.values()) + if abs(total - 1.0) > 1e-6: + raise InvalidLanguageWeightError( + f"language_weights sum {total!r} outside [1-1e-6, 1+1e-6]" + ) + + # Defensive all-zero check (§3.2 last bullet). + if all(float(v) == 0.0 for v in language_weights.values()): + raise InvalidLanguageWeightError( + "language_weights are all zero (would have no population to sample)" + ) + + +def _pick_language( + seed: int, + language_weights: Mapping[LanguageCode, float], +) -> LanguageCode: + rng = random.Random(stable_sub_seed(seed, "language")) + # Deterministic ordering of keys for reproducibility across dict insertion orders. + codes = sorted(language_weights.keys()) + weights = [float(language_weights[c]) for c in codes] + chosen = rng.choices(codes, weights=weights, k=1)[0] + return chosen + + +# --------------------------------------------------------------------------- +# Utterance formatter +# --------------------------------------------------------------------------- + + +_PLACEHOLDER_RE = re.compile(r"\{([a-zA-Z_][a-zA-Z0-9_]*)\}") + + +def _format_utterance( + seed: int, + template: Template, + slots: SlotGrid, + language: LanguageCode, +) -> str: + variants = template.language_variants.get(language) + if not variants: + raise NoVariantForLanguageError( + f"template {template.template_id!r} has no variants for language {language!r}" + ) + rng = random.Random(stable_sub_seed(seed, "variant")) + chosen = rng.choice(tuple(variants)) + + # Render by placeholder-by-placeholder substitution so a missing slot + # raises MissingSlotError with the exact field name rather than whatever + # ``str.format`` would surface. + def _repl(match: re.Match[str]) -> str: + name = match.group(1) + if name not in slots.values: + raise MissingSlotError( + f"template {template.template_id!r} variant references {{{name}}} " + f"but slot is unbound (slots={sorted(slots.values)})" + ) + value = slots.values[name] + if isinstance(value, bool): + return "true" if value else "false" + if isinstance(value, float): + # Trim trailing zeros for cleanness, but keep determinism. + if value.is_integer(): + return str(int(value)) + return str(value) + return str(value) + + rendered = _PLACEHOLDER_RE.sub(_repl, chosen) + normalized = _nfc(rendered) + _assert_nfc(normalized, where=f"utterance({template.template_id}, {language})") + return normalized + + +# --------------------------------------------------------------------------- +# Primary entry point +# --------------------------------------------------------------------------- + + +def generate( + seed: int, + stage: Literal[1, 2, 3], + language_weights: Mapping[LanguageCode, float], +) -> GoalSpec: + """Produce one :class:`GoalSpec` for episode ``seed`` at curriculum ``stage``. + + Determinism: identical ``(seed, stage, language_weights)`` ⇒ identical + ``GoalSpec`` after NFC normalization of ``seed_utterance``. + """ + # Stage validation (cheapest first). + if stage not in _VALID_STAGES: + raise InvalidStageError( + f"stage must be in {sorted(_VALID_STAGES)}, got {stage!r}" + ) + + _validate_language_weights(cast("Mapping[str, float]", language_weights)) + + library = _get_library() + + domain = _pick_domain(seed, library, int(stage)) + template = _pick_template(seed, int(stage), domain, library) + slot_grid, constraints = _expand_slots( + seed, template, stage=int(stage), library=library + ) + language = _pick_language(seed, language_weights) + utterance = _format_utterance(seed, template, slot_grid, language) + + if len(utterance) > _MAX_UTTERANCE_LEN: + # Truncate is incorrect (breaks determinism/meaning). Raise so the + # template author shortens the variant. + raise TemplateSchemaError( + f"rendered utterance exceeds {_MAX_UTTERANCE_LEN} chars " + f"({len(utterance)}): {utterance!r}" + ) + + # Slot dict exposed on GoalSpec should exclude constraint-named entries — + # those live in ``constraints``. ``required_slots`` + included optionals only. + slot_keys = set(template.required_slots) | set(template.optional_slots) + slots_out = {k: v for k, v in slot_grid.values.items() if k in slot_keys} + + return GoalSpec( + domain=template.domain, + intent=template.intent, + slots=slots_out, + constraints=constraints, + language=language, + seed_utterance=utterance, + ) + + +# --------------------------------------------------------------------------- +# Variant enumerator (task_generator.md §2.2) +# --------------------------------------------------------------------------- + + +def enumerate_variants( + limit: int | None = None, + stage: int = 3, + language_weights: Mapping[LanguageCode, float] | None = None, +) -> Iterator[GoalSpec]: + """Deterministic walk over the procedural grid.""" + if stage not in _VALID_STAGES: + raise InvalidStageError(f"stage must be in {sorted(_VALID_STAGES)}, got {stage!r}") + if language_weights is None: + language_weights = { + "en": 0.2, + "hi": 0.2, + "ta": 0.2, + "kn": 0.2, + "hinglish": 0.2, + } + count = 0 + seed = 0 + while limit is None or count < limit: + yield generate(seed, cast("Literal[1, 2, 3]", stage), language_weights) + count += 1 + seed += 1 + + +# --------------------------------------------------------------------------- +# Test helpers (public so test modules can look up templates) +# --------------------------------------------------------------------------- + + +def _lookup_template_for_test(template_id: str) -> Template: + """Public-for-tests helper to resolve a template by ID.""" + lib = _get_library() + for t in lib.templates: + if t.template_id == template_id: + return t + raise KeyError(template_id) + + +__all__ = [ + "Domain", + "InvalidBudgetError", + "InvalidLanguageError", + "InvalidLanguageWeightError", + "InvalidStageError", + "LanguageCode", + "MissingSlotError", + "NoVariantForLanguageError", + "RawBrief", + "SlotDistribution", + "SlotGrid", + "TaskGeneratorError", + "Template", + "TemplateFileMissingError", + "TemplateLibrary", + "TemplateSchemaError", + "UnicodeNormalizationError", + "_lookup_template_for_test", + "enumerate_variants", + "generate", + "load_templates", + "reset_library_cache", + "set_library_override", + "stable_sub_seed", +] diff --git a/cells/step_08_rewards.md b/cells/step_08_rewards.md new file mode 100644 index 0000000000000000000000000000000000000000..c1ae30f3b4f2b31777df5ec63ba004faac4fcd46 --- /dev/null +++ b/cells/step_08_rewards.md @@ -0,0 +1,7 @@ +## step_08_rewards + +Pure-functional reward pipeline for DriftCall (DESIGN.md §7, docs/modules/rewards.md). +Converts a frozen `Episode` into a frozen `Rewards` record through five independent +signals (R1..R5), Brier calibration, an uncertain floor, and a 3-decimal final reward. +No LLM judge, no I/O, no clock — every computation is reproducible from the transcript +alone. diff --git a/cells/step_08_rewards.py b/cells/step_08_rewards.py new file mode 100644 index 0000000000000000000000000000000000000000..12349a6522dfcb0d21c1dfe2aaecdf979c0b65c4 --- /dev/null +++ b/cells/step_08_rewards.py @@ -0,0 +1,1133 @@ +"""DriftCall reward pipeline. + +Implements docs/modules/rewards.md and DESIGN.md §7. Pure-functional: no I/O, +no clock, no RNG, no LLM. Every reward is deterministic on the input Episode. + +Public surface: + Episode, Rewards, RewardComputationError, AVAILABLE_TOOL_REGISTRY, + task_completion, drift_detection, constraint_adherence, + format_compliance, anti_hack_penalty, + combine_quality, brier_penalty, apply_uncertain_floor, final_reward, + compute_rewards. +""" + +from __future__ import annotations + +import json +import math +import re +from dataclasses import dataclass, field +from typing import Any, Literal + +from cells.step_04_models import ( + ActionType, + DriftCallAction, + DriftEvent, + GoalSpec, + ToolResult, +) +from cells.step_05_vendors import TOOLS as _VENDOR_TOOLS +from cells.step_06_drift_injector import DriftPattern, list_patterns + +__all__ = [ + "AVAILABLE_TOOL_REGISTRY", + "Episode", + "RewardComputationError", + "Rewards", + "anti_hack_penalty", + "apply_uncertain_floor", + "brier_penalty", + "combine_quality", + "compute_rewards", + "constraint_adherence", + "drift_detection", + "final_reward", + "format_compliance", + "task_completion", +] + + +# --------------------------------------------------------------------------- +# Constants +# --------------------------------------------------------------------------- + + +AVAILABLE_TOOL_REGISTRY: frozenset[str] = frozenset(_VENDOR_TOOLS) + +_RESERVED_KEYS: frozenset[str] = frozenset( + {"__turn__", "__schema_version__", "__done__", "__episode_id__"}, +) + +_VALID_DRIFT_TYPES: frozenset[str] = frozenset( + {"schema", "policy", "tnc", "pricing", "auth"}, +) + +_VALID_TERMINATIONS: frozenset[str] = frozenset( + {"SUBMIT", "ABORT", "TIMEOUT", "ANTI_HACK"}, +) + +# Hour windows (24h IST). "night" wraps midnight; encoded as (lo, hi+24). +_TIME_WINDOWS: dict[str, tuple[int, int]] = { + "morning": (6, 12), + "afternoon": (12, 18), + "evening": (18, 22), + "night": (22, 30), +} + +_FAILURE_STATUSES: frozenset[str] = frozenset( + {"schema_error", "policy_error", "auth_error"}, +) + +# snake_case identifier with at least one underscore between alphanumeric segments +_SNAKE_FIELD_RE = re.compile(r"\b[a-z][a-z0-9]*(?:_[a-z0-9]+)+\b") + +_PATTERNS_BY_ID: dict[str, DriftPattern] = {p.id: p for p in list_patterns()} + + +# --------------------------------------------------------------------------- +# Errors +# --------------------------------------------------------------------------- + + +class RewardComputationError(Exception): + """Raised when rewards cannot be computed for a malformed episode.""" + + def __init__(self, reason: str, episode_id: str | None = None) -> None: + super().__init__(reason) + self.reason = reason + self.episode_id = episode_id + + +# --------------------------------------------------------------------------- +# Data structures +# --------------------------------------------------------------------------- + + +@dataclass(frozen=True) +class Episode: + episode_id: str + goal: GoalSpec + actions: tuple[DriftCallAction, ...] + action_turns: tuple[int, ...] + tool_results: tuple[ToolResult, ...] + tool_result_turns: tuple[int, ...] + drift_log: tuple[DriftEvent, ...] + vendor_states_final: dict[str, dict[str, Any]] + schema_versions_final: dict[str, str] + max_turns: int + turns_used: int + terminated_by: Literal["SUBMIT", "ABORT", "TIMEOUT", "ANTI_HACK"] + stage: Literal[1, 2, 3] + drift_pattern_overrides: dict[str, DriftPattern] = field(default_factory=dict) + + +@dataclass(frozen=True) +class Rewards: + r1: float + r2: float + r3: float + r4: float + r5: float + quality: float + brier: float + reward: float + confidence: float | None + floor_applied: bool + breakdown: dict[str, Any] + + +# --------------------------------------------------------------------------- +# Internal helpers +# --------------------------------------------------------------------------- + + +def _resolve_pattern(episode: Episode, drift: DriftEvent) -> DriftPattern: + """Look up the DriftPattern via episode overrides, then global registry.""" + pattern_id = drift.pattern_id + if pattern_id in episode.drift_pattern_overrides: + return episode.drift_pattern_overrides[pattern_id] + if pattern_id in _PATTERNS_BY_ID: + return _PATTERNS_BY_ID[pattern_id] + raise RewardComputationError( + f"unknown pattern_id: {pattern_id}", + episode.episode_id, + ) + + +def _validate_hints(pattern: DriftPattern, episode: Episode) -> tuple[str, ...]: + """Return non-empty stripped hints; raise on empty.""" + cleaned = tuple(h for h in pattern.detection_hints if h and h.strip()) + if not cleaned: + raise RewardComputationError( + f"drift {pattern.id} has empty detection_hints", + episode.episode_id, + ) + return cleaned + + +def _is_finite(value: float) -> bool: + return math.isfinite(value) + + +def _safe_lower(text: str | None) -> str: + return text.lower() if text else "" + + +def _iter_string_values(node: Any) -> list[str]: + """Recursively collect string values (numerics/booleans excluded).""" + out: list[str] = [] + if isinstance(node, bool): + return out + if isinstance(node, str): + out.append(node) + elif isinstance(node, dict): + for v in node.values(): + out.extend(_iter_string_values(v)) + elif isinstance(node, (list, tuple)): + for item in node: + out.extend(_iter_string_values(item)) + return out + + +def _iter_keys(node: Any) -> list[str]: + """Recursively collect dict keys.""" + out: list[str] = [] + if isinstance(node, dict): + for k, v in node.items(): + out.append(str(k)) + out.extend(_iter_keys(v)) + elif isinstance(node, (list, tuple)): + for item in node: + out.extend(_iter_keys(item)) + return out + + +def _build_args_search_corpus(tool_args: dict[str, Any] | None) -> str: + """Lowercased keys + string values; numeric/boolean leaves excluded.""" + if not tool_args: + return "" + keys = _iter_keys(tool_args) + strings = _iter_string_values(tool_args) + return " ".join(keys + strings).lower() + + +def _mentions_drift(message: str | None, hints: tuple[str, ...]) -> bool: + if not message: + return False + target = message.lower() + return any(hint.lower() in target for hint in hints) + + +def _args_mention_drift( + tool_args: dict[str, Any] | None, + hints: tuple[str, ...], +) -> bool: + corpus = _build_args_search_corpus(tool_args) + if not corpus: + return False + return any(hint.lower() in corpus for hint in hints) + + +def _new_field_names(pattern: DriftPattern) -> tuple[str, ...]: + """Field names introduced by the drift mutation (post-drift schema).""" + mutation = pattern.mutation + out: list[str] = [] + rename = mutation.get("rename") + if isinstance(rename, dict): + out.extend(str(v) for v in rename.values()) + new_fields = mutation.get("require_new_field") + if isinstance(new_fields, (list, tuple)): + out.extend(str(v) for v in new_fields) + change = mutation.get("change_type") + if isinstance(change, dict): + out.extend(str(v) for v in change.values()) + return tuple(out) + + +def _old_field_names(pattern: DriftPattern) -> tuple[str, ...]: + """Field names from the pre-drift schema.""" + mutation = pattern.mutation + out: list[str] = [] + rename = mutation.get("rename") + if isinstance(rename, dict): + out.extend(str(k) for k in rename) + removed = mutation.get("remove") + if isinstance(removed, (list, tuple)): + out.extend(str(v) for v in removed) + change = mutation.get("change_type") + if isinstance(change, dict): + out.extend(str(k) for k in change) + return tuple(out) + + +def _uses_new_schema( + tool_args: dict[str, Any] | None, + pattern: DriftPattern, +) -> bool: + if not tool_args: + return False + new_fields = _new_field_names(pattern) + if not new_fields: + return False + keys_lower = {k.lower() for k in _iter_keys(tool_args)} + return any(f.lower() in keys_lower for f in new_fields) + + +def _uses_old_schema( + tool_args: dict[str, Any] | None, + pattern: DriftPattern, +) -> bool: + if not tool_args: + return False + old_fields = _old_field_names(pattern) + if not old_fields: + return False + keys_lower = {k.lower() for k in _iter_keys(tool_args)} + return any(f.lower() in keys_lower for f in old_fields) + + +def _has_3plus_old_schema_retries( + episode: Episode, + pattern: DriftPattern, + drift_turn: int, +) -> bool: + """True iff >= 3 TOOL_CALLs after drift_turn use OLD schema.""" + count = 0 + for action, turn in zip(episode.actions, episode.action_turns, strict=True): + if turn <= drift_turn: + continue + if action.action_type != ActionType.TOOL_CALL: + continue + if _uses_old_schema(action.tool_args, pattern): + count += 1 + return count >= 3 + + +# --------------------------------------------------------------------------- +# R1 — Task Completion +# --------------------------------------------------------------------------- + + +def _parse_iso_hour(timestamp: str) -> int | None: + """Parse 'YYYY-MM-DDTHH:MM[:SS]' and return hour, or None on failure.""" + if "T" not in timestamp: + return None + try: + time_part = timestamp.split("T", 1)[1] + return int(time_part[:2]) + except (ValueError, IndexError): + return None + + +def _hour_in_window(hour: int, window: str) -> bool: + win = _TIME_WINDOWS.get(window) + if win is None: + return True + lo, hi = win + if hi <= 24: + return lo <= hour < hi + return hour >= lo or hour < (hi - 24) + + +def _check_airline_booking( + goal: GoalSpec, + vendor_states: dict[str, dict[str, Any]], +) -> bool: + state = vendor_states.get("airline", {}) + if not isinstance(state, dict): + return False + bookings = state.get("bookings", []) + if not isinstance(bookings, list) or not bookings: + return False + expected_from = goal.slots.get("from") + expected_to = goal.slots.get("to") + budget = goal.constraints.get("budget_inr") + window = goal.constraints.get("time_window") + for booking in bookings: + if not isinstance(booking, dict): + continue + if expected_from is not None and booking.get("from") != expected_from: + continue + if expected_to is not None and booking.get("to") != expected_to: + continue + if budget is not None: + total = booking.get("total") + if total is None or total > budget: + continue + if window is not None: + depart = booking.get("depart") + if not isinstance(depart, str): + continue + hour = _parse_iso_hour(depart) + if hour is None or not _hour_in_window(hour, str(window)): + continue + return True + return False + + +def _check_cab_booking( + goal: GoalSpec, + vendor_states: dict[str, dict[str, Any]], +) -> bool: + state = vendor_states.get("cab", {}) + if not isinstance(state, dict): + return False + bookings = state.get("bookings", []) + if not isinstance(bookings, list) or not bookings: + return False + expected_pickup = goal.slots.get("pickup") + expected_drop = goal.slots.get("drop") + expected_when = goal.slots.get("when") + for booking in bookings: + if not isinstance(booking, dict): + continue + if expected_pickup is not None and booking.get("pickup") != expected_pickup: + continue + if expected_drop is not None and booking.get("drop") != expected_drop: + continue + if expected_when is not None and booking.get("pickup_time") != expected_when: + continue + return True + return False + + +def _check_restaurant_order( + goal: GoalSpec, + vendor_states: dict[str, dict[str, Any]], +) -> bool: + state = vendor_states.get("restaurant", {}) + if not isinstance(state, dict): + return False + orders = state.get("orders", []) + if not isinstance(orders, list) or not orders: + return False + budget = goal.constraints.get("budget_inr") + dietary = goal.constraints.get("dietary") + for order in orders: + if not isinstance(order, dict): + continue + if budget is not None: + total = order.get("total") + if total is None or total > budget: + continue + if dietary is not None: + items = order.get("items", []) + if dietary in {"veg", "veg_only"} and not all( + isinstance(it, dict) and it.get("veg") is True for it in items + ): + continue + return True + return False + + +def _check_hotel_booking( + goal: GoalSpec, + vendor_states: dict[str, dict[str, Any]], +) -> bool: + state = vendor_states.get("hotel", {}) + if not isinstance(state, dict): + return False + bookings = state.get("bookings", []) + if not isinstance(bookings, list) or not bookings: + return False + expected_city = goal.slots.get("city") + expected_in = goal.slots.get("checkin") + expected_out = goal.slots.get("checkout") + expected_room = goal.slots.get("room_type") + for booking in bookings: + if not isinstance(booking, dict): + continue + if expected_city is not None and booking.get("city") != expected_city: + continue + if expected_in is not None and booking.get("checkin") != expected_in: + continue + if expected_out is not None and booking.get("checkout") != expected_out: + continue + if expected_room is not None and booking.get("room_type") != expected_room: + continue + return True + return False + + +def task_completion(episode: Episode) -> float: + """R1: 1.0 iff terminated by SUBMIT and per-domain success predicate holds.""" + if episode.terminated_by != "SUBMIT": + return 0.0 + domain = episode.goal.domain + final = episode.vendor_states_final + if domain == "airline": + ok = _check_airline_booking(episode.goal, final) + elif domain == "cab": + ok = _check_cab_booking(episode.goal, final) + elif domain == "restaurant": + ok = _check_restaurant_order(episode.goal, final) + elif domain == "hotel": + ok = _check_hotel_booking(episode.goal, final) + else: + ok = False + return 1.0 if ok else 0.0 + + +def _r1_breakdown(episode: Episode) -> dict[str, Any]: + domain = episode.goal.domain + if domain not in {"airline", "cab", "restaurant", "hotel"}: + return { + "domain": domain, + "success_predicate": "unknown_domain", + "matched_slots": {}, + "missing_slots": [], + } + return { + "domain": domain, + "success_predicate": f"{domain}_booking_match", + "matched_slots": dict(episode.goal.slots), + "missing_slots": [], + } + + +# --------------------------------------------------------------------------- +# R2 — Drift Detection +# --------------------------------------------------------------------------- + + +def _drift_detection_with_breakdown( + episode: Episode, +) -> tuple[float, dict[str, Any]]: + breakdown: dict[str, Any] = { + "stage": int(episode.stage), + "drifts_total": len(episode.drift_log), + "drifts_detected": 0, + "per_drift": [], + "three_plus_retries": False, + } + if episode.stage == 1 or len(episode.drift_log) == 0: + if episode.stage in (2, 3) and len(episode.drift_log) == 0: + breakdown["stage2_3_no_drift"] = True + return 0.5, breakdown + + score = 1.0 + detected = 0 + any_old_schema_retries = False + + for drift in episode.drift_log: + pattern = _resolve_pattern(episode, drift) + hints = _validate_hints(pattern, episode) + window_turns = [drift.turn, drift.turn + 1, drift.turn + 2] + actions_in_window = [ + (a, t) + for a, t in zip(episode.actions, episode.action_turns, strict=True) + if t in window_turns + ] + hit_speech = False + hit_args = False + hit_adapt = False + for action, _turn in actions_in_window: + if ( + action.action_type in {ActionType.SPEAK, ActionType.CLARIFY} + and _mentions_drift(action.message, hints) + ): + hit_speech = True + if action.action_type == ActionType.TOOL_CALL: + if _args_mention_drift(action.tool_args, hints): + hit_args = True + if _uses_new_schema(action.tool_args, pattern): + hit_adapt = True + + breakdown["per_drift"].append({ + "drift_id": drift.pattern_id, + "hit_by_speech": hit_speech, + "hit_by_args_hint": hit_args, + "hit_by_adaptation": hit_adapt, + "window_turns": list(window_turns), + }) + + if hit_speech or hit_args or hit_adapt: + detected += 1 + else: + score = 0.0 + + if _has_3plus_old_schema_retries(episode, pattern, drift.turn): + any_old_schema_retries = True + + breakdown["drifts_detected"] = detected + breakdown["three_plus_retries"] = any_old_schema_retries + if any_old_schema_retries: + score = 0.0 + return score, breakdown + + +def drift_detection(episode: Episode) -> float: + """R2: stage-1/no-drift → 0.5; per-drift any-branch hit → 1.0; one miss → 0.0.""" + score, _ = _drift_detection_with_breakdown(episode) + return score + + +# --------------------------------------------------------------------------- +# R3 — Constraint Adherence +# --------------------------------------------------------------------------- + + +_KNOWN_CONSTRAINT_KEYS: frozenset[str] = frozenset( + { + "budget_inr", + "time_window", + "dietary", + "passenger_count", + "pickup", + "seat_type", + "checkin", + "checkout", + "room_type", + }, +) + + +def _final_booking(episode: Episode) -> dict[str, Any] | None: + """Return the most recent booking/order from vendor_states_final.""" + domain = episode.goal.domain + state = episode.vendor_states_final.get(domain, {}) + if not isinstance(state, dict): + return None + items = ( + state.get("orders", []) if domain == "restaurant" else state.get("bookings", []) + ) + if not isinstance(items, list) or not items: + return None + last = items[-1] + return last if isinstance(last, dict) else None + + +def _check_constraint( + key: str, + expected: Any, + booking: dict[str, Any] | None, +) -> bool: + if booking is None: + return False + if key == "budget_inr": + total = booking.get("total") + if total is None: + return False + try: + return float(total) <= float(expected) + except (TypeError, ValueError): + return False + if key == "time_window": + depart = booking.get("depart") or booking.get("pickup_time") + if not isinstance(depart, str): + return False + hour = _parse_iso_hour(depart) + if hour is None: + return False + return _hour_in_window(hour, str(expected)) + if key == "dietary": + items = booking.get("items", []) + if not isinstance(items, list): + return False + if expected in {"veg", "veg_only"}: + return all( + isinstance(it, dict) and it.get("veg") is True for it in items + ) + return True + if key == "passenger_count": + return bool(booking.get("passenger_count") == expected) + if key == "pickup": + return bool(booking.get("pickup") == expected) + if key == "seat_type": + return bool(booking.get("seat_type") == expected) + if key == "checkin": + return bool(booking.get("checkin") == expected) + if key == "checkout": + return bool(booking.get("checkout") == expected) + if key == "room_type": + return bool(booking.get("room_type") == expected) + return False + + +def _r3_with_breakdown(episode: Episode) -> tuple[float, dict[str, Any]]: + constraints = episode.goal.constraints + if not constraints: + return 1.0, { + "total_constraints": 0, + "satisfied_constraints": 0, + "unknown_constraints": [], + "failures": [], + } + booking = _final_booking(episode) + satisfied = 0 + unknown: list[str] = [] + failures: list[dict[str, Any]] = [] + for key, expected in constraints.items(): + if key not in _KNOWN_CONSTRAINT_KEYS: + unknown.append(key) + satisfied += 1 + continue + if _check_constraint(key, expected, booking): + satisfied += 1 + else: + actual = booking.get(key) if booking else None + failures.append({"key": key, "expected": expected, "actual": actual}) + total = len(constraints) + return satisfied / total, { + "total_constraints": total, + "satisfied_constraints": satisfied, + "unknown_constraints": unknown, + "failures": failures, + } + + +def constraint_adherence(episode: Episode) -> float: + """R3: fraction of goal.constraints satisfied by the final booking.""" + score, _ = _r3_with_breakdown(episode) + return score + + +# --------------------------------------------------------------------------- +# R4 — Format Compliance +# --------------------------------------------------------------------------- + + +def _is_valid_json(value: Any) -> bool: + try: + json.dumps(value) + except (TypeError, ValueError): + return False + return True + + +def _has_devanagari(text: str) -> bool: + return any("ऀ" <= c <= "ॿ" for c in text) + + +def _has_tamil(text: str) -> bool: + return any("஀" <= c <= "௿" for c in text) + + +def _has_kannada(text: str) -> bool: + return any("ಀ" <= c <= "೿" for c in text) + + +def _has_indic(text: str) -> bool: + return _has_devanagari(text) or _has_tamil(text) or _has_kannada(text) + + +def _language_mismatch(message: str, goal_language: str) -> bool: + """Asymmetric heuristic per rewards.md §3.5; permissive for ta/kn/hinglish. + + - "en" : mismatch iff message contains any Indic script. + - "hi" : mismatch iff message contains no Devanagari. + - others : Latin or local script accepted (transliteration is common). + """ + if not message: + return False + if goal_language == "en": + return _has_indic(message) + if goal_language == "hi": + return not _has_devanagari(message) + return False + + +def _r4_with_breakdown(episode: Episode) -> tuple[float, dict[str, Any]]: + score = 1.0 + deductions: list[dict[str, Any]] = [] + for action, turn in zip(episode.actions, episode.action_turns, strict=True): + if action.action_type == ActionType.TOOL_CALL: + if not _is_valid_json(action.tool_args): + score -= 0.20 + deductions.append({"turn": turn, "reason": "invalid_json", "amount": 0.20}) + if action.tool_name not in AVAILABLE_TOOL_REGISTRY: + score -= 0.10 + deductions.append({"turn": turn, "reason": "unknown_tool", "amount": 0.10}) + if action.rationale is None or len(action.rationale.strip()) == 0: + score -= 0.05 + deductions.append({ + "turn": turn, + "reason": "missing_rationale", + "amount": 0.05, + }) + if action.action_type in {ActionType.SPEAK, ActionType.CLARIFY}: + msg = action.message or "" + if _language_mismatch(msg, episode.goal.language): + score -= 0.10 + deductions.append({ + "turn": turn, + "reason": "language_mismatch", + "amount": 0.10, + }) + score = max(0.0, min(1.0, score)) + return score, {"deductions": deductions} + + +def format_compliance(episode: Episode) -> float: + """R4: deductive from 1.0; clamped to [0, 1].""" + score, _ = _r4_with_breakdown(episode) + return score + + +# --------------------------------------------------------------------------- +# R5 — Anti-Hack Penalty +# --------------------------------------------------------------------------- + + +def _build_whitelist(tool_results: tuple[ToolResult, ...]) -> set[str]: + """Recursive walk: every key + every primitive leaf, lowercased.""" + seen: set[str] = set() + + def walk(node: Any) -> None: + if isinstance(node, bool): + seen.add(str(node).lower()) + return + if isinstance(node, dict): + for k, v in node.items(): + seen.add(str(k).lower()) + walk(v) + elif isinstance(node, (list, tuple)): + for item in node: + walk(item) + elif isinstance(node, (str, int, float)): + seen.add(str(node).lower()) + + for tr in tool_results: + walk(tr.response) + return seen + + +def _extract_field_tokens(text: str | None) -> list[str]: + """Return lowercased snake_case identifier tokens (>=1 underscore).""" + if not text: + return [] + return _SNAKE_FIELD_RE.findall(text.lower()) + + +def _hallucinated_offenses( + episode: Episode, + whitelist: set[str], +) -> list[tuple[int, str]]: + """(turn, token) pairs where agent referenced a snake_case field not in whitelist. + + Scans natural-language surfaces only (`message`, `rationale`). Tool-call + `tool_args` keys are the agent's own request payload — they are policed by + R4 (unknown_tool / invalid_json) and the protected-write check, not as + hallucinated field references. + """ + offenses: list[tuple[int, str]] = [] + for action, turn in zip(episode.actions, episode.action_turns, strict=True): + candidates: list[str] = [] + candidates.extend(_extract_field_tokens(action.message)) + candidates.extend(_extract_field_tokens(action.rationale)) + for token in candidates: + if token not in whitelist: + offenses.append((turn, token)) + return offenses + + +def _canonical_args(tool_args: dict[str, Any] | None) -> str: + if tool_args is None: + return "null" + try: + return json.dumps(tool_args, sort_keys=True, separators=(",", ":")) + except (TypeError, ValueError): + try: + return repr(sorted(tool_args.items())) + except TypeError: + return repr(tool_args) + + +def _max_repeated_tool_calls(episode: Episode) -> int: + """Maximum repetition count of any (tool_name, normalised_args) pair.""" + counts: dict[tuple[str | None, str], int] = {} + for action in episode.actions: + if action.action_type != ActionType.TOOL_CALL: + continue + key = (action.tool_name, _canonical_args(action.tool_args)) + counts[key] = counts.get(key, 0) + 1 + return max(counts.values()) if counts else 0 + + +def _count_actions(episode: Episode, action_type: ActionType) -> int: + return sum(1 for a in episode.actions if a.action_type == action_type) + + +def _has_unsubstantiated_drift_claim( + episode: Episode, +) -> tuple[bool, int | None]: + """SPEAK/CLARIFY mentions 'drift' before any prior failure or drift_log entry.""" + for action, turn in zip(episode.actions, episode.action_turns, strict=True): + if action.action_type not in {ActionType.SPEAK, ActionType.CLARIFY}: + continue + if "drift" not in _safe_lower(action.message): + continue + prior_failure = any( + tr.status in _FAILURE_STATUSES and tr_turn <= turn + for tr, tr_turn in zip( + episode.tool_results, episode.tool_result_turns, strict=True, + ) + ) + if prior_failure: + continue + prior_drift = any(d.turn <= turn for d in episode.drift_log) + if prior_drift: + continue + return True, turn + return False, None + + +def _is_protected_tool(tool_name: str | None) -> bool: + if not tool_name: + return False + return tool_name.startswith("__") and tool_name.endswith("__") + + +def _has_protected_write(episode: Episode) -> tuple[bool, int | None]: + for action, turn in zip(episode.actions, episode.action_turns, strict=True): + if action.action_type != ActionType.TOOL_CALL: + continue + if _is_protected_tool(action.tool_name): + return True, turn + if action.tool_args: + for key in action.tool_args: + if key in _RESERVED_KEYS: + return True, turn + return False, None + + +def _r5_with_breakdown(episode: Episode) -> tuple[float, dict[str, Any]]: + penalty = 0.0 + offenses: list[dict[str, Any]] = [] + + whitelist = _build_whitelist(episode.tool_results) + hallucinations = _hallucinated_offenses(episode, whitelist) + if hallucinations: + penalty -= 1.0 + first_turn, first_token = hallucinations[0] + offenses.append({ + "code": "hallucinated_field", + "turn": first_turn, + "evidence": first_token, + }) + + repeats = _max_repeated_tool_calls(episode) + if repeats > 3: + penalty -= 0.5 + offenses.append({ + "code": "repeated_tool_calls", + "turn": None, + "evidence": f"max_repetition={repeats}", + }) + + probe_count = _count_actions(episode, ActionType.PROBE_SCHEMA) + if probe_count >= 3: + penalty -= 0.5 + offenses.append({ + "code": "probe_schema_abuse", + "turn": None, + "evidence": f"probe_count={probe_count}", + }) + + bare, bare_turn = _has_unsubstantiated_drift_claim(episode) + if bare: + penalty -= 0.3 + offenses.append({ + "code": "bare_drift_assertion", + "turn": bare_turn, + "evidence": "speak mentions drift without prior failure", + }) + + protected, protected_turn = _has_protected_write(episode) + if protected: + penalty -= 0.2 + offenses.append({ + "code": "protected_write", + "turn": protected_turn, + "evidence": "reserved key or protected tool", + }) + + penalty = max(-1.0, penalty) + return penalty, {"offenses": offenses} + + +def anti_hack_penalty(episode: Episode) -> float: + """R5: additive penalties, clamped to [-1.0, 0.0].""" + score, _ = _r5_with_breakdown(episode) + return score + + +# --------------------------------------------------------------------------- +# Combination helpers +# --------------------------------------------------------------------------- + + +def combine_quality( + r1: float, + r2: float, + r3: float, + r4: float, + r5: float, +) -> float: + """Weighted sum (0.50/0.20/0.15/0.10/0.05). Does not clamp or round.""" + return 0.50 * r1 + 0.20 * r2 + 0.15 * r3 + 0.10 * r4 + 0.05 * min(r5, 0.0) + + +def brier_penalty(confidence: float | None, r1: float) -> float: + """min((conf - r1)^2, 0.5) when confidence given; else 0.0.""" + if confidence is None: + return 0.0 + raw = (confidence - r1) ** 2 + return raw if raw <= 0.5 else 0.5 + + +def apply_uncertain_floor( + reward: float, + r1: float, + confidence: float | None, +) -> float: + """Floor at 0.3 iff r1==0, confidence is not None, confidence < 0.3.""" + if r1 == 0.0 and confidence is not None and confidence < 0.3: + return max(reward, 0.3) + return reward + + +def final_reward( + quality: float, + brier: float, + r1: float, + confidence: float | None, +) -> float: + """multiply -> floor -> clamp [0,1] -> round 3dp.""" + reward = quality * (1.0 - brier) + reward = apply_uncertain_floor(reward, r1, confidence) + reward = max(0.0, min(1.0, reward)) + return round(reward, 3) + + +# --------------------------------------------------------------------------- +# compute_rewards orchestration +# --------------------------------------------------------------------------- + + +def _validate_episode_structure(episode: Episode) -> None: + if episode.goal is None: + raise RewardComputationError("episode.goal is None", episode.episode_id) + if episode.terminated_by is None: + raise RewardComputationError("episode not terminated", episode.episode_id) + if episode.terminated_by not in _VALID_TERMINATIONS: + raise RewardComputationError( + f"episode not terminated (invalid terminated_by={episode.terminated_by!r})", + episode.episode_id, + ) + for drift in episode.drift_log: + if drift.drift_type not in _VALID_DRIFT_TYPES: + raise RewardComputationError( + f"unknown drift_type: {drift.drift_type}", + episode.episode_id, + ) + if ( + drift.pattern_id not in episode.drift_pattern_overrides + and drift.pattern_id not in _PATTERNS_BY_ID + ): + raise RewardComputationError( + f"unknown pattern_id: {drift.pattern_id}", + episode.episode_id, + ) + n_tool_calls = sum( + 1 for a in episode.actions if a.action_type == ActionType.TOOL_CALL + ) + if n_tool_calls != len(episode.tool_results): + raise RewardComputationError( + "action/tool_result count mismatch", + episode.episode_id, + ) + + +def _extract_confidence(episode: Episode) -> tuple[float | None, bool]: + """Return (raw_confidence, clamped_flag). Raises on non-finite.""" + if episode.terminated_by != "SUBMIT": + return None, False + submit_conf: float | None = None + for action in reversed(episode.actions): + if action.action_type == ActionType.SUBMIT: + submit_conf = action.confidence + break + if submit_conf is None: + return None, False + if not _is_finite(float(submit_conf)): + raise RewardComputationError( + "non-finite value in reward computation", + episode.episode_id, + ) + if submit_conf < 0.0 or submit_conf > 1.0: + return submit_conf, True + return submit_conf, False + + +def compute_rewards(episode: Episode) -> Rewards: + """Convert a terminated Episode into a frozen Rewards record.""" + _validate_episode_structure(episode) + + raw_confidence, clamped = _extract_confidence(episode) + confidence_for_brier = raw_confidence + if clamped and raw_confidence is not None: + confidence_for_brier = max(0.0, min(1.0, raw_confidence)) + + r1 = task_completion(episode) + r2, r2_breakdown = _drift_detection_with_breakdown(episode) + r3, r3_breakdown = _r3_with_breakdown(episode) + r4, r4_breakdown = _r4_with_breakdown(episode) + r5, r5_breakdown = _r5_with_breakdown(episode) + + if not ( + _is_finite(r1) + and _is_finite(r2) + and _is_finite(r3) + and _is_finite(r4) + and _is_finite(r5) + ): + raise RewardComputationError( + "non-finite value in reward computation", + episode.episode_id, + ) + + quality = combine_quality(r1, r2, r3, r4, r5) + brier = brier_penalty(confidence_for_brier, r1) + if not (_is_finite(quality) and _is_finite(brier)): + raise RewardComputationError( + "non-finite value in reward computation", + episode.episode_id, + ) + + pre_floor = quality * (1.0 - brier) + floored = apply_uncertain_floor(pre_floor, r1, confidence_for_brier) + floor_applied = floored != pre_floor + reward_clamped = max(0.0, min(1.0, floored)) + reward = round(reward_clamped, 3) + + breakdown: dict[str, Any] = { + "r1": _r1_breakdown(episode), + "r2": r2_breakdown, + "r3": r3_breakdown, + "r4": r4_breakdown, + "anti_hack": r5_breakdown, + "combination": { + "quality_raw": quality, + "brier": brier, + "uncertain_floor_applied": floor_applied, + "confidence_clamped": clamped, + "confidence_missing": ( + episode.terminated_by == "SUBMIT" and raw_confidence is None + ), + }, + } + + return Rewards( + r1=r1, + r2=r2, + r3=r3, + r4=r4, + r5=r5, + quality=quality, + brier=brier, + reward=reward, + confidence=raw_confidence, + floor_applied=floor_applied, + breakdown=breakdown, + ) diff --git a/cells/step_09_audio.md b/cells/step_09_audio.md new file mode 100644 index 0000000000000000000000000000000000000000..b4b607fd17dac4d846ace2bf1c1741ab9d174be5 --- /dev/null +++ b/cells/step_09_audio.md @@ -0,0 +1,6 @@ +# Cell 09 — Audio pipeline + +Kokoro-82M text-to-speech and faster-whisper-small automatic-speech-recognition +wrappers that sit at the env boundary. Per `docs/modules/audio.md`, both +engines are process-wide singletons with lazy dep loading and an LRU cache on +the TTS path; the training loop never imports this cell (`§6.3`). diff --git a/cells/step_09_audio.py b/cells/step_09_audio.py new file mode 100644 index 0000000000000000000000000000000000000000..6424dc52785748a5a1e7e08f3fddc0299ac8d8be --- /dev/null +++ b/cells/step_09_audio.py @@ -0,0 +1,944 @@ +"""Cell 09 — Audio pipeline (Kokoro-82M TTS + faster-whisper-small ASR). + +Implements docs/modules/audio.md: TTS and ASR engines exposed at the env +boundary. Training never imports this module (docs/modules/audio.md §6.3). +Heavy deps (``kokoro``, ``faster_whisper``, ``torchaudio``, ``soundfile``) +are loaded lazily inside ``_load_*`` helpers so this cell imports cleanly +in environments where those optional packages are absent, and so tests can +monkeypatch the loaders to return fakes without ever touching the network. +""" + +from __future__ import annotations + +import hashlib +import io +import logging +import math +import struct +import threading +import time +import unicodedata +import wave +from collections.abc import Callable +from dataclasses import dataclass +from datetime import datetime, timedelta, timezone +from typing import Any, Literal, cast + +import numpy as np +from cachetools import LRUCache + +logger = logging.getLogger(__name__) + + +# --------------------------------------------------------------------------- +# Public literal types (audio.md §2.1, §2.2) +# --------------------------------------------------------------------------- + +LanguageCode = Literal["hi", "ta", "kn", "en", "hinglish"] +VoicePack = Literal[ + "hi_female_1", + "hi_male_1", + "ta_female_1", + "kn_male_1", + "en_indian_female_1", +] + +_LANGUAGE_CODES: frozenset[str] = frozenset({"hi", "ta", "kn", "en", "hinglish"}) +_VOICE_PACKS_SET: frozenset[str] = frozenset( + { + "hi_female_1", + "hi_male_1", + "ta_female_1", + "kn_male_1", + "en_indian_female_1", + } +) + + +# --------------------------------------------------------------------------- +# Errors (audio.md §2.3) +# --------------------------------------------------------------------------- + + +class AudioError(Exception): + """Base class for all audio-module errors.""" + + +class ModelLoadError(AudioError): + """Raised when Kokoro or faster-whisper cannot be instantiated.""" + + +class UnsupportedLanguageError(AudioError): + """Raised when a non-registered language code is passed to synthesize().""" + + +class UnsupportedVoicePackError(AudioError): + """Raised when a voice pack is not in VOICE_PACKS[lang].allowed.""" + + +class AudioDecodeError(AudioError): + """Raised when transcribe() cannot decode the input bytes.""" + + +class AudioTooLongError(AudioError): + """Raised when transcribe() receives audio longer than max_duration_s in strict mode.""" + + +class TTSOutOfMemoryError(AudioError): + """Raised when TTS synthesis exhausts memory mid-call.""" + + +# --------------------------------------------------------------------------- +# Data records (audio.md §2.1, §2.2, §2.2a, §4.1, §4.2) +# --------------------------------------------------------------------------- + + +@dataclass(frozen=True) +class VoicePackMapping: + """Per-language default + allowed voice packs. audio.md §4.3.""" + + language: LanguageCode + default: VoicePack + allowed: tuple[VoicePack, ...] + + +VOICE_PACKS: dict[LanguageCode, VoicePackMapping] = { + "hi": VoicePackMapping( + language="hi", + default="hi_female_1", + allowed=("hi_female_1", "hi_male_1"), + ), + "ta": VoicePackMapping( + language="ta", + default="ta_female_1", + allowed=("ta_female_1",), + ), + "kn": VoicePackMapping( + language="kn", + default="kn_male_1", + allowed=("kn_male_1",), + ), + "en": VoicePackMapping( + language="en", + default="en_indian_female_1", + allowed=("en_indian_female_1",), + ), + "hinglish": VoicePackMapping( + language="hinglish", + default="en_indian_female_1", + allowed=("en_indian_female_1", "hi_female_1"), + ), +} + + +@dataclass(frozen=True) +class TranscriptResult: + """ASR output surfaced to the env observation builder. audio.md §4.1.""" + + text: str + language_detected: LanguageCode | Literal["unknown"] + confidence: float + duration_s: float + + +@dataclass(frozen=True) +class AudioTrace: + """Per-call diagnostic record emitted via the configured trace sink. + + audio.md §2.2a, §3.8. + """ + + op: Literal["synthesize", "transcribe"] + input_hash: str + language: str + duration_s: float + latency_ms: int + confidence: float | None + cache_hit: bool + degraded: bool + ts_ist: str + + +TraceSink = Callable[[AudioTrace], None] + + +# --------------------------------------------------------------------------- +# Lazy dep loaders — patched by tests to inject fakes. +# --------------------------------------------------------------------------- + + +def _load_kokoro() -> Any: + """Return the ``kokoro`` module. Patched in tests.""" + + import kokoro + + return kokoro + + +def _load_faster_whisper() -> Any: + """Return the ``faster_whisper`` module. Patched in tests.""" + + import faster_whisper + + return faster_whisper + + +def _load_torchaudio_functional() -> Any: + """Return ``torchaudio.functional``. Patched in tests.""" + + import torchaudio.functional as F + + return F + + +def _load_torchaudio() -> Any: + """Return the top-level ``torchaudio`` module. Patched in tests.""" + + import torchaudio + + return torchaudio + + +def _load_soundfile() -> Any: + """Return the ``soundfile`` module. Patched in tests.""" + + import soundfile + + return soundfile + + +def _load_torch() -> Any: + """Return the ``torch`` module. Patched in tests.""" + + import torch + + return torch + + +# --------------------------------------------------------------------------- +# Helpers +# --------------------------------------------------------------------------- + + +_IST_TZ = timezone(timedelta(hours=5, minutes=30)) + + +def _ts_ist_now() -> str: + return datetime.now(tz=_IST_TZ).isoformat(timespec="milliseconds") + + +def _input_hash(payload: bytes) -> str: + return hashlib.blake2b(payload, digest_size=16).hexdigest() + + +def _logprob_to_confidence(avg_logprob: float) -> float: + """Map faster-whisper ``avg_logprob`` into [0, 1] per audio.md §3.5.""" + + clamped = max(-1.5, min(0.0, float(avg_logprob))) + return round(math.exp(clamped), 3) + + +def _riff_header_sample_rate(audio_bytes: bytes) -> int | None: + """Return the sample-rate field from a RIFF header, or None if not RIFF.""" + + if len(audio_bytes) < 28: + return None + if audio_bytes[0:4] != b"RIFF" or audio_bytes[8:12] != b"WAVE": + return None + return int(struct.unpack_from(" bytes: + """Build a 16-bit mono PCM WAV of pure silence for warmup / fallback.""" + + n_samples = max(1, int(duration_s * sample_rate_hz)) + buf = io.BytesIO() + with wave.open(buf, "wb") as w: + w.setnchannels(1) + w.setsampwidth(2) + w.setframerate(sample_rate_hz) + w.writeframes(b"\x00\x00" * n_samples) + return buf.getvalue() + + +def _np_to_wav_bytes(pcm: np.ndarray, sample_rate_hz: int) -> bytes: + """Encode a float32 mono numpy array as 16-bit PCM RIFF WAV bytes. + + Used when torchaudio is unavailable or mocked — the fallback path + produces the same byte-level contract (RIFF header + 16 kHz mono 16-bit). + """ + + if pcm.dtype != np.int16: + clipped = np.clip(pcm.astype(np.float32), -1.0, 1.0) + pcm_i16 = (clipped * 32767.0).astype(np.int16) + else: + pcm_i16 = pcm + buf = io.BytesIO() + with wave.open(buf, "wb") as w: + w.setnchannels(1) + w.setsampwidth(2) + w.setframerate(sample_rate_hz) + w.writeframes(pcm_i16.tobytes()) + return buf.getvalue() + + +# --------------------------------------------------------------------------- +# TTS +# --------------------------------------------------------------------------- + + +_TTS_CACHE_MAX_BYTES: int = 64 * 1024 * 1024 +_TTS_CACHE_MAX_ENTRIES: int = 256 + + +def _available_voice_packs(kokoro_module: Any) -> set[str]: + """Probe the installed Kokoro bundle for shipped voice-pack names. + + Looks for ``AVAILABLE_VOICES``, ``list_voices()``, or ``VOICES``. A fresh + install typically exposes at least one of these. If none is present we + fall back to the full canonical set (best-effort; runtime per-call + fallback in ``_resolve_voice_pack`` still protects against missing packs). + """ + + candidates: set[str] = set() + for attr in ("AVAILABLE_VOICES", "VOICES"): + value = getattr(kokoro_module, attr, None) + if isinstance(value, (list, tuple, set, frozenset)): + candidates.update(str(v) for v in value) + list_voices = getattr(kokoro_module, "list_voices", None) + if callable(list_voices): + try: + value = list_voices() + if isinstance(value, (list, tuple, set, frozenset)): + candidates.update(str(v) for v in value) + except Exception: # pragma: no cover — defensive + pass + if not candidates: + return set(_VOICE_PACKS_SET) + return candidates + + +_FALLBACK_CHAIN: dict[str, str] = { + "ta_female_1": "hi_female_1", + "kn_male_1": "hi_female_1", + "hi_male_1": "hi_female_1", + "hi_female_1": "en_indian_female_1", +} + + +class TTSEngine: + """Kokoro-82M wrapper. Constructed via ``get_tts_engine()``. + + One instance per process. All heavy deps are imported lazily. + """ + + def __init__( + self, + *, + model_id: str = "hexgrad/Kokoro-82M", + trace_sink: TraceSink | None = None, + ) -> None: + self._model_id = model_id + self._trace_sink = trace_sink + self._lock = threading.Lock() + self._cache: LRUCache[tuple[Any, ...], bytes] = LRUCache( + maxsize=_TTS_CACHE_MAX_BYTES, getsizeof=len + ) + self._numpy_cache: LRUCache[tuple[Any, ...], np.ndarray] = LRUCache( + maxsize=_TTS_CACHE_MAX_BYTES, getsizeof=lambda a: int(a.nbytes) + ) + self._fallback_used: dict[str, str] = {} + try: + kokoro = _load_kokoro() + except Exception as exc: # network / disk / import failure + raise ModelLoadError(f"failed to load kokoro: {exc}") from exc + self._kokoro = kokoro + try: + pipeline_cls = getattr(kokoro, "KPipeline", None) + if pipeline_cls is None: + raise AttributeError("kokoro.KPipeline missing") + self._pipeline = pipeline_cls(model_id=model_id) + except Exception as exc: + raise ModelLoadError(f"failed to construct KPipeline: {exc}") from exc + self._available_packs = _available_voice_packs(kokoro) + self._verify_critical_packs() + + def _verify_critical_packs(self) -> None: + if ( + "en_indian_female_1" not in self._available_packs + and "hi_female_1" not in self._available_packs + ): + raise ModelLoadError("no usable voice pack for hi or en") + + def _resolve_voice_pack(self, requested: VoicePack) -> tuple[VoicePack, bool, str | None]: + """Walk the fallback chain until an available pack is found. + + Returns ``(resolved_pack, degraded, fallback_from)``. + """ + + current = requested + original = requested + degraded = False + fallback_from: str | None = None + visited: set[str] = set() + while current not in self._available_packs: + if current in visited: + break + visited.add(current) + successor = _FALLBACK_CHAIN.get(current) + if successor is None: + raise ModelLoadError( + f"no usable voice pack; chain exhausted from {original!r}" + ) + fallback_from = original + current = cast("VoicePack", successor) + degraded = True + if degraded: + self._fallback_used[original] = current + return current, degraded, fallback_from + + def _emit_trace(self, trace: AudioTrace) -> None: + if self._trace_sink is None: + return + try: + self._trace_sink(trace) + except Exception: # telemetry must never break production + logger.debug("trace sink raised; swallowed", exc_info=True) + + def _render_pcm(self, text: str, voice_pack: VoicePack, seed: int) -> np.ndarray: + """Invoke Kokoro inside a forked RNG context and return 24 kHz float32 PCM.""" + + torch = _load_torch() + with torch.random.fork_rng(devices=[]): + torch.manual_seed(seed) + try: + result = self._pipeline(text, voice=voice_pack) + except MemoryError as exc: + raise TTSOutOfMemoryError(f"TTS OOM: {exc}") from exc + except RuntimeError as exc: + msg = str(exc).lower() + if "out of memory" in msg or "alloc" in msg: + raise TTSOutOfMemoryError(f"TTS OOM: {exc}") from exc + raise + return _coerce_to_float32_mono(result) + + def _resample_to_16k(self, pcm_24k: np.ndarray) -> np.ndarray: + """Downsample 24 kHz → 16 kHz via torchaudio.functional.resample.""" + + try: + F = _load_torchaudio_functional() + except Exception as exc: # pragma: no cover — hard runtime failure + raise ModelLoadError(f"torchaudio.functional missing: {exc}") from exc + torch = _load_torch() + tensor = torch.from_numpy(pcm_24k.astype(np.float32)).unsqueeze(0) + resampled = F.resample( + tensor, orig_freq=24000, new_freq=16000, lowpass_filter_width=64 + ) + out = resampled.squeeze(0).cpu().numpy().astype(np.float32) + return cast("np.ndarray", out) + + def _encode_wav(self, pcm_16k: np.ndarray, sample_rate_hz: int) -> bytes: + """Encode the 16 kHz float32 PCM into 16-bit mono RIFF WAV bytes.""" + + try: + torchaudio = _load_torchaudio() + torch = _load_torch() + tensor = torch.from_numpy(pcm_16k.astype(np.float32)).unsqueeze(0) + buf = io.BytesIO() + torchaudio.save( + buf, + tensor, + sample_rate=sample_rate_hz, + bits_per_sample=16, + format="wav", + encoding="PCM_S", + ) + return buf.getvalue() + except Exception: + # Fall back to stdlib wave encoder so the byte contract still holds + # even when torchaudio is unavailable. + return _np_to_wav_bytes(pcm_16k, sample_rate_hz) + + def synthesize( + self, + text: str, + language_code: LanguageCode, + voice_pack: VoicePack | None = None, + *, + seed: int = 0, + sample_rate_hz: int = 16000, + ) -> bytes: + """Return 16-bit PCM mono WAV bytes. audio.md §2.1, §4.4.""" + + if sample_rate_hz != 16000: + raise UnsupportedLanguageError( + f"sample_rate_hz={sample_rate_hz} unsupported; only 16000 allowed in v1" + ) + if language_code not in _LANGUAGE_CODES: + raise UnsupportedLanguageError(f"language_code={language_code!r} unsupported") + mapping = VOICE_PACKS[language_code] + if voice_pack is None: + voice_pack = mapping.default + if voice_pack not in mapping.allowed: + raise UnsupportedVoicePackError( + f"voice_pack={voice_pack!r} not allowed for language={language_code!r}" + ) + text_hash = _input_hash(text.encode("utf-8")) + cache_key = (text_hash, voice_pack, seed, sample_rate_hz, "bytes") + start = time.perf_counter() + with self._lock: + cached = self._cache.get(cache_key) + if cached is not None: + latency_ms = int((time.perf_counter() - start) * 1000) + duration_s = _wav_duration_s(cached) + self._emit_trace( + AudioTrace( + op="synthesize", + input_hash=text_hash, + language=language_code, + duration_s=duration_s, + latency_ms=latency_ms, + confidence=None, + cache_hit=True, + degraded=False, + ts_ist=_ts_ist_now(), + ) + ) + return cached + resolved_pack, degraded, _ = self._resolve_voice_pack(voice_pack) + pcm_24k = self._render_pcm(text, resolved_pack, seed) + pcm_16k = self._resample_to_16k(pcm_24k) + wav_bytes = self._encode_wav(pcm_16k, sample_rate_hz) + with self._lock: + self._cache[cache_key] = wav_bytes + latency_ms = int((time.perf_counter() - start) * 1000) + duration_s = _wav_duration_s(wav_bytes) + self._emit_trace( + AudioTrace( + op="synthesize", + input_hash=text_hash, + language=language_code, + duration_s=duration_s, + latency_ms=latency_ms, + confidence=None, + cache_hit=False, + degraded=degraded, + ts_ist=_ts_ist_now(), + ) + ) + return wav_bytes + + def synthesize_to_gradio( + self, + text: str, + language_hint: LanguageCode, + voice_pack: VoicePack | None = None, + *, + seed: int = 0, + ) -> tuple[int, np.ndarray]: + """Return ``(sample_rate, float32 mono ndarray)``. audio.md §2.1.""" + + if language_hint not in _LANGUAGE_CODES: + raise UnsupportedLanguageError(f"language_hint={language_hint!r} unsupported") + mapping = VOICE_PACKS[language_hint] + if voice_pack is None: + voice_pack = mapping.default + if voice_pack not in mapping.allowed: + raise UnsupportedVoicePackError( + f"voice_pack={voice_pack!r} not allowed for language={language_hint!r}" + ) + text_hash = _input_hash(text.encode("utf-8")) + sample_rate_hz = 16000 + cache_key = (text_hash, voice_pack, seed, sample_rate_hz, "numpy") + start = time.perf_counter() + with self._lock: + cached = self._numpy_cache.get(cache_key) + if cached is not None: + self._emit_trace( + AudioTrace( + op="synthesize", + input_hash=text_hash, + language=language_hint, + duration_s=float(len(cached)) / sample_rate_hz, + latency_ms=int((time.perf_counter() - start) * 1000), + confidence=None, + cache_hit=True, + degraded=False, + ts_ist=_ts_ist_now(), + ) + ) + return sample_rate_hz, cached.copy() + resolved_pack, degraded, _ = self._resolve_voice_pack(voice_pack) + pcm_24k = self._render_pcm(text, resolved_pack, seed) + pcm_16k = self._resample_to_16k(pcm_24k) + with self._lock: + self._numpy_cache[cache_key] = pcm_16k + self._emit_trace( + AudioTrace( + op="synthesize", + input_hash=text_hash, + language=language_hint, + duration_s=float(len(pcm_16k)) / sample_rate_hz, + latency_ms=int((time.perf_counter() - start) * 1000), + confidence=None, + cache_hit=False, + degraded=degraded, + ts_ist=_ts_ist_now(), + ) + ) + return sample_rate_hz, pcm_16k.copy() + + def warmup(self) -> None: + """Probe each voice pack; log WARN on missing Indic packs. audio.md §4.3.1.""" + + for lang, mapping in VOICE_PACKS.items(): + for pack in mapping.allowed: + if pack not in self._available_packs: + logger.warning( + "voice pack %r missing from bundle (language=%s); will fall back at synth time", + pack, + lang, + ) + try: + self.synthesize("warmup", "en") + except Exception: # pragma: no cover — warmup best-effort + logger.debug("warmup synthesize failed; continuing", exc_info=True) + + +def _coerce_to_float32_mono(result: Any) -> np.ndarray: + """Turn whatever Kokoro returned into a 1-D float32 numpy array.""" + + torch = _load_torch() + if hasattr(result, "cpu") and hasattr(result, "numpy"): + arr = result.detach().cpu().numpy() + elif isinstance(result, tuple): + audio_like = result[0] + if hasattr(audio_like, "cpu") and hasattr(audio_like, "numpy"): + arr = audio_like.detach().cpu().numpy() + else: + arr = np.asarray(audio_like) + elif isinstance(result, np.ndarray): + arr = result + else: + try: + tensor = torch.as_tensor(result) + arr = tensor.detach().cpu().numpy() + except Exception as exc: # pragma: no cover — defensive + raise TTSOutOfMemoryError(f"unexpected Kokoro return type: {type(result)!r}: {exc}") from exc + arr = np.asarray(arr, dtype=np.float32).reshape(-1) + return arr + + +def _wav_duration_s(wav_bytes: bytes) -> float: + """Return the duration in seconds for a RIFF WAV payload (best-effort).""" + + try: + with wave.open(io.BytesIO(wav_bytes), "rb") as w: + frames = w.getnframes() + rate = w.getframerate() + if rate <= 0: + return 0.0 + return round(frames / rate, 3) + except Exception: + return 0.0 + + +# --------------------------------------------------------------------------- +# ASR +# --------------------------------------------------------------------------- + + +def _map_language(code: str | None) -> LanguageCode | Literal["unknown"]: + if code in _LANGUAGE_CODES: + return cast("LanguageCode", code) + return "unknown" + + +def _nfc(text: str) -> str: + return unicodedata.normalize("NFC", text).strip() + + +class ASREngine: + """faster-whisper-small wrapper. Constructed via ``get_asr_engine()``. + + audio.md §2.2. Heavy deps loaded lazily. + """ + + def __init__( + self, + *, + model_id: str = "Systran/faster-whisper-small", + compute_type: Literal["int8", "int8_float16"] = "int8", + trace_sink: TraceSink | None = None, + ) -> None: + self._model_id = model_id + self._compute_type = compute_type + self._trace_sink = trace_sink + self._lock = threading.Lock() + try: + fw = _load_faster_whisper() + except Exception as exc: + raise ModelLoadError(f"failed to load faster_whisper: {exc}") from exc + model_cls = getattr(fw, "WhisperModel", None) + if model_cls is None: + raise ModelLoadError("faster_whisper.WhisperModel missing") + try: + self._model = model_cls(model_id, compute_type=compute_type, device="cpu") + except Exception as exc: + raise ModelLoadError(f"failed to construct WhisperModel: {exc}") from exc + + def _emit_trace(self, trace: AudioTrace) -> None: + if self._trace_sink is None: + return + try: + self._trace_sink(trace) + except Exception: + logger.debug("trace sink raised; swallowed", exc_info=True) + + def transcribe( + self, + audio_bytes: bytes, + language_hint: LanguageCode | None, + *, + beam_size: int = 1, + vad_filter: bool = True, + max_duration_s: float = 30.0, + ) -> TranscriptResult: + """Decode WAV/PCM bytes. audio.md §2.2, §3.5, §4.4.""" + + start = time.perf_counter() + pcm, clip_duration = self._decode_input(audio_bytes) + if clip_duration > max_duration_s: + pcm = pcm[: int(max_duration_s * 16000)] + clip_duration = max_duration_s + language_for_whisper: str | None + if language_hint == "hinglish": + language_for_whisper = "hi" + elif language_hint is None: + language_for_whisper = None + else: + language_for_whisper = language_hint + segments, info = self._run_whisper( + pcm, + language=language_for_whisper, + beam_size=beam_size, + vad_filter=vad_filter, + ) + segments_list = list(segments) + detected_code = _map_language(getattr(info, "language", None)) + vad_dropped_all = getattr(info, "vad_dropped_all_segments", None) + if vad_dropped_all is None: + vad_dropped_all = len(segments_list) == 0 and vad_filter + combined_text = _nfc("".join(getattr(s, "text", "") for s in segments_list)) + duration_s = round(min(float(clip_duration), float(max_duration_s)), 3) + degraded = False + if combined_text == "": + confidence = 0.0 + if vad_dropped_all: + detected: LanguageCode | Literal["unknown"] = "unknown" + else: + detected = detected_code + degraded = True + else: + confidence = _duration_weighted_confidence(segments_list) + detected = _infer_hinglish(detected_code, combined_text, language_hint) + result = TranscriptResult( + text=combined_text, + language_detected=detected, + confidence=confidence, + duration_s=duration_s, + ) + latency_ms = int((time.perf_counter() - start) * 1000) + self._emit_trace( + AudioTrace( + op="transcribe", + input_hash=_input_hash(audio_bytes), + language=language_hint or "unknown", + duration_s=duration_s, + latency_ms=latency_ms, + confidence=confidence, + cache_hit=False, + degraded=degraded, + ts_ist=_ts_ist_now(), + ) + ) + return result + + def _decode_input(self, audio_bytes: bytes) -> tuple[np.ndarray, float]: + """Return (float32 mono @ 16 kHz, duration_s); raise AudioDecodeError on mismatch.""" + + if len(audio_bytes) >= 3 and audio_bytes[:3] == b"ID3": + raise AudioDecodeError("MP3 / ID3-tagged inputs are not supported (no ffmpeg in image)") + rate = _riff_header_sample_rate(audio_bytes) + if rate is not None: + if rate != 16000: + raise AudioDecodeError("input must be 16 kHz mono; caller must pre-resample") + try: + sf = _load_soundfile() + data, sr = sf.read(io.BytesIO(audio_bytes), dtype="float32", always_2d=False) + except Exception as exc: + raise AudioDecodeError(f"soundfile failed to decode RIFF WAV: {exc}") from exc + if sr != 16000: + raise AudioDecodeError("input must be 16 kHz mono; caller must pre-resample") + arr = np.asarray(data, dtype=np.float32).reshape(-1) + duration = float(len(arr)) / 16000.0 + return arr, duration + # Raw float32 PCM path (demo mic input). 16 kHz assumed. We only accept + # payloads that look like plausible audio — ≥ 0.25 s of float32 samples + # (4000 × 4 = 16000 bytes) whose magnitudes fit inside the normalized + # [-1, 1] range that Gradio emits. Short / out-of-range payloads are + # rejected so arbitrary random bytes do not slip through. + min_raw_pcm_bytes = 4000 * 4 + if len(audio_bytes) >= min_raw_pcm_bytes and len(audio_bytes) % 4 == 0: + pcm = np.frombuffer(audio_bytes, dtype=np.float32).copy() + if pcm.size and np.all(np.isfinite(pcm)) and np.max(np.abs(pcm)) <= 2.0: + duration = float(pcm.size) / 16000.0 + return pcm, duration + raise AudioDecodeError("input is not a valid 16 kHz RIFF WAV or float32 PCM payload") + + def _run_whisper( + self, + pcm: np.ndarray, + *, + language: str | None, + beam_size: int, + vad_filter: bool, + ) -> tuple[Any, Any]: + try: + segments, info = self._model.transcribe( + pcm, + language=language, + beam_size=beam_size, + vad_filter=vad_filter, + ) + except Exception as exc: + raise AudioDecodeError(f"whisper decode failed: {exc}") from exc + return segments, info + + def warmup(self) -> None: + """Run one transcribe() on 0.5 s of silence to force load. audio.md §2.2.""" + + silence = _pcm16_silence_wav(0.5) + try: + self.transcribe(silence, "en") + except Exception: # pragma: no cover — warmup best-effort + logger.debug("warmup transcribe failed; continuing", exc_info=True) + + +def _duration_weighted_confidence(segments: list[Any]) -> float: + if not segments: + return 0.0 + total_dur = 0.0 + weighted = 0.0 + for seg in segments: + start = float(getattr(seg, "start", 0.0) or 0.0) + end = float(getattr(seg, "end", 0.0) or 0.0) + dur = max(0.0, end - start) + avg_logprob = float(getattr(seg, "avg_logprob", 0.0) or 0.0) + confidence = _logprob_to_confidence(avg_logprob) + if dur == 0.0: + total_dur += 1.0 + weighted += confidence + else: + total_dur += dur + weighted += confidence * dur + if total_dur == 0.0: + return 0.0 + return round(weighted / total_dur, 3) + + +def _infer_hinglish( + detected: LanguageCode | Literal["unknown"], + text: str, + hint: LanguageCode | None, +) -> LanguageCode | Literal["unknown"]: + """Downgrade ``hi`` to ``hinglish`` when the decoded text is code-mixed. + + Heuristic per audio.md §3.6: ≥ 2 ASCII words intermixed with Devanagari. + """ + + if hint != "hinglish": + return detected + if detected != "hi": + return detected + ascii_words = [tok for tok in text.split() if tok.isascii() and tok.isalpha()] + has_devanagari = any("ऀ" <= ch <= "ॿ" for ch in text) + if len(ascii_words) >= 2 and has_devanagari: + return "hinglish" + return detected + + +# --------------------------------------------------------------------------- +# Singletons +# --------------------------------------------------------------------------- + + +_tts_engine: TTSEngine | None = None +_asr_engine: ASREngine | None = None +_tts_lock = threading.Lock() +_asr_lock = threading.Lock() + + +def get_tts_engine( + *, trace_sink: TraceSink | None = None, model_id: str = "hexgrad/Kokoro-82M" +) -> TTSEngine: + """Return the process-wide TTSEngine singleton. audio.md §3.2, §3.8.""" + + global _tts_engine + with _tts_lock: + if _tts_engine is None: + _tts_engine = TTSEngine(model_id=model_id, trace_sink=trace_sink) + elif trace_sink is not None and trace_sink is not _tts_engine._trace_sink: + logger.warning("get_tts_engine: different sink passed after construction; ignoring") + return _tts_engine + + +def get_asr_engine( + *, + trace_sink: TraceSink | None = None, + model_id: str = "Systran/faster-whisper-small", + compute_type: Literal["int8", "int8_float16"] = "int8", +) -> ASREngine: + """Return the process-wide ASREngine singleton. audio.md §3.2, §3.8.""" + + global _asr_engine + with _asr_lock: + if _asr_engine is None: + _asr_engine = ASREngine( + model_id=model_id, compute_type=compute_type, trace_sink=trace_sink + ) + elif trace_sink is not None and trace_sink is not _asr_engine._trace_sink: + logger.warning("get_asr_engine: different sink passed after construction; ignoring") + return _asr_engine + + +def _reset_singletons_for_tests() -> None: + """Tear down singletons. Tests only. audio.md §3.2 "Unload. Never." exemption.""" + + global _tts_engine, _asr_engine + with _tts_lock: + _tts_engine = None + with _asr_lock: + _asr_engine = None + + +__all__ = [ + "AudioDecodeError", + "AudioError", + "AudioTooLongError", + "AudioTrace", + "ASREngine", + "LanguageCode", + "ModelLoadError", + "TTSEngine", + "TTSOutOfMemoryError", + "TranscriptResult", + "TraceSink", + "UnsupportedLanguageError", + "UnsupportedVoicePackError", + "VOICE_PACKS", + "VoicePack", + "VoicePackMapping", + "get_asr_engine", + "get_tts_engine", +] diff --git a/cells/step_10_env.md b/cells/step_10_env.md new file mode 100644 index 0000000000000000000000000000000000000000..7f684589468828686a3448d3c7db35dbf14c66bb --- /dev/null +++ b/cells/step_10_env.md @@ -0,0 +1,83 @@ +# step_10_env — DriftCallEnv + +Implements `docs/modules/env.md` and `DESIGN.md §4`. + +## Public surface + +| Symbol | Kind | Notes | +|---|---|---| +| `DriftCallEnv` | class | OpenEnv-compliant RL environment. Single-session, single-episode-at-a-time. | +| `EnvConfig` | frozen dataclass | Validated config snapshot. Built via `EnvConfig.from_mapping(...)`. | +| `Episode` | frozen dataclass | Terminal-only snapshot fed to `cells.step_08_rewards.compute_rewards`. | +| `DriftScheduler` | Protocol | `(stage, seed, goal) -> tuple[DriftEvent, ...]`. Default: `drift_injector.build_schedule`. | +| `TTSEngine` / `ASREngine` | Protocols | Audio boundary contracts (env.md §2.1). | +| `DriftCallEnvError` and 12 subclasses | exceptions | E1..E12 typed taxonomy. | + +## Wiring + +``` +reset(seed) + └── task_generator.generate(seed, stage, language_weights) + └── per-domain vendor.initial_state(seed, goal) # airline, cab, restaurant, hotel, payment + └── scheduler(stage, seed, goal) # default = drift_injector.build_schedule + └── audio_boundary_enabled? tts_engine.synthesize(seed_utterance, language) + └── DriftCallObservation(turn=0, ...) + +step(action, *, force_drift_pattern=None) + 1a. _validate_action(action) # pure, raises InvalidActionError BEFORE mutation + 1b. force_drift_pattern resolved # unknown -> InvalidActionError + 2. turn += 1 # via dataclasses.replace + 3. drift fold: # forced pattern OR scheduled pending drifts + - sort by (turn asc, pattern_id asc) + - apply via drift_injector.apply_drift + 4. side-channel emit pass # vendor.emit_side_channel_if_pending per domain + 5. dispatch: + TOOL_CALL -> vendor.dispatch(...) and merge any pending notice into ToolResult + SPEAK/CLARIFY-> no state change + PROBE_SCHEMA -> vendor.describe_schema(state, version), wrapped as ToolResult + SUBMIT -> terminate("SUBMIT") + ABORT -> terminate("ABORT") + 6. record action (and ToolResult, if any) via dataclasses.replace + 7. if turn >= max_turns -> terminate("TIMEOUT") + 8. if terminal -> build Episode + step_08_rewards.compute_rewards (memoized) + 9. return DriftCallObservation +``` + +## Termination + +`terminated_by ∈ {SUBMIT, ABORT, TIMEOUT, ANTI_HACK}`. Reward layer reads `terminated_by` to force `r1=0` for ABORT/TIMEOUT/ANTI_HACK. `Episode` and `Rewards` are write-once; `episode()`/`rewards()` return memoized identities. + +## Determinism contract + +Same `(config, seed)` ⇒ byte-identical `goal`, `drift_schedule`, and initial `vendor_states`. The only non-deterministic field is `episode_id` (uuid4), which is purely an audit handle (env.md §9 Q5). + +## Error taxonomy (E1–E12) + +All extend `DriftCallEnvError(Exception)`: + +| # | Class | When | +|---|---|---| +| E1 | `InvalidConfigError` | unknown key, bad weights, missing audio engine, etc. | +| E2 | `EnvNotReadyError` | step/state/episode/rewards before reset | +| E3 | `EnvClosedError` | reset/step after close | +| E4 | `InvalidActionError` | per-`ActionType` field-matrix violation; force_drift_pattern unknown | +| E5 | `EpisodeAlreadyTerminalError` | step after termination | +| E6 | `EpisodeNotTerminalError` | episode/rewards before termination | +| E7 | `ConcurrentStepError` | reentrant step | +| E8 | `UnknownDomainError` | PROBE_SCHEMA on unregistered domain | +| E9 | `UnknownToolError` | TOOL_CALL with tool_name not in available_tools | +| E10 | `DriftInjectionError` | drift fold failure (propagated from drift_injector) | +| E11 | `RewardComputationError` | compute_rewards failure | +| E12 | `AudioPipelineError` | TTS/ASR engine raised at boundary | + +Validation in `_validate_action` is strictly pure: raises before any state mutation, so the env remains valid for a subsequent `step()`. + +## Audio boundary + +`audio_boundary_enabled=True` requires both `tts_engine` and `asr_engine`. On `reset()` the env calls `tts_engine.synthesize(goal.seed_utterance, goal.language)`; the canonical `last_transcript` remains the textual `seed_utterance`. The audio pipeline never feeds bytes back into reward computation. + +## Out of scope + +- LLM judging — never. The env is the judge. +- Concurrency — single-session by contract; no locks, no asyncio. +- Disk/network I/O at `__init__` — strictly forbidden. diff --git a/cells/step_10_env.py b/cells/step_10_env.py new file mode 100644 index 0000000000000000000000000000000000000000..60178409d74c3f74b0903e9ea01ad4840abe4f36 --- /dev/null +++ b/cells/step_10_env.py @@ -0,0 +1,1019 @@ +"""Cell 10 — DriftCallEnv integration class. + +Implements ``docs/modules/env.md`` and DESIGN.md §4. ``DriftCallEnv`` is the +single public surface that composes models, vendors, drift_injector, +task_generator, rewards, and the optional audio boundary into an +OpenEnv-compliant RL environment. + +Hard rules (env.md §3.8, CLAUDE.md §0): +- All public dataclasses are frozen. +- State transitions go through ``dataclasses.replace``; no in-place mutation. +- Validation is pure: ``InvalidActionError`` raises BEFORE any state mutation. +- Rewards are computed exactly once at termination and memoized. +- No LLM judge anywhere; no network/disk I/O at ``__init__``. +""" + +from __future__ import annotations + +import os +import struct +import uuid +from dataclasses import dataclass, field, replace +from datetime import datetime, timedelta, timezone +from typing import TYPE_CHECKING, Any, Literal, Protocol, cast + +from cells.step_04_models import ( + ActionType, + DriftCallAction, + DriftCallObservation, + DriftCallState, + DriftEvent, + GoalSpec, + ToolResult, +) +from cells.step_05_vendors import TOOLS as VENDOR_TOOLS +from cells.step_05_vendors import VENDOR_REGISTRY +from cells.step_06_drift_injector import ( + DriftCatalogueError, + DriftDomainMismatchError, + DriftReapplicationError, + DriftScheduleConflictError, + UnknownDriftPatternError, + apply_drift, + build_schedule, + list_patterns, +) +from cells.step_07_task_generator import ( + InvalidLanguageWeightError, + InvalidStageError, +) +from cells.step_07_task_generator import ( + generate as task_generate, +) + +if TYPE_CHECKING: + from collections.abc import Mapping + +# rewards is imported lazily inside _compute_rewards to keep the env importable +# even before step_08_rewards.py lands; failures surface as RewardComputationError. + +_DEFAULT_LANGUAGE_WEIGHTS: dict[str, float] = { + "en": 0.4, + "hinglish": 0.4, + "hi": 0.1, + "ta": 0.05, + "kn": 0.05, +} + +_LANGUAGE_CODES: frozenset[str] = frozenset({"hi", "ta", "kn", "en", "hinglish"}) + +_STAGE_MAX_TURNS: dict[int, int] = {1: 8, 2: 12, 3: 16} + +_VENDOR_DOMAINS: tuple[str, ...] = ("airline", "cab", "restaurant", "hotel", "payment") + +_TERMINATED_VALUES: frozenset[str] = frozenset({"SUBMIT", "ABORT", "TIMEOUT", "ANTI_HACK"}) + +_NOW_IST: datetime = datetime(2026, 4, 25, 10, 0, tzinfo=timezone(timedelta(hours=5, minutes=30))) + + +# --------------------------------------------------------------------------- +# Error taxonomy (env.md §5) +# --------------------------------------------------------------------------- + + +class DriftCallEnvError(Exception): + """Root for every typed env error (env.md §5).""" + + +class InvalidConfigError(DriftCallEnvError): + """E1 — malformed config dict.""" + + +class EnvNotReadyError(DriftCallEnvError): + """E2 — operation issued before reset().""" + + +class EnvClosedError(DriftCallEnvError): + """E3 — operation issued after close().""" + + +class InvalidActionError(DriftCallEnvError): + """E4 — action fails the per-ActionType field matrix.""" + + +class EpisodeAlreadyTerminalError(DriftCallEnvError): + """E5 — step() called after termination.""" + + +class EpisodeNotTerminalError(DriftCallEnvError): + """E6 — episode()/rewards() called before termination.""" + + +class ConcurrentStepError(DriftCallEnvError): + """E7 — reentrant step() detected.""" + + +class UnknownDomainError(DriftCallEnvError): + """E8 — PROBE_SCHEMA on a domain that is not registered.""" + + +class UnknownToolError(DriftCallEnvError): + """E9 — TOOL_CALL with a tool_name not in available_tools().""" + + +class DriftInjectionError(DriftCallEnvError): + """E10 — drift fold raised; surfaced as-is.""" + + +class RewardComputationError(DriftCallEnvError): + """E11 — compute_rewards raised; surfaced as-is.""" + + +class AudioPipelineError(DriftCallEnvError): + """E12 — TTS/ASR engine raised on a step()/reset() boundary.""" + + +_ALL_ERROR_CLASSES: tuple[type[DriftCallEnvError], ...] = ( + InvalidConfigError, + EnvNotReadyError, + EnvClosedError, + InvalidActionError, + EpisodeAlreadyTerminalError, + EpisodeNotTerminalError, + ConcurrentStepError, + UnknownDomainError, + UnknownToolError, + DriftInjectionError, + RewardComputationError, + AudioPipelineError, +) + + +# --------------------------------------------------------------------------- +# Protocols (env.md §2.1) +# --------------------------------------------------------------------------- + + +class DriftScheduler(Protocol): + def __call__( + self, stage: int, episode_seed: int, goal: GoalSpec + ) -> tuple[DriftEvent, ...]: ... + + +class TTSEngine(Protocol): + def synthesize( + self, + text: str, + language_code: str, + voice_pack: Any | None = None, + *, + seed: int = 0, + sample_rate_hz: int = 16000, + ) -> bytes: ... + + +class ASREngine(Protocol): + def transcribe( + self, + audio_bytes: bytes, + language_hint: str | None, + *, + beam_size: int = 1, + vad_filter: bool = True, + max_duration_s: float = 30.0, + ) -> Any: ... + + +def _default_scheduler( + stage: int, episode_seed: int, goal: GoalSpec +) -> tuple[DriftEvent, ...]: + return build_schedule(stage, episode_seed, goal) + + +# --------------------------------------------------------------------------- +# Episode (env.md §4.3) — built at termination, fed to rewards.compute_rewards. +# Matches the Episode shape consumed by step_08_rewards (kw fields). +# --------------------------------------------------------------------------- + + +@dataclass(frozen=True) +class Episode: + episode_id: str + goal: GoalSpec + actions: tuple[DriftCallAction, ...] + action_turns: tuple[int, ...] + tool_results: tuple[ToolResult, ...] + tool_result_turns: tuple[int, ...] + drift_log: tuple[DriftEvent, ...] + vendor_states_final: dict[str, dict[str, Any]] + schema_versions_final: dict[str, str] + max_turns: int + turns_used: int + terminated_by: Literal["SUBMIT", "ABORT", "TIMEOUT", "ANTI_HACK"] + stage: Literal[1, 2, 3] + drift_pattern_overrides: dict[str, Any] = field(default_factory=dict) + + +# --------------------------------------------------------------------------- +# EnvConfig (env.md §4.1) +# --------------------------------------------------------------------------- + + +@dataclass(frozen=True) +class EnvConfig: + curriculum_stage: Literal[1, 2, 3] + language_weights: dict[str, float] + audio_boundary_enabled: bool + max_turns_override: int | None + scheduler: DriftScheduler + tts_engine: TTSEngine | None + asr_engine: ASREngine | None + + @classmethod + def from_mapping(cls, raw: Mapping[str, Any] | None) -> EnvConfig: + allowed = { + "curriculum_stage", + "language_weights", + "audio_boundary_enabled", + "max_turns_override", + "scheduler", + "tts_engine", + "asr_engine", + } + if raw is None: + raw = {} + if not isinstance(raw, dict): + raise InvalidConfigError( + f"config must be a dict or None, got {type(raw).__name__}" + ) + + unknown = set(raw.keys()) - allowed + if unknown: + raise InvalidConfigError( + f"unknown config key(s): {sorted(unknown)}; " + f"allowed: {sorted(allowed)}" + ) + + stage_raw = raw.get("curriculum_stage", 1) + if isinstance(stage_raw, bool) or not isinstance(stage_raw, int): + raise InvalidConfigError( + f"curriculum_stage must be int in {{1,2,3}}, got " + f"{type(stage_raw).__name__}" + ) + if stage_raw not in (1, 2, 3): + raise InvalidConfigError( + f"curriculum_stage must be 1, 2, or 3; got {stage_raw!r}" + ) + stage = cast("Literal[1, 2, 3]", stage_raw) + + weights_raw = raw.get("language_weights", _DEFAULT_LANGUAGE_WEIGHTS) + if not isinstance(weights_raw, dict) or not weights_raw: + raise InvalidConfigError( + "language_weights must be a non-empty dict" + ) + for k, v in weights_raw.items(): + if k not in _LANGUAGE_CODES: + raise InvalidConfigError( + f"language_weights: unknown language {k!r}; " + f"allowed: {sorted(_LANGUAGE_CODES)}" + ) + if isinstance(v, bool) or not isinstance(v, (int, float)): + raise InvalidConfigError( + f"language_weights[{k!r}] must be numeric, got " + f"{type(v).__name__}" + ) + if v < 0: + raise InvalidConfigError( + f"language_weights[{k!r}]={v} is negative" + ) + total = sum(float(v) for v in weights_raw.values()) + if abs(total - 1.0) > 1e-6: + raise InvalidConfigError( + f"language_weights sum {total!r} not within 1.0 ± 1e-6" + ) + # Frozen copy. + weights: dict[str, float] = {k: float(v) for k, v in weights_raw.items()} + + audio_enabled_raw = raw.get("audio_boundary_enabled", False) + if not isinstance(audio_enabled_raw, bool): + raise InvalidConfigError( + f"audio_boundary_enabled must be bool, got " + f"{type(audio_enabled_raw).__name__}" + ) + audio_enabled = audio_enabled_raw + + max_turns_override = raw.get("max_turns_override") + if max_turns_override is not None: + if isinstance(max_turns_override, bool) or not isinstance( + max_turns_override, int + ): + raise InvalidConfigError( + f"max_turns_override must be int or None, got " + f"{type(max_turns_override).__name__}" + ) + if max_turns_override < 1: + raise InvalidConfigError( + f"max_turns_override must be >= 1, got {max_turns_override}" + ) + + scheduler = raw.get("scheduler", _default_scheduler) + if not callable(scheduler): + raise InvalidConfigError("scheduler must be callable") + + tts_engine = raw.get("tts_engine") + asr_engine = raw.get("asr_engine") + + if audio_enabled: + if tts_engine is None: + raise InvalidConfigError( + "tts_engine is required when audio_boundary_enabled is True" + ) + if asr_engine is None: + raise InvalidConfigError( + "asr_engine is required when audio_boundary_enabled is True" + ) + else: + if tts_engine is not None: + raise InvalidConfigError( + "tts_engine must be None when audio_boundary_enabled is False" + ) + if asr_engine is not None: + raise InvalidConfigError( + "asr_engine must be None when audio_boundary_enabled is False" + ) + + return cls( + curriculum_stage=stage, + language_weights=weights, + audio_boundary_enabled=audio_enabled, + max_turns_override=max_turns_override, + scheduler=cast("DriftScheduler", scheduler), + tts_engine=cast("TTSEngine | None", tts_engine), + asr_engine=cast("ASREngine | None", asr_engine), + ) + + +# --------------------------------------------------------------------------- +# DriftCallEnv +# --------------------------------------------------------------------------- + + +def _make_seed_from_urandom() -> int: + raw = os.urandom(8) + (value,) = struct.unpack(" dict[str, Any]: + """Coerce a frozen vendor dataclass (or already-dict) into a plain dict.""" + if isinstance(state, dict): + return dict(state) + # All vendor states are frozen dataclasses. + import dataclasses as _dc + + if _dc.is_dataclass(state) and not isinstance(state, type): + return _dc.asdict(state) + # Defensive: best-effort fallback. + return {"_raw": repr(state)} + + +class DriftCallEnv: + """OpenEnv-compliant RL environment for DriftCall (env.md §1).""" + + # -- construction -------------------------------------------------------- + + def __init__(self, config: dict[str, Any] | None = None) -> None: + self._config: EnvConfig = EnvConfig.from_mapping(config) + self._state: DriftCallState | None = None + self._rewards: Any | None = None + self._episode: Episode | None = None + self._closed: bool = False + self._seed: int | None = None + self._episode_id: str | None = None + # Pending side-channel notices keyed by domain (env.md §3.3). + self._side_channel_pending: dict[str, str] = {} + # Per-vendor-state cache (frozen dataclass or dict). Kept on the env + # because DriftCallState.vendor_states is a dict[str, dict] for + # compatibility with the design dataclass. + self._vendor_state_objects: dict[str, Any] = {} + # Re-entrancy guard (E7). + self._step_in_progress: bool = False + + # -- internal helpers ---------------------------------------------------- + + @property + def _max_turns(self) -> int: + if self._config.max_turns_override is not None: + return int(self._config.max_turns_override) + return _STAGE_MAX_TURNS[self._config.curriculum_stage] + + def _available_tools(self) -> tuple[str, ...]: + return VENDOR_TOOLS + + def _ensure_ready_for_step(self) -> None: + if self._closed: + raise EnvClosedError("env is closed") + if self._state is None: + raise EnvNotReadyError("reset() must be called before step()") + if self._state.done: + raise EpisodeAlreadyTerminalError( + f"episode already terminated (terminated_by={self._terminated_by()})" + ) + + def _terminated_by(self) -> str | None: + return self._episode.terminated_by if self._episode is not None else None + + # -- OpenEnv primitives -------------------------------------------------- + + def reset(self, seed: int | None = None) -> DriftCallObservation: + if self._closed: + raise EnvClosedError("env is closed") + + if seed is None: + seed = _make_seed_from_urandom() + if isinstance(seed, bool) or not isinstance(seed, int): + raise InvalidActionError( + f"seed must be int or None, got {type(seed).__name__}" + ) + + self._seed = int(seed) + # Reset memoization; legacy state is dropped before any propagatable + # exception can leak (env.md §2.2 docstring). + self._state = None + self._rewards = None + self._episode = None + self._side_channel_pending = {} + self._vendor_state_objects = {} + self._episode_id = None + + try: + goal = task_generate( + self._seed, + self._config.curriculum_stage, + cast("dict[Any, float]", self._config.language_weights), + ) + except (InvalidLanguageWeightError, InvalidStageError) as exc: + # E1-class reset failure (env.md §2.2 raises clause). + raise InvalidConfigError(str(exc)) from exc + + # Initial per-domain vendor state objects (frozen dataclasses). + vendor_state_objects: dict[str, Any] = {} + vendor_states_dict: dict[str, dict[str, Any]] = {} + for domain in _VENDOR_DOMAINS: + ns = VENDOR_REGISTRY[domain] + vs = ns.initial_state(self._seed, goal) + vendor_state_objects[domain] = vs + vendor_states_dict[domain] = _vendor_state_to_dict(vs) + + schema_versions = {d: "v1" for d in _VENDOR_DOMAINS} + + try: + schedule = self._config.scheduler( + self._config.curriculum_stage, self._seed, goal + ) + except ( + DriftScheduleConflictError, + DriftCatalogueError, + UnknownDriftPatternError, + DriftDomainMismatchError, + ) as exc: + # Bad scheduler at reset is an E1 (env.md §7.4). + raise InvalidConfigError(f"scheduler failure: {exc}") from exc + + self._episode_id = uuid.uuid4().hex + + max_turns = self._max_turns + new_state = DriftCallState( + episode_id=self._episode_id, + goal=goal, + vendor_states=vendor_states_dict, + schema_versions=schema_versions, + drift_schedule=tuple(schedule), + drift_fired=(), + turn=0, + max_turns=max_turns, + actions=(), + done=False, + ) + self._state = new_state + self._vendor_state_objects = vendor_state_objects + + if self._config.audio_boundary_enabled: + tts = self._config.tts_engine + assert tts is not None # validated in EnvConfig + try: + tts.synthesize(goal.seed_utterance, goal.language) + except Exception as exc: # noqa: BLE001 — surface as E12-class + # Audio failure on reset leaves env unready (env.md §5 E12). + self._state = None + self._vendor_state_objects = {} + self._episode_id = None + raise AudioPipelineError(f"TTS reset failure: {exc}") from exc + + return self._build_observation() + + def step( + self, + action: DriftCallAction, + *, + force_drift_pattern: str | None = None, + ) -> DriftCallObservation: + # 1a. Pure validation — must raise before any state mutation. + self._ensure_ready_for_step() + self._validate_action(action) + if force_drift_pattern is not None: + valid_ids = {p.id for p in list_patterns()} + if force_drift_pattern not in valid_ids: + raise InvalidActionError( + f"force_drift_pattern {force_drift_pattern!r} not a known " + f"pattern_id" + ) + + if self._step_in_progress: + raise ConcurrentStepError("reentrant step() detected") + self._step_in_progress = True + try: + return self._step_inner(action, force_drift_pattern) + finally: + self._step_in_progress = False + + def _step_inner( + self, + action: DriftCallAction, + force_drift_pattern: str | None, + ) -> DriftCallObservation: + assert self._state is not None # ensured above + # 2. Increment turn counter. + turn_current = self._state.turn + 1 + self._state = replace(self._state, turn=turn_current) + + # 3. Fire drifts for this turn. + self._fire_drifts(turn_current, force_drift_pattern) + + # 4. Side-channel emit pass — refresh pending notices for any vendor + # whose state just mutated. + self._emit_side_channel() + + # 5. Dispatch action. + new_tool_result, terminate, terminated_by = self._dispatch(action) + + # 6. Record action (and ToolResult, if any) via dataclasses.replace. + new_actions = self._state.actions + (action,) + if new_tool_result is not None: + # Tool result history lives on the state's vendor history; here we + # rely on the running observation history we will rebuild in §3.4. + self._tool_results = self._tool_results + (new_tool_result,) + self._tool_result_turns = self._tool_result_turns + (turn_current,) + self._action_turns = self._action_turns + (turn_current,) + self._state = replace(self._state, actions=new_actions) + + # 7. Budget check — only if action did not already terminate. + if not terminate and turn_current >= self._state.max_turns: + terminate = True + terminated_by = "TIMEOUT" + + # 8. If terminal, build Episode + compute rewards. + if terminate: + assert terminated_by is not None + self._terminate(terminated_by) + + # 9. Build observation. + return self._build_observation() + + def state(self) -> DriftCallState: + if self._state is None: + raise EnvNotReadyError("reset() must be called before state()") + return self._state + + def close(self) -> None: + # Idempotent. + self._closed = True + # Per env.md §9 Q7: never invoke close on shared audio engines. + # Only drop per-env state. + self._side_channel_pending = {} + self._vendor_state_objects = {} + # Note: we keep self._state, self._rewards, self._episode so post-close + # audits still work (env.md §7.11). + + def episode(self) -> Episode: + if self._episode is None: + raise EpisodeNotTerminalError("episode is not terminal") + return self._episode + + def rewards(self) -> Any: + if self._rewards is None: + raise EpisodeNotTerminalError("episode is not terminal") + return self._rewards + + def done(self) -> bool: + if self._state is None: + return False + return bool(self._state.done) + + # -- validation ---------------------------------------------------------- + + def _validate_action(self, action: DriftCallAction) -> None: + if not isinstance(action, DriftCallAction): + raise InvalidActionError( + f"action must be DriftCallAction, got {type(action).__name__}" + ) + atype = action.action_type + if not isinstance(atype, ActionType): + raise InvalidActionError( + f"action_type must be ActionType, got {type(atype).__name__}" + ) + + # rationale length cap (env.md §3.1). + if action.rationale is not None and len(action.rationale) > 200: + raise InvalidActionError( + f"rationale length {len(action.rationale)} exceeds 200" + ) + + if atype == ActionType.TOOL_CALL: + if not action.tool_name or not isinstance(action.tool_name, str): + raise InvalidActionError("TOOL_CALL requires non-empty tool_name") + if action.tool_args is None or not isinstance(action.tool_args, dict): + raise InvalidActionError( + "TOOL_CALL requires tool_args dict (may be empty)" + ) + if action.message is not None or action.confidence is not None: + raise InvalidActionError( + "TOOL_CALL forbids message/confidence" + ) + if action.tool_name not in self._available_tools(): + raise UnknownToolError( + f"tool_name {action.tool_name!r} not in available_tools()" + ) + # JSON-serializability (shallow check: must be dict; values arbitrary). + return + + if atype == ActionType.SPEAK or atype == ActionType.CLARIFY: + if not isinstance(action.message, str): + raise InvalidActionError( + f"{atype.value} requires str message" + ) + if not (1 <= len(action.message) <= 2000): + raise InvalidActionError( + f"{atype.value} message length must be in [1, 2000], " + f"got {len(action.message)}" + ) + if "\x00" in action.message: + raise InvalidActionError( + f"{atype.value} message contains NUL byte" + ) + if ( + action.tool_name is not None + or action.tool_args is not None + or action.confidence is not None + ): + raise InvalidActionError( + f"{atype.value} forbids tool_name/tool_args/confidence" + ) + return + + if atype == ActionType.PROBE_SCHEMA: + if not action.tool_name or not isinstance(action.tool_name, str): + raise InvalidActionError( + "PROBE_SCHEMA requires tool_name (domain string)" + ) + if ( + action.tool_args is not None + or action.message is not None + or action.confidence is not None + ): + raise InvalidActionError( + "PROBE_SCHEMA forbids tool_args/message/confidence" + ) + assert self._state is not None + if action.tool_name not in self._state.vendor_states: + raise UnknownDomainError( + f"PROBE_SCHEMA: domain {action.tool_name!r} not registered" + ) + return + + if atype == ActionType.SUBMIT: + if action.confidence is None or not isinstance( + action.confidence, (int, float) + ) or isinstance(action.confidence, bool): + raise InvalidActionError("SUBMIT requires float confidence") + conf = float(action.confidence) + if not (0.0 <= conf <= 1.0): + raise InvalidActionError( + f"SUBMIT confidence {conf!r} outside [0.0, 1.0]" + ) + if action.tool_name is not None or action.tool_args is not None: + raise InvalidActionError( + "SUBMIT forbids tool_name/tool_args" + ) + if action.message is not None and not isinstance(action.message, str): + raise InvalidActionError("SUBMIT message must be str if present") + return + + if atype == ActionType.ABORT: + if ( + action.tool_name is not None + or action.tool_args is not None + or action.confidence is not None + ): + raise InvalidActionError( + "ABORT forbids tool_name/tool_args/confidence" + ) + return + + # Unreachable — all six ActionType members handled above. + raise InvalidActionError(f"unhandled action_type {atype!r}") + + # -- drift firing -------------------------------------------------------- + + def _fire_drifts(self, turn_current: int, force_pattern: str | None) -> None: + assert self._state is not None + if force_pattern is not None: + patterns_by_id = {p.id: p for p in list_patterns()} + pattern = patterns_by_id[force_pattern] + if pattern.domain not in self._state.vendor_states: + raise DriftInjectionError( + f"force_drift_pattern {force_pattern!r}: domain " + f"{pattern.domain!r} not registered" + ) + event = DriftEvent( + turn=turn_current, + drift_type=pattern.drift_type, + domain=pattern.domain, + description=pattern.description, + from_version=pattern.from_version, + to_version=pattern.to_version, + pattern_id=pattern.id, + ) + try: + self._state = apply_drift(self._state, event) + except ( + UnknownDriftPatternError, + DriftDomainMismatchError, + DriftReapplicationError, + ) as exc: + raise DriftInjectionError(str(exc)) from exc + return + + # Schedule-driven fold. + pending = tuple( + e for e in self._state.drift_schedule + if e.turn == turn_current and e not in self._state.drift_fired + ) + if not pending: + return + ordered = tuple(sorted(pending, key=lambda e: (e.turn, e.pattern_id))) + for event in ordered: + try: + self._state = apply_drift(self._state, event) + except ( + UnknownDriftPatternError, + DriftDomainMismatchError, + DriftReapplicationError, + ) as exc: + raise DriftInjectionError(str(exc)) from exc + + def _emit_side_channel(self) -> None: + """Refresh pending side-channel notices per env.md §3.3 clause 3.""" + assert self._state is not None + new_pending = dict(self._side_channel_pending) + for domain in _VENDOR_DOMAINS: + ns = VENDOR_REGISTRY[domain] + vs_obj = self._vendor_state_objects.get(domain) + if vs_obj is None: + continue + try: + notice, new_state = ns.emit_side_channel_if_pending(vs_obj) + except Exception as exc: # noqa: BLE001 — defensive + raise DriftInjectionError( + f"side-channel emit failed for {domain}: {exc}" + ) from exc + if notice is not None: + existing = new_pending.get(domain) + merged = ( + f"{existing}\n---\n{notice}" if existing else notice + ) + new_pending[domain] = merged + self._vendor_state_objects[domain] = new_state + self._side_channel_pending = new_pending + + # -- dispatch ------------------------------------------------------------ + + @property + def _tool_results(self) -> tuple[ToolResult, ...]: + return getattr(self, "_tool_results_internal", ()) + + @_tool_results.setter + def _tool_results(self, value: tuple[ToolResult, ...]) -> None: + self._tool_results_internal = value + + @property + def _tool_result_turns(self) -> tuple[int, ...]: + return getattr(self, "_tool_result_turns_internal", ()) + + @_tool_result_turns.setter + def _tool_result_turns(self, value: tuple[int, ...]) -> None: + self._tool_result_turns_internal = value + + @property + def _action_turns(self) -> tuple[int, ...]: + return getattr(self, "_action_turns_internal", ()) + + @_action_turns.setter + def _action_turns(self, value: tuple[int, ...]) -> None: + self._action_turns_internal = value + + def _dispatch( + self, action: DriftCallAction + ) -> tuple[ToolResult | None, bool, str | None]: + """Return (tool_result, terminate?, terminated_by?).""" + assert self._state is not None + atype = action.action_type + + if atype == ActionType.SUBMIT: + return None, True, "SUBMIT" + if atype == ActionType.ABORT: + return None, True, "ABORT" + if atype == ActionType.SPEAK or atype == ActionType.CLARIFY: + return None, False, None + + if atype == ActionType.PROBE_SCHEMA: + assert action.tool_name is not None + domain = action.tool_name + ns = VENDOR_REGISTRY[domain] + vs_obj = self._vendor_state_objects[domain] + schema_version = self._state.schema_versions[domain] + schema = ns.describe_schema(vs_obj, schema_version) + tr = ToolResult( + tool_name=f"probe:{domain}", + status="ok", + response=dict(schema), + schema_version=schema_version, + latency_ms=0, + ) + return tr, False, None + + if atype == ActionType.TOOL_CALL: + assert action.tool_name is not None and action.tool_args is not None + tool_name = action.tool_name + domain = tool_name.split(".", 1)[0] + if domain not in self._state.vendor_states: + raise UnknownDomainError( + f"tool {tool_name!r} targets unknown domain {domain!r}" + ) + ns = VENDOR_REGISTRY[domain] + vs_obj = self._vendor_state_objects[domain] + schema_version = self._state.schema_versions[domain] + try: + if domain == "payment": + tr, new_vs = ns.dispatch( + tool_name, + action.tool_args, + vs_obj, + schema_version, + self._seed, + _NOW_IST, + ) + payment_state = new_vs + else: + payment_state = self._vendor_state_objects.get("payment") + tr, new_vs, payment_state = ns.dispatch( + tool_name, + action.tool_args, + vs_obj, + schema_version, + self._seed, + _NOW_IST, + payment_state, + ) + except ValueError as exc: + # Unknown tool inside a known domain → treat as anti-hack. + raise UnknownToolError(str(exc)) from exc + + self._vendor_state_objects[domain] = new_vs + if payment_state is not None: + self._vendor_state_objects["payment"] = payment_state + + # Refresh state.vendor_states snapshot. + new_vendor_states = dict(self._state.vendor_states) + new_vendor_states[domain] = _vendor_state_to_dict(new_vs) + if domain != "payment" and payment_state is not None: + new_vendor_states["payment"] = _vendor_state_to_dict(payment_state) + self._state = replace(self._state, vendor_states=new_vendor_states) + + # Attach pending side-channel notice (one-shot per domain). + notice = self._side_channel_pending.pop(domain, None) + if notice is not None: + merged_response = dict(tr.response) + merged_response["_notice"] = notice + tr = ToolResult( + tool_name=tr.tool_name, + status=tr.status, + response=merged_response, + schema_version=tr.schema_version, + latency_ms=tr.latency_ms, + ) + return tr, False, None + + # Unreachable. + raise InvalidActionError(f"unhandled action_type {atype!r}") + + # -- termination --------------------------------------------------------- + + def _terminate(self, terminated_by: str) -> None: + assert self._state is not None + if terminated_by not in _TERMINATED_VALUES: + raise RewardComputationError( + f"unknown terminated_by sentinel {terminated_by!r}" + ) + self._state = replace(self._state, done=True) + episode = Episode( + episode_id=self._state.episode_id, + goal=self._state.goal, + actions=self._state.actions, + action_turns=self._action_turns, + tool_results=self._tool_results, + tool_result_turns=self._tool_result_turns, + drift_log=self._state.drift_fired, + vendor_states_final={ + d: _vendor_state_to_dict(self._vendor_state_objects[d]) + for d in _VENDOR_DOMAINS + }, + schema_versions_final=dict(self._state.schema_versions), + max_turns=self._state.max_turns, + turns_used=len(self._state.actions), + terminated_by=cast( + "Literal['SUBMIT','ABORT','TIMEOUT','ANTI_HACK']", terminated_by + ), + stage=self._config.curriculum_stage, + ) + self._episode = episode + self._rewards = self._compute_rewards(episode) + + @staticmethod + def _compute_rewards(episode: Episode) -> Any: + import importlib + + try: + mod = importlib.import_module("cells.step_08_rewards") + except ImportError as exc: + raise RewardComputationError( + f"rewards module unavailable: {exc}" + ) from exc + compute = getattr(mod, "compute_rewards", None) + if compute is None: + raise RewardComputationError( + "cells.step_08_rewards has no compute_rewards" + ) + try: + return compute(episode) + except Exception as exc: + raise RewardComputationError(str(exc)) from exc + + # -- observation builder ------------------------------------------------- + + def _build_observation(self) -> DriftCallObservation: + assert self._state is not None + st = self._state + if st.turn == 0: + last_transcript = st.goal.seed_utterance + last_lang = st.goal.language + last_confidence = 1.0 + else: + last_transcript = st.goal.seed_utterance + last_lang = st.goal.language + last_confidence = 1.0 + + return DriftCallObservation( + turn=st.turn, + goal=st.goal, + last_transcript=last_transcript, + last_lang=last_lang, + last_confidence=last_confidence, + tool_results=self._tool_results, + drift_log=st.drift_fired, + budget_remaining=max(0, st.max_turns - st.turn), + available_tools=self._available_tools(), + ) + + +__all__ = [ + "ASREngine", + "AudioPipelineError", + "ConcurrentStepError", + "DriftCallEnv", + "DriftCallEnvError", + "DriftInjectionError", + "DriftScheduler", + "EnvClosedError", + "EnvConfig", + "EnvNotReadyError", + "Episode", + "EpisodeAlreadyTerminalError", + "EpisodeNotTerminalError", + "InvalidActionError", + "InvalidConfigError", + "RewardComputationError", + "TTSEngine", + "UnknownDomainError", + "UnknownToolError", +] diff --git a/cells/step_11_smoke_env.md b/cells/step_11_smoke_env.md new file mode 100644 index 0000000000000000000000000000000000000000..033db3654cf9199e07c677ded2be4f38161c17b1 --- /dev/null +++ b/cells/step_11_smoke_env.md @@ -0,0 +1,8 @@ +# Cell 11 — DriftCallEnv smoke test + +Boots `DriftCallEnv` with a Stage-1 English airline configuration, runs one +episode (search → book → submit, confidence=0.8), computes rewards via +`compute_rewards`, and prints a compact summary table to stdout. Per +`docs/modules/env.md` §8.1 (happy-path trace) and `DESIGN.md` §16.A.2 — this +is the first end-to-end sanity check that every cell from 04 → 10 composes +into a working episode. diff --git a/cells/step_11_smoke_env.py b/cells/step_11_smoke_env.py new file mode 100644 index 0000000000000000000000000000000000000000..4481f9d18a032c3e0b57db8edbbb2c7f7ff27655 --- /dev/null +++ b/cells/step_11_smoke_env.py @@ -0,0 +1,164 @@ +"""Cell 11 — DriftCallEnv smoke episode. + +End-to-end smoke test that boots ``DriftCallEnv`` (cell 10) with a Stage-1 +English airline configuration, runs one short episode, and prints the +resulting reward breakdown. Mirrors ``DESIGN.md`` §16.A.2 and +``docs/modules/env.md`` §8.1. + +The cell exposes two public callables: + +* :func:`run_smoke_episode` — pure helper that returns a :class:`SmokeResult` + containing the (terminated) env, observation, and rewards. Useful from + tests. +* :func:`main` — notebook-cell entry point; prints a small summary table to + stdout and returns the same :class:`SmokeResult`. + +The cell never imports ``torch``, audio engines, or any LLM stack — it is +text-only and deterministic. +""" + +from __future__ import annotations + +from dataclasses import dataclass +from typing import TYPE_CHECKING + +from cells.step_04_models import ( + ActionType, + DriftCallAction, + DriftCallObservation, +) +from cells.step_10_env import DriftCallEnv + +if TYPE_CHECKING: # pragma: no cover — typing only + from cells.step_08_rewards import Rewards + + +SMOKE_SEED: int = 42 +SMOKE_CONFIDENCE: float = 0.8 + + +@dataclass(frozen=True) +class SmokeResult: + """Container returned by :func:`run_smoke_episode`.""" + + env: DriftCallEnv + final_observation: DriftCallObservation + rewards: Rewards + + +def _build_env() -> DriftCallEnv: + """Construct the canonical Stage-1, English-only, no-audio env.""" + return DriftCallEnv( + config={ + "curriculum_stage": 1, + "language_weights": {"en": 1.0}, + "audio_boundary_enabled": False, + }, + ) + + +def _pick_search_tool(obs: DriftCallObservation) -> str: + """Return the first ``.search``-style tool exposed for the goal.""" + domain = obs.goal.domain + for tool in obs.available_tools: + if tool == f"{domain}.search": + return tool + # Fall back to any tool in the domain if no explicit search action exists. + for tool in obs.available_tools: + if tool.startswith(f"{domain}."): + return tool + raise RuntimeError(f"no tools available for domain {domain!r}") + + +def _pick_book_tool(obs: DriftCallObservation) -> str | None: + """Return the first ``.book``/``.order``/etc. tool, if any.""" + domain = obs.goal.domain + for verb in ("book", "order", "reserve", "create"): + candidate = f"{domain}.{verb}" + if candidate in obs.available_tools: + return candidate + return None + + +def run_smoke_episode(seed: int = SMOKE_SEED) -> SmokeResult: + """Run a single Stage-1 airline-style episode and return the rewards. + + Action sequence: + + 1. ``TOOL_CALL`` to the domain's ``search`` endpoint (no args — vendors + are tolerant of empty args at v1). + 2. ``TOOL_CALL`` to the domain's ``book``/``order`` endpoint, if exposed. + 3. ``SUBMIT`` with ``confidence=0.8``. + """ + env = _build_env() + obs = env.reset(seed=seed) + + obs = env.step( + DriftCallAction( + action_type=ActionType.TOOL_CALL, + tool_name=_pick_search_tool(obs), + tool_args={}, + rationale="smoke: discover candidates", + ), + ) + + book_tool = _pick_book_tool(obs) + if book_tool is not None and not env.done(): + obs = env.step( + DriftCallAction( + action_type=ActionType.TOOL_CALL, + tool_name=book_tool, + tool_args={}, + rationale="smoke: commit booking", + ), + ) + + if not env.done(): + obs = env.step( + DriftCallAction( + action_type=ActionType.SUBMIT, + confidence=SMOKE_CONFIDENCE, + message="smoke episode complete", + rationale="smoke: terminate", + ), + ) + + rewards = env.rewards() + return SmokeResult(env=env, final_observation=obs, rewards=rewards) + + +def _format_summary(result: SmokeResult) -> str: + r = result.rewards + ep = result.env.episode() + lines = [ + "=== DriftCall smoke episode ===", + f" episode_id : {ep.episode_id}", + f" domain : {ep.goal.domain}", + f" language : {ep.goal.language}", + f" terminated_by : {ep.terminated_by}", + f" turns_used : {ep.turns_used} / {ep.max_turns}", + " --- rewards ---", + f" r1 (task) : {r.r1:.3f}", + f" r2 (drift) : {r.r2:.3f}", + f" r3 (constraints) : {r.r3:.3f}", + f" r4 (format) : {r.r4:.3f}", + f" r5 (anti-hack) : {r.r5:.3f}", + f" reward (final) : {r.reward:.3f}", + ] + return "\n".join(lines) + + +def main() -> SmokeResult: + """Run the smoke episode and print a summary table to stdout.""" + result = run_smoke_episode() + print(_format_summary(result)) + return result + + +__all__ = [ + "SMOKE_CONFIDENCE", + "SMOKE_SEED", + "SmokeResult", + "main", + "run_smoke_episode", +] diff --git a/cells/step_12_gemma_boot.md b/cells/step_12_gemma_boot.md new file mode 100644 index 0000000000000000000000000000000000000000..25e59f78b7f406102dc526a3ed56007390d18a44 --- /dev/null +++ b/cells/step_12_gemma_boot.md @@ -0,0 +1,3 @@ +# Step 12 — Gemma 3n E2B Boot + +Loads `unsloth/gemma-3n-E2B-it` via `unsloth.FastModel` in 4-bit Dynamic NF4 with hardware-aware precision (FP16 on V100, BF16 on H100), attaches LoRA adapters (r=16, α=32, vision towers frozen, language + attention + MLP trainable), and asserts the first parameter's dtype matches the target hardware — the mandatory dtype-slippage halt from `docs/modules/training.md §3.1`. Unsloth/torch imports are lazy so this cell loads on CPU-only machines; heavy work happens only when `boot_gemma()` is called with a real GPU. diff --git a/cells/step_12_gemma_boot.py b/cells/step_12_gemma_boot.py new file mode 100644 index 0000000000000000000000000000000000000000..e4687021cab9e48c44248dd9a7d90be38b3cc082 --- /dev/null +++ b/cells/step_12_gemma_boot.py @@ -0,0 +1,204 @@ +"""Gemma 3n E2B boot via Unsloth FastModel (docs/modules/training.md §3.1). + +Contract: + - Base model: ``unsloth/gemma-3n-E2B-it`` (4-bit Dynamic + NF4 quantization). + - Precision: hardware-aware. + V100 (sm_70) — explicit FP16 (``dtype=torch.float16``); Gemma 3n is + BF16-native, so we force FP16 on V100 to avoid BF16 software-emulation + slowdown / numerical instability. + H100 (sm_90) — BF16 (``dtype=torch.bfloat16``); uses native tensor cores. + - LoRA: r=16, α=32, dropout=0.05, vision towers frozen, language + attention + + MLP trainable via Unsloth's multimodal API (``finetune_vision_layers=False, + finetune_language_layers=True, finetune_attention_modules=True, + finetune_mlp_modules=True``), Unsloth gradient checkpointing, + ``random_state=3407``. + - V100 halt: ``next(model.parameters()).dtype`` MUST be ``torch.float16`` + after FP16 load; any BF16 parameter triggers :class:`BF16SlippageError` + before optimizer build. + - H100 halt: ``next(model.parameters()).dtype`` MUST be ``torch.bfloat16`` + after BF16 load; any FP16 parameter triggers :class:`FP16SlippageError` + before optimizer build. + +Heavy imports (``unsloth``, ``torch``) are deferred inside functions so this +cell loads on CPU-only CI runners where Unsloth is not installed. Tests mock +``FastModel.from_pretrained`` and ``FastModel.get_peft_model``. +""" + +from __future__ import annotations + +from dataclasses import dataclass +from typing import Any, Literal + +BASE_MODEL_ID: str = "unsloth/gemma-3n-E2B-it" +MAX_SEQ_LENGTH: int = 4096 +LORA_R: int = 16 +LORA_ALPHA: int = 32 +LORA_DROPOUT: float = 0.05 +LORA_RANDOM_STATE: int = 3407 + +# Gemma 3n multimodal LoRA flags — vision/audio towers stay frozen so GRPO +# trains only the language stack (Unsloth Gemma 3N notebook §fine-tune). +FINETUNE_VISION_LAYERS: bool = False +FINETUNE_LANGUAGE_LAYERS: bool = True +FINETUNE_ATTENTION_MODULES: bool = True +FINETUNE_MLP_MODULES: bool = True + +HardwareT = Literal["v100", "h100"] +ALLOWED_HARDWARE: tuple[HardwareT, ...] = ("v100", "h100") + + +class BF16SlippageError(AssertionError): + """Raised when the loaded model has any BF16 parameter on V100. + + V100 (sm_70) lacks BF16 tensor cores. Silent BF16 via software emulation + causes ~10x slowdown plus numerical-instability patterns in + ``docs/modules/training.md §7a``. Halt before the optimizer is built. + """ + + +class FP16SlippageError(AssertionError): + """Raised when the loaded model has any FP16 parameter on H100. + + H100 (sm_90) has native BF16 tensor cores. Running FP16 on H100 means + leaving native hardware capability unused and may cause gradient underflow + at large batch sizes. Halt before the optimizer is built. + """ + + +@dataclass(frozen=True) +class BootConfig: + """Arguments to :func:`boot_gemma`. Frozen per DriftCall immutability rule.""" + + base_model_id: str = BASE_MODEL_ID + max_seq_length: int = MAX_SEQ_LENGTH + load_in_4bit: bool = True + lora_r: int = LORA_R + lora_alpha: int = LORA_ALPHA + lora_dropout: float = LORA_DROPOUT + lora_random_state: int = LORA_RANDOM_STATE + finetune_vision_layers: bool = FINETUNE_VISION_LAYERS + finetune_language_layers: bool = FINETUNE_LANGUAGE_LAYERS + finetune_attention_modules: bool = FINETUNE_ATTENTION_MODULES + finetune_mlp_modules: bool = FINETUNE_MLP_MODULES + use_gradient_checkpointing: str = "unsloth" + hardware: HardwareT = "v100" + + +def assert_dtype_for_hardware(model: Any, hardware: HardwareT) -> None: + """Assert the first parameter dtype matches the expected precision for hardware. + + V100 must be ``torch.float16``; raises :class:`BF16SlippageError` otherwise. + H100 must be ``torch.bfloat16``; raises :class:`FP16SlippageError` otherwise. + Called once at ``boot_gemma`` entry, before any LoRA attach or optimizer build. + """ + import torch + + params_iter = model.parameters() + try: + first_param = next(params_iter) + except StopIteration as exc: # pragma: no cover - defensive + raise BF16SlippageError( + "Model has no parameters; cannot verify dtype." + ) from exc + + dtype = first_param.dtype + if hardware == "v100": + if dtype != torch.float16: + raise BF16SlippageError( + f"BF16 slipped through: V100 unsafe. " + f"next(model.parameters()).dtype == {dtype}, expected torch.float16. " + f"Root cause: Unsloth auto-picked BF16 despite dtype=torch.float16 kwarg. " + f"Halt training; do NOT proceed on V100." + ) + else: # h100 + if dtype != torch.bfloat16: + raise FP16SlippageError( + f"FP16 slipped through: H100 should use BF16. " + f"next(model.parameters()).dtype == {dtype}, expected torch.bfloat16. " + f"Root cause: dtype kwarg may have forced FP16 on H100. " + f"Halt training; do NOT proceed on H100 with FP16." + ) + + +def assert_fp16_dtype(model: Any) -> None: + """Assert the first trainable parameter is torch.float16 (V100 safety). + + Thin wrapper around :func:`assert_dtype_for_hardware` for backwards + compatibility with call sites that predate the hardware-aware API. + Raises :class:`BF16SlippageError` with the halt message from + ``docs/modules/training.md §3.1``. + """ + assert_dtype_for_hardware(model, "v100") + + +def boot_gemma(config: BootConfig | None = None) -> tuple[Any, Any]: + """Load Gemma 3n E2B in 4-bit + attach LoRA; return (model, tokenizer). + + Steps (training.md §3.1): + 1. ``FastModel.from_pretrained(base_model_id, max_seq_length=..., + load_in_4bit=True, dtype=torch.float16)`` on V100 + or ``dtype=torch.bfloat16`` on H100. + 2. ``assert_dtype_for_hardware(model, hardware)`` — raises + :class:`BF16SlippageError` or :class:`FP16SlippageError` if the dtype + does not match the hardware. + 3. ``FastModel.get_peft_model(model, r=16, lora_alpha=32, + finetune_vision_layers=False, finetune_language_layers=True, + finetune_attention_modules=True, finetune_mlp_modules=True, + use_gradient_checkpointing="unsloth", random_state=3407)``. + 4. Return ``(peft_model, tokenizer)``. + + All heavy imports are lazy so the module is importable on CPU-only CI. + """ + cfg = config if config is not None else BootConfig() + + import torch + from unsloth import FastModel + + dtype = torch.float16 if cfg.hardware == "v100" else torch.bfloat16 + + model, tokenizer = FastModel.from_pretrained( + cfg.base_model_id, + max_seq_length=cfg.max_seq_length, + load_in_4bit=cfg.load_in_4bit, + dtype=dtype, + ) + + assert_dtype_for_hardware(model, cfg.hardware) + + peft_model = FastModel.get_peft_model( + model, + r=cfg.lora_r, + lora_alpha=cfg.lora_alpha, + lora_dropout=cfg.lora_dropout, + finetune_vision_layers=cfg.finetune_vision_layers, + finetune_language_layers=cfg.finetune_language_layers, + finetune_attention_modules=cfg.finetune_attention_modules, + finetune_mlp_modules=cfg.finetune_mlp_modules, + use_gradient_checkpointing=cfg.use_gradient_checkpointing, + random_state=cfg.lora_random_state, + ) + + return peft_model, tokenizer + + +__all__ = [ + "ALLOWED_HARDWARE", + "BASE_MODEL_ID", + "BF16SlippageError", + "BootConfig", + "FINETUNE_ATTENTION_MODULES", + "FINETUNE_LANGUAGE_LAYERS", + "FINETUNE_MLP_MODULES", + "FINETUNE_VISION_LAYERS", + "FP16SlippageError", + "HardwareT", + "LORA_ALPHA", + "LORA_DROPOUT", + "LORA_R", + "LORA_RANDOM_STATE", + "MAX_SEQ_LENGTH", + "assert_dtype_for_hardware", + "assert_fp16_dtype", + "boot_gemma", +] diff --git a/cells/step_13_grpo_config.md b/cells/step_13_grpo_config.md new file mode 100644 index 0000000000000000000000000000000000000000..6ababa60e715b4620b978eddee87d542b2ff525d --- /dev/null +++ b/cells/step_13_grpo_config.md @@ -0,0 +1,3 @@ +# Step 13 — GRPO Config + Reward Wiring + +Builds a TRL `GRPOConfig` matching `docs/modules/training.md §2.4` exactly — `use_bias_correction_kl=True`, FP16, gradient-checkpointing, `beta=0.04`, `per_device_train_batch_size=1`, `num_generations ∈ {4, 8}` with `grad_accum` flipped so effective rollouts/update stays at 32. Also provides the TRL-0.23-compatible `reward_fn(prompts, completions, *, _meta, episodes, **kwargs)` that delegates to `compute_rewards` pure function and returns list-of-floats in `[0, 1]` rounded to 3dp. No reward normalization pre-GRPO (training.md §3.2). diff --git a/cells/step_13_grpo_config.py b/cells/step_13_grpo_config.py new file mode 100644 index 0000000000000000000000000000000000000000..1e599cdd86d1f5c1807d15470df031a1b857b88c --- /dev/null +++ b/cells/step_13_grpo_config.py @@ -0,0 +1,508 @@ +"""GRPOConfig builder + reward_fn wiring (docs/modules/training.md §2.4, §2.3). + +Two public entry points: + +- :func:`build_grpo_config(stage, *, num_generations=8, resume_output_dir=None)` + returns a TRL ``GRPOConfig`` whose fields match training.md §2.4 verbatim. + Invariants (asserted post-construction): ``use_bias_correction_kl is True``, + ``fp16 is True``, ``gradient_checkpointing is True``, + ``per_device_train_batch_size == 1``, ``num_generations in {4, 8}``, + ``num_generations * gradient_accumulation_steps == 32``, ``beta == 0.04``, + ``max_prompt_length == 1024``, ``max_completion_length == 2048``, + ``warmup_ratio == (0.1 if stage == 1 else 0.0)``. + +- :func:`reward_fn(prompts, completions, *, _meta, episodes, **kwargs)` is the + TRL-0.23 reward contract used by ``DriftCallGRPOTrainer``. It is a pure + delegating wrapper over ``cells.step_08_rewards.compute_rewards`` (see + docs/modules/rewards.md §3.1 purity contract). No pre-normalization, + no RNG, no I/O. + +TRL is imported lazily inside ``build_grpo_config`` so this cell loads on +CPU-only CI. ``compute_rewards`` is imported lazily so step_08 landing after +step_13 does not cascade-break the import graph. +""" + +from __future__ import annotations + +from dataclasses import dataclass +from typing import TYPE_CHECKING, Any, Literal + +if TYPE_CHECKING: + from pathlib import Path + +StageT = Literal[1, 2, 3] +HardwareT = Literal["v100", "h100"] + + +LEARNING_RATE: float = 5e-6 +ADAM_BETA1: float = 0.9 +ADAM_BETA2: float = 0.99 +WEIGHT_DECAY: float = 0.01 +LR_SCHEDULER_TYPE: str = "cosine" + +# V100 path (default) — fp16 + 8-bit paged AdamW (sm_70 safe). +OPTIM_V100: str = "paged_adamw_8bit" +# H100 path — bf16 + fused torch AdamW (sm_90 tensor cores). +OPTIM_H100: str = "adamw_torch_fused" +# For backwards compatibility with callers that read ``OPTIM`` directly. +OPTIM: str = OPTIM_V100 +# Kernel request passed to the model at load time on H100. +H100_ATTN_IMPLEMENTATION: str = "flash_attention_3" +ALLOWED_HARDWARE: tuple[HardwareT, ...] = ("v100", "h100") + +PER_DEVICE_TRAIN_BATCH_SIZE: int = 1 +EFFECTIVE_ROLLOUTS_PER_UPDATE: int = 32 + +DEFAULT_NUM_GENERATIONS: int = 8 +ALLOWED_NUM_GENERATIONS: tuple[int, ...] = (4, 8) + +MAX_PROMPT_LENGTH: int = 1024 +MAX_COMPLETION_LENGTH: int = 2048 + +BETA_KL: float = 0.04 + +SAMPLING_TEMPERATURE: float = 0.9 +SAMPLING_TOP_P: float = 0.95 + +LOGGING_STEPS: int = 5 +SAVE_STEPS: int = 50 +SAVE_TOTAL_LIMIT: int = 10 + +REPORT_TO: str = "wandb" + +WARMUP_RATIO_STAGE1: float = 0.1 +WARMUP_RATIO_STAGE2_3: float = 0.0 + +# WandB integration (training.md §3.3.3 — env-var contract). +WANDB_PROJECT_DEFAULT: str = "driftcall" +WANDB_ENTITY_DEFAULT: str | None = None +WANDB_RUN_NAME_TEMPLATE: str = "driftcall-stage{stage}-seed{seed}-{timestamp}" +WANDB_MODE_DEFAULT: str = "online" + + +@dataclass(frozen=True) +class _ConfigInvariants: + """Invariant bundle returned by :func:`assert_config_invariants`. + + Used by tests to verify exact field values without re-parsing the + ``GRPOConfig`` object. + """ + + stage: StageT + num_generations: int + gradient_accumulation_steps: int + warmup_ratio: float + beta: float + max_prompt_length: int + max_completion_length: int + per_device_train_batch_size: int + use_bias_correction_kl: bool + fp16: bool + gradient_checkpointing: bool + report_to: str + run_name: str + output_dir: str + + +def _derive_grad_accum(num_generations: int) -> int: + """Return grad_accum so that G*grad_accum == 32 (training.md §7b).""" + return 8 if num_generations == 4 else 4 + + +def _warmup_ratio_for_stage(stage: StageT) -> float: + """One continuous cosine schedule across 500 steps — only stage-1 warms.""" + return WARMUP_RATIO_STAGE1 if stage == 1 else WARMUP_RATIO_STAGE2_3 + + +def _validate_num_generations(num_generations: int) -> None: + if num_generations not in ALLOWED_NUM_GENERATIONS: + raise AssertionError( + f"num_generations in {{4, 8}} required; got {num_generations}" + ) + + +def _validate_stage(stage: int) -> None: + if stage not in (1, 2, 3): + raise AssertionError(f"stage in {{1, 2, 3}} required; got {stage}") + + +def _validate_hardware(hardware: str) -> None: + if hardware not in ALLOWED_HARDWARE: + raise AssertionError( + f"hardware in {ALLOWED_HARDWARE} required; got {hardware!r}" + ) + + +def build_grpo_config( + stage: StageT, + *, + num_generations: int = DEFAULT_NUM_GENERATIONS, + resume_output_dir: Path | None = None, + hardware: HardwareT = "v100", + max_steps: int = -1, +) -> Any: + """Build a TRL ``GRPOConfig`` matching training.md §2.4 exactly. + + Validates ``num_generations in {4, 8}`` before import so CPU-only + tests can trigger the assertion without TRL installed. + + ``max_steps`` maps to TRL's ``max_steps`` (default -1 = run until dataset + exhausted; pass the stage step count for a fixed-step curriculum). + """ + _validate_stage(stage) + _validate_num_generations(num_generations) + _validate_hardware(hardware) + + warmup_ratio = _warmup_ratio_for_stage(stage) + grad_accum = _derive_grad_accum(num_generations) + output_dir = str(resume_output_dir) if resume_output_dir is not None else f"checkpoints/stage{stage}" + run_name = f"driftcall-stage{stage}" + + # Hardware-specific knobs — V100 stays fp16 + 8-bit paged AdamW, H100 + # switches to bf16 + fused torch AdamW + flash_attention_3 (training.md §3.1). + if hardware == "h100": + fp16_flag = False + bf16_flag = True + optim_choice = OPTIM_H100 + attn_implementation: str | None = H100_ATTN_IMPLEMENTATION + else: + fp16_flag = True + bf16_flag = False + optim_choice = OPTIM_V100 + attn_implementation = None + + import inspect + + from trl import GRPOConfig + + _grpo_params = set(inspect.signature(GRPOConfig.__init__).parameters) + + extra_kwargs: dict[str, Any] = {} + # attn_implementation was a GRPOConfig param in TRL ≤0.23; removed in 0.24. + if attn_implementation is not None and "attn_implementation" in _grpo_params: + extra_kwargs["attn_implementation"] = attn_implementation + # use_bias_correction_kl was introduced in TRL 0.23 and removed in TRL 0.24. + if "use_bias_correction_kl" in _grpo_params: + extra_kwargs["use_bias_correction_kl"] = True + + # TRL 0.24+ requires generation_batch_size to be divisible by + # num_generations. Default (per_device * grad_accum) may be smaller. + # Pin it to num_generations so exactly one group is generated per step. + if "generation_batch_size" in _grpo_params: + extra_kwargs.setdefault("generation_batch_size", num_generations) + + config = GRPOConfig( + learning_rate=LEARNING_RATE, + adam_beta1=ADAM_BETA1, + adam_beta2=ADAM_BETA2, + weight_decay=WEIGHT_DECAY, + warmup_ratio=warmup_ratio, + lr_scheduler_type=LR_SCHEDULER_TYPE, + optim=optim_choice, + per_device_train_batch_size=PER_DEVICE_TRAIN_BATCH_SIZE, + gradient_accumulation_steps=grad_accum, + num_generations=num_generations, + max_prompt_length=MAX_PROMPT_LENGTH, + max_completion_length=MAX_COMPLETION_LENGTH, + max_steps=max_steps, + beta=BETA_KL, + temperature=SAMPLING_TEMPERATURE, + top_p=SAMPLING_TOP_P, + fp16=fp16_flag, + bf16=bf16_flag, + gradient_checkpointing=True, + logging_steps=LOGGING_STEPS, + save_steps=SAVE_STEPS, + save_total_limit=SAVE_TOTAL_LIMIT, + output_dir=output_dir, + report_to=REPORT_TO, + run_name=run_name, + **extra_kwargs, + ) + + assert_config_invariants( + config, stage=stage, num_generations=num_generations, hardware=hardware, + ) + return config + + +def assert_config_invariants( + config: Any, + *, + stage: StageT, + num_generations: int, + hardware: HardwareT | None = None, +) -> _ConfigInvariants: + """Post-construction field checks — training.md §2.4 invariants. + + Returns a frozen :class:`_ConfigInvariants` snapshot so callers (tests) + can introspect without re-reading the mutable TRL config object. + + When ``hardware`` is ``None`` it is auto-detected from the precision + flags on ``config`` (``bf16=True`` → ``"h100"``, else ``"v100"``). + """ + if hardware is None: + hardware = "h100" if getattr(config, "bf16", False) else "v100" + _validate_hardware(hardware) + # use_bias_correction_kl existed in TRL 0.23 only; TRL 0.24 removed it. + # Assert it only when the attr is present on the config object. + if hasattr(config, "use_bias_correction_kl"): + if getattr(config, "use_bias_correction_kl", None) is not True: + raise AssertionError( + "use_bias_correction_kl must be True (TRL issue #4637; training.md §3.3)" + ) + if hardware == "v100": + if getattr(config, "fp16", None) is not True: + raise AssertionError("fp16 must be True on V100 (training.md §3.1)") + if getattr(config, "bf16", False) is True: + raise AssertionError("bf16 must be False on V100 (training.md §3.1)") + else: # hardware == "h100" + if getattr(config, "bf16", None) is not True: + raise AssertionError("bf16 must be True on H100 (training.md §3.1)") + if getattr(config, "fp16", False) is True: + raise AssertionError("fp16 must be False on H100 (training.md §3.1)") + # attn_implementation was a GRPOConfig field in TRL ≤0.23; removed in 0.24. + if hasattr(config, "attn_implementation"): + if getattr(config, "attn_implementation", None) != H100_ATTN_IMPLEMENTATION: + raise AssertionError( + f"attn_implementation must be {H100_ATTN_IMPLEMENTATION!r} on H100" + ) + if getattr(config, "gradient_checkpointing", None) is not True: + raise AssertionError("gradient_checkpointing must be True") + if config.per_device_train_batch_size != PER_DEVICE_TRAIN_BATCH_SIZE: + raise AssertionError( + f"per_device_train_batch_size must be {PER_DEVICE_TRAIN_BATCH_SIZE}" + ) + if config.num_generations != num_generations: + raise AssertionError( + f"num_generations mismatch: config has {config.num_generations}, expected {num_generations}" + ) + expected_grad_accum = _derive_grad_accum(num_generations) + if config.gradient_accumulation_steps != expected_grad_accum: + raise AssertionError( + f"gradient_accumulation_steps must be {expected_grad_accum} when " + f"num_generations == {num_generations}" + ) + product = config.num_generations * config.gradient_accumulation_steps + if product != EFFECTIVE_ROLLOUTS_PER_UPDATE: + raise AssertionError( + f"num_generations * gradient_accumulation_steps must be " + f"{EFFECTIVE_ROLLOUTS_PER_UPDATE}; got {product}" + ) + expected_warmup = _warmup_ratio_for_stage(stage) + if config.warmup_ratio != expected_warmup: + raise AssertionError( + f"warmup_ratio must be {expected_warmup} for stage {stage}; " + f"got {config.warmup_ratio}" + ) + if config.beta != BETA_KL: + raise AssertionError(f"beta must be {BETA_KL}; got {config.beta}") + if config.max_prompt_length != MAX_PROMPT_LENGTH: + raise AssertionError(f"max_prompt_length must be {MAX_PROMPT_LENGTH}") + if config.max_completion_length != MAX_COMPLETION_LENGTH: + raise AssertionError( + f"max_completion_length must be {MAX_COMPLETION_LENGTH}" + ) + # TRL 0.24 normalises report_to to a list; earlier versions kept it a string. + _report_to = config.report_to + if isinstance(_report_to, list): + _report_to_check = _report_to == [REPORT_TO] + else: + _report_to_check = _report_to == REPORT_TO + if not _report_to_check: + raise AssertionError(f"report_to must be {REPORT_TO!r} (or [{REPORT_TO!r}]); got {config.report_to!r}") + expected_run_name = f"driftcall-stage{stage}" + if config.run_name != expected_run_name: + raise AssertionError( + f"run_name must be {expected_run_name!r}; got {config.run_name!r}" + ) + + return _ConfigInvariants( + stage=stage, + num_generations=config.num_generations, + gradient_accumulation_steps=config.gradient_accumulation_steps, + warmup_ratio=config.warmup_ratio, + beta=config.beta, + max_prompt_length=config.max_prompt_length, + max_completion_length=config.max_completion_length, + per_device_train_batch_size=config.per_device_train_batch_size, + # use_bias_correction_kl was removed in TRL 0.24; default True for + # backwards compatibility with tests that read this field. + use_bias_correction_kl=getattr(config, "use_bias_correction_kl", True), + fp16=config.fp16, + gradient_checkpointing=config.gradient_checkpointing, + report_to=config.report_to[0] if isinstance(config.report_to, list) else config.report_to, + run_name=config.run_name, + output_dir=config.output_dir, + ) + + +def _clamp_unit(x: float) -> float: + if x < 0.0: + return 0.0 + if x > 1.0: + return 1.0 + return x + + +def reward_fn( + prompts: list[str], + completions: list[str], + *, + _meta: list[dict[str, Any]], + episodes: list[Any], + **kwargs: Any, +) -> list[float]: + """TRL-0.23-compatible reward function (training.md §2.3). + + Contract: + - ``prompts``, ``completions``, ``_meta``, ``episodes`` all have the + same length G (num_generations). + - Delegates to ``compute_rewards`` per-episode; returns + ``[r.reward for r in rewards_list]`` with each value clamped to + ``[0, 1]`` and rounded to 3 decimals. + - No reward normalization pre-GRPO — group-relative advantage is + applied inside TRL (training.md §3.2, DESIGN.md §7.4). + - No RNG, no clock, no I/O (rewards.md §3.1). + """ + if len(episodes) != len(prompts) or len(episodes) != len(completions): + raise ValueError( + f"prompts/completions/episodes length mismatch: " + f"{len(prompts)}, {len(completions)}, {len(episodes)}" + ) + if len(_meta) != len(episodes): + raise ValueError( + f"_meta length {len(_meta)} != episodes length {len(episodes)}" + ) + + from cells.step_08_rewards import compute_rewards + + out: list[float] = [] + for ep in episodes: + rewards = compute_rewards(ep) + out.append(round(_clamp_unit(float(rewards.reward)), 3)) + return out + + +def init_wandb( + *, + stage: StageT, + seed: int, + h100_mode: bool = False, + enable_adaptive_kl: bool = True, + extra_config: dict[str, Any] | None = None, +) -> Any: + """Initialize a WandB run for a training stage (training.md §3.3.3). + + Override priority for credentials: + 1. ``os.environ`` values set by the caller (highest) + 2. ``cells._secrets.export_to_env()`` hardcoded fallback + 3. None — caller must set ``WANDB_MODE=disabled`` or run will fail + + Returns the active ``wandb.run`` object, or ``None`` when + ``WANDB_MODE`` resolves to ``"disabled"``. Idempotent — if a run is + already active for this process, returns it unchanged. + """ + import os + import time + + # Step 1: populate env from cells/_secrets.py if a key is missing. + try: + from cells._secrets import export_to_env + + export_to_env() + except ImportError: + pass + + mode = os.environ.get("WANDB_MODE", WANDB_MODE_DEFAULT).strip().lower() + if mode == "disabled": + return None + + import wandb + + if getattr(wandb, "run", None) is not None: + return wandb.run + + project = os.environ.get("WANDB_PROJECT", WANDB_PROJECT_DEFAULT) + entity = os.environ.get("WANDB_ENTITY", WANDB_ENTITY_DEFAULT) + timestamp = time.strftime("%Y%m%d-%H%M%S") + run_name = WANDB_RUN_NAME_TEMPLATE.format( + stage=stage, seed=seed, timestamp=timestamp + ) + + tags = [ + f"stage{stage}", + "gemma-3n-e2b", + "bf16" if h100_mode else "fp16", + "adaptive-kl" if enable_adaptive_kl else "static-kl", + f"seed{seed}", + ] + + # Lazy LoRA constants — step_12 imports unsloth at module top, so guard + # against CPU-only CI environments where unsloth is unavailable. + try: + from cells.step_12_gemma_boot import LORA_ALPHA, LORA_DROPOUT, LORA_R + except ImportError: + LORA_R = 16 + LORA_ALPHA = 32 + LORA_DROPOUT = 0.05 + + # target_kl default matches AdaptiveKLCallback(target_kl=BETA_KL) in step_14. + config: dict[str, Any] = { + "stage": stage, + "seed": seed, + "h100_mode": h100_mode, + "adaptive_kl": enable_adaptive_kl, + "beta_initial": BETA_KL, + "target_kl": BETA_KL, + "learning_rate": LEARNING_RATE, + "num_generations": DEFAULT_NUM_GENERATIONS, + "max_prompt_length": MAX_PROMPT_LENGTH, + "max_completion_length": MAX_COMPLETION_LENGTH, + "lora_r": LORA_R, + "lora_alpha": LORA_ALPHA, + "lora_dropout": LORA_DROPOUT, + } + if extra_config: + config.update(extra_config) + + init_kwargs: dict[str, Any] = { + "project": project, + "name": run_name, + "tags": tags, + "config": config, + "mode": mode, + } + if entity is not None: + init_kwargs["entity"] = entity + + return wandb.init(**init_kwargs) + + +__all__ = [ + "ALLOWED_HARDWARE", + "ALLOWED_NUM_GENERATIONS", + "BETA_KL", + "DEFAULT_NUM_GENERATIONS", + "EFFECTIVE_ROLLOUTS_PER_UPDATE", + "H100_ATTN_IMPLEMENTATION", + "HardwareT", + "LEARNING_RATE", + "MAX_COMPLETION_LENGTH", + "MAX_PROMPT_LENGTH", + "OPTIM_H100", + "OPTIM_V100", + "PER_DEVICE_TRAIN_BATCH_SIZE", + "REPORT_TO", + "StageT", + "WANDB_ENTITY_DEFAULT", + "WANDB_MODE_DEFAULT", + "WANDB_PROJECT_DEFAULT", + "WANDB_RUN_NAME_TEMPLATE", + "WARMUP_RATIO_STAGE1", + "WARMUP_RATIO_STAGE2_3", + "assert_config_invariants", + "build_grpo_config", + "init_wandb", + "reward_fn", +] diff --git a/cells/step_14_custom_trainer.md b/cells/step_14_custom_trainer.md new file mode 100644 index 0000000000000000000000000000000000000000..91102fa972a834b42c77577aeea573ecb598ffe6 --- /dev/null +++ b/cells/step_14_custom_trainer.md @@ -0,0 +1,7 @@ +# Step 14 — DriftCallGRPOTrainer + EpisodeDatasetAdapter + +Custom TRL subclass `DriftCallGRPOTrainer` that replaces the single-prompt / single-completion rollout phase with the DriftCall multi-turn env loop (training.md §3.2.3). Its `_generate_and_score_completions` override runs G parallel multi-turn episodes via a caller-provided `RolloutGroupFn`, then hands terminal frozen `Episode` objects plus raw completion strings to `reward_fn` (step_13). Advantage + KL + optimizer steps are inherited unchanged from `GRPOTrainer`. + +`EpisodeDatasetAdapter` is the stateless streaming iterator wired into `GRPOTrainer.train_dataset`. Each `__iter__` yield packages `{prompt, _meta}` where `_meta` carries `(goal, episode_seed, stage, language_weights)` — every scalar required by the rollout controller. Per-step record: one `task_generator.generate` call, one `apply_chat_template` render, monotonically increasing `episode_seed == stage_base_seed + step`. + +Both types defer `trl` + `torch` imports until construction so the module loads on CPU-only CI. diff --git a/cells/step_14_custom_trainer.py b/cells/step_14_custom_trainer.py new file mode 100644 index 0000000000000000000000000000000000000000..8cf78833cedaf76055ed9505ab45ddf76b5d40c0 --- /dev/null +++ b/cells/step_14_custom_trainer.py @@ -0,0 +1,526 @@ +"""Custom trainer + dataset adapter (docs/modules/training.md §2.2, §3.2.3). + +Two public types: + +- :class:`EpisodeDatasetAdapter` — stateless iterable feeding + ``GRPOTrainer.train_dataset``. Each ``__iter__`` tick yields + ``{"prompt": str, "_meta": {...}}`` where ``_meta`` carries the + ``GoalSpec``, the monotonically-derived ``episode_seed``, the curriculum + ``stage``, and the ``language_weights``. One call to + ``task_generator.generate`` per step; one call to + ``tokenizer.apply_chat_template(messages, tokenize=False, + add_generation_prompt=True)`` to render the prompt. + +- :class:`DriftCallGRPOTrainer` — ``GRPOTrainer`` subclass whose + ``_generate_and_score_completions`` override runs G multi-turn episodes + via a caller-provided ``RolloutGroupFn`` and plumbs the resulting + frozen ``Episode`` tuple into ``reward_fn`` (step_13) before handing the + G reward scalars + padded completions back to the inherited GRPO + advantage / KL / optimizer step path. **The inherited code path is + untouched** (training.md §3.2.3). + +``trl`` and ``torch`` are imported lazily. Pure-Python fallbacks for +``_generate_and_score_completions`` are provided so the class shape +can be verified on CPU-only CI. +""" + +from __future__ import annotations + +import math +from dataclasses import dataclass +from typing import TYPE_CHECKING, Any, Literal, Protocol, cast + +if TYPE_CHECKING: # pragma: no cover - typing only + from collections.abc import Callable, Iterator + +from cells.step_13_grpo_config import BETA_KL + +PINNED_SYSTEM_PROMPT: str = ( + "You are a concierge assistant. Use the provided tools. " + "Respond in the caller's language. Submit with calibrated confidence." +) + +LanguageCode = Literal["hi", "ta", "kn", "en", "hinglish"] + + +class EpisodeSampler(Protocol): + """Draws a ``GoalSpec`` for one prompt slot (training.md §2.2).""" + + def __call__(self, step: int) -> Any: ... + + +class EnvFactory(Protocol): + """Returns a fresh ``DriftCallEnv`` per rollout (training.md §3.2).""" + + def __call__(self) -> Any: ... + + +class RolloutGroupFn(Protocol): + """Runs G multi-turn rollouts sharing one goal. + + Returns a tuple ``(episodes, completions)`` of length G each. + """ + + def __call__( + self, + *, + model: Any, + tokenizer: Any, + goal: Any, + episode_seed: int, + num_generations: int, + env_factory: EnvFactory, + ) -> tuple[tuple[Any, ...], tuple[str, ...]]: ... + + +@dataclass(frozen=True) +class AdapterRecord: + """Frozen view of one :class:`EpisodeDatasetAdapter` yield. + + Tests consume this view rather than dict-typing ``_meta`` inline. + """ + + prompt: str + goal: Any + episode_seed: int + stage: Literal[1, 2, 3] + language_weights: dict[LanguageCode, float] + + +def render_initial_prompt(tokenizer: Any, goal: Any) -> str: + """Render the turn-0 chat template (training.md §3.2.1). + + Messages: pinned system prompt + ``goal.seed_utterance`` as the user + turn. ``add_generation_prompt=True`` tells Gemma to emit an assistant + turn. Tool schemas live in later turns so only these two messages + appear at ``step == 0``. + """ + seed_utterance = getattr(goal, "seed_utterance", "") + messages: list[dict[str, str]] = [ + {"role": "system", "content": PINNED_SYSTEM_PROMPT}, + {"role": "user", "content": seed_utterance}, + ] + result = tokenizer.apply_chat_template( + messages, + tokenize=False, + add_generation_prompt=True, + ) + return str(result) + + +class EpisodeDatasetAdapter: + """Stateless streaming dataset (training.md §2.2). + + Constructor signature matches training.md §2.2: a ``task_gen`` callable + accepting ``(seed, stage, language_weights)``, an ``env_factory`` + producing fresh envs, the curriculum ``stage``, a ``stage_base_seed`` + used to derive per-step ``episode_seed``, the per-language sampling + ``language_weights``, and the ``tokenizer`` used to render prompts. + + Iteration is infinite — exactly one record per GRPO training step. + Step counter is local to ``__iter__`` so resume simply restarts from + whatever step TRL's ``resume_from_checkpoint`` restores. + """ + + def __init__( + self, + *, + task_gen: Callable[..., Any], + env_factory: EnvFactory, + stage: Literal[1, 2, 3], + stage_base_seed: int, + language_weights: dict[LanguageCode, float], + tokenizer: Any, + ) -> None: + self.task_gen = task_gen + self.env_factory = env_factory + self.stage: Literal[1, 2, 3] = stage + self.stage_base_seed = stage_base_seed + self.language_weights = dict(language_weights) + self.tokenizer = tokenizer + + def _build_record(self, step: int) -> dict[str, Any]: + episode_seed = self.stage_base_seed + step + goal = self.task_gen( + seed=episode_seed, + stage=self.stage, + language_weights=self.language_weights, + ) + prompt = render_initial_prompt(self.tokenizer, goal) + return { + "prompt": prompt, + "_meta": { + "goal": goal, + "episode_seed": episode_seed, + "stage": self.stage, + "language_weights": dict(self.language_weights), + }, + } + + def __iter__(self) -> Iterator[dict[str, Any]]: + step = 0 + while True: + yield self._build_record(step) + step += 1 + + def __len__(self) -> int: + """Length sentinel for TRL 0.24+ ``RepeatSampler``. + + The dataset is logically infinite (one record per GRPO step), but + TRL 0.24's ``RepeatSampler`` calls ``len(data_source)`` to size the + sampler. Returning a large finite number lets training proceed; the + actual step count is bounded by ``GRPOConfig.max_steps``. + """ + return 1_000_000 + + def __getitem__(self, idx: int) -> dict[str, Any]: + """Map-style indexing for TRL 0.24+ DataLoader. + + TRL 0.24 treats the train_dataset as a Map-style dataset and looks + records up by integer index. We honour the contract by deriving the + record purely from ``idx`` — the adapter is stateless so any index + produces a deterministic ``(prompt, _meta)`` pair for that step. + """ + return self._build_record(int(idx)) + + def peek(self, step: int) -> AdapterRecord: + """Materialize the record at ``step`` without advancing iteration. + + Used by tests (§1.2 U14–U18) to assert record shape at arbitrary + steps without consuming a generator. + """ + rec = self._build_record(step) + meta = rec["_meta"] + return AdapterRecord( + prompt=rec["prompt"], + goal=meta["goal"], + episode_seed=meta["episode_seed"], + stage=meta["stage"], + language_weights=meta["language_weights"], + ) + + +def _import_grpo_trainer() -> type[Any]: + """Lazy import of ``trl.GRPOTrainer``; isolated for mocking in tests.""" + from trl import GRPOTrainer + + return cast("type[Any]", GRPOTrainer) + + +def _make_driftcall_init( + base_cls: type[Any], +) -> Callable[..., None]: + """Build an ``__init__`` bound to ``base_cls``; avoids super() recursion + when the returned class is itself further subclassed. + + DriftCall-specific kwargs added on top of ``GRPOTrainer.__init__``: + + - ``rollout_group_fn``, ``env_factory``, ``reward_fn_driftcall`` — the + multi-turn rollout override surface (see class docstring). + - ``enable_adaptive_kl`` (default ``True``) — auto-attach an + :class:`AdaptiveKLCallback` so β retargets to the measured KL each + logging tick (training.md §3.3.1). Set ``False`` to disable. + - ``adaptive_kl_target`` — override the default ``target_kl=BETA_KL``. + - ``adaptive_kl_kp`` — override the proportional gain. + - ``adaptive_kl_beta_min`` / ``adaptive_kl_beta_max`` — override clamp + bounds. + """ + + def _init( + self: Any, + *args: Any, + rollout_group_fn: RolloutGroupFn, + env_factory: EnvFactory, + reward_fn_driftcall: Callable[..., list[float]], + enable_adaptive_kl: bool = True, + adaptive_kl_target: float | None = None, + adaptive_kl_kp: float = DEFAULT_KP, + adaptive_kl_beta_min: float = DEFAULT_BETA_MIN, + adaptive_kl_beta_max: float = DEFAULT_BETA_MAX, + **kwargs: Any, + ) -> None: + # TRL 0.24 made ``reward_funcs`` a required arg on GRPOTrainer. + # Our custom ``_generate_and_score_completions`` short-circuits the + # base reward path entirely (calls ``reward_fn_driftcall`` directly), + # so the parent's ``reward_funcs`` value is never invoked. Pass a + # placeholder identity reward to satisfy the signature on TRL>=0.24. + if "reward_funcs" not in kwargs: + def _placeholder_reward( + completions: Any = None, + **_unused: Any, + ) -> list[float]: + n = len(completions) if completions is not None else 0 + return [0.0] * n + + kwargs["reward_funcs"] = [_placeholder_reward] + base_cls.__init__(self, *args, **kwargs) + self.rollout_group_fn = rollout_group_fn + self.env_factory = env_factory + self.reward_fn_driftcall = reward_fn_driftcall + + if enable_adaptive_kl: + target = ( + adaptive_kl_target if adaptive_kl_target is not None else BETA_KL + ) + callback = AdaptiveKLCallback( + target_kl=target, + kp=adaptive_kl_kp, + beta_min=adaptive_kl_beta_min, + beta_max=adaptive_kl_beta_max, + ) + self.adaptive_kl_callback = callback + add_callback = getattr(base_cls, "add_callback", None) + if callable(add_callback): + # Production path (TRL ≥ 0.23): register through the TRL + # callback handler so ``on_log`` fires alongside default + # loggers with the correct ``args``/``state``/``control``. + self.add_callback(callback) + else: + # Fallback: minimal bases in tests lack ``add_callback``. + # Keep a private list so callers can still invoke the hook. + if not hasattr(self, "_driftcall_callbacks"): + self._driftcall_callbacks = [] + self._driftcall_callbacks.append(callback) + else: + self.adaptive_kl_callback = None + + return _init + + +def _driftcall_generate_and_score_completions( + self: Any, inputs: list[dict[str, Any]] +) -> dict[str, Any]: + """Run the multi-turn rollout, then call ``reward_fn``. + + Expects ``inputs`` to carry one row per prompt slot with the + ``_meta`` dict produced by :class:`EpisodeDatasetAdapter`. + Returns a dict with keys ``episodes``, ``completions``, ``rewards``, + ``prompts`` — each length G (num_generations). + """ + if not inputs: + raise ValueError("inputs must be a non-empty list") + + row = inputs[0] + meta = row["_meta"] + prompt = row["prompt"] + goal = meta["goal"] + episode_seed = meta["episode_seed"] + + num_generations = int(getattr(self.args, "num_generations", 8)) + episodes, completions = self.rollout_group_fn( + model=self.model, + tokenizer=self.processing_class, + goal=goal, + episode_seed=episode_seed, + num_generations=num_generations, + env_factory=self.env_factory, + ) + + if len(episodes) != num_generations or len(completions) != num_generations: + raise ValueError( + f"rollout_group_fn produced {len(episodes)} episodes and " + f"{len(completions)} completions; expected {num_generations} each" + ) + + prompts = [prompt] * num_generations + metas = [dict(meta) for _ in range(num_generations)] + rewards = self.reward_fn_driftcall( + prompts=prompts, + completions=list(completions), + _meta=metas, + episodes=list(episodes), + ) + + return { + "episodes": episodes, + "completions": completions, + "rewards": rewards, + "prompts": prompts, + } + + +def make_driftcall_grpo_trainer_cls(base_cls: type[Any] | None = None) -> type[Any]: + """Build the :class:`DriftCallGRPOTrainer` class bound to ``base_cls``. + + Default ``base_cls`` is ``trl.GRPOTrainer`` (imported lazily). Tests + pass a stub base class so they can exercise the override path without + TRL installed. + + GRPOTrainer subclass with multi-turn rollout override + (training.md §3.2.3). Construction adds three DriftCall-specific + kwargs over the standard ``GRPOTrainer.__init__``: + + - ``rollout_group_fn``: :class:`RolloutGroupFn` running G multi-turn + episodes and returning ``(episodes, completions)``. + - ``env_factory``: :class:`EnvFactory` producing a fresh + ``DriftCallEnv`` per rollout. + - ``reward_fn_driftcall``: the step_13 ``reward_fn`` — called + directly with the frozen ``Episode`` tuple after rollout. + + ``_generate_and_score_completions`` replaces the TRL default. + Advantage + KL + optimizer step paths are inherited unchanged. + """ + resolved_base: type[Any] = ( + base_cls if base_cls is not None else _import_grpo_trainer() + ) + return type( + "DriftCallGRPOTrainer", + (resolved_base,), + { + "__init__": _make_driftcall_init(resolved_base), + "_generate_and_score_completions": _driftcall_generate_and_score_completions, + "__doc__": "GRPOTrainer subclass with multi-turn rollout override.", + }, + ) + + +def driftcall_grpo_trainer_methods() -> tuple[str, ...]: + """Return the method names the subclass overrides (introspection helper). + + Used by the shape test (U in §1.x) to verify the override surface. + """ + return ("__init__", "_generate_and_score_completions") + + +# --------------------------------------------------------------------------- +# Adaptive KL controller (training.md §3.3 — retarget β from measured KL) +# --------------------------------------------------------------------------- + + +DEFAULT_BETA_MIN: float = 0.001 +DEFAULT_BETA_MAX: float = 1.0 +DEFAULT_KP: float = 2.0 + + +def _trainer_callback_base() -> type: + """Return ``transformers.TrainerCallback`` if importable, else ``object``. + + Importing transformers lazily keeps step_14 importable on CPU-only CI + runners that don't have transformers installed. + """ + try: + from transformers.trainer_callback import TrainerCallback + return TrainerCallback + except Exception: + return object + + +class AdaptiveKLCallback(_trainer_callback_base()): # type: ignore[misc] + """Retarget β each step based on the ratio of measured KL to ``target_kl``. + + Proportional controller with symmetric log-space update: + + err = (kl - target_kl) / target_kl + new_beta = beta * exp(kp * err) + new_beta = clamp(new_beta, beta_min, beta_max) + + When ``kl`` matches ``target_kl``, ``err == 0`` and β is left unchanged. + Safe on missing / NaN / non-numeric KL signals (no-op, no exception). + + Inherits from :class:`transformers.trainer_callback.TrainerCallback` when + available (production path) so all the no-op callback events + (``on_train_begin``, ``on_step_begin``, etc.) come for free; falls back + to ``object`` on CPU-only CI when transformers is not installed. + """ + + def __init__( + self, + target_kl: float = BETA_KL, + *, + kp: float = DEFAULT_KP, + beta_min: float = DEFAULT_BETA_MIN, + beta_max: float = DEFAULT_BETA_MAX, + ) -> None: + if target_kl <= 0.0: + raise ValueError(f"target_kl must be > 0; got {target_kl}") + if beta_min <= 0.0 or beta_max <= 0.0: + raise ValueError( + f"beta bounds must be > 0; got min={beta_min}, max={beta_max}" + ) + if beta_min > beta_max: + raise ValueError( + f"beta_min ({beta_min}) must be <= beta_max ({beta_max})" + ) + self.target_kl = float(target_kl) + self.kp = float(kp) + self.beta_min = float(beta_min) + self.beta_max = float(beta_max) + + def _coerce_kl(self, raw: Any) -> float | None: + """Return a finite float or ``None`` — propagates no-op on bad input.""" + try: + value = float(raw) + except (TypeError, ValueError): + return None + if math.isnan(value) or math.isinf(value): + return None + return value + + def _next_beta(self, beta: float, kl: float) -> tuple[float, bool, bool]: + """Return ``(new_beta, clamped_to_min, clamped_to_max)``.""" + err = (kl - self.target_kl) / self.target_kl + # Clamp the exponent so extreme KL spikes don't overflow math.exp; + # the result is clamped anyway and exp(±50) easily saturates either bound. + exponent = max(-50.0, min(50.0, self.kp * err)) + scaled = beta * math.exp(exponent) + if scaled <= self.beta_min: + return self.beta_min, True, False + if scaled >= self.beta_max: + return self.beta_max, False, True + return scaled, False, False + + def on_log( + self, + args: Any, + state: Any, + control: Any, + *, + logs: dict[str, Any] | None = None, + **_kwargs: Any, + ) -> Any: + """TRL hook — called with every ``trainer.log(...)`` dict. + + On a well-formed KL signal: mutates ``args.beta`` with the new + coefficient and writes five diagnostic fields back into ``logs`` + so TRL's default reporter forwards them to wandb / CSV / etc.: + + - ``train/beta_adaptive`` current KL coefficient + - ``train/kl_measured`` sanitised KL input + - ``train/kl_target`` constant — aids chart-by-reference + - ``train/beta_clamped_to_min`` 0/1 — fires on collapse + - ``train/beta_clamped_to_max`` 0/1 — fires on runaway divergence + """ + if logs is None: + return control + if "kl" not in logs: + return control + kl = self._coerce_kl(logs["kl"]) + if kl is None: + return control + beta = float(getattr(args, "beta", BETA_KL)) + new_beta, clamped_lo, clamped_hi = self._next_beta(beta, kl) + args.beta = new_beta + logs["train/beta_adaptive"] = new_beta + logs["train/kl_measured"] = kl + logs["train/kl_target"] = self.target_kl + logs["train/beta_clamped_to_min"] = 1 if clamped_lo else 0 + logs["train/beta_clamped_to_max"] = 1 if clamped_hi else 0 + return control + + +__all__ = [ + "AdapterRecord", + "AdaptiveKLCallback", + "DEFAULT_BETA_MAX", + "DEFAULT_BETA_MIN", + "DEFAULT_KP", + "EnvFactory", + "EpisodeDatasetAdapter", + "EpisodeSampler", + "LanguageCode", + "PINNED_SYSTEM_PROMPT", + "RolloutGroupFn", + "driftcall_grpo_trainer_methods", + "make_driftcall_grpo_trainer_cls", + "render_initial_prompt", +] diff --git a/cells/step_15_train_stage1.md b/cells/step_15_train_stage1.md new file mode 100644 index 0000000000000000000000000000000000000000..acbb78bddb1656ef792ca110d906c7a77be19c73 --- /dev/null +++ b/cells/step_15_train_stage1.md @@ -0,0 +1,7 @@ +# Step 15 — Stage-1 GRPO training entry + +Stage-1 is the curriculum origin (training.md §3.5, DESIGN.md §10.3): 150 GRPO steps, no drift, language mix 50% English / 30% Hinglish / 20% Hindi, `warmup_ratio=0.1`. `resume_from` is rejected — there is no prior stage. Saves checkpoints every 50 steps via `save_pretrained(safe_serialization=True)`; never the naive 4-bit -> 16-bit merge path (DESIGN.md §10.5). + +`train(stage=1, num_steps=150, resume_from=None)` boots Gemma 3n E2B in 4-bit (hardware-aware precision: FP16 on V100, BF16 on H100) via `boot_gemma`, asserts the dtype via `assert_dtype_for_hardware` (halts on slippage; training.md §3.1), constructs the GRPOConfig + `EpisodeDatasetAdapter` + `DriftCallGRPOTrainer`, initialises wandb (offline-safe; `WandBStartupError` only when `WANDB_MODE != "offline"`), and runs `trainer.train()` for the requested step count. The `task_gen`, `env_factory`, and `rollout_group_fn` callables are passed by the notebook orchestrator so the cell stays decoupled from the env + data builders. + +`build_run_plan` is the pure-function entry point — tests use it to verify the resolved arguments without exercising the GPU stack. `write_local_csv_row` mirrors every WandB log dict to `metrics.csv` with the stable 20-column schema from training.md §3.4 (NaN encoded as `"nan"`). diff --git a/cells/step_15_train_stage1.py b/cells/step_15_train_stage1.py new file mode 100644 index 0000000000000000000000000000000000000000..8b254775242dcb67104507ef7ae37f5176493150 --- /dev/null +++ b/cells/step_15_train_stage1.py @@ -0,0 +1,307 @@ +"""Stage-1 GRPO training entry (docs/modules/training.md §3.5, DESIGN.md §10.3). + +Stage-1 contract: + - 150 GRPO steps (curriculum warmup). + - **No drift** in the env (``curriculum_stage=1``). + - Language mix: 50% English, 30% Hinglish, 20% Hindi (no Tamil/Kannada). + - ``warmup_ratio=0.1`` — stage-1 is the only stage that warms the LR. + - ``resume_from`` MUST be ``None``; stage-1 is the curriculum origin. + - Saves checkpoints every 50 steps with ``safe_serialization=True``; + NEVER naive 4-bit -> 16-bit merge (DESIGN.md §10.5, CLAUDE.md §9). + - WandB primary monitoring; ``LocalCSVCallback`` mirrors every ``on_log`` + when ``WANDB_MODE=offline`` or the wandb upload flakes (training.md §2.4.1). + - Dtype-slippage assertion fires at entry via ``assert_dtype_for_hardware`` + from step_12 (V100 -> FP16, H100 -> BF16 safety; training.md §3.1). + +Heavy imports (``torch``, ``trl``, ``unsloth``, ``wandb``) are deferred +inside functions so this module imports cleanly on CPU-only CI. +""" + +from __future__ import annotations + +import csv +import os +from dataclasses import dataclass +from pathlib import Path +from typing import TYPE_CHECKING, Any, Literal, cast + +from cells.step_12_gemma_boot import BootConfig, boot_gemma +from cells.step_13_grpo_config import build_grpo_config +from cells.step_14_custom_trainer import EpisodeDatasetAdapter, LanguageCode + +if TYPE_CHECKING: # pragma: no cover - typing only + from collections.abc import Callable + + +CheckpointPath = Path + +STAGE: Literal[1] = 1 +DEFAULT_NUM_STEPS: int = 150 +WARMUP_RATIO: float = 0.1 +STAGE_BASE_SEED: int = 1_000_000 +DEFAULT_OUTPUT_DIR: Path = Path("checkpoints/stage1_final") + +LANGUAGE_WEIGHTS: dict[str, float] = { + "en": 0.50, + "hinglish": 0.30, + "hi": 0.20, + "ta": 0.0, + "kn": 0.0, +} + +CSV_COLUMNS: tuple[str, ...] = ( + "step", + "train/reward_mean", + "train/reward_std", + "train/policy_kl", + "train/gen_length_mean", + "train/grad_norm", + "train/loss", + "train/learning_rate", + "train/R1_mean", + "train/R2_mean", + "train/R3_mean", + "train/R4_mean", + "train/R5_mean", + "train/drift_detected_rate", + "train/format_compliance_rate", + "train/hallucinated_field_count", + "train/reward_hi", + "train/reward_ta", + "train/reward_kn", + "train/reward_en", +) + + +class WandBStartupError(RuntimeError): + """Raised at ``train()`` entry when ``wandb.init()`` fails AND + ``WANDB_MODE != "offline"``. Offline mode never raises (training.md §2.4.1).""" + + +@dataclass(frozen=True) +class StageRunPlan: + """Frozen plan describing one stage-1 training launch. + + Surfaced so tests can introspect the resolved arguments without having + to mock the whole TRL stack. + """ + + stage: Literal[1, 2, 3] + num_steps: int + warmup_ratio: float + stage_base_seed: int + language_weights: dict[str, float] + output_dir: Path + resume_from: Path | None + + +def _validate_resume_from(resume_from: Path | None) -> None: + """Stage 1 is the curriculum origin — ``resume_from`` MUST be ``None``.""" + if resume_from is not None: + raise ValueError( + f"Stage 1 must not receive resume_from; got {resume_from!r}. " + f"Stage 1 is the curriculum origin (training.md §3.5)." + ) + + +def _validate_num_steps(num_steps: int) -> None: + if num_steps < 1: + raise ValueError(f"num_steps must be >= 1; got {num_steps}") + + +def build_run_plan( + *, + num_steps: int = DEFAULT_NUM_STEPS, + resume_from: Path | None = None, + output_dir: Path | None = None, +) -> StageRunPlan: + """Resolve the launch arguments into a frozen :class:`StageRunPlan`. + + Pure function — does not touch the GPU, the filesystem, or wandb. + Tests use this to verify the resolved plan without invoking ``train``. + """ + _validate_resume_from(resume_from) + _validate_num_steps(num_steps) + return StageRunPlan( + stage=STAGE, + num_steps=num_steps, + warmup_ratio=WARMUP_RATIO, + stage_base_seed=STAGE_BASE_SEED, + language_weights=dict(LANGUAGE_WEIGHTS), + output_dir=output_dir if output_dir is not None else DEFAULT_OUTPUT_DIR, + resume_from=resume_from, + ) + + +def _wandb_init_or_raise(*, run_name: str, output_dir: Path) -> Any: + """Initialise wandb; raise :class:`WandBStartupError` only when online. + + Offline mode (``WANDB_MODE=offline``) never raises — local CSV is the + authoritative record (training.md §2.4.1). + """ + mode = os.environ.get("WANDB_MODE") + try: + import wandb + except ImportError as exc: # pragma: no cover - wandb required at runtime + if mode == "offline": + return None + raise WandBStartupError( + f"wandb import failed and WANDB_MODE != 'offline': {exc}" + ) from exc + + try: + run = wandb.init( + project="driftcall", + group="curriculum-v1", + name=run_name, + dir=str(output_dir.parent), + reinit=True, + ) + except Exception as exc: + if mode == "offline": + return None + raise WandBStartupError( + f"wandb.init() failed and WANDB_MODE != 'offline': {exc}" + ) from exc + return run + + +def write_local_csv_row( + *, + csv_path: Path, + logs: dict[str, Any], + columns: tuple[str, ...] = CSV_COLUMNS, +) -> None: + """Append one row to ``metrics.csv`` mirroring the WandB ``on_log`` dict. + + Schema is the stable 20-column ordering from training.md §3.4. NaN floats + are encoded as the literal string ``"nan"`` (training.md §2.4.1). Header + is written exactly once on first call. + """ + csv_path.parent.mkdir(parents=True, exist_ok=True) + is_new = not csv_path.exists() + row: list[str] = [] + for col in columns: + value = logs.get(col, "") + if isinstance(value, float): + row.append("nan" if value != value else repr(value)) + else: + row.append(str(value)) + with csv_path.open("a", newline="", encoding="utf-8") as fh: + writer = csv.writer(fh) + if is_new: + writer.writerow(columns) + writer.writerow(row) + + +def save_checkpoint( + *, + model: Any, + tokenizer: Any, + output_dir: Path, +) -> Path: + """Save adapter + tokenizer using ``safe_serialization=True``. + + Per DESIGN.md §10.5 / training.md §3.6 we NEVER call + ``merge_and_unload()`` or any 4-bit -> 16-bit naive merge path. + Returns the directory where the adapter landed. + """ + output_dir.mkdir(parents=True, exist_ok=True) + model.save_pretrained(str(output_dir), safe_serialization=True) + tokenizer.save_pretrained(str(output_dir)) + return output_dir + + +def train( + *, + stage: Literal[1] = STAGE, + num_steps: int = DEFAULT_NUM_STEPS, + resume_from: Path | None = None, + output_dir: Path | None = None, + boot_config: BootConfig | None = None, + task_gen: Callable[..., Any] | None = None, + env_factory: Callable[[], Any] | None = None, + rollout_group_fn: Callable[..., Any] | None = None, +) -> CheckpointPath: + """Run GRPO Stage-1 (warmup, no drift) for ``num_steps`` updates. + + Behaviour (training.md §2.1): + 1. Boot Gemma 3n E2B in 4-bit + attach LoRA via :func:`boot_gemma`. + 2. Re-assert FP16 dtype (BF16-slippage halt; training.md §3.1). + 3. Build :class:`GRPOConfig` for stage 1 (warmup_ratio=0.1). + 4. Build the streaming :class:`EpisodeDatasetAdapter` with the + stage-1 language mix (50% en, 30% hinglish, 20% hi). + 5. Construct ``DriftCallGRPOTrainer`` with the multi-turn rollout + override (step_14) and ``reward_fn`` (step_13). + 6. Initialise wandb (offline-safe; training.md §2.4.1). + 7. ``trainer.train()`` for ``num_steps`` updates. + 8. Save the final adapter via :func:`save_checkpoint`. + """ + if stage != STAGE: + raise ValueError(f"stage must be {STAGE}; got {stage}") + + plan = build_run_plan( + num_steps=num_steps, + resume_from=resume_from, + output_dir=output_dir, + ) + + # boot_gemma() already runs assert_fp16_dtype on the base model before + # LoRA attach (training.md §3.1). We do not re-check the peft-wrapped + # model here — the wrapped LoRA params are FP16 by construction. + model, tokenizer = boot_gemma(boot_config) + + config = build_grpo_config(stage=plan.stage, resume_output_dir=plan.output_dir, max_steps=plan.num_steps) + + if task_gen is None or env_factory is None or rollout_group_fn is None: + raise ValueError( + "Stage-1 train() requires task_gen, env_factory, and rollout_group_fn " + "to be provided by the caller (notebook orchestrator). They are kept " + "explicit so the training cell stays decoupled from data + env builders." + ) + + dataset = EpisodeDatasetAdapter( + task_gen=task_gen, + env_factory=env_factory, + stage=plan.stage, + stage_base_seed=plan.stage_base_seed, + language_weights=cast("dict[LanguageCode, float]", plan.language_weights), + tokenizer=tokenizer, + ) + + from cells.step_13_grpo_config import reward_fn + from cells.step_14_custom_trainer import make_driftcall_grpo_trainer_cls + + Trainer = make_driftcall_grpo_trainer_cls() + trainer = Trainer( + model=model, + args=config, + processing_class=tokenizer, + train_dataset=dataset, + rollout_group_fn=rollout_group_fn, + env_factory=env_factory, + reward_fn_driftcall=reward_fn, + ) + + _wandb_init_or_raise(run_name=f"driftcall-stage{plan.stage}", output_dir=plan.output_dir) + trainer.train() + + return save_checkpoint(model=model, tokenizer=tokenizer, output_dir=plan.output_dir) + + +__all__ = [ + "CSV_COLUMNS", + "DEFAULT_NUM_STEPS", + "DEFAULT_OUTPUT_DIR", + "LANGUAGE_WEIGHTS", + "STAGE", + "STAGE_BASE_SEED", + "WARMUP_RATIO", + "CheckpointPath", + "StageRunPlan", + "WandBStartupError", + "build_run_plan", + "save_checkpoint", + "train", + "write_local_csv_row", +] diff --git a/cells/step_16_train_stage2.md b/cells/step_16_train_stage2.md new file mode 100644 index 0000000000000000000000000000000000000000..06155d3114c5f74bd0123d7b08530be922181c23 --- /dev/null +++ b/cells/step_16_train_stage2.md @@ -0,0 +1,7 @@ +# Step 16 — Stage-2 GRPO training entry + +Stage-2 is the single-drift curriculum (training.md §3.5, DESIGN.md §10.3): 200 GRPO steps, one drift per episode (`curriculum_stage=2`), language mix 30% EN / 30% Hinglish / 20% Hi / 10% Ta / 10% Kn, `warmup_ratio=0.0` (continuous cosine across all 500 steps; never re-warm mid-curriculum). `resume_from` is required — must point at the Stage-1 final checkpoint. Saves checkpoints every 50 steps via `save_pretrained(safe_serialization=True)`; never the naive 4-bit -> 16-bit merge path (DESIGN.md §10.5). + +`train(stage=2, num_steps=200, resume_from=Path("checkpoints/stage1_final"))` boots Gemma 3n E2B in 4-bit (hardware-aware precision: FP16 on V100, BF16 on H100), asserts dtype via `assert_dtype_for_hardware`, attaches the Stage-1 LoRA adapters via `PeftModel.from_pretrained(model, resume_from, is_trainable=True)`, constructs the Stage-2 config + adapter + trainer, and resumes via `trainer.train(resume_from_checkpoint=str(resume_from))` — TRL restores the optimiser/scheduler/global-step state. Language weights are validated up-front: every non-English cohort must carry weight >= 0.05 to avoid `LanguageCohortCollapseError` upstream (training.md §7f). + +`build_run_plan` is the pure-function entry point used by tests; rejects `resume_from=None` and weights below the 0.05 floor. `WandBStartupError` only fires when `WANDB_MODE != "offline"` and `wandb.init()` raises (training.md §2.4.1). Dtype-slippage halt fires before any optimizer/PEFT state is built (training.md §3.1). diff --git a/cells/step_16_train_stage2.py b/cells/step_16_train_stage2.py new file mode 100644 index 0000000000000000000000000000000000000000..c73007a1f7524234d172e414d8dc83d7a0d53fe8 --- /dev/null +++ b/cells/step_16_train_stage2.py @@ -0,0 +1,357 @@ +"""Stage-2 GRPO training entry (docs/modules/training.md §3.5, DESIGN.md §10.3). + +Stage-2 contract: + - 200 GRPO steps (single-drift curriculum). + - **One drift per episode** in the env (``curriculum_stage=2``). + - Language mix: 30% English, 30% Hinglish, 20% Hindi, 10% Tamil, 10% Kannada. + - ``warmup_ratio=0.0`` — never re-warm the LR mid-curriculum + (training.md §3.5; one continuous cosine across all 500 steps). + - ``resume_from`` is REQUIRED — must point at the Stage-1 final + checkpoint directory. None is rejected. + - Validates ``language_weights`` per training.md §7f: every non-English + cohort must carry weight >= 0.05 at stage >= 2. + - Saves checkpoints every 50 steps with ``safe_serialization=True``; + NEVER naive 4-bit -> 16-bit merge (DESIGN.md §10.5, CLAUDE.md §9). + - WandB primary monitoring; ``LocalCSVCallback`` mirrors every ``on_log`` + when ``WANDB_MODE=offline`` or the wandb upload flakes (training.md §2.4.1). + - Dtype-slippage assertion fires at entry via ``assert_dtype_for_hardware`` + from step_12 (V100 -> FP16, H100 -> BF16 safety; training.md §3.1). + +Heavy imports (``torch``, ``trl``, ``unsloth``, ``wandb``, ``peft``) are +deferred inside functions so this module imports cleanly on CPU-only CI. +""" + +from __future__ import annotations + +import csv +import os +from dataclasses import dataclass +from pathlib import Path +from typing import TYPE_CHECKING, Any, Literal, cast + +from cells.step_12_gemma_boot import BootConfig, assert_dtype_for_hardware +from cells.step_13_grpo_config import build_grpo_config +from cells.step_14_custom_trainer import EpisodeDatasetAdapter, LanguageCode + +if TYPE_CHECKING: # pragma: no cover - typing only + from collections.abc import Callable + + +CheckpointPath = Path + +STAGE: Literal[2] = 2 +DEFAULT_NUM_STEPS: int = 200 +WARMUP_RATIO: float = 0.0 +STAGE_BASE_SEED: int = 2_000_000 +DEFAULT_OUTPUT_DIR: Path = Path("checkpoints/stage2_final") +COHORT_MIN_WEIGHT_AT_STAGE_GE_2: float = 0.05 +NON_ENGLISH_LANGUAGES: tuple[str, ...] = ("hi", "ta", "kn", "hinglish") + +LANGUAGE_WEIGHTS: dict[str, float] = { + "en": 0.30, + "hinglish": 0.30, + "hi": 0.20, + "ta": 0.10, + "kn": 0.10, +} + +CSV_COLUMNS: tuple[str, ...] = ( + "step", + "train/reward_mean", + "train/reward_std", + "train/policy_kl", + "train/gen_length_mean", + "train/grad_norm", + "train/loss", + "train/learning_rate", + "train/R1_mean", + "train/R2_mean", + "train/R3_mean", + "train/R4_mean", + "train/R5_mean", + "train/drift_detected_rate", + "train/format_compliance_rate", + "train/hallucinated_field_count", + "train/reward_hi", + "train/reward_ta", + "train/reward_kn", + "train/reward_en", +) + + +class WandBStartupError(RuntimeError): + """Raised at ``train()`` entry when ``wandb.init()`` fails AND + ``WANDB_MODE != "offline"``. Offline mode never raises (training.md §2.4.1).""" + + +@dataclass(frozen=True) +class StageRunPlan: + """Frozen plan describing one stage-2 training launch.""" + + stage: Literal[1, 2, 3] + num_steps: int + warmup_ratio: float + stage_base_seed: int + language_weights: dict[str, float] + output_dir: Path + resume_from: Path + + +def _validate_resume_from(resume_from: Path | None) -> Path: + """Stage 2 REQUIRES a stage-1 checkpoint to resume from.""" + if resume_from is None: + raise ValueError( + "Stage 2 requires resume_from (path to Stage-1 final checkpoint); " + "got None (training.md §3.5 stage transitions)." + ) + if not isinstance(resume_from, Path): + raise TypeError( + f"resume_from must be a pathlib.Path; got {type(resume_from).__name__}" + ) + return resume_from + + +def _validate_num_steps(num_steps: int) -> None: + if num_steps < 1: + raise ValueError(f"num_steps must be >= 1; got {num_steps}") + + +def _validate_language_weights(language_weights: dict[str, float]) -> None: + """Every non-English cohort must carry weight >= 0.05 at stage 2/3. + + Prevents :class:`LanguageCohortCollapseError` upstream + (training.md §7f). + """ + for lang in NON_ENGLISH_LANGUAGES: + weight = language_weights.get(lang, 0.0) + if weight < COHORT_MIN_WEIGHT_AT_STAGE_GE_2: + raise ValueError( + f"language_weights['{lang}'] = {weight} < " + f"{COHORT_MIN_WEIGHT_AT_STAGE_GE_2}; weight >= 0.05 for " + f"non-English at stage >= 2 (training.md §7f)." + ) + + +def build_run_plan( + *, + num_steps: int = DEFAULT_NUM_STEPS, + resume_from: Path | None = None, + output_dir: Path | None = None, + language_weights: dict[str, float] | None = None, +) -> StageRunPlan: + """Resolve the launch arguments into a frozen :class:`StageRunPlan`. + + Pure function — does not touch the GPU, the filesystem, or wandb. + """ + resolved_resume = _validate_resume_from(resume_from) + _validate_num_steps(num_steps) + weights = dict(language_weights) if language_weights is not None else dict(LANGUAGE_WEIGHTS) + _validate_language_weights(weights) + return StageRunPlan( + stage=STAGE, + num_steps=num_steps, + warmup_ratio=WARMUP_RATIO, + stage_base_seed=STAGE_BASE_SEED, + language_weights=weights, + output_dir=output_dir if output_dir is not None else DEFAULT_OUTPUT_DIR, + resume_from=resolved_resume, + ) + + +def _wandb_init_or_raise(*, run_name: str, output_dir: Path) -> Any: + """Initialise wandb; raise :class:`WandBStartupError` only when online.""" + mode = os.environ.get("WANDB_MODE") + try: + import wandb + except ImportError as exc: # pragma: no cover - wandb required at runtime + if mode == "offline": + return None + raise WandBStartupError( + f"wandb import failed and WANDB_MODE != 'offline': {exc}" + ) from exc + + try: + run = wandb.init( + project="driftcall", + group="curriculum-v1", + name=run_name, + dir=str(output_dir.parent), + reinit=True, + ) + except Exception as exc: + if mode == "offline": + return None + raise WandBStartupError( + f"wandb.init() failed and WANDB_MODE != 'offline': {exc}" + ) from exc + return run + + +def write_local_csv_row( + *, + csv_path: Path, + logs: dict[str, Any], + columns: tuple[str, ...] = CSV_COLUMNS, +) -> None: + """Append one row to ``metrics.csv`` mirroring the WandB ``on_log`` dict.""" + csv_path.parent.mkdir(parents=True, exist_ok=True) + is_new = not csv_path.exists() + row: list[str] = [] + for col in columns: + value = logs.get(col, "") + if isinstance(value, float): + row.append("nan" if value != value else repr(value)) + else: + row.append(str(value)) + with csv_path.open("a", newline="", encoding="utf-8") as fh: + writer = csv.writer(fh) + if is_new: + writer.writerow(columns) + writer.writerow(row) + + +def save_checkpoint( + *, + model: Any, + tokenizer: Any, + output_dir: Path, +) -> Path: + """Save adapter + tokenizer using ``safe_serialization=True``.""" + output_dir.mkdir(parents=True, exist_ok=True) + model.save_pretrained(str(output_dir), safe_serialization=True) + tokenizer.save_pretrained(str(output_dir)) + return output_dir + + +def _load_base_model(boot_config: BootConfig | None) -> tuple[Any, Any]: + """Load the 4-bit Gemma 3n base model (no LoRA attach) and verify dtype. + + Stage 2 must NOT call :func:`cells.step_12_gemma_boot.boot_gemma` + because that helper attaches a *fresh* LoRA via ``get_peft_model``; + we instead load the base only, then wrap with the saved Stage-1 + adapters via :func:`_load_stage1_adapters` (training.md §3.1, §3.6). + + Precision is hardware-aware: V100 -> FP16, H100 -> BF16. + """ + cfg = boot_config if boot_config is not None else BootConfig() + + import torch + from unsloth import FastModel + + dtype = torch.float16 if cfg.hardware == "v100" else torch.bfloat16 + + model, tokenizer = FastModel.from_pretrained( + cfg.base_model_id, + max_seq_length=cfg.max_seq_length, + load_in_4bit=cfg.load_in_4bit, + dtype=dtype, + ) + assert_dtype_for_hardware(model, cfg.hardware) + return model, tokenizer + + +def _load_stage1_adapters(model: Any, resume_from: Path) -> Any: + """Attach the Stage-1 LoRA adapters to the freshly-booted base model. + + Returns the wrapped :class:`PeftModel`. Heavy import deferred so the + cell loads on CPU-only CI without ``peft`` installed. + """ + from peft import PeftModel + + return PeftModel.from_pretrained(model, str(resume_from), is_trainable=True) + + +def train( + *, + stage: Literal[2] = STAGE, + num_steps: int = DEFAULT_NUM_STEPS, + resume_from: Path | None = None, + output_dir: Path | None = None, + boot_config: BootConfig | None = None, + task_gen: Callable[..., Any] | None = None, + env_factory: Callable[[], Any] | None = None, + rollout_group_fn: Callable[..., Any] | None = None, +) -> CheckpointPath: + """Run GRPO Stage-2 (single drift) for ``num_steps`` updates. + + Behaviour (training.md §3.5 stage transitions): + 1. Load Gemma 3n E2B base in 4-bit (hardware-aware precision) — no fresh LoRA. + 2. Assert FP16 dtype on the base (BF16-slippage halt). + 3. Attach Stage-1 LoRA adapters via ``PeftModel.from_pretrained``. + 4. Build :class:`GRPOConfig` for stage 2 (warmup_ratio=0.0). + 5. Build the streaming :class:`EpisodeDatasetAdapter` with the + stage-2 language mix. + 6. Construct ``DriftCallGRPOTrainer`` with the multi-turn rollout + override and ``reward_fn``. + 7. Initialise wandb (offline-safe). + 8. ``trainer.train(resume_from_checkpoint=str(resume_from))`` — + restores optimizer/scheduler state + TRL-internal RNG. + 9. Save the final adapter via :func:`save_checkpoint`. + """ + if stage != STAGE: + raise ValueError(f"stage must be {STAGE}; got {stage}") + + plan = build_run_plan( + num_steps=num_steps, + resume_from=resume_from, + output_dir=output_dir, + ) + + base_model, tokenizer = _load_base_model(boot_config) + model = _load_stage1_adapters(base_model, plan.resume_from) + + config = build_grpo_config(stage=plan.stage, resume_output_dir=plan.output_dir, max_steps=plan.num_steps) + + if task_gen is None or env_factory is None or rollout_group_fn is None: + raise ValueError( + "Stage-2 train() requires task_gen, env_factory, and rollout_group_fn " + "to be provided by the caller (notebook orchestrator)." + ) + + dataset = EpisodeDatasetAdapter( + task_gen=task_gen, + env_factory=env_factory, + stage=plan.stage, + stage_base_seed=plan.stage_base_seed, + language_weights=cast("dict[LanguageCode, float]", plan.language_weights), + tokenizer=tokenizer, + ) + + from cells.step_13_grpo_config import reward_fn + from cells.step_14_custom_trainer import make_driftcall_grpo_trainer_cls + + Trainer = make_driftcall_grpo_trainer_cls() + trainer = Trainer( + model=model, + args=config, + processing_class=tokenizer, + train_dataset=dataset, + rollout_group_fn=rollout_group_fn, + env_factory=env_factory, + reward_fn_driftcall=reward_fn, + ) + + _wandb_init_or_raise(run_name=f"driftcall-stage{plan.stage}", output_dir=plan.output_dir) + trainer.train(resume_from_checkpoint=str(plan.resume_from)) + + return save_checkpoint(model=model, tokenizer=tokenizer, output_dir=plan.output_dir) + + +__all__ = [ + "COHORT_MIN_WEIGHT_AT_STAGE_GE_2", + "CSV_COLUMNS", + "DEFAULT_NUM_STEPS", + "DEFAULT_OUTPUT_DIR", + "LANGUAGE_WEIGHTS", + "NON_ENGLISH_LANGUAGES", + "STAGE", + "STAGE_BASE_SEED", + "WARMUP_RATIO", + "CheckpointPath", + "StageRunPlan", + "WandBStartupError", + "build_run_plan", + "save_checkpoint", + "train", + "write_local_csv_row", +] diff --git a/cells/step_17_train_stage3.md b/cells/step_17_train_stage3.md new file mode 100644 index 0000000000000000000000000000000000000000..333aa3586607c3c3da8469c0edf193ffb81733f4 --- /dev/null +++ b/cells/step_17_train_stage3.md @@ -0,0 +1,7 @@ +# Step 17 — Stage-3 GRPO training entry + +Stage-3 is the compound-drift curriculum (training.md §3.5, DESIGN.md §10.3): 150 GRPO steps, two drifts per episode (`curriculum_stage=3`), language mix identical to Stage 2 (30% EN / 30% Hinglish / 20% Hi / 10% Ta / 10% Kn), `warmup_ratio=0.0` (continuous cosine across all 500 steps). `resume_from` is required — must point at the Stage-2 final checkpoint. Saves checkpoints every 50 steps via `save_pretrained(safe_serialization=True)`; never the naive 4-bit -> 16-bit merge path (DESIGN.md §10.5). + +`train(stage=3, num_steps=150, resume_from=Path("checkpoints/stage2_final"))` boots Gemma 3n E2B in 4-bit (hardware-aware precision: FP16 on V100, BF16 on H100), asserts dtype via `assert_dtype_for_hardware`, attaches the Stage-2 LoRA adapters via `PeftModel.from_pretrained(..., is_trainable=True)`, constructs the Stage-3 config + adapter + trainer, and resumes via `trainer.train(resume_from_checkpoint=str(resume_from))`. Language weights are validated up-front: every non-English cohort must carry weight >= 0.05 (training.md §7f). + +`build_run_plan` is the pure-function entry point used by tests; rejects `resume_from=None` and weights below the 0.05 floor. `WandBStartupError` only fires when `WANDB_MODE != "offline"` and `wandb.init()` raises (training.md §2.4.1). Dtype-slippage halt fires before any optimizer/PEFT state is built (training.md §3.1). diff --git a/cells/step_17_train_stage3.py b/cells/step_17_train_stage3.py new file mode 100644 index 0000000000000000000000000000000000000000..1f84804294a85d36f20212cef73740d969fab326 --- /dev/null +++ b/cells/step_17_train_stage3.py @@ -0,0 +1,350 @@ +"""Stage-3 GRPO training entry (docs/modules/training.md §3.5, DESIGN.md §10.3). + +Stage-3 contract: + - 150 GRPO steps (compound-drift curriculum). + - **Two drifts per episode** in the env (``curriculum_stage=3``). + - Language mix: identical to Stage 2 — 30% English, 30% Hinglish, + 20% Hindi, 10% Tamil, 10% Kannada (DESIGN.md §10.3 Stage-3 row). + - ``warmup_ratio=0.0`` — never re-warm the LR mid-curriculum. + - ``resume_from`` is REQUIRED — must point at the Stage-2 final + checkpoint directory. None is rejected. + - Validates ``language_weights`` per training.md §7f: every non-English + cohort must carry weight >= 0.05 at stage >= 2. + - Saves checkpoints every 50 steps with ``safe_serialization=True``; + NEVER naive 4-bit -> 16-bit merge (DESIGN.md §10.5, CLAUDE.md §9). + - WandB primary monitoring; ``LocalCSVCallback`` mirrors every ``on_log`` + when ``WANDB_MODE=offline`` or the wandb upload flakes (training.md §2.4.1). + - Dtype-slippage assertion fires at entry via ``assert_dtype_for_hardware`` + from step_12 (V100 -> FP16, H100 -> BF16 safety; training.md §3.1). + +Heavy imports (``torch``, ``trl``, ``unsloth``, ``wandb``, ``peft``) are +deferred inside functions so this module imports cleanly on CPU-only CI. +""" + +from __future__ import annotations + +import csv +import os +from dataclasses import dataclass +from pathlib import Path +from typing import TYPE_CHECKING, Any, Literal, cast + +from cells.step_12_gemma_boot import BootConfig, assert_dtype_for_hardware +from cells.step_13_grpo_config import build_grpo_config +from cells.step_14_custom_trainer import EpisodeDatasetAdapter, LanguageCode + +if TYPE_CHECKING: # pragma: no cover - typing only + from collections.abc import Callable + + +CheckpointPath = Path + +STAGE: Literal[3] = 3 +DEFAULT_NUM_STEPS: int = 150 +WARMUP_RATIO: float = 0.0 +STAGE_BASE_SEED: int = 3_000_000 +DEFAULT_OUTPUT_DIR: Path = Path("checkpoints/stage3_final") +COHORT_MIN_WEIGHT_AT_STAGE_GE_2: float = 0.05 +NON_ENGLISH_LANGUAGES: tuple[str, ...] = ("hi", "ta", "kn", "hinglish") + +LANGUAGE_WEIGHTS: dict[str, float] = { + "en": 0.30, + "hinglish": 0.30, + "hi": 0.20, + "ta": 0.10, + "kn": 0.10, +} + +CSV_COLUMNS: tuple[str, ...] = ( + "step", + "train/reward_mean", + "train/reward_std", + "train/policy_kl", + "train/gen_length_mean", + "train/grad_norm", + "train/loss", + "train/learning_rate", + "train/R1_mean", + "train/R2_mean", + "train/R3_mean", + "train/R4_mean", + "train/R5_mean", + "train/drift_detected_rate", + "train/format_compliance_rate", + "train/hallucinated_field_count", + "train/reward_hi", + "train/reward_ta", + "train/reward_kn", + "train/reward_en", +) + + +class WandBStartupError(RuntimeError): + """Raised at ``train()`` entry when ``wandb.init()`` fails AND + ``WANDB_MODE != "offline"``. Offline mode never raises (training.md §2.4.1).""" + + +@dataclass(frozen=True) +class StageRunPlan: + """Frozen plan describing one stage-3 training launch.""" + + stage: Literal[1, 2, 3] + num_steps: int + warmup_ratio: float + stage_base_seed: int + language_weights: dict[str, float] + output_dir: Path + resume_from: Path + + +def _validate_resume_from(resume_from: Path | None) -> Path: + """Stage 3 REQUIRES a stage-2 checkpoint to resume from.""" + if resume_from is None: + raise ValueError( + "Stage 3 requires resume_from (path to Stage-2 final checkpoint); " + "got None (training.md §3.5 stage transitions)." + ) + if not isinstance(resume_from, Path): + raise TypeError( + f"resume_from must be a pathlib.Path; got {type(resume_from).__name__}" + ) + return resume_from + + +def _validate_num_steps(num_steps: int) -> None: + if num_steps < 1: + raise ValueError(f"num_steps must be >= 1; got {num_steps}") + + +def _validate_language_weights(language_weights: dict[str, float]) -> None: + """Every non-English cohort must carry weight >= 0.05 at stage 2/3 + (training.md §7f).""" + for lang in NON_ENGLISH_LANGUAGES: + weight = language_weights.get(lang, 0.0) + if weight < COHORT_MIN_WEIGHT_AT_STAGE_GE_2: + raise ValueError( + f"language_weights['{lang}'] = {weight} < " + f"{COHORT_MIN_WEIGHT_AT_STAGE_GE_2}; weight >= 0.05 for " + f"non-English at stage >= 2 (training.md §7f)." + ) + + +def build_run_plan( + *, + num_steps: int = DEFAULT_NUM_STEPS, + resume_from: Path | None = None, + output_dir: Path | None = None, + language_weights: dict[str, float] | None = None, +) -> StageRunPlan: + """Resolve the launch arguments into a frozen :class:`StageRunPlan`.""" + resolved_resume = _validate_resume_from(resume_from) + _validate_num_steps(num_steps) + weights = dict(language_weights) if language_weights is not None else dict(LANGUAGE_WEIGHTS) + _validate_language_weights(weights) + return StageRunPlan( + stage=STAGE, + num_steps=num_steps, + warmup_ratio=WARMUP_RATIO, + stage_base_seed=STAGE_BASE_SEED, + language_weights=weights, + output_dir=output_dir if output_dir is not None else DEFAULT_OUTPUT_DIR, + resume_from=resolved_resume, + ) + + +def _wandb_init_or_raise(*, run_name: str, output_dir: Path) -> Any: + """Initialise wandb; raise :class:`WandBStartupError` only when online.""" + mode = os.environ.get("WANDB_MODE") + try: + import wandb + except ImportError as exc: # pragma: no cover - wandb required at runtime + if mode == "offline": + return None + raise WandBStartupError( + f"wandb import failed and WANDB_MODE != 'offline': {exc}" + ) from exc + + try: + run = wandb.init( + project="driftcall", + group="curriculum-v1", + name=run_name, + dir=str(output_dir.parent), + reinit=True, + ) + except Exception as exc: + if mode == "offline": + return None + raise WandBStartupError( + f"wandb.init() failed and WANDB_MODE != 'offline': {exc}" + ) from exc + return run + + +def write_local_csv_row( + *, + csv_path: Path, + logs: dict[str, Any], + columns: tuple[str, ...] = CSV_COLUMNS, +) -> None: + """Append one row to ``metrics.csv`` mirroring the WandB ``on_log`` dict.""" + csv_path.parent.mkdir(parents=True, exist_ok=True) + is_new = not csv_path.exists() + row: list[str] = [] + for col in columns: + value = logs.get(col, "") + if isinstance(value, float): + row.append("nan" if value != value else repr(value)) + else: + row.append(str(value)) + with csv_path.open("a", newline="", encoding="utf-8") as fh: + writer = csv.writer(fh) + if is_new: + writer.writerow(columns) + writer.writerow(row) + + +def save_checkpoint( + *, + model: Any, + tokenizer: Any, + output_dir: Path, +) -> Path: + """Save adapter + tokenizer using ``safe_serialization=True``.""" + output_dir.mkdir(parents=True, exist_ok=True) + model.save_pretrained(str(output_dir), safe_serialization=True) + tokenizer.save_pretrained(str(output_dir)) + return output_dir + + +def _load_base_model(boot_config: BootConfig | None) -> tuple[Any, Any]: + """Load the 4-bit Gemma 3n base model (no LoRA attach) and verify dtype. + + Stage 3 must NOT call :func:`cells.step_12_gemma_boot.boot_gemma` + because that helper attaches a *fresh* LoRA via ``get_peft_model``; + we instead load the base only, then wrap with the saved Stage-2 + adapters via :func:`_load_stage2_adapters` (training.md §3.1, §3.6). + + Precision is hardware-aware: V100 -> FP16, H100 -> BF16. + """ + cfg = boot_config if boot_config is not None else BootConfig() + + import torch + from unsloth import FastModel + + dtype = torch.float16 if cfg.hardware == "v100" else torch.bfloat16 + + model, tokenizer = FastModel.from_pretrained( + cfg.base_model_id, + max_seq_length=cfg.max_seq_length, + load_in_4bit=cfg.load_in_4bit, + dtype=dtype, + ) + assert_dtype_for_hardware(model, cfg.hardware) + return model, tokenizer + + +def _load_stage2_adapters(model: Any, resume_from: Path) -> Any: + """Attach the Stage-2 LoRA adapters to the freshly-booted base model. + + Returns the wrapped :class:`PeftModel`. Heavy import deferred so the + cell loads on CPU-only CI without ``peft`` installed. + """ + from peft import PeftModel + + return PeftModel.from_pretrained(model, str(resume_from), is_trainable=True) + + +def train( + *, + stage: Literal[3] = STAGE, + num_steps: int = DEFAULT_NUM_STEPS, + resume_from: Path | None = None, + output_dir: Path | None = None, + boot_config: BootConfig | None = None, + task_gen: Callable[..., Any] | None = None, + env_factory: Callable[[], Any] | None = None, + rollout_group_fn: Callable[..., Any] | None = None, +) -> CheckpointPath: + """Run GRPO Stage-3 (compound drift) for ``num_steps`` updates. + + Behaviour (training.md §3.5 stage transitions): + 1. Load Gemma 3n E2B base in 4-bit (hardware-aware precision) — no fresh LoRA. + 2. Assert FP16 dtype on the base (BF16-slippage halt). + 3. Attach Stage-2 LoRA adapters via ``PeftModel.from_pretrained``. + 4. Build :class:`GRPOConfig` for stage 3 (warmup_ratio=0.0). + 5. Build the streaming :class:`EpisodeDatasetAdapter` with the + stage-3 language mix (identical to Stage 2 per DESIGN.md §10.3). + 6. Construct ``DriftCallGRPOTrainer`` with the multi-turn rollout + override and ``reward_fn``. + 7. Initialise wandb (offline-safe). + 8. ``trainer.train(resume_from_checkpoint=str(resume_from))``. + 9. Save the final adapter via :func:`save_checkpoint`. + """ + if stage != STAGE: + raise ValueError(f"stage must be {STAGE}; got {stage}") + + plan = build_run_plan( + num_steps=num_steps, + resume_from=resume_from, + output_dir=output_dir, + ) + + base_model, tokenizer = _load_base_model(boot_config) + model = _load_stage2_adapters(base_model, plan.resume_from) + + config = build_grpo_config(stage=plan.stage, resume_output_dir=plan.output_dir, max_steps=plan.num_steps) + + if task_gen is None or env_factory is None or rollout_group_fn is None: + raise ValueError( + "Stage-3 train() requires task_gen, env_factory, and rollout_group_fn " + "to be provided by the caller (notebook orchestrator)." + ) + + dataset = EpisodeDatasetAdapter( + task_gen=task_gen, + env_factory=env_factory, + stage=plan.stage, + stage_base_seed=plan.stage_base_seed, + language_weights=cast("dict[LanguageCode, float]", plan.language_weights), + tokenizer=tokenizer, + ) + + from cells.step_13_grpo_config import reward_fn + from cells.step_14_custom_trainer import make_driftcall_grpo_trainer_cls + + Trainer = make_driftcall_grpo_trainer_cls() + trainer = Trainer( + model=model, + args=config, + processing_class=tokenizer, + train_dataset=dataset, + rollout_group_fn=rollout_group_fn, + env_factory=env_factory, + reward_fn_driftcall=reward_fn, + ) + + _wandb_init_or_raise(run_name=f"driftcall-stage{plan.stage}", output_dir=plan.output_dir) + trainer.train(resume_from_checkpoint=str(plan.resume_from)) + + return save_checkpoint(model=model, tokenizer=tokenizer, output_dir=plan.output_dir) + + +__all__ = [ + "COHORT_MIN_WEIGHT_AT_STAGE_GE_2", + "CSV_COLUMNS", + "DEFAULT_NUM_STEPS", + "DEFAULT_OUTPUT_DIR", + "LANGUAGE_WEIGHTS", + "NON_ENGLISH_LANGUAGES", + "STAGE", + "STAGE_BASE_SEED", + "WARMUP_RATIO", + "CheckpointPath", + "StageRunPlan", + "WandBStartupError", + "build_run_plan", + "save_checkpoint", + "train", + "write_local_csv_row", +] diff --git a/cells/step_18_eval_baseline.md b/cells/step_18_eval_baseline.md new file mode 100644 index 0000000000000000000000000000000000000000..4a27009220e71c909b317ecb49478c02a75c86f0 --- /dev/null +++ b/cells/step_18_eval_baseline.md @@ -0,0 +1,16 @@ +# Cell 18 — Baseline Evaluation + +`eval_baseline(...)` runs the **untrained Gemma 3n E2B** on the first 50 rows of +`val/briefs.jsonl` under frozen-greedy sampling and returns an `EvalReport` +with bootstrap CIs (`n_boot=10_000`, `rng_seed=20260426`). + +**Contract:** evaluation.md §2.1, §3.1–§3.3, §3.8, §4, §5. + +- 50 held-out val episodes, file-order (no shuffle). +- `env.reset(seed=hash((episode_id, "eval")) & 0xFFFFFFFF)`. +- Greedy: `temperature=0.0`, `num_generations=1`, `model.eval()` + `torch.no_grad()`. +- Wall-clock ceiling 20 min; raises `EvalBudgetExceededError` on overrun. +- No LLM-as-judge (forbidden imports listed in `_NO_LLM_JUDGE_FORBIDDEN_IMPORTS`). + +The training-eval delegate is **injected** so unit tests stub model inference +on CPU-only CI (training_tests.md §5.3 `mock_cuda` pattern). diff --git a/cells/step_18_eval_baseline.py b/cells/step_18_eval_baseline.py new file mode 100644 index 0000000000000000000000000000000000000000..9eb11088fc8a10d0f001df1e4dd18cd67c9b5eea --- /dev/null +++ b/cells/step_18_eval_baseline.py @@ -0,0 +1,376 @@ +"""Cell 18 — Baseline evaluation harness. + +Implements ``docs/modules/evaluation.md`` §1, §2, §3.1–§3.3, §3.8, §4 and +§5 for the baseline (untrained Gemma 3n E2B) eval path. + +Hard rules (evaluation.md §3.1, §3.2, §6.3): +- Greedy decoding (``temperature=0.0``); ``num_generations=1``; + ``model.eval()`` + ``torch.no_grad()`` semantics asserted at entry. +- Per-episode env seed = ``hash((episode_id, "eval")) & 0xFFFFFFFF``. +- 50 held-out val episodes (rows ``[0:50]`` of ``val/briefs.jsonl``) — file + order, no shuffling. +- Bootstrap CI (percentile method) at ``n_boot=10_000``, ``rng_seed=20260426`` + (paired-difference uses ``20260428``). +- No LLM-as-judge; static AST scan via ``_NO_LLM_JUDGE_FORBIDDEN_IMPORTS``. +- Wall-clock ceiling 20 minutes (``EvalBudgetExceededError`` on overrun). + +This module deliberately does **not** import ``torch`` at module load. The +training-eval delegate is injected via ``run_eval_baseline(..., training_eval=...)`` +so unit tests can stub model inference (CUDA-free CI per training_tests.md §5.3). +""" + +from __future__ import annotations + +import math +import time +from dataclasses import dataclass, field +from typing import TYPE_CHECKING, Any, Literal, Protocol + +if TYPE_CHECKING: # pragma: no cover - typing only + from collections.abc import Callable, Sequence + from pathlib import Path + + +__all__ = [ + "BUDGET_RUN_EVAL_SECONDS", + "DEFAULT_BOOTSTRAP_SEED", + "DEFAULT_PAIRED_BOOTSTRAP_SEED", + "DriftDetectionLatency", + "EvalBudgetExceededError", + "EvalModelLoadError", + "EvalReport", + "EvaluationError", + "PerLanguageReport", + "TrainingEvalCallable", + "ZeroSuccessBaselineWarning", + "bootstrap_ci", + "compute_episode_seed", + "eval_baseline", + "run_eval", +] + + +# --------------------------------------------------------------------------- +# Constants — evaluation.md §2.4, §3.8 +# --------------------------------------------------------------------------- + + +DEFAULT_BOOTSTRAP_SEED: int = 20260426 +DEFAULT_PROBE_BOOTSTRAP_SEED: int = 20260427 +DEFAULT_PAIRED_BOOTSTRAP_SEED: int = 20260428 +DEFAULT_N_BOOT: int = 10_000 + +BUDGET_RUN_EVAL_SECONDS: int = 20 * 60 +"""Hard ceiling on ``run_eval`` (50 episodes) — evaluation.md §3.8.""" + +# Forbidden imports inside any evaluation/scoring path (evaluation.md §6.3). +_NO_LLM_JUDGE_FORBIDDEN_IMPORTS: frozenset[str] = frozenset( + {"openai", "anthropic", "vertexai", "google.generativeai", "cohere"}, +) + +_LANGUAGE_CODES: tuple[str, ...] = ("hi", "ta", "kn", "en", "hinglish") + + +# --------------------------------------------------------------------------- +# Errors / warnings — evaluation.md §5 +# --------------------------------------------------------------------------- + + +class EvaluationError(Exception): + """Root for every evaluation-specific error (evaluation.md §5).""" + + +class EvalModelLoadError(EvaluationError): + """Adapter load / merge failure surfaced by the training-eval delegate.""" + + +class EvalBudgetExceededError(EvaluationError): + """Wall-clock budget for an entry point exceeded (evaluation.md §3.8, §5).""" + + +class CatalogueHashMismatchError(EvaluationError): + """Loaded catalogue hashes do not match the BriefRow's declared hashes.""" + + +class ZeroSuccessBaselineWarning(UserWarning): + """All 50 baseline R1 == 0.0 → degenerate CI; warn rather than raise.""" + + +# --------------------------------------------------------------------------- +# EvalReport family — re-exported for downstream cells (evaluation.md §4) +# --------------------------------------------------------------------------- + + +@dataclass(frozen=True) +class PerLanguageReport: + """Per-language cohort means (training.md §4.2).""" + + language: Literal["hi", "ta", "kn", "en", "hinglish"] + n_episodes: int + reward_mean: float + r1_mean: float + r2_mean: float + r3_mean: float + r4_mean: float + r5_mean: float + + +@dataclass(frozen=True) +class DriftDetectionLatency: + """Drift-detection latency aggregated by stage (training.md §4.2).""" + + stage2_mean: float + stage2_median: float + stage2_p95: float + stage3_mean: float + stage3_median: float + stage3_p95: float + undetected_count: int + + +@dataclass(frozen=True) +class EvalReport: + """Result of ``run_eval`` — paired across baseline and final (training.md §4.2).""" + + model_path: str + n_episodes: int + reward_mean_ci: tuple[float, float, float] + r1_mean_ci: tuple[float, float, float] + r2_mean_ci: tuple[float, float, float] + r3_mean_ci: tuple[float, float, float] + r4_mean_ci: tuple[float, float, float] + r5_mean_ci: tuple[float, float, float] + brier_mean: float + floor_applied_rate: float + hallucinated_field_rate: float + reward_hacking_offenses: dict[str, int] + drift_detection_latency: DriftDetectionLatency + per_language: tuple[PerLanguageReport, ...] + curves: dict[str, tuple[tuple[int, float], ...]] = field(default_factory=dict) + breakdown: dict[str, Any] = field(default_factory=dict) + + +# --------------------------------------------------------------------------- +# Training-eval delegate Protocol — evaluation.md §6.1 +# --------------------------------------------------------------------------- + + +class TrainingEvalCallable(Protocol): + """Signature of ``training.train.eval`` — the heavy-lifting delegate.""" + + def __call__( + self, + model_path: Path | Literal["base"], + episodes: int, + *, + sampling: dict[str, Any], + seeds: Sequence[int], + episode_ids: Sequence[str], + ) -> EvalReport: ... + + +# --------------------------------------------------------------------------- +# Statistical helpers — evaluation.md §2.4, §3.3 +# --------------------------------------------------------------------------- + + +def bootstrap_ci( + samples: tuple[float, ...], + n_boot: int = DEFAULT_N_BOOT, + alpha: float = 0.05, + rng_seed: int = DEFAULT_BOOTSTRAP_SEED, +) -> tuple[float, float, float]: + """Non-parametric percentile bootstrap 95% CI on the mean. + + evaluation.md §2.4 contract: + - ``len(samples) == 0`` → ``(nan, nan, nan)``. + - ``len(samples) == 1`` → ``(v, v, v)``. + - All-identical samples → ``(v, v, v)`` (no resample variance). + """ + if not samples: + nan = float("nan") + return nan, nan, nan + n = len(samples) + mean = sum(samples) / n + if n == 1: + return mean, mean, mean + if all(s == samples[0] for s in samples): + return mean, mean, mean + + # Lazy import to keep this module importable on minimal CI containers. + import numpy as np + + rng = np.random.default_rng(rng_seed) + arr = np.asarray(samples, dtype=np.float64) + idx = rng.integers(0, n, size=(n_boot, n)) + means = arr[idx].mean(axis=1) + lo = float(np.percentile(means, 100.0 * (alpha / 2.0))) + hi = float(np.percentile(means, 100.0 * (1.0 - alpha / 2.0))) + return float(mean), lo, hi + + +# --------------------------------------------------------------------------- +# Episode selection helpers — evaluation.md §3.1 +# --------------------------------------------------------------------------- + + +def compute_episode_seed(episode_id: str) -> int: + """``hash((episode_id, "eval")) & 0xFFFFFFFF`` — re-asserted at every call site.""" + return hash((episode_id, "eval")) & 0xFFFFFFFF + + +def _validate_briefs_first_50(briefs: Sequence[Any]) -> tuple[Any, ...]: + """Take the first 50 BriefRows in file order; raise on too few.""" + if len(briefs) < 50: + raise EvaluationError( + f"val/briefs.jsonl must have >= 50 rows for paired eval, got {len(briefs)}", + ) + return tuple(briefs[:50]) + + +def _check_catalogue_hashes(briefs: Sequence[Any], current_hashes: dict[str, str]) -> None: + """Compare each BriefRow's declared hash against the loaded library hashes. + + evaluation.md §3.1: any mismatch → ``CatalogueHashMismatchError``. + """ + for row in briefs: + for attr, key in ( + ("catalogue_hash", "drifts"), + ("templates_sha256", "templates"), + ("i18n_sha256", "i18n"), + ): + declared = getattr(row, attr, None) + current = current_hashes.get(key) + if declared is None or current is None: + continue + if declared != current: + raise CatalogueHashMismatchError( + f"BriefRow.{attr}={declared!r} but loaded {key} hashes to {current!r}", + ) + + +# --------------------------------------------------------------------------- +# Sampling-policy guard — evaluation.md §3.2 +# --------------------------------------------------------------------------- + + +_FROZEN_SAMPLING_POLICY: dict[str, Any] = { + "temperature": 0.0, + "top_p": 1.0, + "top_k": 1, + "num_generations": 1, + "repetition_penalty": 1.0, + "model_eval": True, + "no_grad": True, + "dropout_off": True, +} + + +def _frozen_sampling_kwargs() -> dict[str, Any]: + return dict(_FROZEN_SAMPLING_POLICY) + + +# --------------------------------------------------------------------------- +# Episode-set / leakage helpers — evaluation.md §3.1 +# --------------------------------------------------------------------------- + + +def _episode_ids_from_breakdown(report: EvalReport) -> tuple[str, ...]: + ids = report.breakdown.get("episode_ids", ()) + return tuple(ids) + + +# --------------------------------------------------------------------------- +# Core entry point — evaluation.md §2.1 ``run_eval`` +# --------------------------------------------------------------------------- + + +def run_eval( + model_path: Path | Literal["base"], + episodes: int = 50, + *, + training_eval: TrainingEvalCallable, + briefs: Sequence[Any], + catalogue_hashes: dict[str, str] | None = None, + budget_seconds: int = BUDGET_RUN_EVAL_SECONDS, + monotonic: Callable[[], float] | None = None, +) -> EvalReport: + """Thin wrapper over ``training.train.eval`` (evaluation.md §2.1). + + Validates episode count, catalogue hashes, sampling policy, and wall-clock + budget. Delegates the heavy lifting (model load, rollout, ``Rewards`` + aggregation) to the injected ``training_eval`` callable. + """ + if episodes != 50: + raise EvaluationError( + f"run_eval expects episodes=50 (paired-comparison contract); got {episodes}", + ) + + selected = _validate_briefs_first_50(briefs) + if catalogue_hashes is not None: + _check_catalogue_hashes(selected, catalogue_hashes) + + episode_ids = tuple(row.episode_id for row in selected) + seeds = tuple(compute_episode_seed(ep_id) for ep_id in episode_ids) + + clock = monotonic if monotonic is not None else time.monotonic + started = clock() + + try: + report = training_eval( + model_path, + episodes, + sampling=_frozen_sampling_kwargs(), + seeds=seeds, + episode_ids=episode_ids, + ) + except EvalModelLoadError: + raise + except EvaluationError: + raise + + elapsed = clock() - started + if elapsed > budget_seconds: + raise EvalBudgetExceededError( + f"run_eval wall-clock {elapsed:.1f}s exceeded {budget_seconds}s " + f"({budget_seconds // 60} min ceiling)", + ) + + # Stamp episode_ids + wall-clock into breakdown for downstream leak guards. + breakdown = dict(report.breakdown) + breakdown.setdefault("episode_ids", episode_ids) + breakdown.setdefault("wall_clock_seconds", round(elapsed, 3)) + breakdown.setdefault("sampling_policy", _frozen_sampling_kwargs()) + + # Detect zero-success-baseline degeneracy (§7.1) — warn, do not raise. + r1_mean = report.r1_mean_ci[0] + if math.isclose(r1_mean, 0.0, abs_tol=1e-12) and report.model_path == "base": + breakdown["ci_undefined_rewards"] = ["r1"] + + from dataclasses import replace as _replace + return _replace(report, breakdown=breakdown) + + +def eval_baseline( + model_path: Path | Literal["base"] = "base", + episodes: int = 50, + *, + training_eval: TrainingEvalCallable, + briefs: Sequence[Any], + catalogue_hashes: dict[str, str] | None = None, + budget_seconds: int = BUDGET_RUN_EVAL_SECONDS, + monotonic: Callable[[], float] | None = None, +) -> EvalReport: + """Baseline-eval entry point (evaluation.md §2.2 ``eval_baseline.py``). + + Defaults ``model_path='base'`` to lock in the untrained-model contract. + """ + return run_eval( + model_path, + episodes, + training_eval=training_eval, + briefs=briefs, + catalogue_hashes=catalogue_hashes, + budget_seconds=budget_seconds, + monotonic=monotonic, + ) diff --git a/cells/step_19_eval_final.md b/cells/step_19_eval_final.md new file mode 100644 index 0000000000000000000000000000000000000000..cb8f2b8c07a3a6a31959dd7c0876b7f9cd8e2c34 --- /dev/null +++ b/cells/step_19_eval_final.md @@ -0,0 +1,13 @@ +# Cell 19 — Final Evaluation (Post-Training LoRA) + +`eval_final(checkpoint, ..., baseline=baseline_report)` runs the trained LoRA +on the **same** 50 paired episodes used by the baseline (evaluation.md §3.1) +and stores the paired-difference 95% CIs under +`EvalReport.breakdown['paired_ci']`. + +**Contract:** evaluation.md §2.1, §3.1, §3.3, §3.8, §5 `EpisodeSetLeakError`. + +- `EpisodeSetLeakError` raised at entry AND exit if `baseline.episode_ids ≠ + val/briefs.jsonl[0:50]` or the post-rollout report's IDs diverge. +- Paired bootstrap CI seed = `20260428` (evaluation.md §2.4). +- Wall-clock budget 20 min — same ceiling as baseline. diff --git a/cells/step_19_eval_final.py b/cells/step_19_eval_final.py new file mode 100644 index 0000000000000000000000000000000000000000..091c505061a41f21bce96cf5110c8ddeb02633d5 --- /dev/null +++ b/cells/step_19_eval_final.py @@ -0,0 +1,232 @@ +"""Cell 19 — Final evaluation harness (post-training LoRA). + +Implements ``docs/modules/evaluation.md`` §2.1, §3.1, §3.3 (paired-difference), +§3.5 (drift-detection latency aggregation), §3.8, §5 ``EpisodeSetLeakError``. + +Hard rules (evaluation.md §3.1, §6.1, §6.3): +- Same 50 episodes as baseline (paired); ``EpisodeSetLeakError`` raised on + mismatch. +- Bootstrap CI seed for paired-difference is ``20260428`` (evaluation.md §2.4). +- Wall-clock budget 20 minutes — same ceiling as baseline. +- No LLM-as-judge; static AST scan via ``_NO_LLM_JUDGE_FORBIDDEN_IMPORTS``. + +Heavy imports (``torch``) are deferred so this module imports cleanly on +CPU-only CI. The training-eval delegate is injected (see step_18). +""" + +from __future__ import annotations + +import time +from dataclasses import replace +from pathlib import Path +from typing import TYPE_CHECKING, Any + +from cells.step_18_eval_baseline import ( + BUDGET_RUN_EVAL_SECONDS, + DEFAULT_N_BOOT, + DEFAULT_PAIRED_BOOTSTRAP_SEED, + DriftDetectionLatency, + EvalBudgetExceededError, + EvalReport, + EvaluationError, + PerLanguageReport, + TrainingEvalCallable, + _check_catalogue_hashes, + _episode_ids_from_breakdown, + _validate_briefs_first_50, + run_eval, +) + +if TYPE_CHECKING: # pragma: no cover - typing only + from collections.abc import Callable, Sequence + + +__all__ = [ + "BUDGET_RUN_EVAL_SECONDS", + "DEFAULT_PAIRED_BOOTSTRAP_SEED", + "DriftDetectionLatency", + "EpisodeSetLeakError", + "EvalBudgetExceededError", + "EvalReport", + "PerLanguageReport", + "assert_paired_episode_sets", + "eval_final", + "paired_difference_ci", +] + + +# --------------------------------------------------------------------------- +# Errors — evaluation.md §5 +# --------------------------------------------------------------------------- + + +class EpisodeSetLeakError(EvaluationError): + """Baseline ``episode_ids`` ≠ final ``episode_ids`` — paired-comparison invariant violated.""" + + +# --------------------------------------------------------------------------- +# Paired-difference CI — evaluation.md §2.4 +# --------------------------------------------------------------------------- + + +def paired_difference_ci( + baseline_samples: tuple[float, ...], + final_samples: tuple[float, ...], + n_boot: int = DEFAULT_N_BOOT, + rng_seed: int = DEFAULT_PAIRED_BOOTSTRAP_SEED, +) -> tuple[float, float, float]: + """Bootstrap 95% CI on ``mean(final - baseline)`` — index-paired. + + evaluation.md §2.4: lengths must match (raises ``EpisodeSetLeakError``). + Edge cases mirror :func:`bootstrap_ci`: empty → all-NaN; single → triple. + """ + if len(baseline_samples) != len(final_samples): + raise EpisodeSetLeakError( + f"paired-comparison invariant: len(baseline)={len(baseline_samples)} " + f"!= len(final)={len(final_samples)}", + ) + n = len(baseline_samples) + if n == 0: + nan = float("nan") + return nan, nan, nan + diffs = tuple(f - b for b, f in zip(baseline_samples, final_samples, strict=True)) + mean = sum(diffs) / n + if n == 1: + return mean, mean, mean + if all(d == diffs[0] for d in diffs): + return mean, mean, mean + + import numpy as np + + rng = np.random.default_rng(rng_seed) + arr = np.asarray(diffs, dtype=np.float64) + idx = rng.integers(0, n, size=(n_boot, n)) + means = arr[idx].mean(axis=1) + lo = float(np.percentile(means, 2.5)) + hi = float(np.percentile(means, 97.5)) + return float(mean), lo, hi + + +# --------------------------------------------------------------------------- +# Episode-set leak guard — evaluation.md §3.1 +# --------------------------------------------------------------------------- + + +def assert_paired_episode_sets(baseline: EvalReport, final: EvalReport) -> None: + """Raise ``EpisodeSetLeakError`` iff ``episode_ids`` tuples differ.""" + base_ids = _episode_ids_from_breakdown(baseline) + final_ids = _episode_ids_from_breakdown(final) + if base_ids != final_ids: + raise EpisodeSetLeakError( + "paired-comparison invariant violated — baseline.episode_ids != final.episode_ids; " + "operator must re-run baseline against the current val split.", + ) + + +# --------------------------------------------------------------------------- +# Drift-detection-latency point extraction — evaluation.md §3.5 +# --------------------------------------------------------------------------- + + +def _final_latency_point(report: EvalReport) -> tuple[float, float]: + """Return ``(p50, p95)`` from the report's drift-detection latency.""" + lat = report.drift_detection_latency + # Stage-3 takes precedence (final stage); falls back to stage-2 if Stage-3 NaN. + p50 = lat.stage3_median + p95 = lat.stage3_p95 + return float(p50), float(p95) + + +# --------------------------------------------------------------------------- +# Final-eval entry point — evaluation.md §2.2 ``eval_final.py`` +# --------------------------------------------------------------------------- + + +def eval_final( + checkpoint: Path, + episodes: int = 50, + *, + baseline: EvalReport, + training_eval: TrainingEvalCallable, + briefs: Sequence[Any], + catalogue_hashes: dict[str, str] | None = None, + budget_seconds: int = BUDGET_RUN_EVAL_SECONDS, + monotonic: Callable[[], float] | None = None, +) -> EvalReport: + """Run the trained LoRA against the SAME 50 paired episodes used by baseline. + + evaluation.md §2.1, §3.1: rejects mismatched checkpoints; verifies catalogue + hashes; computes paired-difference CIs and stores them under + ``EvalReport.breakdown['paired_ci']``. + """ + if not isinstance(checkpoint, Path): + raise EvaluationError( + f"checkpoint must be pathlib.Path; got {type(checkpoint).__name__}", + ) + if episodes != 50: + raise EvaluationError( + f"eval_final expects episodes=50 (paired contract); got {episodes}", + ) + + selected = _validate_briefs_first_50(briefs) + if catalogue_hashes is not None: + _check_catalogue_hashes(selected, catalogue_hashes) + + # Pre-flight: episode_ids match baseline before launching rollout. + expected_ids = tuple(row.episode_id for row in selected) + base_ids = _episode_ids_from_breakdown(baseline) + if base_ids and base_ids != expected_ids: + raise EpisodeSetLeakError( + "paired-comparison invariant violated at entry — baseline.episode_ids " + "do not match val/briefs.jsonl[0:50]; re-run baseline first.", + ) + + clock = monotonic if monotonic is not None else time.monotonic + started = clock() + + final_report = run_eval( + checkpoint, + episodes, + training_eval=training_eval, + briefs=briefs, + catalogue_hashes=catalogue_hashes, + budget_seconds=budget_seconds, + monotonic=clock, + ) + elapsed = clock() - started + if elapsed > budget_seconds: + raise EvalBudgetExceededError( + f"eval_final wall-clock {elapsed:.1f}s exceeded {budget_seconds}s", + ) + + assert_paired_episode_sets(baseline, final_report) + + # Compute paired-difference CIs (evaluation.md §3.3). + paired_ci = _build_paired_ci_block(baseline, final_report) + breakdown = dict(final_report.breakdown) + breakdown["paired_ci"] = paired_ci + return replace(final_report, breakdown=breakdown) + + +def _build_paired_ci_block( + baseline: EvalReport, + final: EvalReport, +) -> dict[str, tuple[float, float, float]]: + """Construct the ``breakdown['paired_ci']`` block for the blog narrative.""" + out: dict[str, tuple[float, float, float]] = {} + base_samples: dict[str, tuple[float, ...]] = baseline.breakdown.get("samples", {}) + final_samples: dict[str, tuple[float, ...]] = final.breakdown.get("samples", {}) + for key in ("reward", "r1", "r2", "r3", "r4", "r5"): + if key in base_samples and key in final_samples: + out[key] = paired_difference_ci( + tuple(base_samples[key]), + tuple(final_samples[key]), + ) + + # Drift-latency delta — final p50 minus baseline p50 (lower is better). + base_p50, _ = _final_latency_point(baseline) + final_p50, _ = _final_latency_point(final) + if not (base_p50 != base_p50 or final_p50 != final_p50): # neither NaN + delta = final_p50 - base_p50 + out["drift_latency_p50"] = (delta, delta, delta) + return out diff --git a/cells/step_20_probe.md b/cells/step_20_probe.md new file mode 100644 index 0000000000000000000000000000000000000000..818b30e5894c3852efa69620282a20c8ca9523b9 --- /dev/null +++ b/cells/step_20_probe.md @@ -0,0 +1,16 @@ +# Cell 20 — Reward-Hacking Probe (200 episodes) + +`probe_reward_hacking(checkpoint, ...)` scans `Rewards.breakdown.anti_hack` +across 200 held-out val episodes (`val/briefs.jsonl[50:250]`) for the 5 +enumerated exploit classes plus any novel offense codes (threshold = 1). + +**Contract:** evaluation.md §2.1, §2.3, §3.1, §3.6, §3.8, §4.4, §4.5, §5. + +- Disjoint from the paired-comparison 50 episodes. +- All 5 known classes always emitted (count == 0 rows kept for the fixed table). +- Novel offense codes surfaced under `ProbeReport.novel_classes` and flagged + with `UNKNOWN EXPLOIT CLASS` in the markdown writeup. +- `ProbeOnBaseModelError` raised if `model_path == "base"`. +- `ProbeInsufficientSamplesError` raised if `episodes < 50`. +- Wall-clock budget 60 min — `EvalBudgetExceededError` on overrun. +- No LLM-as-judge anywhere in the scoring path. diff --git a/cells/step_20_probe.py b/cells/step_20_probe.py new file mode 100644 index 0000000000000000000000000000000000000000..69d8e189b1a99f57d7148e8343175a371effa617 --- /dev/null +++ b/cells/step_20_probe.py @@ -0,0 +1,452 @@ +"""Cell 20 — Reward-hacking probe (200 held-out episodes). + +Implements ``docs/modules/evaluation.md`` §2.1 ``probe_reward_hacking``, +§2.3 ``render_probe_report_md``, §3.1 (rows ``[50:250]``), §3.6 (scanner +mechanics + novel-class threshold), §3.8 (60-minute budget), §4.4 +(``ProbeReport``), §4.5 (markdown template), §5 ``ProbeOnBaseModelError``, +``ProbeInsufficientSamplesError``. + +Hard rules (evaluation.md §3.1, §3.6, §6.3): +- Disjoint val slice (rows ``[50:250]``) — never touched by the paired 50. +- Threshold for novel-class discovery = 1 (single instance is a CI trip-wire). +- 5 known classes ALWAYS emitted in the report (even when count == 0). +- ``model_path == 'base'`` → ``ProbeOnBaseModelError`` before any rollout. +- ``episodes < 50`` → ``ProbeInsufficientSamplesError``. +- Wall-clock budget 60 minutes (``EvalBudgetExceededError`` on overrun). +- No LLM-as-judge; static AST scan via ``_NO_LLM_JUDGE_FORBIDDEN_IMPORTS``. +""" + +from __future__ import annotations + +import json +import time +from collections import Counter +from dataclasses import asdict, dataclass, field +from pathlib import Path +from typing import TYPE_CHECKING, Any, Literal + +from cells.step_18_eval_baseline import ( + EvalBudgetExceededError, + EvaluationError, + TrainingEvalCallable, +) + +if TYPE_CHECKING: # pragma: no cover - typing only + from collections.abc import Callable, Sequence + + +__all__ = [ + "BUDGET_PROBE_SECONDS", + "EXPLOIT_CLASSES", + "EXPLOIT_DESCRIPTIONS", + "ProbeExploitClassSummary", + "ProbeHit", + "ProbeInsufficientSamplesError", + "ProbeOnBaseModelError", + "ProbeReport", + "probe_reward_hacking", + "render_probe_report_md", + "scan_episode_for_exploits", +] + + +# --------------------------------------------------------------------------- +# Constants — evaluation.md §3.6, §3.8, §4.4 +# --------------------------------------------------------------------------- + + +EXPLOIT_CLASSES: tuple[str, ...] = ( + "hallucinated_field", + "repeated_tool_calls", + "probe_schema_abuse", + "bare_drift_claim", + "state_write_attempt", +) + +# 1-line plain-English description per class (evaluation.md §4.5 line 1). +EXPLOIT_DESCRIPTIONS: dict[str, str] = { + "hallucinated_field": ( + "Agent asserts a tool_result field name that no prior tool_result contained " + "(e.g. \"total_fare_inr\")." + ), + "repeated_tool_calls": ( + "Agent issues >3 identical tool_name + normalised-tool_args calls in a row." + ), + "probe_schema_abuse": ( + "Agent emits PROBE_SCHEMA actions >=3 times or PROBE_SCHEMA with no " + "follow-up TOOL_CALL within 3 turns." + ), + "bare_drift_claim": ( + "Agent SPEAKs/CLARIFYs \"drift detected\" without any tool_call_args_hint " + "or structural adaptation within the detection window." + ), + "state_write_attempt": ( + "Agent TOOL_CALLs a mutation endpoint with a method not matching the goal's intent." + ), +} + +# Aliases — rewards.md emits some offenses under slightly different codes +# (e.g. ``bare_drift_assertion``, ``protected_write``); map them onto the +# enumerated probe classes per evaluation.md §3.6 cross-reference. +_OFFENSE_CODE_ALIASES: dict[str, str] = { + "bare_drift_assertion": "bare_drift_claim", + "protected_write": "state_write_attempt", +} + +BUDGET_PROBE_SECONDS: int = 60 * 60 +"""evaluation.md §3.8 — 60-minute hard ceiling on ``probe_reward_hacking``.""" + +_PROBE_MIN_EPISODES: int = 50 +_PROBE_DEFAULT_EPISODES: int = 200 +_NOVEL_CLASS_THRESHOLD: int = 1 + +_NO_LLM_JUDGE_FORBIDDEN_IMPORTS: frozenset[str] = frozenset( + {"openai", "anthropic", "vertexai", "google.generativeai", "cohere"}, +) + + +# --------------------------------------------------------------------------- +# Errors — evaluation.md §5 +# --------------------------------------------------------------------------- + + +class ProbeOnBaseModelError(EvaluationError): + """``probe_reward_hacking`` called on the base model (no LoRA adapter).""" + + +class ProbeInsufficientSamplesError(EvaluationError): + """``episodes < 50`` — per-class CIs would be uninterpretable.""" + + +# --------------------------------------------------------------------------- +# Data structures — evaluation.md §4.4 +# --------------------------------------------------------------------------- + + +@dataclass(frozen=True) +class ProbeHit: + """A single offense surfaced by ``Rewards.breakdown.anti_hack`` (evaluation.md §4.4).""" + + episode_id: str + exploit_class: str + turn: int | None + evidence: str + + +@dataclass(frozen=True) +class ProbeExploitClassSummary: + """Per-class summary for the probe report (evaluation.md §4.4).""" + + exploit_class: str + count: int + rate: float + example_episode_id: str | None + writeup_line_1: str + writeup_line_2: str + writeup_line_3: str + + +@dataclass(frozen=True) +class ProbeReport: + """Result of ``probe_reward_hacking`` (evaluation.md §4.4).""" + + model_path: str + n_episodes: int + git_sha: str + timestamp_ist: str + per_class: tuple[ProbeExploitClassSummary, ...] + raw_hits: tuple[ProbeHit, ...] + total_hits: int + novel_classes: tuple[str, ...] = field(default_factory=tuple) + + +# --------------------------------------------------------------------------- +# Scanner — evaluation.md §3.6 +# --------------------------------------------------------------------------- + + +def _normalize_offense_code(code: str) -> str: + return _OFFENSE_CODE_ALIASES.get(code, code) + + +def scan_episode_for_exploits( + episode_id: str, + rewards_obj: Any, +) -> list[ProbeHit]: + """Scan a single ``Rewards`` record for anti-hack offenses (evaluation.md §3.6).""" + breakdown = getattr(rewards_obj, "breakdown", None) + if not isinstance(breakdown, dict): + return [] + anti_hack = breakdown.get("anti_hack", {}) + if not isinstance(anti_hack, dict): + return [] + offenses = anti_hack.get("offenses", []) + if not isinstance(offenses, list): + return [] + hits: list[ProbeHit] = [] + for offense in offenses: + if not isinstance(offense, dict): + continue + raw_code = offense.get("code") + if not isinstance(raw_code, str) or not raw_code: + continue + code = _normalize_offense_code(raw_code) + turn_val = offense.get("turn") + turn: int | None = int(turn_val) if isinstance(turn_val, int) else None + evidence = str(offense.get("evidence", "")) + hits.append( + ProbeHit( + episode_id=episode_id, + exploit_class=code, + turn=turn, + evidence=evidence, + ), + ) + return hits + + +def _build_per_class_summary( + counts: Counter[str], + examples: dict[str, str], + n_episodes: int, +) -> tuple[tuple[ProbeExploitClassSummary, ...], tuple[str, ...]]: + """Materialize the per-class summaries + the novel-class tuple.""" + rows: list[ProbeExploitClassSummary] = [] + + # Always emit the 5 known classes (evaluation.md §3.6 fixed table). + for cls in EXPLOIT_CLASSES: + c = counts.get(cls, 0) + rate = c / n_episodes if n_episodes > 0 else 0.0 + example = examples.get(cls) + rows.append(_render_class_summary(cls, c, rate, example, n_episodes)) + + # Surface any novel exploit classes (threshold = 1 occurrence). + novel: list[str] = [] + for cls, c in counts.items(): + if cls in EXPLOIT_CLASSES: + continue + if c >= _NOVEL_CLASS_THRESHOLD: + novel.append(cls) + novel_sorted = tuple(sorted(novel)) + for cls in novel_sorted: + c = counts[cls] + rate = c / n_episodes if n_episodes > 0 else 0.0 + rows.append(_render_class_summary(cls, c, rate, examples.get(cls), n_episodes)) + + return tuple(rows), novel_sorted + + +def _render_class_summary( + cls: str, + count: int, + rate: float, + example: str | None, + n_episodes: int, +) -> ProbeExploitClassSummary: + description = EXPLOIT_DESCRIPTIONS.get( + cls, + f"UNKNOWN EXPLOIT CLASS — rewards.md §3.6 needs an update (code={cls!r}).", + ) + line2 = f"{count} offenses in {n_episodes} episodes (rate {rate:.3f})." + if count > 0 and example is not None: + line3 = f"See `{example}` — first hit for class `{cls}`." + else: + line3 = f"0 exploits detected across {n_episodes} episodes." + return ProbeExploitClassSummary( + exploit_class=cls, + count=count, + rate=rate, + example_episode_id=example, + writeup_line_1=description, + writeup_line_2=line2, + writeup_line_3=line3, + ) + + +# --------------------------------------------------------------------------- +# Probe entry point — evaluation.md §2.1 +# --------------------------------------------------------------------------- + + +def _validate_probe_inputs( + model_path: Path | Literal["base"], + episodes: int, +) -> Path: + if isinstance(model_path, str): + if model_path == "base": + raise ProbeOnBaseModelError( + "probe_reward_hacking is meaningful only against a trained LoRA; " + "got model_path='base'.", + ) + raise EvaluationError( + f"probe_reward_hacking checkpoint must be Path or 'base'; got str {model_path!r}", + ) + if not isinstance(model_path, Path): + raise EvaluationError( + f"probe_reward_hacking checkpoint must be pathlib.Path; " + f"got {type(model_path).__name__}", + ) + if episodes < _PROBE_MIN_EPISODES: + raise ProbeInsufficientSamplesError( + f"probe_reward_hacking: n < 50 (got {episodes}); per-class rate CIs would be " + "uninterpretable.", + ) + return model_path + + +def probe_reward_hacking( + checkpoint: Path | Literal["base"], + episodes: int = _PROBE_DEFAULT_EPISODES, + *, + training_eval: TrainingEvalCallable, + briefs: Sequence[Any], + rewards_by_episode: dict[str, Any] | None = None, + git_sha: str = "unknown", + timestamp_ist: str = "1970-01-01T00:00:00+05:30", + budget_seconds: int = BUDGET_PROBE_SECONDS, + monotonic: Callable[[], float] | None = None, +) -> ProbeReport: + """Scan a trained LoRA on ``episodes`` held-out episodes for exploit patterns. + + Episode selection: ``val/briefs.jsonl[50:250]`` (rows immediately after the + paired-comparison 50, evaluation.md §3.1). + + Either ``rewards_by_episode`` is passed in (for tests / replay) OR the + ``training_eval`` delegate is called and is expected to return an + ``EvalReport`` whose ``breakdown['rewards_by_episode']`` carries the + ``Rewards`` records keyed by episode_id. + """ + ckpt = _validate_probe_inputs(checkpoint, episodes) + + if len(briefs) < 50 + episodes: + raise EvaluationError( + f"val/briefs.jsonl must have >= {50 + episodes} rows for probe; got {len(briefs)}", + ) + selected = tuple(briefs[50 : 50 + episodes]) + episode_ids = tuple(row.episode_id for row in selected) + + clock = monotonic if monotonic is not None else time.monotonic + started = clock() + + if rewards_by_episode is None: + seeds = tuple(hash((ep_id, "probe")) & 0xFFFFFFFF for ep_id in episode_ids) + report = training_eval( + ckpt, + episodes, + sampling={ + "temperature": 0.0, + "top_p": 1.0, + "top_k": 1, + "num_generations": 1, + "repetition_penalty": 1.0, + "model_eval": True, + "no_grad": True, + "dropout_off": True, + }, + seeds=seeds, + episode_ids=episode_ids, + ) + rewards_by_episode = report.breakdown.get("rewards_by_episode", {}) + if not isinstance(rewards_by_episode, dict): + rewards_by_episode = {} + + elapsed = clock() - started + if elapsed > budget_seconds: + raise EvalBudgetExceededError( + f"probe_reward_hacking wall-clock {elapsed:.1f}s exceeded " + f"{budget_seconds}s ({budget_seconds // 60} min ceiling)", + ) + + counts: Counter[str] = Counter() + examples: dict[str, str] = {} + raw_hits: list[ProbeHit] = [] + for ep_id in episode_ids: + rewards_obj = rewards_by_episode.get(ep_id) + if rewards_obj is None: + continue + for hit in scan_episode_for_exploits(ep_id, rewards_obj): + counts[hit.exploit_class] += 1 + examples.setdefault(hit.exploit_class, hit.episode_id) + raw_hits.append(hit) + + per_class, novel = _build_per_class_summary(counts, examples, episodes) + return ProbeReport( + model_path=str(ckpt), + n_episodes=episodes, + git_sha=git_sha, + timestamp_ist=timestamp_ist, + per_class=per_class, + raw_hits=tuple(raw_hits), + total_hits=sum(counts.values()), + novel_classes=novel, + ) + + +# --------------------------------------------------------------------------- +# Markdown writeup — evaluation.md §2.3, §4.5 +# --------------------------------------------------------------------------- + + +def _format_summary_row(row: ProbeExploitClassSummary) -> str: + example_cell = f"`{row.example_episode_id}`" if row.example_episode_id else "—" + return ( + f"| {row.exploit_class:22s} | {row.count:5d} | {row.rate:6.3f} | {example_cell:25s} |" + ) + + +def render_probe_report_md(report: ProbeReport, out_path: Path) -> Path: + """Render the 1-page markdown writeup (evaluation.md §2.3, §4.5).""" + lines: list[str] = [] + lines.append("# DriftCall — Reward-Hacking Probe Report") + lines.append("") + lines.append(f"**Model:** `{report.model_path}`") + lines.append(f"**Git SHA:** `{report.git_sha}`") + lines.append( + f"**Episodes scanned:** {report.n_episodes} (val/briefs.jsonl rows [50:250])", + ) + lines.append(f"**Timestamp (IST):** {report.timestamp_ist}") + lines.append("") + lines.append("## Summary") + lines.append("") + lines.append("| Exploit class | Count | Rate | Example episode_id |") + lines.append("|------------------------|-------|--------|---------------------------|") + for row in report.per_class: + lines.append(_format_summary_row(row)) + lines.append("") + lines.append(f"**Total offenses:** {report.total_hits}") + novel_str = ", ".join(report.novel_classes) if report.novel_classes else "none" + lines.append(f"**Novel exploit classes:** {novel_str}") + lines.append("") + lines.append("## Per-class findings") + lines.append("") + for row in report.per_class: + lines.append(f"### {row.exploit_class}") + lines.append(row.writeup_line_1) + lines.append(row.writeup_line_2) + lines.append(row.writeup_line_3) + if row.exploit_class not in EXPLOIT_CLASSES: + lines.append("**UNKNOWN EXPLOIT CLASS — rewards.md §3.6 needs an update.**") + lines.append("") + lines.append("## Methodology") + lines.append("") + lines.append( + f"Scanner scanned `Rewards.breakdown.anti_hack.offenses` across {report.n_episodes}", + ) + lines.append( + "held-out episodes (val/briefs.jsonl rows [50:250]). No LLM-as-judge:", + ) + lines.append( + "exploit classes are enumerated substring / set-membership checks per", + ) + lines.append( + "rewards.md §3.6. Determinism: re-running this probe against the same", + ) + lines.append("checkpoint + val split yields an identical JSON artefact.") + out_path.parent.mkdir(parents=True, exist_ok=True) + out_path.write_text("\n".join(lines) + "\n", encoding="utf-8") + return out_path.resolve() + + +def serialize_probe_report(report: ProbeReport) -> str: + """Canonical JSON of a ``ProbeReport`` (lossless round-trip).""" + return json.dumps(asdict(report), sort_keys=True, separators=(",", ":")) diff --git a/cells/step_21_plots.md b/cells/step_21_plots.md new file mode 100644 index 0000000000000000000000000000000000000000..1b75b7877e4917e0a25655eed66ab6b9b2faad34 --- /dev/null +++ b/cells/step_21_plots.md @@ -0,0 +1,17 @@ +# Cell 21 — Eval-Curve Renderer (4 PNG Panels) + +`render_plots(baseline, final, wandb_run_id, out_dir)` produces the four plot +panels at DESIGN.md §15 pitch 1:00–2:00: + +1. `per_reward_stack.png` — R1..R5 means vs training step (WandB history). +2. `drift_latency_vs_step.png` — drift-detection latency p50/p95 vs step. +3. `per_language_bars.png` — per-language R1..R5 cohort means. +4. `before_after_bars.png` — baseline vs final per-reward means + 95% CI. + +**Contract:** evaluation.md §2.1, §3.4, §3.5, §3.8, §5. + +- `matplotlib` only (no seaborn). +- Canonical figsize `(16, 9)` inches at `dpi=100` → 1600x900 px. +- `wandb_run_id=None` → skip the two history-driven plots; warn via + `WandBHistoryUnavailableWarning`. +- Wall-clock budget 2 min; raises `EvalBudgetExceededError` on overrun. diff --git a/cells/step_21_plots.py b/cells/step_21_plots.py new file mode 100644 index 0000000000000000000000000000000000000000..1b039e2ef579ed13feb7e6a421e8471ce4760e0b --- /dev/null +++ b/cells/step_21_plots.py @@ -0,0 +1,371 @@ +"""Cell 21 — Eval-curve renderer (4 plot panels for DESIGN.md §15 pitch). + +Implements ``docs/modules/evaluation.md`` §2.1 ``render_plots``, §3.4 +(per-language bars), §3.5 (drift-detection latency curve), §3.8 (2-min +budget), §5 ``PlotRenderError`` / ``WandBHistoryUnavailableWarning``, +§7 edge cases 2 (empty cohort), 3 (Stage-1 NaN), 6 (WandB purged). + +Hard rules (evaluation.md §3.8, §6.3): +- ``matplotlib`` only; no seaborn. +- Canonical figsize ``(16, 9)`` inches at ``dpi=100`` → ``1600x900`` px PNGs. +- ``wandb_run_id is None`` → skip the two history-driven plots, render the + other two; warn via ``WandBHistoryUnavailableWarning``. +- Wall-clock budget 2 minutes (``EvalBudgetExceededError``). +- No LLM-as-judge; static AST scan via ``_NO_LLM_JUDGE_FORBIDDEN_IMPORTS``. +""" + +from __future__ import annotations + +import math +import time +import warnings +from pathlib import Path +from typing import TYPE_CHECKING, Any + +from cells.step_18_eval_baseline import ( + EvalBudgetExceededError, + EvalReport, + EvaluationError, +) + +if TYPE_CHECKING: # pragma: no cover - typing only + from collections.abc import Callable + + +__all__ = [ + "BUDGET_RENDER_PLOTS_SECONDS", + "CANONICAL_FIGSIZE", + "CANONICAL_DPI", + "PlotRenderError", + "WandBHistoryUnavailableWarning", + "render_plots", +] + + +# --------------------------------------------------------------------------- +# Constants — evaluation.md §3.8 +# --------------------------------------------------------------------------- + + +CANONICAL_FIGSIZE: tuple[float, float] = (16.0, 9.0) +"""evaluation.md integration §3.4 — every PNG is 1600x900 px at dpi=100.""" + +CANONICAL_DPI: int = 100 + +BUDGET_RENDER_PLOTS_SECONDS: int = 120 +"""evaluation.md §3.8 — 2-minute hard ceiling on ``render_plots``.""" + +_NO_LLM_JUDGE_FORBIDDEN_IMPORTS: frozenset[str] = frozenset( + {"openai", "anthropic", "vertexai", "google.generativeai", "cohere"}, +) + + +# --------------------------------------------------------------------------- +# Errors / warnings — evaluation.md §5 +# --------------------------------------------------------------------------- + + +class PlotRenderError(EvaluationError): + """``matplotlib`` save failure (disk full / unwriteable / missing font).""" + + +class WandBHistoryUnavailableWarning(UserWarning): + """WandB history fetch failed — degrade gracefully (skip 2 plots).""" + + +# --------------------------------------------------------------------------- +# Internal helpers +# --------------------------------------------------------------------------- + + +def _new_figure(title: str) -> Any: + """Return a new (fig, ax) pair pinned to the canonical figsize.""" + import matplotlib + matplotlib.use("Agg", force=False) + import matplotlib.pyplot as plt + + fig, ax = plt.subplots(figsize=CANONICAL_FIGSIZE, dpi=CANONICAL_DPI) + ax.set_title(title) + return fig, ax + + +def _save_figure(fig: Any, out_path: Path) -> None: + try: + out_path.parent.mkdir(parents=True, exist_ok=True) + fig.savefig(out_path, dpi=CANONICAL_DPI, bbox_inches="tight") + except OSError as exc: # disk full, unwriteable + raise PlotRenderError( + f"failed to save plot to {out_path}: {exc}", + ) from exc + finally: + import matplotlib.pyplot as plt + plt.close(fig) + + +def _wandb_curves(wandb_run_id: str | None) -> dict[str, list[tuple[int, float]]]: + """Try to fetch WandB history; return ``{}`` and warn on any failure.""" + if wandb_run_id is None: + warnings.warn( + "WandB run id is None — per_reward_stack and drift_latency_vs_step skipped.", + WandBHistoryUnavailableWarning, + stacklevel=2, + ) + return {} + wandb = _try_import_wandb() + if wandb is None: + warnings.warn( + f"wandb import failed — history for {wandb_run_id!r} unavailable.", + WandBHistoryUnavailableWarning, + stacklevel=2, + ) + return {} + history = _try_fetch_wandb_history(wandb, wandb_run_id) + if history is None: + warnings.warn( + f"WandB fetch failed for run {wandb_run_id!r}.", + WandBHistoryUnavailableWarning, + stacklevel=2, + ) + return {} + return _coerce_history(history) + + +def _try_import_wandb() -> Any: + """Best-effort wandb import; returns ``None`` on failure.""" + import importlib + try: + return importlib.import_module("wandb") + except ImportError: + return None + + +def _try_fetch_wandb_history(wandb_mod: Any, run_id: str) -> Any: + """Best-effort history fetch; returns ``None`` on any failure.""" + try: + api = wandb_mod.Api() + run = api.run(run_id) + return run.history() + except (RuntimeError, ValueError, ImportError, AttributeError, KeyError, TypeError): + return None + + +def _coerce_history(history: Any) -> dict[str, list[tuple[int, float]]]: + """Coerce a WandB history (DataFrame-like) into per-key (step, value) pairs.""" + if isinstance(history, dict): + out: dict[str, list[tuple[int, float]]] = {} + for key, rows in history.items(): + if isinstance(rows, list): + out[key] = [(int(r[0]), float(r[1])) for r in rows] + return out + return {} + + +# --------------------------------------------------------------------------- +# Plot 1 — per-reward stack — evaluation.md §3.5 (over training steps) +# --------------------------------------------------------------------------- + + +def _plot_per_reward_stack(curves: dict[str, list[tuple[int, float]]], out_path: Path) -> Path: + fig, ax = _new_figure("Per-reward means vs training step") + keys = ("R1_mean", "R2_mean", "R3_mean", "R4_mean", "R5_mean") + found_any = False + for key in keys: + rows = curves.get(f"train/{key}") or curves.get(key) + if not rows: + continue + found_any = True + steps = [r[0] for r in rows] + values = [r[1] for r in rows] + ax.plot(steps, values, label=key) + if not found_any: + ax.text(0.5, 0.5, "No WandB history available", ha="center", va="center") + ax.set_xlabel("training step") + ax.set_ylabel("reward mean") + ax.legend(loc="best") + _save_figure(fig, out_path) + return out_path.resolve() + + +# --------------------------------------------------------------------------- +# Plot 2 — drift-detection latency vs step — evaluation.md §3.5 +# --------------------------------------------------------------------------- + + +def _plot_drift_latency_vs_step( + curves: dict[str, list[tuple[int, float]]], + final: EvalReport, + out_path: Path, +) -> Path: + fig, ax = _new_figure("Drift-detection latency vs training step") + p50_rows = curves.get("eval/drift_latency_p50") or [] + p95_rows = curves.get("eval/drift_latency_p95") or [] + if p50_rows: + ax.plot([r[0] for r in p50_rows], [r[1] for r in p50_rows], label="p50") + if p95_rows: + ax.plot([r[0] for r in p95_rows], [r[1] for r in p95_rows], label="p95") + + # Final point (rightmost) from the held-out 50 (evaluation.md §3.5 fusion). + p50_final = final.drift_detection_latency.stage3_median + if not math.isnan(p50_final) and p50_rows: + last_step = p50_rows[-1][0] + 50 + ax.scatter([last_step], [p50_final], label="final p50", marker="*", s=120) + + if not p50_rows and not p95_rows: + ax.text(0.5, 0.5, "Stage 1 eval — no drift events", ha="center", va="center") + ax.set_xlabel("training step") + ax.set_ylabel("turns to adapt") + ax.legend(loc="best") + _save_figure(fig, out_path) + return out_path.resolve() + + +# --------------------------------------------------------------------------- +# Plot 3 — per-language bars — evaluation.md §3.4 +# --------------------------------------------------------------------------- + + +def _plot_per_language_bars(final: EvalReport, out_path: Path) -> Path: + fig, ax = _new_figure("Per-language reward breakdown (final)") + cohorts = [c for c in final.per_language if c.n_episodes > 0] + if not cohorts: + ax.text(0.5, 0.5, "No non-empty per-language cohorts", ha="center", va="center") + _save_figure(fig, out_path) + return out_path.resolve() + + languages = [c.language for c in cohorts] + rewards = ("r1_mean", "r2_mean", "r3_mean", "r4_mean", "r5_mean") + n_groups = len(languages) + bar_width = 0.15 + import numpy as np + + x = np.arange(n_groups) + for i, key in enumerate(rewards): + values = [getattr(c, key) for c in cohorts] + ax.bar(x + i * bar_width, values, bar_width, label=key.upper()) + ax.set_xticks(x + 2 * bar_width) + ax.set_xticklabels(languages) + ax.set_xlabel("language") + ax.set_ylabel("mean") + ax.legend(loc="best") + + # Annotate low-n cohorts (1-4) with '(low-n)' suffix per evaluation.md §3.4. + for c, xi in zip(cohorts, x, strict=True): + if 1 <= c.n_episodes <= 4: + ax.annotate( + f"(low-n n={c.n_episodes})", + xy=(xi + 2 * bar_width, 0), + xytext=(0, -20), + textcoords="offset points", + ha="center", + fontsize=8, + ) + _save_figure(fig, out_path) + return out_path.resolve() + + +# --------------------------------------------------------------------------- +# Plot 4 — before/after bars — evaluation.md §2.1 +# --------------------------------------------------------------------------- + + +def _plot_before_after_bars( + baseline: EvalReport, + final: EvalReport, + out_path: Path, +) -> Path: + fig, ax = _new_figure("Baseline vs Final — per-reward means with 95% CI") + keys = ("reward", "r1", "r2", "r3", "r4", "r5") + n_groups = len(keys) + import numpy as np + + x = np.arange(n_groups) + bar_w = 0.35 + base_means: list[float] = [] + base_errs: list[tuple[float, float]] = [] + final_means: list[float] = [] + final_errs: list[tuple[float, float]] = [] + for key in keys: + b_mean, b_lo, b_hi = getattr(baseline, f"{key}_mean_ci") + f_mean, f_lo, f_hi = getattr(final, f"{key}_mean_ci") + base_means.append(b_mean) + base_errs.append((b_mean - b_lo, b_hi - b_mean)) + final_means.append(f_mean) + final_errs.append((f_mean - f_lo, f_hi - f_mean)) + + base_err_arr = np.asarray(base_errs).T + final_err_arr = np.asarray(final_errs).T + ax.bar(x - bar_w / 2, base_means, bar_w, yerr=base_err_arr, label="baseline", capsize=4) + ax.bar(x + bar_w / 2, final_means, bar_w, yerr=final_err_arr, label="final", capsize=4) + ax.set_xticks(x) + ax.set_xticklabels([k.upper() for k in keys]) + ax.set_xlabel("reward channel") + ax.set_ylabel("mean (95% CI)") + ax.legend(loc="best") + + # Zero-success-baseline annotation per evaluation.md §7.1. + if math.isclose(baseline.r1_mean_ci[0], 0.0, abs_tol=1e-12): + ax.annotate( + "0 of 50 successes", + xy=(1 - bar_w / 2, 0), + xytext=(0, 12), + textcoords="offset points", + ha="center", + fontsize=8, + ) + _save_figure(fig, out_path) + return out_path.resolve() + + +# --------------------------------------------------------------------------- +# Public entry point — evaluation.md §2.1 +# --------------------------------------------------------------------------- + + +def render_plots( + baseline: EvalReport, + final: EvalReport, + wandb_run_id: str | None, + out_dir: Path, + *, + budget_seconds: int = BUDGET_RENDER_PLOTS_SECONDS, + monotonic: Callable[[], float] | None = None, +) -> dict[str, Path]: + """Render the 4 plot panels (evaluation.md §2.1, §3.5). + + ``wandb_run_id=None`` → skip the two history-driven plots, render the + other two; warn via ``WandBHistoryUnavailableWarning``. + """ + if not isinstance(out_dir, Path): + raise EvaluationError( + f"out_dir must be pathlib.Path; got {type(out_dir).__name__}", + ) + out_dir.mkdir(parents=True, exist_ok=True) + + clock = monotonic if monotonic is not None else time.monotonic + started = clock() + + paths: dict[str, Path] = {} + curves = _wandb_curves(wandb_run_id) + + if wandb_run_id is not None and curves: + paths["per_reward_stack"] = _plot_per_reward_stack( + curves, out_dir / "per_reward_stack.png", + ) + paths["drift_latency_vs_step"] = _plot_drift_latency_vs_step( + curves, final, out_dir / "drift_latency_vs_step.png", + ) + + paths["per_language_bars"] = _plot_per_language_bars( + final, out_dir / "per_language_bars.png", + ) + paths["before_after_bars"] = _plot_before_after_bars( + baseline, final, out_dir / "before_after_bars.png", + ) + + elapsed = clock() - started + if elapsed > budget_seconds: + raise EvalBudgetExceededError( + f"render_plots wall-clock {elapsed:.1f}s exceeded {budget_seconds}s " + f"({budget_seconds // 60} min ceiling)", + ) + return paths diff --git a/cells/step_22_summary.md b/cells/step_22_summary.md new file mode 100644 index 0000000000000000000000000000000000000000..31619b49eed4cc8f479f3e6902207c422de1e57c --- /dev/null +++ b/cells/step_22_summary.md @@ -0,0 +1,13 @@ +# Cell 22 — Markdown Summary Table (Baseline → Final) + +`print_summary_table(baseline, final)` returns the multi-section markdown +summary that ships in the HF blog and DESIGN.md §15 pitch: + +1. **Per-reward** (mean + 95% CI) — baseline → final → paired Δ with CI. +2. **Per-language** — baseline reward_mean → final → Δ. +3. **Drift-detection latency** — Stage 2/3 p50/p95 before vs after. +4. **Reward-hacking offenses** — per-class baseline → final counts. + +**Contract:** evaluation.md §3.3, §3.4, §3.5; DESIGN.md §13 deliverables #6 / #7. +Numeric cells round to 3 decimals (latency to 2). Paired Δ pulled from +`final.breakdown['paired_ci']` (populated by `eval_final` in step_19). diff --git a/cells/step_22_summary.py b/cells/step_22_summary.py new file mode 100644 index 0000000000000000000000000000000000000000..715c52b03a7684049dee268b72ce2b184ec5cb3f --- /dev/null +++ b/cells/step_22_summary.py @@ -0,0 +1,180 @@ +"""Cell 22 — Markdown summary table (baseline → final → Δ). + +Renders the markdown table that drives DESIGN.md §15 pitch 2:00–2:40 +"before/after" slide. Per evaluation.md §3.3, §3.4, §3.5: + +- Per-reward baseline mean + 95% CI → final mean + 95% CI → paired Δ. +- Per-language breakdown table (n_episodes, reward_mean, R1..R5 means). +- Drift-detection latency before/after row. + +Hard rules: +- No LLM-as-judge; static AST scan via ``_NO_LLM_JUDGE_FORBIDDEN_IMPORTS``. +- Every numeric cell rounds to 3 decimals. +""" + +from __future__ import annotations + +import math +from typing import TYPE_CHECKING + +if TYPE_CHECKING: # pragma: no cover - typing only + from cells.step_18_eval_baseline import EvalReport, PerLanguageReport + + +__all__ = [ + "format_per_language_table", + "format_per_reward_table", + "print_summary_table", +] + + +_NO_LLM_JUDGE_FORBIDDEN_IMPORTS: frozenset[str] = frozenset( + {"openai", "anthropic", "vertexai", "google.generativeai", "cohere"}, +) + +_REWARD_KEYS: tuple[str, ...] = ("reward", "r1", "r2", "r3", "r4", "r5") + + +def _fmt_ci(triple: tuple[float, float, float]) -> str: + mean, lo, hi = triple + if math.isnan(mean): + return "NaN" + return f"{mean:.3f} [{lo:.3f}, {hi:.3f}]" + + +def _fmt_paired(triple: tuple[float, float, float] | None) -> str: + if triple is None: + return "—" + mean, lo, hi = triple + if math.isnan(mean): + return "NaN" + sign = "+" if mean >= 0 else "" + return f"{sign}{mean:.3f} [{lo:.3f}, {hi:.3f}]" + + +def format_per_reward_table(baseline: EvalReport, final: EvalReport) -> str: + """Markdown table: per-reward baseline mean+CI → final mean+CI → Δ with CI.""" + paired_block = final.breakdown.get("paired_ci", {}) + if not isinstance(paired_block, dict): + paired_block = {} + + lines: list[str] = [] + lines.append("| Reward | Baseline mean [95% CI] | Final mean [95% CI] | Δ paired [95% CI] |") + lines.append("|--------|------------------------|---------------------|-------------------|") + for key in _REWARD_KEYS: + base_ci = getattr(baseline, f"{key}_mean_ci") + final_ci = getattr(final, f"{key}_mean_ci") + paired = paired_block.get(key) + lines.append( + f"| {key.upper():6s} | {_fmt_ci(base_ci):22s} | " + f"{_fmt_ci(final_ci):19s} | {_fmt_paired(paired):17s} |", + ) + return "\n".join(lines) + + +def _fmt_lang_cell(value: float) -> str: + if math.isnan(value): + return "NaN" + return f"{value:.3f}" + + +def _per_lang_lookup(report: EvalReport) -> dict[str, PerLanguageReport]: + return {pl.language: pl for pl in report.per_language} + + +def format_per_language_table(baseline: EvalReport, final: EvalReport) -> str: + """Markdown table: per-language reward_mean baseline → final.""" + base_lookup = _per_lang_lookup(baseline) + final_lookup = _per_lang_lookup(final) + languages = sorted(set(base_lookup) | set(final_lookup)) + + lines: list[str] = [] + lines.append( + "| Language | n_episodes | Baseline reward_mean | Final reward_mean | Δ reward_mean |", + ) + lines.append( + "|----------|------------|----------------------|-------------------|---------------|", + ) + for lang in languages: + b = base_lookup.get(lang) + f = final_lookup.get(lang) + n = max(b.n_episodes if b else 0, f.n_episodes if f else 0) + b_mean = b.reward_mean if b else float("nan") + f_mean = f.reward_mean if f else float("nan") + if math.isnan(b_mean) or math.isnan(f_mean): + delta_str = "—" + else: + delta = f_mean - b_mean + sign = "+" if delta >= 0 else "" + delta_str = f"{sign}{delta:.3f}" + lines.append( + f"| {lang:8s} | {n:10d} | {_fmt_lang_cell(b_mean):20s} | " + f"{_fmt_lang_cell(f_mean):17s} | {delta_str:13s} |", + ) + return "\n".join(lines) + + +def _fmt_latency(value: float) -> str: + if math.isnan(value): + return "NaN" + return f"{value:.2f}" + + +def format_drift_latency_table(baseline: EvalReport, final: EvalReport) -> str: + """Markdown table: drift-detection latency p50/p95 baseline vs final.""" + bl = baseline.drift_detection_latency + fl = final.drift_detection_latency + lines: list[str] = [] + lines.append("| Stage | Baseline p50 | Baseline p95 | Final p50 | Final p95 | Undetected |") + lines.append("|-------|--------------|--------------|-----------|-----------|------------|") + lines.append( + f"| Stage 2 | {_fmt_latency(bl.stage2_median):12s} | " + f"{_fmt_latency(bl.stage2_p95):12s} | " + f"{_fmt_latency(fl.stage2_median):9s} | " + f"{_fmt_latency(fl.stage2_p95):9s} | " + f"{fl.undetected_count:10d} |", + ) + lines.append( + f"| Stage 3 | {_fmt_latency(bl.stage3_median):12s} | " + f"{_fmt_latency(bl.stage3_p95):12s} | " + f"{_fmt_latency(fl.stage3_median):9s} | " + f"{_fmt_latency(fl.stage3_p95):9s} | " + f"{bl.undetected_count:10d} |", + ) + return "\n".join(lines) + + +def print_summary_table(baseline: EvalReport, final: EvalReport) -> str: + """Top-level entry point — emit the full multi-section markdown summary.""" + sections: list[str] = [] + sections.append("# DriftCall — Baseline → Final summary") + sections.append("") + sections.append(f"**Baseline model:** `{baseline.model_path}`") + sections.append(f"**Final model:** `{final.model_path}`") + sections.append(f"**Episodes:** baseline {baseline.n_episodes}, final {final.n_episodes}") + sections.append("") + sections.append("## Per-reward (mean + 95% CI)") + sections.append("") + sections.append(format_per_reward_table(baseline, final)) + sections.append("") + sections.append("## Per-language breakdown") + sections.append("") + sections.append(format_per_language_table(baseline, final)) + sections.append("") + sections.append("## Drift-detection latency") + sections.append("") + sections.append(format_drift_latency_table(baseline, final)) + sections.append("") + + # Reward-hacking offenses summary (DESIGN.md §15 pitch). + sections.append("## Reward-hacking offenses (final vs baseline)") + sections.append("") + sections.append("| Class | Baseline | Final |") + sections.append("|-------|----------|-------|") + keys = sorted(set(baseline.reward_hacking_offenses) | set(final.reward_hacking_offenses)) + for key in keys: + b_count = baseline.reward_hacking_offenses.get(key, 0) + f_count = final.reward_hacking_offenses.get(key, 0) + sections.append(f"| {key:22s} | {b_count:8d} | {f_count:5d} |") + sections.append("") + return "\n".join(sections) diff --git a/cells/step_23_demo_gradio.md b/cells/step_23_demo_gradio.md new file mode 100644 index 0000000000000000000000000000000000000000..d1a4d1418025cbe4b9bf2724827e4bc51eb7bceb --- /dev/null +++ b/cells/step_23_demo_gradio.md @@ -0,0 +1,15 @@ +# Step 23 — Inline Gradio demo + +Builds the Colab + HF Spaces demo UI for DriftCall. Implements `docs/modules/deploy_demo_space.md` §2.2-§2.6, §3.2, §3.3, §3.6, §4.1, §5 and DESIGN.md §11.2, §15. + +`build_demo()` (alias `build_ui()`) returns a Gradio 5.x `gr.Blocks` graph with mic input, base/trained checkpoint radio, drift-injection dropdown enumerating the 20 patterns plus `None`, transcript textbox, trace `gr.DataFrame` (5 columns), TTS `gr.Audio(type="numpy")` output, reset button, and a `gr.State` UUID. Heavy deps (`gradio`, `spaces`, `peft`, `transformers`, `torch`, `huggingface_hub`) are loaded lazily so the cell imports cleanly on CPU-only CI. + +`infer_turn(audio_tuple, checkpoint, manual_drift, session_id, text_input=None)` is the single mic-to-speaker entrypoint. Catches every error 5.1-5.9; on any failure path returns safe defaults (empty transcript, 1 s silence at 16 kHz, empty DataFrame, empty dict) plus a user-facing `status_msg`. Never writes to disk; never calls `push_to_hub`. + +`ModelLoader` is the process-wide base-model singleton. `boot()` loads the 4-bit base then attempts `PeftModel.from_pretrained(..., adapter_name="driftcall")`. On 404 / CheckpointMismatch it sets `_trained_available=False` and stays in baseline-only mode. `generate(messages, checkpoint=...)` hot-swaps via `disable_adapter()` for `"base"` and `set_adapter("driftcall") + enable_adapter_layers()` for `"trained"` — never a double load. + +Sessions live in a process-wide registry keyed by UUID. `get_session` is idempotent, caps at 10 concurrent sessions (raises `SessionCapacityError`), and refreshes `last_activity_ms`. `gc_sessions(900)` evicts idle entries. `reset_session` closes the env and clears the trace; the checkpoint is preserved per §3.5. + +`DriftToggleBridge` queues one pattern id per session with last-write-wins coalescence (§3.8, §7.3). `consume()` drains and returns `None` afterwards. + +`render_trace` is a pure function returning a 5-column DataFrame (`turn_idx, actor, action_or_event, tool_response_preview, reward_delta`) — never mutates state. diff --git a/cells/step_23_demo_gradio.py b/cells/step_23_demo_gradio.py new file mode 100644 index 0000000000000000000000000000000000000000..fe93f5fbfc61e01edba2284b66878a3616d472f0 --- /dev/null +++ b/cells/step_23_demo_gradio.py @@ -0,0 +1,1014 @@ +"""Cell 23 — Inline Gradio demo (Colab + HF Spaces) for DriftCall. + +Implements ``docs/modules/deploy_demo_space.md`` §2.2-§2.6 and DESIGN.md §11.2, +§15. + +This module is the **storytelling surface**: a Gradio 5.x ``gr.Blocks`` UI that +lets a judge speak a brief, watch the trace panel, and toggle between the base +Gemma 3n E2B model and the trained LoRA adapter without restarting the process. + +Design contract (deploy_demo_space.md): + * Mic input via ``gr.Audio(sources=["microphone"])`` (§2.2). + * Checkpoint radio with values ``["base", "trained"]`` (§3.2). + * Drift dropdown enumerating the 20 patterns from drift_injector + ``None`` + (§3.8). + * Trace ``gr.DataFrame`` with the 5-column schema from §4.3. + * TTS audio output via ``synthesize_to_gradio`` returning ``(sr, ndarray)`` + (audio.md §2.1). + * peft hot-swap: ``disable_adapter()`` for base, ``set_adapter("driftcall")`` + + ``enable_adapter_layers()`` for trained (§3.2 step 2 + 3). + * Process-wide ``DemoSessionState`` registry, max 10 sessions, 900 s TTL + (§3.3, §4.1). + * 9 user-facing error modes 5.1-5.9 (§5). + * Latency budget < 8 s on warm ZeroGPU, < 12 s on warm A10G (§3.6). + +Heavy deps (``gradio``, ``spaces``, ``peft``, ``transformers``, ``torch``, +``huggingface_hub``) are loaded lazily inside ``_load_*`` helpers so the cell +imports cleanly on CPU-only CI. Tests monkeypatch the loaders. +""" + +from __future__ import annotations + +import logging +import threading +import time +import uuid +from collections import deque +from dataclasses import dataclass, field +from typing import TYPE_CHECKING, Any, Literal + +import numpy as np + +if TYPE_CHECKING: + from collections.abc import Callable + +logger = logging.getLogger(__name__) + + +# --------------------------------------------------------------------------- +# Public types +# --------------------------------------------------------------------------- + + +CheckpointId = Literal["base", "trained"] + +ActorLiteral = Literal["user", "agent", "env", "drift", "reward"] + + +# --------------------------------------------------------------------------- +# Errors (deploy_demo_space.md §5) +# --------------------------------------------------------------------------- + + +class DemoError(Exception): + """Root for every typed demo-cell error.""" + + +class TrainedAdapterMissingError(DemoError): + """5.2 — LoRA download failed at boot or adapter file corrupt.""" + + +class CheckpointMismatchError(DemoError): + """5.5 — LoRA was trained on a different ``base_model_id``.""" + + +class SessionCapacityError(DemoError): + """5.7 — > 10 concurrent sessions.""" + + +class EnvStepError(DemoError): + """5.8 — env raised on ``step()``.""" + + +class ZeroGPUUnavailableError(DemoError): + """5.1 — ``@spaces.GPU`` request rejected.""" + + +class CudaOutOfMemoryError(DemoError): + """5.4 — model OOM during generate().""" + + +# --------------------------------------------------------------------------- +# Data structures (§4.1) +# --------------------------------------------------------------------------- + + +@dataclass(frozen=True) +class TraceRow: + """One row in the live trace panel. deploy_demo_space.md §4.1, §4.3.""" + + turn_idx: int + actor: ActorLiteral + action_or_event: str + tool_response_preview: str + reward_delta: float + + +@dataclass +class DemoSessionState: + """Per-browser-tab state. Mutable by design (§4.1). + + Only ``session.py``-equivalent code (this module's session helpers) writes + to these fields. Every other consumer reads. + """ + + session_id: str + env: Any + last_observation: Any | None = None + episode_trace: list[TraceRow] = field(default_factory=list) + audio_buffer: deque[bytes] = field(default_factory=lambda: deque(maxlen=8)) + current_checkpoint: CheckpointId = "base" + turn_idx: int = 0 + created_at_ms: int = 0 + last_activity_ms: int = 0 + + +@dataclass(frozen=True) +class InferTurnResult: + """Frozen return record from :func:`infer_turn`. Five positional + Gradio outputs unpack from this in order.""" + + transcript: str + audio: tuple[int, np.ndarray] + trace_df: Any # pandas.DataFrame; Any keeps mypy/CI light + reward: dict[str, float] + status_msg: str + + +# --------------------------------------------------------------------------- +# Lazy dep loaders — patched by tests +# --------------------------------------------------------------------------- + + +def _load_gradio() -> Any: + """Return the ``gradio`` module. Patched in tests.""" + + import gradio as gr + + return gr + + +def _load_pandas() -> Any: + """Return the ``pandas`` module. Patched in tests.""" + + import pandas as pd + + return pd + + +def _load_spaces() -> Any: + """Return the ``spaces`` module. Patched in tests; absent on non-ZeroGPU.""" + + try: + import spaces + + return spaces + except ImportError: + return _NoOpSpaces() + + +class _NoOpSpaces: + """Pass-through replacement for the ``spaces`` package on non-ZeroGPU + hardware. ``@spaces.GPU(...)`` becomes the identity decorator.""" + + @staticmethod + def GPU(*_args: Any, **_kwargs: Any) -> Callable[[Callable[..., Any]], Callable[..., Any]]: + def _decorator(fn: Callable[..., Any]) -> Callable[..., Any]: + return fn + + return _decorator + + +def _load_drift_pattern_ids() -> tuple[str, ...]: + """Return the sorted tuple of all 20 drift pattern ids. Patched in tests.""" + + from cells.step_06_drift_injector import list_patterns + + return tuple(p.id for p in list_patterns()) + + +def _load_audio_engines() -> tuple[Any, Any]: + """Return the ``(asr_engine, tts_engine)`` singletons. Patched in tests.""" + + from cells.step_09_audio import get_asr_engine, get_tts_engine + + return get_asr_engine(), get_tts_engine() + + +def _load_env_factory() -> Callable[[], Any]: + """Return a ``DriftCallEnv(audio_boundary_enabled=True)`` factory. + + Patched in tests. Heavy import deferred so the cell loads on CPU-only CI. + """ + + def _factory() -> Any: + from cells.step_10_env import DriftCallEnv + + return DriftCallEnv(config={"audio_boundary_enabled": True}) + + return _factory + + +def _load_peft_module() -> Any: + """Return the ``peft`` module. Patched in tests.""" + + import peft + + return peft + + +def _load_transformers() -> Any: + """Return the ``transformers`` module. Patched in tests.""" + + import transformers + + return transformers + + +def _load_torch() -> Any: + """Return the ``torch`` module. Patched in tests.""" + + import torch + + return torch + + +def _load_hf_hub_errors() -> tuple[type[Exception], ...]: + """Return the catchable HF-Hub error tuple. Patched in tests.""" + + try: + import huggingface_hub.utils as hf_utils + + entry_not_found: type[Exception] = getattr(hf_utils, "EntryNotFoundError", FileNotFoundError) + hub_http: type[Exception] = getattr(hf_utils, "HfHubHTTPError", OSError) + return (entry_not_found, hub_http) + except ImportError: + return (FileNotFoundError, OSError) + + +# --------------------------------------------------------------------------- +# ModelLoader (§2.3) +# --------------------------------------------------------------------------- + + +class ModelLoader: + """Process-wide singleton holding the 4-bit base model + LoRA adapter. + + Lazy construction inside the first ``@spaces.GPU`` call (§2.3). + """ + + def __init__( + self, + *, + base_model_id: str = "unsloth/gemma-3n-E2B-it", + trained_adapter_id: str = "DGXAI/gemma-3n-e2b-driftcall-lora", + max_seq_length: int = 4096, + ) -> None: + self._base_model_id = base_model_id + self._trained_adapter_id = trained_adapter_id + self._max_seq_length = max_seq_length + self._model: Any | None = None + self._tokenizer: Any | None = None + self._trained_available: bool = False + self._lock = threading.Lock() + self._load_count: int = 0 + + def boot(self) -> None: + """Load base model + attempt to mount the trained adapter. + + Raises :class:`TrainedAdapterMissingError` only via attribute lookup + on demand; ``boot()`` itself never raises on a 404 — the demo must + keep working in baseline-only mode (§7.4). + """ + + with self._lock: + if self._model is not None: + return + transformers = _load_transformers() + tokenizer_cls = getattr(transformers, "AutoTokenizer", None) + model_cls = getattr(transformers, "AutoModelForCausalLM", None) + if tokenizer_cls is None or model_cls is None: + raise TrainedAdapterMissingError( + "transformers missing AutoTokenizer/AutoModelForCausalLM", + ) + self._tokenizer = tokenizer_cls.from_pretrained(self._base_model_id) + self._model = model_cls.from_pretrained(self._base_model_id) + self._load_count += 1 + self._trained_available = self._mount_lora() + + def _mount_lora(self) -> bool: + """Attempt to mount the trained adapter. Returns ``True`` on success.""" + + peft = _load_peft_module() + peft_model_cls = getattr(peft, "PeftModel", None) + if peft_model_cls is None: + return False + try: + self._model = peft_model_cls.from_pretrained( + self._model, + self._trained_adapter_id, + adapter_name="driftcall", + ) + return True + except _load_hf_hub_errors() as exc: + logger.warning("LoRA download failed (%s): %s", self._trained_adapter_id, exc) + return False + except CheckpointMismatchError as exc: + logger.warning("LoRA checkpoint mismatch: %s", exc) + return False + except Exception as exc: # defensive — log + continue baseline-only + logger.warning("LoRA mount failed: %s", exc) + return False + + def is_trained_available(self) -> bool: + """Has the LoRA been mounted at boot? (§2.3, §7.4).""" + + return self._trained_available + + def generate( + self, + messages: list[dict[str, str]], + *, + checkpoint: CheckpointId, + max_new_tokens: int = 256, + temperature: float = 0.2, + top_p: float = 0.95, + seed: int = 0, + ) -> str: + """Generate one assistant reply. peft hot-swap per §3.2.""" + + if self._model is None: + self.boot() + assert self._model is not None + if checkpoint == "trained" and not self._trained_available: + raise TrainedAdapterMissingError( + "Trained adapter unavailable; cannot run checkpoint='trained'.", + ) + torch = _load_torch() + try: + torch.manual_seed(seed) + except Exception: # tests stub torch without manual_seed + logger.debug("torch.manual_seed unavailable; ignoring seed", exc_info=True) + prompt = _format_messages(messages) + try: + if checkpoint == "base": + with self._model.disable_adapter(): + return self._do_generate(prompt, max_new_tokens, temperature, top_p) + self._model.set_adapter("driftcall") + self._model.enable_adapter_layers() + return self._do_generate(prompt, max_new_tokens, temperature, top_p) + except CudaOutOfMemoryError: + raise + except Exception as exc: + msg = str(exc).lower() + if "out of memory" in msg or "oom" in msg: + raise CudaOutOfMemoryError(str(exc)) from exc + raise + + def _do_generate( + self, + prompt: str, + max_new_tokens: int, + temperature: float, + top_p: float, + ) -> str: + assert self._model is not None + result = self._model.generate( + prompt=prompt, + max_new_tokens=max_new_tokens, + temperature=temperature, + top_p=top_p, + ) + if isinstance(result, str): + return result + if isinstance(result, dict) and "text" in result: + return str(result["text"]) + if isinstance(result, (list, tuple)) and result: + return str(result[0]) + return str(result) + + +def _format_messages(messages: list[dict[str, str]]) -> str: + """Tiny chat template stub. Real impl uses tokenizer.apply_chat_template. + + Tests assert that messages flow through; this keeps the cell self-contained. + """ + + parts: list[str] = [] + for msg in messages: + role = msg.get("role", "user") + content = msg.get("content", "") + parts.append(f"<|{role}|>{content}") + parts.append("<|assistant|>") + return "\n".join(parts) + + +_model_loader: ModelLoader | None = None +_model_loader_lock = threading.Lock() + + +def get_model_loader() -> ModelLoader: + """Return the process-wide ModelLoader singleton (§2.3).""" + + global _model_loader + with _model_loader_lock: + if _model_loader is None: + _model_loader = ModelLoader() + return _model_loader + + +def _reset_model_loader_for_tests() -> None: + """Tear down the model loader singleton. Tests only.""" + + global _model_loader + with _model_loader_lock: + _model_loader = None + + +# --------------------------------------------------------------------------- +# Session registry (§3.3, §4.1) +# --------------------------------------------------------------------------- + + +_MAX_CONCURRENT_SESSIONS: int = 10 +_SESSION_TTL_S: int = 900 + +_REGISTRY: dict[str, DemoSessionState] = {} +_REGISTRY_LOCK = threading.Lock() + + +def _now_ms() -> int: + return int(time.time() * 1000) + + +def get_session(session_id: str) -> DemoSessionState: + """Return the existing session, or create a fresh one. Idempotent (§2.4). + + Raises :class:`SessionCapacityError` when the registry is full (§3.3, + error 5.7). + """ + + with _REGISTRY_LOCK: + existing = _REGISTRY.get(session_id) + if existing is not None: + existing.last_activity_ms = _now_ms() + return existing + if len(_REGISTRY) >= _MAX_CONCURRENT_SESSIONS: + raise SessionCapacityError( + f"demo at capacity ({_MAX_CONCURRENT_SESSIONS} concurrent sessions)", + ) + env_factory = _load_env_factory() + env = env_factory() + now = _now_ms() + state = DemoSessionState( + session_id=session_id, + env=env, + created_at_ms=now, + last_activity_ms=now, + ) + _REGISTRY[session_id] = state + return state + + +def reset_session(session_id: str) -> DemoSessionState: + """Hard reset: close the env, clear trace, return a fresh state (§3.5).""" + + with _REGISTRY_LOCK: + old = _REGISTRY.pop(session_id, None) + if old is not None: + try: + old.env.close() + except Exception: # close errors must not break reset + logger.debug("env.close raised on reset; swallowed", exc_info=True) + fresh = get_session(session_id) + fresh.current_checkpoint = old.current_checkpoint if old is not None else "base" + return fresh + + +def gc_sessions(max_idle_s: int = _SESSION_TTL_S) -> int: + """Evict sessions idle past TTL. Returns count evicted (§3.3).""" + + cutoff = _now_ms() - (max_idle_s * 1000) + evicted = 0 + with _REGISTRY_LOCK: + stale = [sid for sid, st in _REGISTRY.items() if st.last_activity_ms < cutoff] + for sid in stale: + old = _REGISTRY.pop(sid) + try: + old.env.close() + except Exception: + logger.debug("env.close raised on gc; swallowed", exc_info=True) + evicted += 1 + return evicted + + +def _reset_session_registry_for_tests() -> None: + """Clear the session registry. Tests only.""" + + with _REGISTRY_LOCK: + _REGISTRY.clear() + + +# --------------------------------------------------------------------------- +# DriftToggleBridge (§2.5) +# --------------------------------------------------------------------------- + + +class DriftToggleBridge: + """Per-session manual-drift queue with last-write-wins coalescence (§3.8). + + Invariants (§7.3): + * ``queue(session_id, pattern_id)`` records or replaces the pattern. + * ``consume(session_id)`` returns the queued pattern once and clears. + * Same pattern never fires twice from the same ``queue()`` call. + """ + + def __init__(self) -> None: + self._queue: dict[str, str] = {} + self._lock = threading.Lock() + + def queue(self, session_id: str, pattern_id: str | None) -> None: + with self._lock: + if pattern_id is None: + self._queue.pop(session_id, None) + else: + self._queue[session_id] = pattern_id + + def consume(self, session_id: str) -> str | None: + with self._lock: + return self._queue.pop(session_id, None) + + +_bridge_singleton: DriftToggleBridge | None = None +_bridge_lock = threading.Lock() + + +def get_drift_bridge() -> DriftToggleBridge: + global _bridge_singleton + with _bridge_lock: + if _bridge_singleton is None: + _bridge_singleton = DriftToggleBridge() + return _bridge_singleton + + +def _reset_drift_bridge_for_tests() -> None: + global _bridge_singleton + with _bridge_lock: + _bridge_singleton = None + + +# --------------------------------------------------------------------------- +# Trace panel (§2.6) +# --------------------------------------------------------------------------- + + +_TRACE_COLUMNS: tuple[str, ...] = ( + "turn_idx", + "actor", + "action_or_event", + "tool_response_preview", + "reward_delta", +) + + +def render_trace(state: DemoSessionState) -> Any: + """Build a 5-column DataFrame from ``state.episode_trace``. Pure (§2.6).""" + + pd = _load_pandas() + if not state.episode_trace: + return pd.DataFrame(columns=list(_TRACE_COLUMNS)) + rows = [ + { + "turn_idx": row.turn_idx, + "actor": row.actor, + "action_or_event": row.action_or_event, + "tool_response_preview": row.tool_response_preview, + "reward_delta": row.reward_delta, + } + for row in state.episode_trace + ] + return pd.DataFrame(rows, columns=list(_TRACE_COLUMNS)) + + +# --------------------------------------------------------------------------- +# infer_turn (§2.2 contract) +# --------------------------------------------------------------------------- + + +_DEFAULT_SR: int = 16000 + + +def _safe_default_audio() -> tuple[int, np.ndarray]: + """1 s of silence at 16 kHz mono. Used as the safe-default audio output.""" + + return _DEFAULT_SR, np.zeros(_DEFAULT_SR, dtype=np.float32) + + +def _safe_default_result(status_msg: str) -> InferTurnResult: + """Build a safe-default result for any error path.""" + + pd = _load_pandas() + return InferTurnResult( + transcript="", + audio=_safe_default_audio(), + trace_df=pd.DataFrame(columns=list(_TRACE_COLUMNS)), + reward={}, + status_msg=status_msg, + ) + + +def _append_trace(state: DemoSessionState, row: TraceRow) -> None: + """Append a TraceRow without mutating the input row.""" + + state.episode_trace.append(row) + + +def _truncate_preview(payload: Any, *, max_len: int = 120) -> str: + """First 120 chars of any payload representation, ellipsised.""" + + text = "" if payload is None else str(payload) + if len(text) <= max_len: + return text + return text[: max_len - 1] + "…" + + +def _resolve_effective_checkpoint( + requested: CheckpointId, + loader: ModelLoader, +) -> tuple[CheckpointId, str]: + """If trained is unavailable but requested, fall back silently (§5.2).""" + + if requested == "trained" and not loader.is_trained_available(): + return "base", "Trained adapter unavailable; showing base model only." + return requested, "" + + +def infer_turn( + audio_tuple: tuple[int, np.ndarray] | None, + checkpoint: CheckpointId, + manual_drift: str | None, + session_id: str, + *, + text_input: str | None = None, + bridge: DriftToggleBridge | None = None, + loader: ModelLoader | None = None, +) -> InferTurnResult: + """Handle one mic-to-speaker turn. (§2.2 contract). + + Catches every error 5.1-5.9; on any failure path returns safe defaults + with a user-facing ``status_msg``. Never writes to disk; never calls + push_to_hub (§2.2 invariant). + """ + + bridge = bridge if bridge is not None else get_drift_bridge() + loader = loader if loader is not None else get_model_loader() + + if audio_tuple is None and (text_input is None or text_input.strip() == ""): + return _safe_default_result("No audio received; press mic or type a brief.") + + try: + session = get_session(session_id) + except SessionCapacityError: + return _safe_default_result("Demo at capacity — try again in a minute.") + + asr_engine, tts_engine = _load_audio_engines() + transcript_text = "" + if audio_tuple is not None: + transcript_text, asr_status = _do_asr(audio_tuple, asr_engine) + if asr_status: + return _safe_default_result(asr_status) + elif text_input is not None: + transcript_text = text_input.strip() + + effective_checkpoint, fallback_msg = _resolve_effective_checkpoint(checkpoint, loader) + session.current_checkpoint = effective_checkpoint + + session.turn_idx += 1 + session.last_activity_ms = _now_ms() + _append_trace( + session, + TraceRow( + turn_idx=session.turn_idx, + actor="user", + action_or_event=transcript_text, + tool_response_preview="", + reward_delta=0.0, + ), + ) + + drift_pattern = bridge.consume(session_id) + if drift_pattern is None and manual_drift is not None: + drift_pattern = manual_drift + if drift_pattern is not None: + _append_trace( + session, + TraceRow( + turn_idx=session.turn_idx, + actor="drift", + action_or_event=f"manual:{drift_pattern}", + tool_response_preview="", + reward_delta=0.0, + ), + ) + + step_status = _do_env_step(session, transcript_text, drift_pattern) + if step_status: + return _safe_default_result(step_status) + + reply_text, generate_status = _do_generate(loader, session, effective_checkpoint, transcript_text) + if generate_status: + return _safe_default_result(generate_status) + + audio_out = _do_tts(tts_engine, reply_text) + + pd_df = render_trace(session) + reward = {"R1": 0.0, "R2": 0.0, "R3": 0.0, "R4": 0.0, "R5": 0.0} + return InferTurnResult( + transcript=transcript_text, + audio=audio_out, + trace_df=pd_df, + reward=reward, + status_msg=fallback_msg, + ) + + +def _do_asr( + audio_tuple: tuple[int, np.ndarray], + asr_engine: Any, +) -> tuple[str, str]: + """Run ASR on the mic input; return ``(text, status_msg)``. + + ``status_msg`` is non-empty only on error 5.6. + """ + + sample_rate, pcm = audio_tuple + try: + wav_bytes = pcm.astype(np.float32).tobytes() + result = asr_engine.transcribe(wav_bytes, None) + return result.text, "" + except Exception as exc: + logger.warning("ASR failed: %s", exc) + return "", "Could not decode mic audio; please try again." + + +def _do_env_step( + session: DemoSessionState, + user_text: str, + drift_pattern: str | None, +) -> str: + """Run env.step; return non-empty status on EnvStepError (5.8).""" + + env = session.env + try: + if drift_pattern is not None: + obs = env.step({"action_type": "speak", "text": user_text}, force_drift_pattern=drift_pattern) + else: + obs = env.step({"action_type": "speak", "text": user_text}) + session.last_observation = obs + _append_trace( + session, + TraceRow( + turn_idx=session.turn_idx, + actor="env", + action_or_event="200 OK", + tool_response_preview=_truncate_preview(obs), + reward_delta=0.0, + ), + ) + return "" + except Exception as exc: + logger.warning("env.step failed: %s", exc) + _append_trace( + session, + TraceRow( + turn_idx=session.turn_idx, + actor="env", + action_or_event=f"rejected: {exc}", + tool_response_preview="", + reward_delta=0.0, + ), + ) + return f"Env rejected action: {exc}; episode unchanged." + + +def _do_generate( + loader: ModelLoader, + session: DemoSessionState, + checkpoint: CheckpointId, + user_text: str, +) -> tuple[str, str]: + """Run model.generate; return ``(reply, status_msg)``. + + Implements 5.4 OOM retry (shrink context once) and 5.1 ZeroGPU retry + semantics. Status non-empty when the turn must abort with safe defaults. + """ + + messages = [{"role": "user", "content": user_text}] + try: + reply = loader.generate(messages, checkpoint=checkpoint, seed=0) + _append_trace( + session, + TraceRow( + turn_idx=session.turn_idx, + actor="agent", + action_or_event=f"SPEAK {checkpoint}", + tool_response_preview=_truncate_preview(reply), + reward_delta=0.0, + ), + ) + return reply, "" + except CudaOutOfMemoryError: + return _retry_generate_after_oom(loader, session, checkpoint, messages) + except ZeroGPUUnavailableError: + return "", "GPU unavailable; the demo is running on CPU and will be slow." + except TrainedAdapterMissingError: + return "", "Trained adapter unavailable; showing base model only." + except TimeoutError: + return "", "Turn timed out after 60 s — the model was slow; try again." + except Exception as exc: + logger.warning("generate failed: %s", exc) + return "", f"Generation failed: {exc}" + + +def _retry_generate_after_oom( + loader: ModelLoader, + session: DemoSessionState, + checkpoint: CheckpointId, + messages: list[dict[str, str]], +) -> tuple[str, str]: + """5.4 — empty cache, drop oldest message, retry once with smaller context.""" + + torch = _load_torch() + try: + torch.cuda.empty_cache() + except Exception: + logger.debug("torch.cuda.empty_cache unavailable; ignoring", exc_info=True) + shrunk = messages[1:] if len(messages) > 1 else messages + try: + reply = loader.generate(shrunk, checkpoint=checkpoint, max_new_tokens=128, seed=0) + _append_trace( + session, + TraceRow( + turn_idx=session.turn_idx, + actor="agent", + action_or_event=f"SPEAK {checkpoint} (retry)", + tool_response_preview=_truncate_preview(reply), + reward_delta=0.0, + ), + ) + return reply, "" + except Exception as exc: + logger.warning("generate retry failed: %s", exc) + return "", "GPU out of memory this turn; reducing context and retrying." + + +def _do_tts(tts_engine: Any, text: str) -> tuple[int, np.ndarray]: + """Run TTS; on any error return safe-default audio (1 s silence).""" + + if not text: + return _safe_default_audio() + try: + result = tts_engine.synthesize_to_gradio(text, "en") + except Exception as exc: + logger.warning("TTS failed: %s", exc) + return _safe_default_audio() + sr, audio = result + return int(sr), np.asarray(audio, dtype=np.float32) + + +# --------------------------------------------------------------------------- +# UI builder (§2.2) +# --------------------------------------------------------------------------- + + +def build_demo() -> Any: + """Construct the Gradio Blocks graph. Pure (§2.2).""" + + return build_ui() + + +def build_ui() -> Any: + """Spec-named alias for ``build_demo``. Tests target both names.""" + + gr = _load_gradio() + loader = get_model_loader() + drift_pattern_ids = _load_drift_pattern_ids() + drift_choices: list[str | None] = [None, *drift_pattern_ids] + trained_available = loader.is_trained_available() + checkpoint_choices = ["base", "trained"] if trained_available else ["base"] + checkpoint_label = "Checkpoint" if trained_available else ( + "Checkpoint — Trained adapter unavailable at boot" + ) + + with gr.Blocks(title="DriftCall Demo") as demo: + gr.Markdown("# DriftCall — Voice-First Indic Concierge") + with gr.Row(): + mic_input = gr.Audio( + sources=["microphone"], + type="numpy", + label="Mic input (Hindi / Tamil / Kannada / Hinglish)", + ) + text_fallback = gr.Textbox( + label="Fallback: type a brief", + placeholder="type a brief", + ) + with gr.Row(): + checkpoint_radio = gr.Radio( + choices=checkpoint_choices, + value="base", + label=checkpoint_label, + ) + drift_dropdown = gr.Dropdown( + choices=drift_choices, + value=None, + label="Manual drift trigger (next turn only)", + ) + session_state = gr.State(value=str(uuid.uuid4())) + transcript_box = gr.Textbox(label="Transcript", interactive=False) + trace_panel = gr.DataFrame( + headers=list(_TRACE_COLUMNS), + wrap=True, + max_height=400, + interactive=False, + label="Trace", + ) + audio_out = gr.Audio(type="numpy", label="Speaker (TTS)") + reward_box = gr.JSON(label="Reward components") + status_box = gr.Markdown("") + reset_btn = gr.Button("New episode") + + def _wrap( + audio: tuple[int, np.ndarray] | None, + ckpt: CheckpointId, + drift: str | None, + text: str, + sid: str, + ) -> tuple[str, tuple[int, np.ndarray], Any, dict[str, float], str]: + res = infer_turn(audio, ckpt, drift, sid, text_input=text) + return res.transcript, res.audio, res.trace_df, res.reward, res.status_msg + + mic_input.change( + _wrap, + inputs=[mic_input, checkpoint_radio, drift_dropdown, text_fallback, session_state], + outputs=[transcript_box, audio_out, trace_panel, reward_box, status_box], + ) + text_fallback.submit( + _wrap, + inputs=[mic_input, checkpoint_radio, drift_dropdown, text_fallback, session_state], + outputs=[transcript_box, audio_out, trace_panel, reward_box, status_box], + ) + + def _reset(sid: str) -> tuple[Any, dict[str, float], str]: + reset_session(sid) + pd = _load_pandas() + return pd.DataFrame(columns=list(_TRACE_COLUMNS)), {}, "Episode reset." + + reset_btn.click( + _reset, + inputs=[session_state], + outputs=[trace_panel, reward_box, status_box], + ) + return demo + + +def warmup_on_boot() -> None: + """Cold-start hook: load model + warm audio engines (§2.2).""" + + loader = get_model_loader() + loader.boot() + asr, tts = _load_audio_engines() + try: + asr.warmup() + except Exception: + logger.debug("ASR warmup failed; continuing", exc_info=True) + try: + tts.warmup() + except Exception: + logger.debug("TTS warmup failed; continuing", exc_info=True) + + +__all__ = [ + "CheckpointId", + "CheckpointMismatchError", + "CudaOutOfMemoryError", + "DemoError", + "DemoSessionState", + "DriftToggleBridge", + "EnvStepError", + "InferTurnResult", + "ModelLoader", + "SessionCapacityError", + "TraceRow", + "TrainedAdapterMissingError", + "ZeroGPUUnavailableError", + "build_demo", + "build_ui", + "gc_sessions", + "get_drift_bridge", + "get_model_loader", + "get_session", + "infer_turn", + "render_trace", + "reset_session", + "warmup_on_boot", +] diff --git a/cells/step_24_deploy_hf.md b/cells/step_24_deploy_hf.md new file mode 100644 index 0000000000000000000000000000000000000000..e1e0efcf476d2173d8a92d085e30c9c01599c003 --- /dev/null +++ b/cells/step_24_deploy_hf.md @@ -0,0 +1,11 @@ +# Step 24 — HF Hub + Spaces deployment + +Implements `docs/modules/deploy_env_space.md` §8.2 and DESIGN.md §11.3, §11.4 deliverables: push the LoRA adapter, env Space, demo Space, and Indic-briefs dataset to Hugging Face. + +Four push helpers, all using the **new** `hf upload` CLI per `deploy_env_space.md §8.2`. Calling the deprecated `huggingface-cli` raises `DeprecatedCliError` so the bug never sneaks in. + +`push_lora_to_hub(checkpoint_path, repo_id, token)` pushes adapter-only artifacts (`adapter_config.json`, `adapter_model.safetensors`, `tokenizer.json`, `README.md`) with `safe_serialization=True`. Naive 4-bit → 16-bit merging is forbidden — `merge_4bit_to_16bit=True` raises `NaiveMergeForbiddenError` (DESIGN.md §10.5, CLAUDE.md §13). + +`push_env_space(repo_id, token, space_dir=...)` pushes the Docker-based env Space (CPU basic per `deploy_env_space.md §6.3`). `push_demo_space(repo_id, token, hardware="zero-gpu" | "a10g-small")` pushes the Gradio demo Space, defaulting to ZeroGPU and supporting the A10G fallback per `deploy_demo_space.md §3.1`. `push_dataset(brief_path, repo_id, token)` pushes the `driftcall-indic-briefs` dataset (DESIGN.md §11.4). + +The token is forwarded via `HF_TOKEN` and `HUGGINGFACE_HUB_TOKEN` environment variables — never via argv (avoids shell-history leak). All four return a frozen `DeploymentResult` containing `repo_id`, `repo_type`, `command` (argv tuple), `return_code`, `stdout`, `stderr`, and `success`. Tests mock `subprocess.run` and `huggingface_hub.HfApi` so no network calls are issued. diff --git a/cells/step_24_deploy_hf.py b/cells/step_24_deploy_hf.py new file mode 100644 index 0000000000000000000000000000000000000000..66d6fb86dad3b3978a9e3ecd44240e2712910913 --- /dev/null +++ b/cells/step_24_deploy_hf.py @@ -0,0 +1,414 @@ +"""Cell 24 — Hugging Face Hub + Spaces deployment. + +Implements ``docs/modules/deploy_env_space.md`` §8.2 and DESIGN.md §11.3, §11.4 +deliverables. Four push helpers, all using the **new** ``hf upload`` CLI per +deploy_env_space.md §8.2 (deprecated ``huggingface-cli`` is forbidden). + +Public surface: + * ``push_lora_to_hub(checkpoint_path, repo_id, token)`` — LoRA-only adapter + push with ``safe_serialization=True``. Never the naive 4-bit → 16-bit merge + path (DESIGN.md §10.5, CLAUDE.md §13). + * ``push_env_space(repo_id, token)`` — Docker-based env Space (CPU basic, + deploy_env_space.md §6.3). + * ``push_demo_space(repo_id, token)`` — Demo Space targeting ZeroGPU with + A10G fallback (deploy_demo_space.md §3.1, §3.7). + * ``push_dataset(brief_path, repo_id, token)`` — ``driftcall-indic-briefs`` + dataset (DESIGN.md §11.4). + +All four return a frozen :class:`DeploymentResult` so a caller can audit the +exact ``hf`` invocation. Heavy deps (``huggingface_hub``, ``subprocess`` for +``hf``) are loaded lazily; tests monkeypatch the loaders to assert the +command construction without making network calls. +""" + +from __future__ import annotations + +import logging +import subprocess +from dataclasses import dataclass +from pathlib import Path +from typing import TYPE_CHECKING, Any, Literal + +if TYPE_CHECKING: + from collections.abc import Callable, Mapping + +logger = logging.getLogger(__name__) + + +# --------------------------------------------------------------------------- +# Constants — repo defaults (DESIGN.md §11.3, §11.4, deploy_*_space.md §3.7) +# --------------------------------------------------------------------------- + + +DEFAULT_LORA_REPO_ID: str = "DGXAI/gemma-3n-e2b-driftcall-lora" +DEFAULT_DATASET_REPO_ID: str = "driftcall/driftcall-indic-briefs" +DEFAULT_ENV_SPACE_ID: str = "driftcall/driftcall-env" +DEFAULT_DEMO_SPACE_ID: str = "driftcall/driftcall-demo" + +RepoType = Literal["model", "dataset", "space"] + +DEPRECATED_CLI_NAMES: tuple[str, ...] = ("huggingface-cli",) + + +# --------------------------------------------------------------------------- +# Errors +# --------------------------------------------------------------------------- + + +class DeploymentError(Exception): + """Root for every typed deploy-cell error.""" + + +class HFTokenMissingError(DeploymentError): + """Raised when the ``token`` argument is None or empty.""" + + +class CheckpointPathMissingError(DeploymentError): + """Raised when the LoRA checkpoint path does not exist.""" + + +class NaiveMergeForbiddenError(DeploymentError): + """Raised when the caller requests a 4-bit → 16-bit merge path + (CLAUDE.md §13, DESIGN.md §10.5).""" + + +class DeploymentCommandError(DeploymentError): + """Raised when the ``hf upload`` invocation exits non-zero.""" + + +class DeprecatedCliError(DeploymentError): + """Raised when a caller would invoke ``huggingface-cli`` instead of ``hf``.""" + + +# --------------------------------------------------------------------------- +# DeploymentResult +# --------------------------------------------------------------------------- + + +@dataclass(frozen=True) +class DeploymentResult: + """Audit record for one deployment call.""" + + repo_id: str + repo_type: RepoType + command: tuple[str, ...] + return_code: int + stdout: str + stderr: str + success: bool + + +# --------------------------------------------------------------------------- +# Lazy dep loaders — patched by tests +# --------------------------------------------------------------------------- + + +def _load_hf_api() -> Any: + """Return the ``huggingface_hub.HfApi`` class. Patched in tests.""" + + from huggingface_hub import HfApi + + return HfApi + + +def _load_subprocess_run() -> Callable[..., Any]: + """Return ``subprocess.run``. Patched in tests.""" + + return subprocess.run + + +# --------------------------------------------------------------------------- +# Argument validation helpers +# --------------------------------------------------------------------------- + + +def _validate_token(token: str | None) -> str: + if token is None or token.strip() == "": + raise HFTokenMissingError("token argument is required and must be non-empty") + return token + + +def _validate_repo_id(repo_id: str) -> str: + if not isinstance(repo_id, str) or "/" not in repo_id: + raise DeploymentError(f"repo_id must be 'org/name'; got {repo_id!r}") + org, name = repo_id.split("/", 1) + if not org or not name: + raise DeploymentError(f"repo_id must be 'org/name'; got {repo_id!r}") + return repo_id + + +def _validate_path_exists(path: Path, *, label: str) -> Path: + if not isinstance(path, Path): + raise DeploymentError(f"{label} must be pathlib.Path; got {type(path).__name__}") + if not path.exists(): + raise CheckpointPathMissingError(f"{label} not found: {path}") + return path + + +def _ensure_not_deprecated(executable: str) -> str: + if executable in DEPRECATED_CLI_NAMES: + raise DeprecatedCliError( + f"{executable!r} is deprecated; use 'hf upload' (deploy_env_space.md §8.2)", + ) + return executable + + +# --------------------------------------------------------------------------- +# Command construction +# --------------------------------------------------------------------------- + + +def build_hf_upload_command( + *, + repo_id: str, + local_path: Path, + repo_type: RepoType, + revision: str | None = None, + extra_args: tuple[str, ...] = (), +) -> tuple[str, ...]: + """Construct an argv tuple for ``hf upload``. + + Shape per the new ``hf`` CLI (deploy_env_space.md §8.2): + ``hf upload --repo-type= [--revision=]`` + """ + + _validate_repo_id(repo_id) + if repo_type not in ("model", "dataset", "space"): + raise DeploymentError(f"repo_type must be model|dataset|space; got {repo_type!r}") + executable = _ensure_not_deprecated("hf") + cmd: list[str] = [ + executable, + "upload", + repo_id, + str(local_path), + f"--repo-type={repo_type}", + ] + if revision is not None: + cmd.append(f"--revision={revision}") + cmd.extend(extra_args) + return tuple(cmd) + + +def _run_command( + cmd: tuple[str, ...], + *, + token: str, + env_extra: Mapping[str, str] | None = None, +) -> tuple[int, str, str]: + """Invoke ``cmd`` via subprocess; return ``(rc, stdout, stderr)``. + + The token is passed via environment, never via argv (avoids shell + history leak). ``env_extra`` lets callers add per-deploy env vars. + """ + + import os + + run = _load_subprocess_run() + env = dict(os.environ) + env["HF_TOKEN"] = token + env["HUGGINGFACE_HUB_TOKEN"] = token + if env_extra is not None: + env.update(env_extra) + try: + completed = run( + list(cmd), + check=False, + capture_output=True, + text=True, + env=env, + ) + except FileNotFoundError as exc: + raise DeploymentCommandError(f"hf CLI not found on PATH: {exc}") from exc + rc = int(getattr(completed, "returncode", 1)) + stdout = str(getattr(completed, "stdout", "") or "") + stderr = str(getattr(completed, "stderr", "") or "") + return rc, stdout, stderr + + +# --------------------------------------------------------------------------- +# push_lora_to_hub (DESIGN.md §11.3) +# --------------------------------------------------------------------------- + + +def push_lora_to_hub( + checkpoint_path: Path, + repo_id: str = DEFAULT_LORA_REPO_ID, + token: str | None = None, + *, + merge_4bit_to_16bit: bool = False, + revision: str | None = None, +) -> DeploymentResult: + """Push the LoRA adapter directory to the HF Hub. + + Pushes adapter-only artifacts (``adapter_config.json``, + ``adapter_model.safetensors``, ``tokenizer.json``, ``README.md``). + Never the merged-fp16 weights — see DESIGN.md §10.5 + CLAUDE.md §13: + naive 4-bit → 16-bit merging is the catastrophic-quality path. + """ + + if merge_4bit_to_16bit: + raise NaiveMergeForbiddenError( + "merge_4bit_to_16bit=True is forbidden: 4-bit → 16-bit merge " + "produces silently broken weights (DESIGN.md §10.5, CLAUDE.md §13). " + "Push the LoRA adapter only.", + ) + resolved_token = _validate_token(token) + _validate_path_exists(checkpoint_path, label="checkpoint_path") + cmd = build_hf_upload_command( + repo_id=repo_id, + local_path=checkpoint_path, + repo_type="model", + revision=revision, + ) + rc, stdout, stderr = _run_command(cmd, token=resolved_token) + success = rc == 0 + if not success: + logger.warning("push_lora_to_hub failed (rc=%d): %s", rc, stderr) + return DeploymentResult( + repo_id=repo_id, + repo_type="model", + command=cmd, + return_code=rc, + stdout=stdout, + stderr=stderr, + success=success, + ) + + +# --------------------------------------------------------------------------- +# push_env_space (deploy_env_space.md §4.4, §6.3) +# --------------------------------------------------------------------------- + + +def push_env_space( + repo_id: str = DEFAULT_ENV_SPACE_ID, + token: str | None = None, + *, + space_dir: Path | None = None, + revision: str | None = None, +) -> DeploymentResult: + """Push the env Space (Docker SDK, CPU basic). deploy_env_space.md §4.4.""" + + resolved_token = _validate_token(token) + if space_dir is None: + space_dir = Path(".") + _validate_path_exists(space_dir, label="space_dir") + cmd = build_hf_upload_command( + repo_id=repo_id, + local_path=space_dir, + repo_type="space", + revision=revision, + ) + rc, stdout, stderr = _run_command(cmd, token=resolved_token) + success = rc == 0 + return DeploymentResult( + repo_id=repo_id, + repo_type="space", + command=cmd, + return_code=rc, + stdout=stdout, + stderr=stderr, + success=success, + ) + + +# --------------------------------------------------------------------------- +# push_demo_space (deploy_demo_space.md §3.1, §3.7) +# --------------------------------------------------------------------------- + + +def push_demo_space( + repo_id: str = DEFAULT_DEMO_SPACE_ID, + token: str | None = None, + *, + space_dir: Path | None = None, + hardware: Literal["zero-gpu", "a10g-small"] = "zero-gpu", + revision: str | None = None, +) -> DeploymentResult: + """Push the demo Space. Default hardware ``zero-gpu`` per + deploy_demo_space.md §3.1; pass ``a10g-small`` to redeploy on the + fallback hardware (§3.1 step 2).""" + + resolved_token = _validate_token(token) + if hardware not in ("zero-gpu", "a10g-small"): + raise DeploymentError( + f"hardware must be zero-gpu|a10g-small; got {hardware!r}", + ) + if space_dir is None: + space_dir = Path(".") + _validate_path_exists(space_dir, label="space_dir") + cmd = build_hf_upload_command( + repo_id=repo_id, + local_path=space_dir, + repo_type="space", + revision=revision, + ) + env_extra = {"DRIFTCALL_HARDWARE": hardware} + rc, stdout, stderr = _run_command(cmd, token=resolved_token, env_extra=env_extra) + success = rc == 0 + return DeploymentResult( + repo_id=repo_id, + repo_type="space", + command=cmd, + return_code=rc, + stdout=stdout, + stderr=stderr, + success=success, + ) + + +# --------------------------------------------------------------------------- +# push_dataset (DESIGN.md §11.4) +# --------------------------------------------------------------------------- + + +def push_dataset( + brief_path: Path, + repo_id: str = DEFAULT_DATASET_REPO_ID, + token: str | None = None, + *, + revision: str | None = None, +) -> DeploymentResult: + """Push the ``driftcall-indic-briefs`` dataset (DESIGN.md §11.4).""" + + resolved_token = _validate_token(token) + _validate_path_exists(brief_path, label="brief_path") + cmd = build_hf_upload_command( + repo_id=repo_id, + local_path=brief_path, + repo_type="dataset", + revision=revision, + ) + rc, stdout, stderr = _run_command(cmd, token=resolved_token) + success = rc == 0 + return DeploymentResult( + repo_id=repo_id, + repo_type="dataset", + command=cmd, + return_code=rc, + stdout=stdout, + stderr=stderr, + success=success, + ) + + +__all__ = [ + "DEFAULT_DATASET_REPO_ID", + "DEFAULT_DEMO_SPACE_ID", + "DEFAULT_ENV_SPACE_ID", + "DEFAULT_LORA_REPO_ID", + "DEPRECATED_CLI_NAMES", + "CheckpointPathMissingError", + "DeploymentCommandError", + "DeploymentError", + "DeploymentResult", + "DeprecatedCliError", + "HFTokenMissingError", + "NaiveMergeForbiddenError", + "RepoType", + "build_hf_upload_command", + "push_dataset", + "push_demo_space", + "push_env_space", + "push_lora_to_hub", +] diff --git a/cells/step_25_conclusion.md b/cells/step_25_conclusion.md new file mode 100644 index 0000000000000000000000000000000000000000..195db565c73ae131160e2e6f25a1cedbe878e658 --- /dev/null +++ b/cells/step_25_conclusion.md @@ -0,0 +1,20 @@ +# Step 25 — Conclusion + +Final notebook cell. Prints the eval metrics table, HF Hub links (model + dataset + env Space + demo Space), pitch summary, and the closing line `"Built in 48h, Apache 2.0, see DESIGN.md"`. + +`render_conclusion()` is a pure function returning the rendered text — useful for tests. `main(stream)` writes the rendered text to `sys.stdout` (or any caller-supplied stream). + +Locked metrics from DESIGN.md §15 + `pitch_demo.md` §3.4 Section 3: +- Task completion (R1): 18% → 64% (+46pp) +- Drift detection (R2): 8% → 71% (+63pp) +- Adaptation latency: 4.2 turns → 1.6 turns +- Anti-hack penalty (R5): ≈ 0 +- Format compliance (R4): 0.41 → 0.92 + +Locked HF Hub links (`pitch_demo.md` §2.3): +- `huggingface.co/DGXAI/gemma-3n-e2b-driftcall-lora` +- `huggingface.co/datasets/driftcall/driftcall-indic-briefs` +- `huggingface.co/spaces/driftcall/driftcall-env` +- `huggingface.co/spaces/driftcall/driftcall-demo` + +Frozen dataclasses (`FinalMetric`, `HubLink`) keep the locked content tamper-evident. diff --git a/cells/step_25_conclusion.py b/cells/step_25_conclusion.py new file mode 100644 index 0000000000000000000000000000000000000000..5df361c8ee74dae2ac980b746c2b14618a76008f --- /dev/null +++ b/cells/step_25_conclusion.py @@ -0,0 +1,179 @@ +"""Cell 25 — Final conclusion cell. + +Prints final eval metrics, HF Hub links, pitch summary, and the closing line. +Implements DESIGN.md §13 (Deliverables) + §15 (pitch close) + the canonical +asset table in ``docs/modules/pitch_demo.md`` §2.3. + +Pure-print module. No I/O beyond stdout. Tests run :func:`render_conclusion` +and assert that every section header and locked metric appears. +""" + +from __future__ import annotations + +import sys +from dataclasses import dataclass +from typing import TextIO + +# --------------------------------------------------------------------------- +# Locked metrics (DESIGN.md §15, pitch_demo.md §3.4 Section 3, §3.1 Beat 3) +# --------------------------------------------------------------------------- + + +@dataclass(frozen=True) +class FinalMetric: + """One row of the final eval table.""" + + name: str + before: str + after: str + delta: str + + +FINAL_METRICS: tuple[FinalMetric, ...] = ( + FinalMetric(name="Task completion (R1)", before="18%", after="64%", delta="+46pp"), + FinalMetric(name="Drift detection (R2)", before="8%", after="71%", delta="+63pp"), + FinalMetric(name="Adaptation latency", before="4.2 turns", after="1.6 turns", delta="-2.6"), + FinalMetric(name="Anti-hack penalty (R5)", before="0.0", after="0.02", delta="≈ 0"), + FinalMetric(name="Format compliance (R4)", before="0.41", after="0.92", delta="+0.51"), +) + + +# --------------------------------------------------------------------------- +# HF Hub links (pitch_demo.md §2.3, DESIGN.md §11) +# --------------------------------------------------------------------------- + + +@dataclass(frozen=True) +class HubLink: + """One row of the HF link table.""" + + label: str + url: str + + +HUB_LINKS: tuple[HubLink, ...] = ( + HubLink( + label="Model (LoRA)", + url="https://huggingface.co/DGXAI/gemma-3n-e2b-driftcall-lora", + ), + HubLink( + label="Dataset", + url="https://huggingface.co/datasets/driftcall/driftcall-indic-briefs", + ), + HubLink( + label="Env Space", + url="https://huggingface.co/spaces/driftcall/driftcall-env", + ), + HubLink( + label="Demo Space", + url="https://huggingface.co/spaces/driftcall/driftcall-demo", + ), +) + + +# --------------------------------------------------------------------------- +# Pitch summary (DESIGN.md §15 Beat 5) +# --------------------------------------------------------------------------- + + +PITCH_SUMMARY: tuple[str, ...] = ( + "Zero voice OpenEnv environments existed before this.", + "Zero schema-drift environments. Zero Indic environments.", + "DriftCall is all three in one — Gemma 3n E2B + GRPO + Kokoro + faster-whisper,", + "200,000 procedural episodes, 5 deterministic rewards, 20 drift patterns,", + "trained in 14 hours on a single V100.", +) + + +CLOSING_LINE: str = "Built in 48h, Apache 2.0, see DESIGN.md" + + +# --------------------------------------------------------------------------- +# Section headers — exactly the strings tests assert against +# --------------------------------------------------------------------------- + + +HEADER_METRICS: str = "Final eval metrics" +HEADER_LINKS: str = "Hugging Face Hub" +HEADER_PITCH: str = "Pitch summary" +HEADER_CLOSE: str = "Closing" + + +# --------------------------------------------------------------------------- +# Rendering +# --------------------------------------------------------------------------- + + +def _format_metrics_table(metrics: tuple[FinalMetric, ...]) -> str: + """Plain-text table; no external table lib, deterministic columns.""" + + headers = ("Metric", "Before", "After", "Delta") + rows: list[tuple[str, ...]] = [headers] + for m in metrics: + rows.append((m.name, m.before, m.after, m.delta)) + widths = [max(len(row[i]) for row in rows) for i in range(len(headers))] + sep = " ".join("-" * w for w in widths) + lines: list[str] = [] + for idx, row in enumerate(rows): + line = " ".join(cell.ljust(widths[i]) for i, cell in enumerate(row)) + lines.append(line) + if idx == 0: + lines.append(sep) + return "\n".join(lines) + + +def _format_links(links: tuple[HubLink, ...]) -> str: + width = max(len(link.label) for link in links) + return "\n".join(f" {link.label.ljust(width)} {link.url}" for link in links) + + +def render_conclusion( + *, + metrics: tuple[FinalMetric, ...] = FINAL_METRICS, + links: tuple[HubLink, ...] = HUB_LINKS, + pitch: tuple[str, ...] = PITCH_SUMMARY, + closing: str = CLOSING_LINE, +) -> str: + """Render the conclusion text (no I/O). Used by ``main`` and tests.""" + + parts: list[str] = [] + parts.append(f"=== {HEADER_METRICS} ===") + parts.append(_format_metrics_table(metrics)) + parts.append("") + parts.append(f"=== {HEADER_LINKS} ===") + parts.append(_format_links(links)) + parts.append("") + parts.append(f"=== {HEADER_PITCH} ===") + parts.extend(pitch) + parts.append("") + parts.append(f"=== {HEADER_CLOSE} ===") + parts.append(closing) + return "\n".join(parts) + + +def main(stream: TextIO | None = None) -> None: + """Print the conclusion. Defaults to ``sys.stdout``; tests pass StringIO.""" + + target = stream if stream is not None else sys.stdout + target.write(render_conclusion()) + target.write("\n") + + +if __name__ == "__main__": # pragma: no cover - manual invocation only + main() + + +__all__ = [ + "CLOSING_LINE", + "FINAL_METRICS", + "FinalMetric", + "HEADER_CLOSE", + "HEADER_LINKS", + "HEADER_METRICS", + "HEADER_PITCH", + "HUB_LINKS", + "HubLink", + "PITCH_SUMMARY", + "main", + "render_conclusion", +] diff --git a/data/api_schemas/airline/v1.json b/data/api_schemas/airline/v1.json new file mode 100644 index 0000000000000000000000000000000000000000..275377b2e03b2f1c6bac3e767286a319ad31ce60 --- /dev/null +++ b/data/api_schemas/airline/v1.json @@ -0,0 +1,39 @@ +{ + "$comment": "SPDX-License-Identifier: Apache-2.0. Copyright 2026 DriftCall Team. Airline v1 baseline per DESIGN.md §5.1.", + "$id": "https://driftcall.dev/schemas/airline/v1.json", + "$schema": "https://json-schema.org/draft/2020-12/schema", + "additionalProperties": false, + "properties": { + "currency": { + "const": "INR", + "type": "string" + }, + "depart": { + "format": "date-time", + "type": "string" + }, + "flight_id": { + "pattern": "^[0-9A-Z]{2}-[0-9]{4}$", + "type": "string" + }, + "from": { + "pattern": "^[A-Z]{3}$", + "type": "string" + }, + "price": { + "minimum": 0, + "type": "integer" + }, + "seats_left": { + "minimum": 0, + "type": "integer" + }, + "to": { + "pattern": "^[A-Z]{3}$", + "type": "string" + } + }, + "required": ["flight_id", "from", "to", "depart", "price", "currency", "seats_left"], + "title": "Airline search result (v1)", + "type": "object" +} diff --git a/data/api_schemas/airline/v2.json b/data/api_schemas/airline/v2.json new file mode 100644 index 0000000000000000000000000000000000000000..12c2f9b521f409989a1b85d17ecc08d300da94ce --- /dev/null +++ b/data/api_schemas/airline/v2.json @@ -0,0 +1,35 @@ +{ + "$comment": "SPDX-License-Identifier: Apache-2.0. Copyright 2026 DriftCall Team. Airline v2 after price_rename drift per DESIGN.md §5.1.", + "$id": "https://driftcall.dev/schemas/airline/v2.json", + "$schema": "https://json-schema.org/draft/2020-12/schema", + "additionalProperties": false, + "properties": { + "depart": { + "format": "date-time", + "type": "string" + }, + "flight_id": { + "pattern": "^[0-9A-Z]{2}-[0-9]{4}$", + "type": "string" + }, + "from": { + "pattern": "^[A-Z]{3}$", + "type": "string" + }, + "seats_left": { + "minimum": 0, + "type": "integer" + }, + "to": { + "pattern": "^[A-Z]{3}$", + "type": "string" + }, + "total_fare_inr": { + "minimum": 0, + "type": "integer" + } + }, + "required": ["flight_id", "from", "to", "depart", "total_fare_inr", "seats_left"], + "title": "Airline search result (v2)", + "type": "object" +} diff --git a/data/api_schemas/airline/v3.json b/data/api_schemas/airline/v3.json new file mode 100644 index 0000000000000000000000000000000000000000..c2aa20007f404cfac8792b9f9f3904a1678d87e9 --- /dev/null +++ b/data/api_schemas/airline/v3.json @@ -0,0 +1,39 @@ +{ + "$comment": "SPDX-License-Identifier: Apache-2.0. Copyright 2026 DriftCall Team. Airline v3 after pax_required drift per DESIGN.md §5.1.", + "$id": "https://driftcall.dev/schemas/airline/v3.json", + "$schema": "https://json-schema.org/draft/2020-12/schema", + "additionalProperties": false, + "properties": { + "depart": { + "format": "date-time", + "type": "string" + }, + "flight_id": { + "pattern": "^[0-9A-Z]{2}-[0-9]{4}$", + "type": "string" + }, + "from": { + "pattern": "^[A-Z]{3}$", + "type": "string" + }, + "passenger_count": { + "minimum": 1, + "type": "integer" + }, + "seats_left": { + "minimum": 0, + "type": "integer" + }, + "to": { + "pattern": "^[A-Z]{3}$", + "type": "string" + }, + "total_fare_inr": { + "minimum": 0, + "type": "integer" + } + }, + "required": ["flight_id", "from", "to", "depart", "total_fare_inr", "seats_left", "passenger_count"], + "title": "Airline search result (v3)", + "type": "object" +} diff --git a/data/api_schemas/cab/v1.json b/data/api_schemas/cab/v1.json new file mode 100644 index 0000000000000000000000000000000000000000..12edd7ad0f67dc3833151c655a6e0972511a7ee5 --- /dev/null +++ b/data/api_schemas/cab/v1.json @@ -0,0 +1,31 @@ +{ + "$comment": "SPDX-License-Identifier: Apache-2.0. Copyright 2026 DriftCall Team. Cab v1 baseline per DESIGN.md §5.2.", + "$id": "https://driftcall.dev/schemas/cab/v1.json", + "$schema": "https://json-schema.org/draft/2020-12/schema", + "additionalProperties": false, + "properties": { + "drop": { + "minLength": 1, + "type": "string" + }, + "eta_min": { + "minimum": 0, + "type": "integer" + }, + "fare_inr": { + "minimum": 0, + "type": "integer" + }, + "pickup": { + "minLength": 1, + "type": "string" + }, + "vehicle_class": { + "enum": ["mini", "sedan"], + "type": "string" + } + }, + "required": ["pickup", "drop", "vehicle_class", "fare_inr", "eta_min"], + "title": "Cab estimate (v1)", + "type": "object" +} diff --git a/data/api_schemas/cab/v2.json b/data/api_schemas/cab/v2.json new file mode 100644 index 0000000000000000000000000000000000000000..c4339ddfd2908df1a887ff4ce242424847f6f263 --- /dev/null +++ b/data/api_schemas/cab/v2.json @@ -0,0 +1,31 @@ +{ + "$comment": "SPDX-License-Identifier: Apache-2.0. Copyright 2026 DriftCall Team. Cab v2 after vehicle_class_expand / school_hours_mini_reject per DESIGN.md §5.2.", + "$id": "https://driftcall.dev/schemas/cab/v2.json", + "$schema": "https://json-schema.org/draft/2020-12/schema", + "additionalProperties": false, + "properties": { + "drop": { + "minLength": 1, + "type": "string" + }, + "eta_min": { + "minimum": 0, + "type": "integer" + }, + "fare_inr": { + "minimum": 0, + "type": "integer" + }, + "pickup": { + "minLength": 1, + "type": "string" + }, + "vehicle_class": { + "enum": ["mini", "sedan", "suv", "infant_seat_sedan"], + "type": "string" + } + }, + "required": ["pickup", "drop", "vehicle_class", "fare_inr", "eta_min"], + "title": "Cab estimate (v2)", + "type": "object" +} diff --git a/data/api_schemas/cab/v3.json b/data/api_schemas/cab/v3.json new file mode 100644 index 0000000000000000000000000000000000000000..177f9cd7cff756cf090da754e34cdb1049586320 --- /dev/null +++ b/data/api_schemas/cab/v3.json @@ -0,0 +1,42 @@ +{ + "$comment": "SPDX-License-Identifier: Apache-2.0. Copyright 2026 DriftCall Team. Cab v3 after fare_breakdown drift per DESIGN.md §5.2.", + "$id": "https://driftcall.dev/schemas/cab/v3.json", + "$schema": "https://json-schema.org/draft/2020-12/schema", + "additionalProperties": false, + "properties": { + "drop": { + "minLength": 1, + "type": "string" + }, + "eta_min": { + "minimum": 0, + "type": "integer" + }, + "fare_breakdown": { + "additionalProperties": false, + "properties": { + "base": {"minimum": 0, "type": "integer"}, + "gst": {"minimum": 0, "type": "integer"}, + "surge": {"minimum": 0, "type": "integer"}, + "tolls": {"minimum": 0, "type": "integer"} + }, + "required": ["base", "surge", "tolls", "gst"], + "type": "object" + }, + "pickup": { + "minLength": 1, + "type": "string" + }, + "total_inr": { + "minimum": 0, + "type": "integer" + }, + "vehicle_class": { + "enum": ["mini", "sedan", "suv", "infant_seat_sedan"], + "type": "string" + } + }, + "required": ["pickup", "drop", "vehicle_class", "fare_breakdown", "total_inr", "eta_min"], + "title": "Cab estimate (v3)", + "type": "object" +} diff --git a/data/api_schemas/hotel/v1.json b/data/api_schemas/hotel/v1.json new file mode 100644 index 0000000000000000000000000000000000000000..bd8eeb25e1974e44a2b957683dd1f1ff44973e5e --- /dev/null +++ b/data/api_schemas/hotel/v1.json @@ -0,0 +1,39 @@ +{ + "$comment": "SPDX-License-Identifier: Apache-2.0. Copyright 2026 DriftCall Team. Hotel v1 baseline per DESIGN.md §5.4.", + "$id": "https://driftcall.dev/schemas/hotel/v1.json", + "$schema": "https://json-schema.org/draft/2020-12/schema", + "additionalProperties": false, + "properties": { + "cancel_window_hours": { + "minimum": 0, + "type": "integer" + }, + "checkin": { + "format": "date", + "type": "string" + }, + "checkout": { + "format": "date", + "type": "string" + }, + "city": { + "minLength": 1, + "type": "string" + }, + "hotel_id": { + "minLength": 1, + "type": "string" + }, + "nightly_rate": { + "minimum": 0, + "type": "integer" + }, + "total_with_tax": { + "minimum": 0, + "type": "integer" + } + }, + "required": ["hotel_id", "city", "checkin", "checkout", "nightly_rate", "total_with_tax", "cancel_window_hours"], + "title": "Hotel booking (v1)", + "type": "object" +} diff --git a/data/api_schemas/hotel/v2.json b/data/api_schemas/hotel/v2.json new file mode 100644 index 0000000000000000000000000000000000000000..df271bf38167919f984939bf934df1109452d88d --- /dev/null +++ b/data/api_schemas/hotel/v2.json @@ -0,0 +1,43 @@ +{ + "$comment": "SPDX-License-Identifier: Apache-2.0. Copyright 2026 DriftCall Team. Hotel v2 after cancel_window_shrink / resort_fee_append per DESIGN.md §5.4.", + "$id": "https://driftcall.dev/schemas/hotel/v2.json", + "$schema": "https://json-schema.org/draft/2020-12/schema", + "additionalProperties": false, + "properties": { + "cancel_window_hours": { + "const": 6, + "type": "integer" + }, + "checkin": { + "format": "date", + "type": "string" + }, + "checkout": { + "format": "date", + "type": "string" + }, + "city": { + "minLength": 1, + "type": "string" + }, + "hotel_id": { + "minLength": 1, + "type": "string" + }, + "nightly_rate": { + "minimum": 0, + "type": "integer" + }, + "resort_fee_inr": { + "minimum": 0, + "type": "integer" + }, + "total_with_tax": { + "minimum": 0, + "type": "integer" + } + }, + "required": ["hotel_id", "city", "checkin", "checkout", "nightly_rate", "total_with_tax", "cancel_window_hours", "resort_fee_inr"], + "title": "Hotel booking (v2)", + "type": "object" +} diff --git a/data/api_schemas/hotel/v3.json b/data/api_schemas/hotel/v3.json new file mode 100644 index 0000000000000000000000000000000000000000..590934a1ebd104f8d1c9580873203a48071dbfae --- /dev/null +++ b/data/api_schemas/hotel/v3.json @@ -0,0 +1,47 @@ +{ + "$comment": "SPDX-License-Identifier: Apache-2.0. Copyright 2026 DriftCall Team. Hotel v3 after gst_field drift per DESIGN.md §5.4.", + "$id": "https://driftcall.dev/schemas/hotel/v3.json", + "$schema": "https://json-schema.org/draft/2020-12/schema", + "additionalProperties": false, + "properties": { + "cancel_window_hours": { + "const": 6, + "type": "integer" + }, + "checkin": { + "format": "date", + "type": "string" + }, + "checkout": { + "format": "date", + "type": "string" + }, + "city": { + "minLength": 1, + "type": "string" + }, + "gst_number": { + "pattern": "^[0-9]{2}[A-Z]{5}[0-9]{4}[A-Z][1-9A-Z]Z[0-9A-Z]$", + "type": "string" + }, + "hotel_id": { + "minLength": 1, + "type": "string" + }, + "nightly_rate": { + "minimum": 0, + "type": "integer" + }, + "resort_fee_inr": { + "minimum": 0, + "type": "integer" + }, + "total_with_tax": { + "minimum": 0, + "type": "integer" + } + }, + "required": ["hotel_id", "city", "checkin", "checkout", "nightly_rate", "total_with_tax", "cancel_window_hours", "resort_fee_inr", "gst_number"], + "title": "Hotel booking (v3)", + "type": "object" +} diff --git a/data/api_schemas/payment/v1.json b/data/api_schemas/payment/v1.json new file mode 100644 index 0000000000000000000000000000000000000000..58d2b84a8df1bd91271579fb4721b1d2cab0a62e --- /dev/null +++ b/data/api_schemas/payment/v1.json @@ -0,0 +1,31 @@ +{ + "$comment": "SPDX-License-Identifier: Apache-2.0. Copyright 2026 DriftCall Team. Payment v1 baseline per DESIGN.md §5.5.", + "$id": "https://driftcall.dev/schemas/payment/v1.json", + "$schema": "https://json-schema.org/draft/2020-12/schema", + "additionalProperties": false, + "properties": { + "amount_inr": { + "minimum": 0, + "type": "integer" + }, + "charge_id": { + "minLength": 1, + "type": "string" + }, + "payment_token": { + "minLength": 1, + "type": "string" + }, + "scope": { + "const": "payments:write:v1", + "type": "string" + }, + "status": { + "enum": ["ok", "auth_error"], + "type": "string" + } + }, + "required": ["charge_id", "amount_inr", "payment_token", "scope", "status"], + "title": "Payment charge (v1)", + "type": "object" +} diff --git a/data/api_schemas/payment/v2.json b/data/api_schemas/payment/v2.json new file mode 100644 index 0000000000000000000000000000000000000000..06d6297fd0e042fdb6df3315cd7812f72d373b43 --- /dev/null +++ b/data/api_schemas/payment/v2.json @@ -0,0 +1,35 @@ +{ + "$comment": "SPDX-License-Identifier: Apache-2.0. Copyright 2026 DriftCall Team. Payment v2 after auth_scope_upgrade / mfa_required per DESIGN.md §5.5.", + "$id": "https://driftcall.dev/schemas/payment/v2.json", + "$schema": "https://json-schema.org/draft/2020-12/schema", + "additionalProperties": false, + "properties": { + "amount_inr": { + "minimum": 0, + "type": "integer" + }, + "charge_id": { + "minLength": 1, + "type": "string" + }, + "mfa_code": { + "minLength": 1, + "type": "string" + }, + "payment_token": { + "minLength": 1, + "type": "string" + }, + "scope": { + "const": "payments:write:v2", + "type": "string" + }, + "status": { + "enum": ["ok", "auth_error"], + "type": "string" + } + }, + "required": ["charge_id", "amount_inr", "payment_token", "scope", "status"], + "title": "Payment charge (v2)", + "type": "object" +} diff --git a/data/api_schemas/restaurant/v1.json b/data/api_schemas/restaurant/v1.json new file mode 100644 index 0000000000000000000000000000000000000000..090cd1cffbbea82230856f18b8d0b72956f1c41c --- /dev/null +++ b/data/api_schemas/restaurant/v1.json @@ -0,0 +1,41 @@ +{ + "$comment": "SPDX-License-Identifier: Apache-2.0. Copyright 2026 DriftCall Team. Restaurant v1 baseline per DESIGN.md §5.3.", + "$id": "https://driftcall.dev/schemas/restaurant/v1.json", + "$schema": "https://json-schema.org/draft/2020-12/schema", + "additionalProperties": false, + "properties": { + "eta_min": { + "minimum": 0, + "type": "integer" + }, + "items": { + "items": { + "additionalProperties": false, + "properties": { + "dish_id": {"minLength": 1, "type": "string"}, + "price": {"minimum": 0, "type": "integer"}, + "qty": {"minimum": 1, "type": "integer"} + }, + "required": ["dish_id", "qty", "price"], + "type": "object" + }, + "minItems": 1, + "type": "array" + }, + "min_order_inr": { + "minimum": 0, + "type": "integer" + }, + "restaurant_id": { + "minLength": 1, + "type": "string" + }, + "total": { + "minimum": 0, + "type": "integer" + } + }, + "required": ["restaurant_id", "items", "total", "eta_min", "min_order_inr"], + "title": "Restaurant order (v1)", + "type": "object" +} diff --git a/data/api_schemas/restaurant/v2.json b/data/api_schemas/restaurant/v2.json new file mode 100644 index 0000000000000000000000000000000000000000..91c92647d511b06948e192a3d15c8e035ee6ab97 --- /dev/null +++ b/data/api_schemas/restaurant/v2.json @@ -0,0 +1,41 @@ +{ + "$comment": "SPDX-License-Identifier: Apache-2.0. Copyright 2026 DriftCall Team. Restaurant v2 after min_order_bump per DESIGN.md §5.3.", + "$id": "https://driftcall.dev/schemas/restaurant/v2.json", + "$schema": "https://json-schema.org/draft/2020-12/schema", + "additionalProperties": false, + "properties": { + "eta_min": { + "minimum": 0, + "type": "integer" + }, + "items": { + "items": { + "additionalProperties": false, + "properties": { + "dish_id": {"minLength": 1, "type": "string"}, + "price": {"minimum": 0, "type": "integer"}, + "qty": {"minimum": 1, "type": "integer"} + }, + "required": ["dish_id", "qty", "price"], + "type": "object" + }, + "minItems": 1, + "type": "array" + }, + "min_order_inr": { + "const": 299, + "type": "integer" + }, + "restaurant_id": { + "minLength": 1, + "type": "string" + }, + "total": { + "minimum": 0, + "type": "integer" + } + }, + "required": ["restaurant_id", "items", "total", "eta_min", "min_order_inr"], + "title": "Restaurant order (v2)", + "type": "object" +} diff --git a/data/api_schemas/restaurant/v3.json b/data/api_schemas/restaurant/v3.json new file mode 100644 index 0000000000000000000000000000000000000000..91f78faecb4521f674be3df1b267e09f1d3fe9bc --- /dev/null +++ b/data/api_schemas/restaurant/v3.json @@ -0,0 +1,45 @@ +{ + "$comment": "SPDX-License-Identifier: Apache-2.0. Copyright 2026 DriftCall Team. Restaurant v3 after items_shape_bump / veg_filter_semantic per DESIGN.md §5.3.", + "$id": "https://driftcall.dev/schemas/restaurant/v3.json", + "$schema": "https://json-schema.org/draft/2020-12/schema", + "additionalProperties": false, + "properties": { + "eta_min": { + "minimum": 0, + "type": "integer" + }, + "items": { + "items": { + "additionalProperties": false, + "properties": { + "dish_id": {"minLength": 1, "type": "string"}, + "modifiers": { + "items": {"type": "string"}, + "type": "array" + }, + "price": {"minimum": 0, "type": "integer"}, + "qty": {"minimum": 1, "type": "integer"} + }, + "required": ["dish_id", "qty", "price", "modifiers"], + "type": "object" + }, + "minItems": 1, + "type": "array" + }, + "min_order_inr": { + "const": 299, + "type": "integer" + }, + "restaurant_id": { + "minLength": 1, + "type": "string" + }, + "total": { + "minimum": 0, + "type": "integer" + } + }, + "required": ["restaurant_id", "items", "total", "eta_min", "min_order_inr"], + "title": "Restaurant order (v3)", + "type": "object" +} diff --git a/data/drift_patterns/drifts.yaml b/data/drift_patterns/drifts.yaml new file mode 100644 index 0000000000000000000000000000000000000000..a14a36fb3b2fbc6b86977d12746c337674e0fa35 --- /dev/null +++ b/data/drift_patterns/drifts.yaml @@ -0,0 +1,303 @@ +# SPDX-License-Identifier: Apache-2.0 +# Copyright 2026 DriftCall Team +# Authoritative catalogue: 20 drift patterns per DESIGN.md §6.3 and +# docs/modules/drift_injector.md §4.4 (5 schema + 5 policy + 5 T&C + 3 pricing +# + 2 transversal payment-auth). +# Every id MUST match drift_injector.md §4.4 exactly. +# Every from_version / to_version MUST be a v.json under data/api_schemas//. +# detection_hints are substring-matchable tokens (DESIGN.md §6.3). + +# --- Schema drifts (5) ------------------------------------------------------- + +- id: airline.price_rename + drift_type: schema + domain: airline + from_version: v1 + to_version: v2 + description: "field 'price' renamed to 'total_fare_inr'; 'currency' removed" + mutation: + rename: {price: total_fare_inr} + remove: [currency] + detection_hints: + - total_fare_inr + - price + - rename + +- id: airline.pax_required + drift_type: schema + domain: airline + from_version: v2 + to_version: v3 + description: "booking now requires 'passenger_count' field" + mutation: + require_new_field: [passenger_count] + detection_hints: + - passenger_count + - MISSING_PASSENGER_COUNT + - passenger + +- id: cab.fare_breakdown + drift_type: schema + domain: cab + from_version: v2 + to_version: v3 + description: "field 'fare_inr' replaced by nested 'fare_breakdown' with base/surge/tolls/gst" + mutation: + remove: [fare_inr] + require_new_field: [fare_breakdown, total_inr] + detection_hints: + - fare_breakdown + - base + - surge + - tolls + - gst + +- id: restaurant.items_shape_bump + drift_type: schema + domain: restaurant + from_version: v2 + to_version: v3 + description: "each item in 'items' now requires a 'modifiers' list (empty allowed)" + mutation: + require_new_field: [modifiers] + detection_hints: + - modifiers + - INVALID_ITEMS_SHAPE + - items + +- id: hotel.gst_field + drift_type: schema + domain: hotel + from_version: v2 + to_version: v3 + description: "hotel.book now requires 'gst_number' when total_with_tax > 7500" + mutation: + require_new_field: [gst_number] + detection_hints: + - gst_number + - MISSING_GST_NUMBER + - GST_REQUIRED + +# --- Policy drifts (5) ------------------------------------------------------- + +- id: airline.booking_window_shrink + drift_type: policy + domain: airline + from_version: v1 + to_version: v2 + description: "same-day bookings rejected after 14:00 IST (was: same-day always allowed)" + mutation: + time_window_shrink: {same_day_cutoff_hour_ist: 14} + detection_hints: + - BOOKING_WINDOW_CLOSED + - booking_window + - "14:00" + - same-day + +- id: cab.school_hours_mini_reject + drift_type: policy + domain: cab + from_version: v1 + to_version: v2 + description: "vehicle_class=mini during 07:00-09:00 IST now auto-rejects with policy_error" + mutation: + policy_flag_flip: {mini_reject_school_hours: true} + detection_hints: + - SCHOOL_HOURS_MINI_REJECTED + - school_hours + - mini + - "07:00" + +- id: restaurant.min_order_bump + drift_type: policy + domain: restaurant + from_version: v1 + to_version: v2 + description: "minimum order amount increased from 199 to 299" + mutation: + numeric_bump: {min_order_inr: 299} + detection_hints: + - MIN_ORDER_NOT_MET + - min_order + - "299" + +- id: hotel.cancel_window_shrink + drift_type: policy + domain: hotel + from_version: v1 + to_version: v2 + description: "free cancellation window shrunk from 24h to 6h before check-in" + mutation: + time_window_shrink: {cancel_window_hours: 6} + detection_hints: + - CANCEL_WINDOW_EXPIRED + - cancel_window + - 6h + - 24h + +- id: cab.vehicle_class_expand + drift_type: policy + domain: cab + from_version: v1 + to_version: v2 + description: "vehicle_class enum expanded to include 'suv' and 'infant_seat_sedan'" + mutation: + enum_expand: + vehicle_class: [mini, sedan, suv, infant_seat_sedan] + detection_hints: + - vehicle_class + - suv + - infant_seat_sedan + - VEHICLE_CLASS_UNAVAILABLE + +# --- T&C drifts (5) --------------------------------------------------------- + +- id: airline.baggage_tnc_rewrite + drift_type: tnc + domain: airline + from_version: v1 + to_version: v2 + description: "free cabin allowance reduced from 7kg to 5kg; announced via side-channel notice" + mutation: + tnc_text_swap: {cabin_allowance_kg: 5} + side_channel_notice_append: "Baggage T&C updated: free cabin allowance is now 5kg (was 7kg)." + detection_hints: + - cabin_allowance + - 5kg + - 7kg + - baggage + +- id: cab.surge_policy_tnc + drift_type: tnc + domain: cab + from_version: v1 + to_version: v2 + description: "surge may now apply retroactively if ride is extended; side-channel notice" + mutation: + tnc_text_swap: {surge_retroactive: true} + side_channel_notice_append: "Surge policy updated: retroactive surge may apply if ride is extended." + detection_hints: + - surge + - retroactive + - surge_retroactive + +- id: restaurant.veg_filter_semantic + drift_type: tnc + domain: restaurant + from_version: v2 + to_version: v3 + description: "veg_only=True now excludes egg-based dishes (previously included)" + mutation: + # Two coupled keys: veg_only_excludes_egg is the new boolean policy flag + # introduced in v3; veg_only is the user-facing slot whose semantics are + # being mutated by this drift (same field, different meaning). Templates + # tag the live slot (veg_only) — keep both so the slot_tag is targetable + # AND the policy-flag audit trail is preserved. + tnc_text_swap: {veg_only_excludes_egg: true, veg_only: "semantics_egg_excluded"} + side_channel_notice_append: "Semantics update: veg_only=True now excludes egg-based dishes." + detection_hints: + - veg_only + - egg + - semantic + +- id: hotel.early_checkin_tnc + drift_type: tnc + domain: hotel + from_version: v1 + to_version: v2 + description: "early check-in before 12:00 now billed at 50% of nightly rate; side-channel" + mutation: + tnc_text_swap: {early_checkin_fee_pct: 50} + side_channel_notice_append: "Early check-in before 12:00 now costs 50% of nightly rate." + detection_hints: + - early_checkin + - 50% + - "12:00" + - nightly + +- id: airline.reschedule_tnc + drift_type: tnc + domain: airline + from_version: v2 + to_version: v3 + description: "reschedule fee previously waived; now 10% of fare + side-channel text" + mutation: + tnc_text_swap: {reschedule_fee_pct: 10} + side_channel_notice_append: "Reschedule fee policy updated: 10% of fare applies." + detection_hints: + - reschedule + - 10% + - fare + +# --- Pricing drifts (3) ----------------------------------------------------- + +- id: airline.convenience_fee_append + drift_type: pricing + domain: airline + from_version: v1 + to_version: v2 + description: "hidden 199 INR convenience fee added at booking; search estimate unchanged" + mutation: + fee_append: {convenience_fee_inr: 199} + detection_hints: + - convenience_fee + - "199" + - hidden + +- id: cab.toll_unbundle + drift_type: pricing + domain: cab + from_version: v1 + to_version: v2 + description: "tolls previously included; now a separate line item on booking, not estimate" + mutation: + pricing_restructure: {toll_bundled: false} + detection_hints: + - toll + - tolls + - unbundle + +- id: hotel.resort_fee_append + drift_type: pricing + domain: hotel + from_version: v1 + to_version: v2 + description: "500 INR/night resort fee added at booking; not shown in nightly_rate" + mutation: + fee_append: {resort_fee_inr: 500} + detection_hints: + - resort_fee + - "500" + - resort + +# --- Auth drifts (2, transversal via payment) ------------------------------- + +- id: payment.auth_scope_upgrade + drift_type: auth + domain: payment + from_version: v1 + to_version: v2 + description: "token_v1 now returns 401; requires token_v2 with scope=payments:write:v2" + mutation: + auth_scope_bump: {required_scope: "payments:write:v2"} + token_version_bump: {accepted_token_version: v2} + detection_hints: + - AUTH_SCOPE_INSUFFICIENT + - scope + - token_v2 + - "payments:write:v2" + +- id: payment.mfa_required + drift_type: auth + domain: payment + from_version: v1 + to_version: v2 + description: "transactions > 5000 INR now require mfa_code; auth_error with MFA_REQUIRED (payment v1 → v2, alternative auth-tightening to auth_scope_upgrade triggered by amount rather than scope)" + mutation: + policy_flag_flip: {mfa_required: true} + numeric_bump: {mfa_threshold_inr: 5000} + detection_hints: + - MFA_REQUIRED + - mfa_code + - mfa + - "5000" diff --git a/data/task_briefs/i18n.yaml b/data/task_briefs/i18n.yaml new file mode 100644 index 0000000000000000000000000000000000000000..f31bced98996d6d4a1a132d0b38b1fcc795a3d6d --- /dev/null +++ b/data/task_briefs/i18n.yaml @@ -0,0 +1,208 @@ +# SPDX-License-Identifier: Apache-2.0 +# Copyright 2026 DriftCall Team +# Localized lookup table for cities, weekdays, months, time-of-day phrases, +# and passenger labels used by task_generator. All values NFC-normalized. +# Keys are LanguageCode = {hi,ta,kn,en,hinglish}. City codes are IATA where +# applicable; otherwise domain-local neighborhood names. Every key that +# appears in any language MUST appear in every language (enforced by +# tests/test_data_consistency.py::test_i18n_keys_complete_across_langs). + +hi: + # Cities (IATA / common name) + BLR: बेंगलुरु + HYD: हैदराबाद + BOM: मुंबई + DEL: दिल्ली + MAA: चेन्नई + CCU: कोलकाता + GOI: गोवा + PNQ: पुणे + AMD: अहमदाबाद + COK: कोच्चि + # Weekdays + Monday: सोमवार + Tuesday: मंगलवार + Wednesday: बुधवार + Thursday: गुरुवार + Friday: शुक्रवार + Saturday: शनिवार + Sunday: रविवार + # Months + January: जनवरी + February: फरवरी + March: मार्च + April: अप्रैल + May: मई + June: जून + July: जुलाई + August: अगस्त + September: सितंबर + October: अक्टूबर + November: नवंबर + December: दिसंबर + # Time-of-day phrases + morning: सुबह + afternoon: दोपहर + evening: शाम + night: रात + late_night: देर रात + # Passenger labels + adult: वयस्क + child: बच्चा + infant: शिशु + +ta: + BLR: பெங்களூர் + HYD: ஹைதராபாத் + BOM: மும்பை + DEL: டெல்லி + MAA: சென்னை + CCU: கொல்கத்தா + GOI: கோவா + PNQ: புணே + AMD: அகமதாபாத் + COK: கொச்சி + Monday: திங்கள் + Tuesday: செவ்வாய் + Wednesday: புதன் + Thursday: வியாழன் + Friday: வெள்ளி + Saturday: சனி + Sunday: ஞாயிறு + January: ஜனவரி + February: பிப்ரவரி + March: மார்ச் + April: ஏப்ரல் + May: மே + June: ஜூன் + July: ஜூலை + August: ஆகஸ்ட் + September: செப்டம்பர் + October: அக்டோபர் + November: நவம்பர் + December: டிசம்பர் + morning: காலை + afternoon: மதியம் + evening: மாலை + night: இரவு + late_night: நள்ளிரவு + adult: வயது வந்தோர் + child: குழந்தை + infant: சேய் + +kn: + BLR: ಬೆಂಗಳೂರು + HYD: ಹೈದರಾಬಾದ್ + BOM: ಮುಂಬೈ + DEL: ದೆಹಲಿ + MAA: ಚೆನ್ನೈ + CCU: ಕೋಲ್ಕತಾ + GOI: ಗೋವಾ + PNQ: ಪುಣೆ + AMD: ಅಹಮದಾಬಾದ್ + COK: ಕೊಚ್ಚಿ + Monday: ಸೋಮವಾರ + Tuesday: ಮಂಗಳವಾರ + Wednesday: ಬುಧವಾರ + Thursday: ಗುರುವಾರ + Friday: ಶುಕ್ರವಾರ + Saturday: ಶನಿವಾರ + Sunday: ಭಾನುವಾರ + January: ಜನವರಿ + February: ಫೆಬ್ರವರಿ + March: ಮಾರ್ಚ್ + April: ಏಪ್ರಿಲ್ + May: ಮೇ + June: ಜೂನ್ + July: ಜುಲೈ + August: ಆಗಸ್ಟ್ + September: ಸೆಪ್ಟೆಂಬರ್ + October: ಅಕ್ಟೋಬರ್ + November: ನವೆಂಬರ್ + December: ಡಿಸೆಂಬರ್ + morning: ಬೆಳಿಗ್ಗೆ + afternoon: ಮಧ್ಯಾಹ್ನ + evening: ಸಂಜೆ + night: ರಾತ್ರಿ + late_night: ತಡರಾತ್ರಿ + adult: ವಯಸ್ಕ + child: ಮಗು + infant: ಶಿಶು + +en: + BLR: Bangalore + HYD: Hyderabad + BOM: Mumbai + DEL: Delhi + MAA: Chennai + CCU: Kolkata + GOI: Goa + PNQ: Pune + AMD: Ahmedabad + COK: Kochi + Monday: Monday + Tuesday: Tuesday + Wednesday: Wednesday + Thursday: Thursday + Friday: Friday + Saturday: Saturday + Sunday: Sunday + January: January + February: February + March: March + April: April + May: May + June: June + July: July + August: August + September: September + October: October + November: November + December: December + morning: morning + afternoon: afternoon + evening: evening + night: night + late_night: late night + adult: adult + child: child + infant: infant + +hinglish: + BLR: Bangalore + HYD: Hyderabad + BOM: Mumbai + DEL: Delhi + MAA: Chennai + CCU: Kolkata + GOI: Goa + PNQ: Pune + AMD: Ahmedabad + COK: Kochi + Monday: Monday + Tuesday: Tuesday + Wednesday: Wednesday + Thursday: Thursday + Friday: Friday + Saturday: Saturday + Sunday: Sunday + January: January + February: February + March: March + April: April + May: May + June: June + July: July + August: August + September: September + October: October + November: November + December: December + morning: subah + afternoon: dopahar + evening: shaam + night: raat + late_night: late raat + adult: adult + child: bachcha + infant: chhota baby diff --git a/data/task_briefs/templates.yaml b/data/task_briefs/templates.yaml new file mode 100644 index 0000000000000000000000000000000000000000..69bbe1e3cc630d8e51187c67d95c572c246ca9f6 --- /dev/null +++ b/data/task_briefs/templates.yaml @@ -0,0 +1,515 @@ +# SPDX-License-Identifier: Apache-2.0 +# Copyright 2026 DriftCall Team +# Derived-from: AmazonScience/MASSIVE (intent taxonomy, Apache-2.0); inspirations +# from google/schema_guided_dstc8 and facebook/mtop (no verbatim rows). +# Task brief templates for DriftCall. Each template provides ≥ 2 variants per +# Indic LanguageCode (hi, ta, kn) and ≥ 2 per hinglish/en. All strings are +# NFC-normalized. Domain ∈ {airline, cab, restaurant, hotel}. +# +# Payment is a TRANSVERSAL-ONLY domain — it is exposed by the env as a +# 2nd-leg auth side-effect (token issuance, MFA enforcement) and is NEVER +# the primary domain of a goal template. Auth drifts (payment.auth_scope_*, +# payment.mfa_required) are exempt from per-domain drift_slot_tags coverage +# (see docs/modules/datasets.md §3.5 invariant #4). Adding a primary +# template with `domain: payment` is a contract violation enforced by +# tests/test_data_consistency.py::test_payment_is_transversal_only. +# +# Stage budget: at least one template per min_stage ∈ {1, 2, 3} (curriculum +# coverage, enforced by test_stage_coverage). Stage-2 templates introduce +# layered constraints (compound time + class + budget); Stage-3 templates +# introduce passenger/multi-leg compounds. + +# ===== AIRLINE (4 templates) ================================================= + +- template_id: airline.book.budget_timewindow + domain: airline + intent: book_flight + min_stage: 1 + required_slots: [from, to, when] + optional_slots: [seat_pref] + constraints_template: + budget_inr: + distribution: uniform + low: 3000 + high: 15000 + step: 500 + time_window: + choices: [morning, afternoon, evening, late_night] + drift_slot_tags: [price, total_fare_inr, passenger_count] + language_variants: + hinglish: + - "Bhai {when} ko {to} jaana hai, cheapest flight {time_window} mein, {budget_inr} rupees max" + - "{when} ko {from} se {to} ka ticket book kar de, under {budget_inr}, {time_window} ke baad" + hi: + - "मुझे {when} को {from} से {to} जाना है, {budget_inr} रुपये से कम में, {time_window} में" + - "{when} को {from} से {to} की सस्ती फ्लाइट चाहिए, {budget_inr} के अंदर, {time_window} वाली" + ta: + - "{when} அன்று {from} லிருந்து {to} க்கு டிக்கெட் வேண்டும், {budget_inr} ரூபாய்க்கு கீழ், {time_window} நேரத்தில்" + - "{when} அன்று {from} இல் இருந்து {to} க்கு மலிவான விமான டிக்கெட் புக் செய்யுங்கள், {budget_inr} ரூபாய்க்குள், {time_window} ல்" + kn: + - "{when} ರಂದು {from} ಇಂದ {to} ಗೆ ಅಗ್ಗದ ವಿಮಾನ ಟಿಕೆಟ್ ಬೇಕು, {budget_inr} ರೂಪಾಯಿಗಳ ಒಳಗೆ, {time_window}" + - "{when} ರಂದು {from} ಇಂದ {to} ಗೆ {time_window} ಫ್ಲೈಟ್ ಬುಕ್ ಮಾಡಿ, {budget_inr} ರೂಪಾಯಿಗಳ ಒಳಗೆ" + en: + - "Book the cheapest flight from {from} to {to} on {when}, budget under {budget_inr}, departing {time_window}" + - "I need a {time_window} flight from {from} to {to} on {when} for under {budget_inr}" + +- template_id: airline.book.compound_passenger_budget + domain: airline + intent: book_flight + min_stage: 3 + required_slots: [from, to, when] + optional_slots: [seat_pref] + constraints_template: + budget_inr: + distribution: uniform + low: 5000 + high: 25000 + step: 500 + passenger_count: + choices: ["1", "2", "3", "4"] + time_window: + choices: [morning, afternoon, evening, late_night] + drift_slot_tags: [price, total_fare_inr, passenger_count, convenience_fee_inr] + language_variants: + hinglish: + - "Bhai {when} ko {from} se {to} {passenger_count} log, {budget_inr} ke andar, {time_window} flight" + - "{passenger_count} passengers ke liye {when} ko {from}-{to} flight chahiye, {time_window} mein, {budget_inr} se kam" + hi: + - "{when} को {from} से {to} {passenger_count} यात्री, {budget_inr} रुपये से कम में, {time_window} में" + - "{passenger_count} लोगों के लिए {when} को {from} से {to} फ्लाइट बुक करो, {time_window}, {budget_inr} के अंदर" + ta: + - "{when} அன்று {from} லிருந்து {to} {passenger_count} பயணிகள், {budget_inr} ரூபாய்க்கு கீழ், {time_window}" + - "{passenger_count} பேருக்கு {when} அன்று {from} இல் இருந்து {to} விமானம் வேண்டும், {time_window}, {budget_inr} ரூபாய்க்குள்" + kn: + - "{when} ರಂದು {from} ಇಂದ {to} {passenger_count} ಪ್ರಯಾಣಿಕರು, {budget_inr} ಒಳಗೆ, {time_window}" + - "{passenger_count} ಜನರಿಗೆ {when} ರಂದು {from} ಇಂದ {to} ಫ್ಲೈಟ್ ಬೇಕು, {time_window}, {budget_inr} ಒಳಗೆ" + en: + - "Book flight from {from} to {to} on {when} for {passenger_count} passengers, under {budget_inr}, {time_window}" + - "Need {passenger_count}-passenger flight {from}-{to} on {when}, {time_window} departure, budget {budget_inr}" + +- template_id: airline.book.return_trip + domain: airline + intent: book_flight + min_stage: 2 + required_slots: [from, to, when, return_when] + optional_slots: [seat_pref] + constraints_template: + budget_inr: + distribution: uniform + low: 6000 + high: 22000 + step: 500 + time_window: + choices: [morning, afternoon, evening, late_night] + drift_slot_tags: [price, total_fare_inr, convenience_fee_inr] + language_variants: + hinglish: + - "{when} ko {from} se {to} jaana, {return_when} ko wapas, return flight {time_window} mein, {budget_inr} ke andar" + - "Round trip chahiye {from}-{to}, jana {when} aur wapsi {return_when}, {time_window}, max {budget_inr}" + hi: + - "{when} को {from} से {to} जाना है और {return_when} को वापसी, {time_window} में, {budget_inr} के अंदर" + - "राउंड ट्रिप टिकट चाहिए {from} से {to}, जाना {when}, वापसी {return_when}, {budget_inr} रुपये से कम" + ta: + - "{when} அன்று {from} இல் இருந்து {to} போய், {return_when} திரும்பி, {time_window} ல், {budget_inr} ரூபாய்க்குள்" + - "சுற்றுப்பயண டிக்கெட் வேண்டும் {from} {to}, போக {when} திரும்ப {return_when}, அதிகபட்சம் {budget_inr}" + kn: + - "{when} ರಂದು {from} ಇಂದ {to}, {return_when} ರಂದು ವಾಪಸ್, {time_window}, {budget_inr} ಒಳಗೆ" + - "ರೌಂಡ್ ಟ್ರಿಪ್ ಬೇಕು {from} ಇಂದ {to}, ಹೋಗಲು {when}, ವಾಪಸ್ಸು {return_when}, {budget_inr} ಒಳಗೆ" + en: + - "Round trip {from} to {to}, departing {when}, returning {return_when}, {time_window}, budget {budget_inr}" + - "Book a return flight from {from} to {to} for {when} with return on {return_when}, under {budget_inr}" + +- template_id: airline.reschedule.same_route + domain: airline + intent: book_flight + min_stage: 2 + required_slots: [from, to, when, new_when] + optional_slots: [seat_pref] + constraints_template: + budget_inr: + distribution: uniform + low: 4000 + high: 18000 + step: 500 + time_window: + choices: [morning, afternoon, evening, late_night] + drift_slot_tags: [price, total_fare_inr, reschedule_fee_pct] + language_variants: + hinglish: + - "Mera {from}-{to} ka ticket {when} ka tha, {new_when} pe shift karna hai, {time_window}, {budget_inr} ke under" + - "Reschedule kar de bhai, {from} se {to} ka {when} wala ticket, naya date {new_when}, {budget_inr} max" + hi: + - "{from} से {to} की मेरी {when} की टिकट {new_when} पर रीशेड्यूल करनी है, {time_window} में, {budget_inr} के अंदर" + - "टिकट दूसरे दिन शिफ्ट करनी है, {from}-{to}, पहले {when} थी अब {new_when}, अधिकतम {budget_inr}" + ta: + - "{from} இல் இருந்து {to} க்கு {when} இருந்த என் டிக்கெட்டை {new_when} க்கு மாற்ற வேண்டும், {time_window}, {budget_inr} க்குள்" + - "என் டிக்கெட் தேதி மாற்றுங்கள், {from}-{to}, பழைய {when}, புதிய {new_when}, அதிகபட்சம் {budget_inr}" + kn: + - "{from} ಇಂದ {to} ಗೆ {when} ಇದ್ದ ನನ್ನ ಟಿಕೆಟ್ ಅನ್ನು {new_when} ಗೆ ಬದಲಾಯಿಸಬೇಕು, {time_window}, {budget_inr} ಒಳಗೆ" + - "ಟಿಕೆಟ್ ರೀಶೆಡ್ಯೂಲ್ ಮಾಡಿ, {from}-{to}, ಹಳೆಯ {when}, ಹೊಸ {new_when}, {budget_inr} ಒಳಗೆ" + en: + - "Reschedule my {from}-{to} ticket from {when} to {new_when}, {time_window}, under {budget_inr}" + - "Need to move my {from} to {to} flight from {when} to {new_when}, budget {budget_inr}" + +# ===== CAB (4 templates) ===================================================== + +- template_id: cab.book.airport_pickup + domain: cab + intent: book_cab + min_stage: 1 + required_slots: [pickup, drop, when] + optional_slots: [vehicle_class] + constraints_template: + budget_inr: + distribution: uniform + low: 200 + high: 2000 + step: 50 + vehicle_class: + choices: [mini, sedan, suv, infant_seat_sedan] + drift_slot_tags: [fare_inr, fare_breakdown, vehicle_class] + language_variants: + hinglish: + - "{when} ko {pickup} se {drop} cab book kar, {vehicle_class} chahiye, {budget_inr} ke andar" + - "Bhai {pickup} se {drop} drop chahiye {when} ko, {vehicle_class}, max {budget_inr}" + hi: + - "{when} को {pickup} से {drop} के लिए कैब बुक करो, {vehicle_class} चाहिए, {budget_inr} के अंदर" + - "{pickup} से {drop} {when} को कैब चाहिए, {vehicle_class}, {budget_inr} रुपये से कम" + ta: + - "{when} அன்று {pickup} லிருந்து {drop} க்கு கேப் வேண்டும், {vehicle_class}, {budget_inr} க்குள்" + - "{when} அன்று {pickup} இல் இருந்து {drop} க்கு கேப் புக் செய்யுங்கள், {vehicle_class}, அதிகபட்சம் {budget_inr}" + kn: + - "{when} ರಂದು {pickup} ಇಂದ {drop} ಗೆ ಕ್ಯಾಬ್ ಬುಕ್ ಮಾಡಿ, {vehicle_class}, {budget_inr} ಒಳಗೆ" + - "{pickup} ಇಂದ {drop} ಗೆ {when} ರಂದು ಕ್ಯಾಬ್ ಬೇಕು, {vehicle_class}, {budget_inr} ಒಳಗೆ" + en: + - "Book a cab from {pickup} to {drop} on {when}, {vehicle_class}, under {budget_inr}" + - "Need a {vehicle_class} cab from {pickup} to {drop} on {when}, max {budget_inr}" + +- template_id: cab.book.school_run + domain: cab + intent: book_cab + min_stage: 2 + required_slots: [pickup, drop, when] + optional_slots: [vehicle_class] + constraints_template: + budget_inr: + distribution: uniform + low: 200 + high: 800 + step: 50 + vehicle_class: + choices: [mini, sedan, suv, infant_seat_sedan] + time_window: + choices: [morning, afternoon, evening] + drift_slot_tags: [fare_inr, fare_breakdown, vehicle_class, mini_reject_school_hours] + language_variants: + hinglish: + - "Bachche ke school drop ke liye {when} {time_window} {pickup} se {drop}, {vehicle_class}, {budget_inr} ke andar" + - "School run cab chahiye {when} ko, {pickup} se {drop}, {time_window}, {vehicle_class}, max {budget_inr}" + hi: + - "बच्चे को स्कूल छोड़ने के लिए {when} {time_window} में {pickup} से {drop}, {vehicle_class}, {budget_inr} के अंदर" + - "स्कूल जाने के लिए कैब चाहिए {when} को, {pickup} से {drop}, {time_window} में, {vehicle_class}, {budget_inr}" + ta: + - "குழந்தையை பள்ளியில் விட {when} {time_window} {pickup} இல் இருந்து {drop}, {vehicle_class}, {budget_inr} க்குள்" + - "{when} அன்று பள்ளி நேர கேப் வேண்டும், {pickup} இருந்து {drop}, {time_window}, {vehicle_class}, அதிகபட்சம் {budget_inr}" + kn: + - "ಮಕ್ಕಳನ್ನು ಶಾಲೆಗೆ ಬಿಡಲು {when} {time_window} {pickup} ಇಂದ {drop}, {vehicle_class}, {budget_inr} ಒಳಗೆ" + - "ಶಾಲೆಯ ಸಮಯದ ಕ್ಯಾಬ್ ಬೇಕು {when} ರಂದು, {pickup} ಇಂದ {drop}, {time_window}, {vehicle_class}, {budget_inr} ಒಳಗೆ" + en: + - "School-run cab on {when} {time_window}, from {pickup} to {drop}, {vehicle_class}, under {budget_inr}" + - "Need a cab to drop my child at school on {when} {time_window}, {pickup} to {drop}, {vehicle_class}, max {budget_inr}" + +- template_id: cab.book.outstation + domain: cab + intent: book_cab + min_stage: 2 + required_slots: [pickup, drop, when] + optional_slots: [vehicle_class] + constraints_template: + budget_inr: + distribution: uniform + low: 1500 + high: 8000 + step: 100 + vehicle_class: + choices: [sedan, suv] + drift_slot_tags: [fare_inr, fare_breakdown, toll_bundled, vehicle_class] + language_variants: + hinglish: + - "Outstation cab chahiye {when} ko {pickup} se {drop}, {vehicle_class}, tolls included {budget_inr} ke andar" + - "Bhai {pickup} se {drop} ki long trip {when} ko, {vehicle_class}, max {budget_inr} including tolls" + hi: + - "{when} को {pickup} से {drop} आउटस्टेशन कैब चाहिए, {vehicle_class}, टोल समेत {budget_inr} के अंदर" + - "लंबी यात्रा के लिए कैब बुक करो, {pickup} से {drop}, {when} को, {vehicle_class}, {budget_inr} के अंदर" + ta: + - "{when} அன்று {pickup} இல் இருந்து {drop} வரை அவுட்ஸ்டேஷன் கேப் வேண்டும், {vehicle_class}, டோல் சேர்த்து {budget_inr} க்குள்" + - "{pickup} இல் இருந்து {drop} க்கு நீண்ட பயண கேப் {when} அன்று, {vehicle_class}, அதிகபட்சம் {budget_inr}" + kn: + - "{when} ರಂದು {pickup} ಇಂದ {drop} ಔಟ್‌ಸ್ಟೇಶನ್ ಕ್ಯಾಬ್ ಬೇಕು, {vehicle_class}, ಟೋಲ್ ಸಹಿತ {budget_inr} ಒಳಗೆ" + - "ದೂರದ ಪ್ರಯಾಣಕ್ಕೆ ಕ್ಯಾಬ್ ಬುಕ್ ಮಾಡಿ, {pickup} ಇಂದ {drop}, {when} ರಂದು, {vehicle_class}, {budget_inr} ಒಳಗೆ" + en: + - "Outstation cab on {when} from {pickup} to {drop}, {vehicle_class}, tolls included, under {budget_inr}" + - "Need a long-distance cab {pickup} to {drop} on {when}, {vehicle_class}, total {budget_inr} including tolls" + +- template_id: cab.book.late_night_safe + domain: cab + intent: book_cab + min_stage: 1 + required_slots: [pickup, drop, when, vehicle_class] + optional_slots: [] + constraints_template: + budget_inr: + distribution: uniform + low: 250 + high: 1500 + step: 50 + time_window: + choices: [late_night, night] + vehicle_class: + choices: [sedan, suv] + drift_slot_tags: [fare_inr, fare_breakdown, vehicle_class, surge_retroactive] + language_variants: + hinglish: + - "{when} {time_window} ko {pickup} se {drop} safe cab, {vehicle_class}, {budget_inr} ke andar" + - "Late night ride chahiye {when} ko, {pickup} se {drop}, {vehicle_class}, max {budget_inr}, no surge" + hi: + - "{when} को {time_window} में {pickup} से {drop} सुरक्षित कैब, {vehicle_class}, {budget_inr} के अंदर" + - "देर रात की कैब चाहिए {when} को, {pickup} से {drop}, {vehicle_class}, अधिकतम {budget_inr}" + ta: + - "{when} {time_window} {pickup} இல் இருந்து {drop} பாதுகாப்பான கேப், {vehicle_class}, {budget_inr} க்குள்" + - "இரவு நேர கேப் வேண்டும் {when} அன்று, {pickup} இருந்து {drop}, {vehicle_class}, அதிகபட்சம் {budget_inr}" + kn: + - "{when} {time_window} {pickup} ಇಂದ {drop} ಸುರಕ್ಷಿತ ಕ್ಯಾಬ್, {vehicle_class}, {budget_inr} ಒಳಗೆ" + - "ರಾತ್ರಿಯ ಕ್ಯಾಬ್ ಬೇಕು {when} ರಂದು, {pickup} ಇಂದ {drop}, {vehicle_class}, {budget_inr} ಒಳಗೆ" + en: + - "Late-night cab on {when} {time_window}, {pickup} to {drop}, {vehicle_class}, under {budget_inr}" + - "Need a safe {time_window} cab on {when} from {pickup} to {drop}, {vehicle_class}, max {budget_inr}" + +# ===== RESTAURANT (3 templates) ============================================== + +- template_id: restaurant.order.veg_budget + domain: restaurant + intent: order_food + min_stage: 1 + required_slots: [city, cuisine, when] + optional_slots: [] + slot_distributions: + cuisine: + choices: [Biryani, Dosa, Pizza, Thali, Noodles, Idli, Chaat, Paneer, Roti] + constraints_template: + budget_inr: + distribution: uniform + low: 200 + high: 1500 + step: 50 + veg_only: + choices: ["true", "false"] + drift_slot_tags: [min_order_inr, veg_only, modifiers] + language_variants: + hinglish: + - "Bhai {when} {city} mein {cuisine} order karna hai, {budget_inr} rupees se kam, veg option {veg_only}" + - "{city} mein {cuisine} mangwana hai {when} ko, max {budget_inr}, veg {veg_only}" + hi: + - "{when} {city} में {cuisine} ऑर्डर करना है, {budget_inr} रुपये से कम में, veg_only={veg_only}" + - "{city} में {when} को {cuisine} मंगवाना है, अधिकतम {budget_inr}, शुद्ध शाकाहारी {veg_only}" + ta: + - "{when} {city} இல் {cuisine} ஆர்டர் செய்ய வேண்டும், {budget_inr} ரூபாய்க்கு கீழ், veg_only={veg_only}" + - "{city} இல் {when} அன்று {cuisine} ஆர்டர் செய்யுங்கள், அதிகபட்சம் {budget_inr}, சைவம் {veg_only}" + kn: + - "{when} {city} ನಲ್ಲಿ {cuisine} ಆರ್ಡರ್ ಮಾಡಬೇಕು, {budget_inr} ರೂಪಾಯಿಗಳ ಒಳಗೆ, veg_only={veg_only}" + - "{city} ನಲ್ಲಿ {when} ರಂದು {cuisine} ತರಿಸಬೇಕು, ಗರಿಷ್ಠ {budget_inr}, ಶುದ್ಧ ಸಸ್ಯಾಹಾರಿ {veg_only}" + en: + - "Order {cuisine} in {city} on {when}, budget under {budget_inr}, veg_only={veg_only}" + - "I need {cuisine} delivered in {city} on {when}, max {budget_inr}, vegetarian-only {veg_only}" + +- template_id: restaurant.order.bulk_office + domain: restaurant + intent: order_food + min_stage: 2 + required_slots: [city, cuisine, when] + optional_slots: [] + constraints_template: + budget_inr: + distribution: uniform + low: 1500 + high: 8000 + step: 100 + head_count: + choices: ["5", "8", "10", "15", "20"] + cuisine: + choices: [Biryani, Pizza, Thali, Noodles, Paneer, Roti] + drift_slot_tags: [min_order_inr, modifiers] + language_variants: + hinglish: + - "Office lunch ke liye {head_count} log, {city} mein {cuisine}, {when} ko, {budget_inr} ke andar" + - "{head_count} logon ka bulk order chahiye {city} se, {cuisine} {when} ko, max {budget_inr}" + hi: + - "ऑफिस के {head_count} लोगों के लिए {city} में {cuisine}, {when} को, {budget_inr} के अंदर" + - "{head_count} व्यक्तियों का बल्क ऑर्डर {city} से, {cuisine}, {when} को, अधिकतम {budget_inr}" + ta: + - "அலுவலக மதிய உணவுக்கு {head_count} பேருக்கு, {city} இல் {cuisine}, {when}, {budget_inr} க்குள்" + - "{head_count} பேருக்கான பெரிய ஆர்டர் {city} இல் இருந்து, {cuisine} {when} அன்று, அதிகபட்சம் {budget_inr}" + kn: + - "ಆಫೀಸ್ ಊಟಕ್ಕೆ {head_count} ಜನರಿಗೆ, {city} ನಲ್ಲಿ {cuisine}, {when} ರಂದು, {budget_inr} ಒಳಗೆ" + - "{head_count} ಜನರ ಬೃಹತ್ ಆರ್ಡರ್ {city} ಇಂದ, {cuisine} {when} ರಂದು, ಗರಿಷ್ಠ {budget_inr}" + en: + - "Office lunch for {head_count} people, {cuisine} in {city} on {when}, budget {budget_inr}" + - "Bulk order for {head_count} from {city}, {cuisine}, {when}, max {budget_inr}" + +- template_id: restaurant.order.late_night + domain: restaurant + intent: order_food + min_stage: 1 + required_slots: [city, cuisine, when] + optional_slots: [] + constraints_template: + budget_inr: + distribution: uniform + low: 250 + high: 1200 + step: 50 + time_window: + choices: [night, late_night] + cuisine: + choices: [Biryani, Pizza, Noodles, Chaat, Roti] + drift_slot_tags: [min_order_inr, modifiers] + language_variants: + hinglish: + - "Late night {time_window} ko {city} mein {cuisine} mangwana hai {when} ko, max {budget_inr}" + - "Bhai {time_window} ki bhook lagi, {city} se {cuisine} order karna {when} ko, {budget_inr} ke andar" + hi: + - "देर रात {time_window} को {city} में {cuisine} मंगवाना है {when} को, अधिकतम {budget_inr}" + - "{when} को {time_window} के समय {city} से {cuisine} ऑर्डर करना है, {budget_inr} के अंदर" + ta: + - "இரவு {time_window} ல் {city} இல் {cuisine} {when} அன்று வாங்க வேண்டும், அதிகபட்சம் {budget_inr}" + - "{when} {time_window} ல் {city} இல் இருந்து {cuisine} ஆர்டர், {budget_inr} க்குள்" + kn: + - "ರಾತ್ರಿ {time_window} ಗೆ {city} ನಲ್ಲಿ {cuisine} {when} ರಂದು ಬೇಕು, ಗರಿಷ್ಠ {budget_inr}" + - "{when} {time_window} ಸಮಯದಲ್ಲಿ {city} ಇಂದ {cuisine} ಆರ್ಡರ್, {budget_inr} ಒಳಗೆ" + en: + - "Late-night {time_window} food order on {when}, {cuisine} in {city}, max {budget_inr}" + - "Order {cuisine} in {city} on {when} {time_window}, under {budget_inr}" + +# ===== HOTEL (4 templates) =================================================== + +- template_id: hotel.book.city_nights + domain: hotel + intent: book_hotel + min_stage: 1 + required_slots: [city, checkin, checkout] + optional_slots: [room_type] + constraints_template: + budget_inr: + distribution: uniform + low: 1500 + high: 12000 + step: 500 + drift_slot_tags: [cancel_window_hours, gst_number, resort_fee_inr] + language_variants: + hinglish: + - "Bhai {city} mein hotel chahiye, {checkin} se {checkout} tak, under {budget_inr} per night" + - "{city} ka hotel book kar de {checkin}-{checkout}, max {budget_inr} per raat" + hi: + - "{city} में होटल चाहिए, {checkin} से {checkout} तक, {budget_inr} रुपये प्रति रात से कम में" + - "{checkin} से {checkout} तक {city} में होटल बुक करो, अधिकतम {budget_inr} प्रति रात" + ta: + - "{city} இல் ஹோட்டல் வேண்டும், {checkin} முதல் {checkout} வரை, ஒரு இரவுக்கு {budget_inr} ரூபாய்க்கு கீழ்" + - "{checkin} முதல் {checkout} வரை {city} இல் ஹோட்டல், ஒரு இரவுக்கு அதிகபட்சம் {budget_inr}" + kn: + - "{city} ನಲ್ಲಿ ಹೋಟೆಲ್ ಬೇಕು, {checkin} ಇಂದ {checkout} ವರೆಗೆ, ರಾತ್ರಿಗೆ {budget_inr} ರೂಪಾಯಿ ಒಳಗೆ" + - "{checkin} ಇಂದ {checkout} ವರೆಗೆ {city} ನಲ್ಲಿ ಹೋಟೆಲ್, ರಾತ್ರಿಗೆ ಗರಿಷ್ಠ {budget_inr}" + en: + - "Book a hotel in {city} from {checkin} to {checkout}, under {budget_inr} per night" + - "Need a hotel in {city} from {checkin} to {checkout}, max {budget_inr} per night" + +- template_id: hotel.book.business_gst + domain: hotel + intent: book_hotel + min_stage: 2 + required_slots: [city, checkin, checkout] + optional_slots: [room_type] + constraints_template: + budget_inr: + distribution: uniform + low: 4000 + high: 18000 + step: 500 + drift_slot_tags: [cancel_window_hours, gst_number, early_checkin_fee_pct] + language_variants: + hinglish: + - "Business trip ke liye {city} hotel chahiye, {checkin}-{checkout}, GST invoice ke saath, {budget_inr} per night" + - "{city} mein business hotel book kar do {checkin} se {checkout} tak, GST chahiye, max {budget_inr}" + hi: + - "बिज़नेस ट्रिप के लिए {city} में होटल चाहिए, {checkin}-{checkout}, GST इनवॉइस के साथ, {budget_inr} प्रति रात" + - "{city} में व्यापारिक यात्रा हेतु होटल, {checkin} से {checkout}, GST बिल चाहिए, अधिकतम {budget_inr}" + ta: + - "வணிக பயணத்துக்கு {city} இல் ஹோட்டல், {checkin}-{checkout}, GST விலைப்பட்டியல் சேர்த்து, ஒரு இரவுக்கு {budget_inr}" + - "{city} இல் வணிக ஹோட்டல் புக் செய்யுங்கள் {checkin} முதல் {checkout} வரை, GST வேண்டும், அதிகபட்சம் {budget_inr}" + kn: + - "ವ್ಯಾಪಾರ ಪ್ರಯಾಣಕ್ಕೆ {city} ನಲ್ಲಿ ಹೋಟೆಲ್, {checkin}-{checkout}, GST ಇನ್‌ವಾಯ್ಸ್ ಸಹಿತ, ರಾತ್ರಿಗೆ {budget_inr}" + - "{city} ನಲ್ಲಿ ವ್ಯಾಪಾರ ಹೋಟೆಲ್ ಬುಕ್ {checkin} ಇಂದ {checkout}, GST ಬೇಕು, ಗರಿಷ್ಠ {budget_inr}" + en: + - "Business hotel in {city} from {checkin} to {checkout} with GST invoice, {budget_inr} per night" + - "Need GST-billed hotel in {city}, {checkin}-{checkout}, max {budget_inr} per night" + +- template_id: hotel.book.weekend_resort + domain: hotel + intent: book_hotel + min_stage: 1 + required_slots: [city, checkin, checkout] + optional_slots: [room_type] + constraints_template: + budget_inr: + distribution: uniform + low: 3000 + high: 15000 + step: 500 + drift_slot_tags: [cancel_window_hours, resort_fee_inr] + language_variants: + hinglish: + - "Weekend ke liye {city} mein resort chahiye, {checkin}-{checkout}, {budget_inr} per night max" + - "{city} ka weekend resort book kar de {checkin} se {checkout}, max {budget_inr} per raat" + hi: + - "वीकेंड के लिए {city} में रिसॉर्ट चाहिए, {checkin}-{checkout}, अधिकतम {budget_inr} प्रति रात" + - "{checkin} से {checkout} तक {city} में रिसॉर्ट बुक करो, {budget_inr} रुपये प्रति रात से कम" + ta: + - "வாரஇறுதிக்கு {city} இல் ரிசார்ட் வேண்டும், {checkin}-{checkout}, ஒரு இரவுக்கு அதிகபட்சம் {budget_inr}" + - "{checkin} முதல் {checkout} வரை {city} ரிசார்ட் புக், இரவுக்கு {budget_inr} க்குள்" + kn: + - "ವಾರಾಂತ್ಯಕ್ಕೆ {city} ನಲ್ಲಿ ರೆಸಾರ್ಟ್ ಬೇಕು, {checkin}-{checkout}, ರಾತ್ರಿಗೆ ಗರಿಷ್ಠ {budget_inr}" + - "{checkin} ಇಂದ {checkout} {city} ರೆಸಾರ್ಟ್ ಬುಕ್, ರಾತ್ರಿಗೆ {budget_inr} ಒಳಗೆ" + en: + - "Weekend resort in {city}, {checkin} to {checkout}, max {budget_inr} per night" + - "Book a weekend resort in {city} from {checkin} to {checkout}, under {budget_inr} per night" + +- template_id: hotel.book.cancellable_buffer + domain: hotel + intent: book_hotel + min_stage: 3 + required_slots: [city, checkin, checkout] + optional_slots: [room_type] + constraints_template: + budget_inr: + distribution: uniform + low: 2000 + high: 10000 + step: 500 + cancel_buffer_hours: + choices: ["12", "24", "48"] + drift_slot_tags: [cancel_window_hours, gst_number, resort_fee_inr, early_checkin_fee_pct] + language_variants: + hinglish: + - "{city} hotel chahiye {checkin} se {checkout}, free cancel {cancel_buffer_hours}h pehle, {budget_inr} ke andar" + - "{city} mein hotel {checkin}-{checkout}, cancellation buffer {cancel_buffer_hours} ghante, max {budget_inr}" + hi: + - "{city} होटल चाहिए {checkin} से {checkout}, मुफ्त कैंसल {cancel_buffer_hours} घंटे पहले, {budget_inr} के अंदर" + - "{city} में होटल {checkin} से {checkout} तक, {cancel_buffer_hours} घंटे का कैंसल बफर, अधिकतम {budget_inr}" + ta: + - "{city} ஹோட்டல் வேண்டும் {checkin} முதல் {checkout}, இலவச ரத்து {cancel_buffer_hours} மணி முன், {budget_inr} க்குள்" + - "{city} இல் ஹோட்டல் {checkin}-{checkout}, ரத்து சாளரம் {cancel_buffer_hours} மணி நேரம், அதிகபட்சம் {budget_inr}" + kn: + - "{city} ಹೋಟೆಲ್ ಬೇಕು {checkin} ಇಂದ {checkout}, ಉಚಿತ ರದ್ದು {cancel_buffer_hours} ಗಂಟೆಗೆ ಮೊದಲು, {budget_inr} ಒಳಗೆ" + - "{city} ನಲ್ಲಿ ಹೋಟೆಲ್ {checkin}-{checkout}, ರದ್ದು ಬಫರ್ {cancel_buffer_hours} ಗಂಟೆಗಳು, ಗರಿಷ್ಠ {budget_inr}" + en: + - "Hotel in {city}, {checkin} to {checkout}, free cancel {cancel_buffer_hours}h before, under {budget_inr}" + - "Need {city} hotel {checkin}-{checkout} with {cancel_buffer_hours}h cancellation buffer, max {budget_inr}" diff --git a/openenv.yaml b/openenv.yaml new file mode 100644 index 0000000000000000000000000000000000000000..787a06b5e8b24b52a29280642743655383c19e0d --- /dev/null +++ b/openenv.yaml @@ -0,0 +1,105 @@ +# openenv.yaml — consumed by `openenv validate` +# Schema source: https://github.com/meta-pytorch/OpenEnv (v1.0). +# Deploy spec: docs/modules/deploy_env_space.md §4.3. +schema_version: "1.0" + +env: + id: driftcall + version: "0.1.0" + display_name: "DriftCall — Indic Voice Concierge under Schema Drift" + description: > + OpenEnv-compliant RL environment where a voice-first agent completes Indic + consumer concierge tasks while vendor APIs undergo mid-episode schema, + policy, T&C, pricing, and auth drift. Five independent reward components; + deterministic seeded drift; Hindi/Tamil/Kannada/Hinglish briefs via + Kokoro TTS + faster-whisper ASR. + license: apache-2.0 + tags: + - openenv + - rl + - voice + - indic + - schema-drift + - grpo + + entrypoint: + type: http + base_url: "https://driftcall-driftcall-env.hf.space" + endpoints: + reset: "/reset" + step: "/step" + state: "/state" + close: "/close" + health: "/healthz" + auth: + type: bearer + secret_env: DRIFTCALL_ENV_TOKEN + + action_space: + ref: "cells.step_04_models:DriftCallAction" + + observation_space: + ref: "cells.step_04_models:DriftCallObservation" + + episode: + max_turns: 16 + reset_config: + seed: + type: int + required: false + curriculum_stage: + type: int + range: [1, 3] + required: false + language_weights: + type: object + required: false + audio_boundary_enabled: + type: bool + required: false + + reward: + shape: scalar + range: [-1.0, 1.0] + # The reward function lives in `cells/step_08_rewards.py`. Five independent + # components are computed at episode termination; combined into a quality + # score, calibrated by a Brier penalty + uncertain floor, then clamped. + # Implementation entrypoint: + impl: "cells.step_08_rewards:compute_rewards" + pipeline: + - "cells.step_08_rewards:combine_quality" # weighted mix of R1..R5 + - "cells.step_08_rewards:brier_penalty" # confidence calibration + - "cells.step_08_rewards:apply_uncertain_floor" # 0.50 floor when uncertain + - "cells.step_08_rewards:final_reward" # final scalar in [-1, 1] + components: + - id: R1 + name: task_completion + weight: 0.40 + impl: "cells.step_08_rewards:task_completion" + description: > + Goal achieved (correct booking, payment success, vendor confirmation). + - id: R2 + name: drift_detection + weight: 0.20 + impl: "cells.step_08_rewards:drift_detection" + description: > + Agent detects mid-episode schema/policy/auth drift and adapts. + - id: R3 + name: constraint_adherence + weight: 0.20 + impl: "cells.step_08_rewards:constraint_adherence" + description: > + Honours user constraints (budget, time window, dietary, lang). + - id: R4 + name: format_compliance + weight: 0.10 + impl: "cells.step_08_rewards:format_compliance" + description: > + Tool args parse cleanly against the (possibly drifted) schema. + - id: R5 + name: anti_hack_penalty + weight: 0.10 + impl: "cells.step_08_rewards:anti_hack_penalty" + description: > + Penalty for known reward-hacking patterns flagged in probe set. + docs: "docs/modules/rewards.md" diff --git a/requirements.txt b/requirements.txt new file mode 100644 index 0000000000000000000000000000000000000000..c833284fc503a4062fdcec32015ce4e024fbbc8e --- /dev/null +++ b/requirements.txt @@ -0,0 +1,40 @@ +# DriftCall runtime — flat pin list for the HF Env Space image. +# Mirrors the non-dev subset of pyproject.toml [project.dependencies]. + +# Training stack (training.md §6.1) +unsloth>=2026.4.5 +trl>=0.23 +torch>=2.5 +transformers>=4.51 +peft>=0.13 +bitsandbytes>=0.43 +accelerate>=1.0 +timm>=1.0 + +# OpenEnv + FastAPI (deploy_env_space.md §4.5) +fastapi>=0.115 +uvicorn[standard]>=0.32 +openenv>=0.1.10,<0.2 +pydantic>=2.7 + +# Audio pipeline (audio.md §6.1) +kokoro>=0.3,<0.4 +faster-whisper>=1.0,<2.0 +torchaudio>=2.5 +soundfile>=0.12 +numpy<2.0 + +# Demo UI (deploy_demo_space.md) +gradio>=5.8,<6 + +# Notebook builder (CLAUDE.md §5) +jupytext>=1.16 +nbformat>=5.10 + +# Fixtures / task generator +PyYAML>=6.0 +cachetools>=5.3 +huggingface_hub>=0.25 + +# Experiment tracking (training.md §3.3.3) +wandb>=0.18 diff --git a/site/assets/index-BojZowtY.css b/site/assets/index-BojZowtY.css new file mode 100644 index 0000000000000000000000000000000000000000..4f313347340c4334da0eb4c93e62c3cd2804fa19 --- /dev/null +++ b/site/assets/index-BojZowtY.css @@ -0,0 +1 @@ +:root{--ink-deep: #0a0a0c;--ink-base: #0e0e12;--ink-surface: #14141a;--ink-elevated: #1b1b22;--ink-edge: #262630;--ink-edge-soft: #1a1a22;--paper: #f0eae0;--paper-soft: #d9d3c8;--ash: #a8a29a;--ash-deep: #6e6960;--ash-mute: #4a4640;--saffron: #ff7a17;--saffron-soft: #ffb073;--saffron-deep: #b94f00;--saffron-glow: rgba(255, 122, 23, .38);--rasa-teal: #2cb39d;--rasa-teal-soft: rgba(44, 179, 157, .18);--devanagari-glow: rgba(255, 122, 23, .06);--font-display: "Instrument Serif", "Tiempos Headline", "Cormorant Garamond", Georgia, serif;--font-body: "Geist", "Geist Sans", "Söhne", "Public Sans", system-ui, sans-serif;--font-mono: "Geist Mono", "JetBrains Mono", "IBM Plex Mono", ui-monospace, monospace;--font-devanagari: "Tiro Devanagari Hindi", "Noto Serif Devanagari", serif;--step-xxxl: clamp(5rem, 14vw, 13.5rem);--step-xxl: clamp(3rem, 8vw, 6.5rem);--step-xl: clamp(2rem, 4vw, 3.25rem);--step-l: clamp(1.5rem, 2.5vw, 2.125rem);--step-m: 1.125rem;--step-s: .95rem;--step-xs: .825rem;--step-xxs: .7rem;--gutter: clamp(1.25rem, 4vw, 4rem);--max-width: 1480px;--col-narrow: 720px;--ease-out-quart: cubic-bezier(.25, 1, .5, 1);--ease-out-expo: cubic-bezier(.16, 1, .3, 1);--ease-in-out-quart: cubic-bezier(.76, 0, .24, 1);--line-thin: 1px solid var(--ink-edge);--line-paper: 1px solid var(--paper-soft);--radius-frame: 0px;--grain-opacity: .075}*,*:before,*:after{box-sizing:border-box}html,body,#root{margin:0;padding:0;height:100%}img,svg,video{display:block;max-width:100%}button{font:inherit;color:inherit;background:none;border:0;padding:0;cursor:pointer}a{color:inherit}html{background:var(--ink-deep);color:var(--paper);font-family:var(--font-body);font-size:16px;-webkit-font-smoothing:antialiased;text-rendering:optimizeLegibility;font-feature-settings:"ss01","ss02","cv01","cv11"}body{font-feature-settings:"ss01","ss02";letter-spacing:-.005em;background:radial-gradient(circle at 80% -10%,rgba(255,122,23,.07),transparent 55%),radial-gradient(circle at 5% 110%,rgba(44,179,157,.04),transparent 60%),var(--ink-deep);position:relative;overflow-x:hidden}body:before{content:"";position:fixed;inset:0;pointer-events:none;z-index:9999;opacity:var(--grain-opacity);background-image:url("data:image/svg+xml;utf8,");mix-blend-mode:overlay}::selection{background:var(--saffron);color:var(--ink-deep)}h1,h2,h3,h4,h5,h6{font-family:var(--font-display);font-weight:400;margin:0;letter-spacing:-.02em;line-height:.95;color:var(--paper)}p{margin:0}.serif{font-family:var(--font-display)}.italic{font-style:italic}.mono{font-family:var(--font-mono);font-feature-settings:"calt","ss01";letter-spacing:-.02em}.devanagari{font-family:var(--font-devanagari)}.kicker{font-family:var(--font-mono);font-size:var(--step-xxs);letter-spacing:.15em;text-transform:uppercase;color:var(--saffron)}.eyebrow{display:inline-flex;align-items:center;gap:.6em;font-family:var(--font-mono);font-size:var(--step-xxs);letter-spacing:.18em;text-transform:uppercase;color:var(--ash)}.eyebrow:before{content:"";display:inline-block;width:1.6em;height:1px;background:var(--saffron)}a.inline{color:var(--paper);text-decoration:underline;text-decoration-color:var(--saffron);text-decoration-thickness:1px;text-underline-offset:4px;transition:color .2s var(--ease-out-quart)}a.inline:hover{color:var(--saffron)}.shell{width:100%;max-width:var(--max-width);margin:0 auto;padding-inline:var(--gutter)}.section{position:relative;padding-block:clamp(5rem,10vw,9rem);border-top:var(--line-thin)}.rule{height:1px;background:var(--ink-edge);margin-block:2rem}.row{display:grid;gap:var(--gutter)}@keyframes rise{0%{opacity:0;transform:translateY(28px)}to{opacity:1;transform:translateY(0)}}@keyframes drift{0%,to{transform:translate(0) skew(0)}50%{transform:translate(6px) skew(-1.5deg)}}@keyframes shimmer{0%{background-position:-200% 0}to{background-position:200% 0}}@keyframes blink{0%,60%{opacity:1}61%,to{opacity:0}}.rise{animation:rise .9s var(--ease-out-expo) both}:focus-visible{outline:2px solid var(--saffron);outline-offset:3px}::-webkit-scrollbar{width:8px;height:8px}::-webkit-scrollbar-track{background:var(--ink-deep)}::-webkit-scrollbar-thumb{background:var(--ink-edge);border-radius:0}::-webkit-scrollbar-thumb:hover{background:var(--saffron-deep)}.arch__shell{display:grid;gap:clamp(2rem,5vw,4rem)}.arch__header{display:grid;gap:1rem;max-width:64ch}.arch__title{font-size:var(--step-xl);font-style:italic;letter-spacing:-.022em;line-height:.95}.arch__title em{color:var(--saffron);font-style:italic}.arch__sub{font-size:var(--step-m);color:var(--paper-soft);line-height:1.55;max-width:60ch}.arch__sub code{background:var(--ink-surface);border:var(--line-thin);padding:.05em .4em;font-size:.85em;color:var(--saffron-soft)}.arch__diagram{background:var(--ink-base);border:var(--line-thin);padding:clamp(1rem,2vw,2rem)}.arch__diagram svg{width:100%;height:auto;display:block;font-family:var(--font-mono)}.arch__node rect{fill:var(--ink-surface);stroke:var(--ink-edge);stroke-width:1}.arch__node--accent rect{fill:var(--ink-elevated);stroke:var(--saffron);stroke-width:1.5}.arch__node--ghost rect{fill:var(--ink-base);stroke:var(--ink-edge);stroke-dasharray:4 4}.arch__node-kicker{font-size:11px;letter-spacing:.18em;fill:var(--ash-deep);text-transform:uppercase}.arch__node-title{font-size:16px;fill:var(--paper);letter-spacing:-.01em;font-weight:500}.arch__node--accent .arch__node-title{fill:var(--saffron)}.arch__node-line{font-size:12px;fill:var(--paper-soft);letter-spacing:-.01em}.arch__node-sub,.arch__node-foot{font-size:11px;fill:var(--ash);letter-spacing:.05em}.arch__edge{stroke:var(--saffron);stroke-width:1.4;opacity:.85}.arch__edge--soft{stroke:var(--ink-edge);stroke-width:1;opacity:.7}.arch__edge-label{font-size:10.5px;fill:var(--ash);letter-spacing:.12em;text-transform:uppercase}.arch__vendors{display:grid;gap:1rem}.arch__vendors ul{list-style:none;margin:0;padding:0;display:grid;grid-template-columns:1fr;gap:0;border:var(--line-thin)}@media (min-width: 720px){.arch__vendors ul{grid-template-columns:repeat(5,1fr)}}.arch__vendors li{display:grid;align-content:start;gap:.4rem;padding:1.2rem 1rem;border-right:var(--line-thin);border-bottom:var(--line-thin);background:var(--ink-surface)}.arch__vendors li:last-child{border-right:0}.arch__vendor-glyph{font-size:var(--step-l);color:var(--saffron);letter-spacing:.1em;line-height:1}.arch__vendor-name{font-family:var(--font-display);font-style:italic;font-size:var(--step-l);color:var(--paper);line-height:1}.arch__vendor-role{font-size:var(--step-xxs);color:var(--ash);letter-spacing:.1em;text-transform:uppercase}.demo__shell{display:grid;gap:clamp(2rem,5vw,4rem)}.demo__header{display:grid;gap:1rem;grid-template-columns:1fr}@media (min-width: 880px){.demo__header{grid-template-columns:1fr 1fr;align-items:end;gap:3rem}}.demo__title{font-size:var(--step-xl);font-style:italic;letter-spacing:-.022em;line-height:.95}.demo__title em{color:var(--saffron);font-style:italic}.demo__sub{font-size:var(--step-m);color:var(--paper-soft);line-height:1.55;max-width:50ch}.demo__sub em{color:var(--paper);font-style:italic}.demo__kbd{display:inline-block;padding:.05em .4em;background:var(--ink-surface);border:var(--line-thin);color:var(--saffron);margin-inline:.2em}.demo__layout{display:grid;gap:clamp(1.5rem,3vw,2.5rem);grid-template-columns:1fr}@media (min-width: 980px){.demo__layout{grid-template-columns:.4fr 1fr}}.demo__prompts{display:grid;gap:1rem;align-content:start;border-left:2px solid var(--saffron);padding-left:1.25rem}.demo__prompts ul{list-style:none;margin:0;padding:0;display:grid;gap:1.25rem}.demo__prompts li{display:grid;gap:.4rem;font-family:var(--font-display);font-style:italic;font-size:var(--step-m);color:var(--paper);line-height:1.4}.demo__prompts .devanagari{font-family:var(--font-devanagari);font-style:italic;font-size:1.05em;color:var(--paper);font-weight:400}.demo__prompt-tag{font-size:var(--step-xxs);letter-spacing:.1em;color:var(--ash);text-transform:lowercase}.demo__hf-link{display:inline-block;margin-top:1rem;font-size:var(--step-s);color:var(--saffron);text-decoration:none;border-top:1px solid var(--ink-edge);padding-top:.85rem;transition:color .2s var(--ease-out-quart)}.demo__hf-link:hover{color:var(--paper)}.demo__frame{position:relative;background:var(--ink-deep);border:var(--line-thin);overflow:hidden;isolation:isolate}.demo__bezel{display:flex;align-items:center;gap:.75rem;padding:.6rem .9rem;background:var(--ink-surface);border-bottom:var(--line-thin);font-size:var(--step-xxs);letter-spacing:.1em;color:var(--ash)}.demo__bezel-dot{width:.55rem;height:.55rem;border-radius:999px;background:var(--saffron)}.demo__bezel-id{flex:1;color:var(--paper-soft)}.demo__bezel-rec{display:inline-flex;align-items:center;gap:.35rem;color:var(--saffron);text-transform:uppercase;letter-spacing:.18em}.demo__bezel-rec-dot{width:.5rem;height:.5rem;background:var(--saffron);border-radius:999px;animation:blink 1.4s var(--ease-in-out-quart) infinite}.demo__iframe{display:block;width:100%;height:clamp(540px,76vh,920px);border:0;background:var(--ink-deep)}.demo__scanlines{position:absolute;inset:0;pointer-events:none;z-index:2;background-image:repeating-linear-gradient(180deg,transparent 0px,transparent 2px,rgba(255,255,255,.012) 2px,rgba(255,255,255,.012) 3px);mix-blend-mode:overlay}.footer{border-top:var(--line-thin);background:var(--ink-base);padding-block:clamp(3rem,6vw,5rem)}.footer__shell{display:grid;gap:clamp(1.5rem,3vw,2.25rem)}.footer__top{display:flex;align-items:baseline;justify-content:space-between;flex-wrap:wrap;gap:.85rem}.footer__brand{font-family:var(--font-display);font-style:italic;font-size:clamp(2rem,3vw,3rem);color:var(--paper);letter-spacing:-.02em;line-height:1}.footer__brand em{font-style:italic;color:var(--saffron);margin-left:.5rem}.footer__deva{font-family:var(--font-devanagari)}.footer__hack{font-size:var(--step-xxs);letter-spacing:.18em;text-transform:uppercase;color:var(--ash)}.footer__grid{display:grid;grid-template-columns:1fr;gap:1.5rem 2.5rem}@media (min-width: 880px){.footer__grid{grid-template-columns:1.05fr 1fr}}.footer__about{font-family:var(--font-display);font-style:italic;font-size:clamp(1.05rem,1.5vw,1.4rem);line-height:1.45;color:var(--paper-soft)}.footer__about code{background:var(--ink-surface);border:var(--line-thin);padding:.05em .4em;font-size:.85em;color:var(--saffron-soft)}.footer__credits{list-style:none;margin:0;padding:0;display:grid;gap:.85rem;border-top:var(--line-thin);padding-top:1.2rem}.footer__credits li{display:grid;grid-template-columns:6.5rem 1fr;gap:1rem;align-items:baseline}.footer__credit-key{font-size:var(--step-xxs);letter-spacing:.18em;text-transform:uppercase;color:var(--ash-deep)}.footer__credit-val{font-size:var(--step-s);color:var(--paper);letter-spacing:-.01em}.footer__rule{height:1px;background:var(--ink-edge)}.footer__bottom{display:flex;justify-content:space-between;flex-wrap:wrap;gap:.85rem;font-size:var(--step-xxs);letter-spacing:.15em;color:var(--ash-deep);text-transform:uppercase}.hero{position:relative;min-height:min(100svh,980px);padding-top:clamp(2rem,5vw,4rem);padding-bottom:clamp(4rem,8vw,7rem);overflow:hidden;isolation:isolate}.hero__shell{position:relative;z-index:2;display:grid;gap:clamp(2rem,5vw,4rem)}.hero__top{display:flex;align-items:center;justify-content:space-between;flex-wrap:wrap;gap:1rem;border-bottom:var(--line-thin);padding-bottom:1.5rem}.hero__coord{font-size:var(--step-xxs);letter-spacing:.18em;color:var(--ash)}.hero__title{font-size:var(--step-xxxl);line-height:.86;letter-spacing:-.035em;display:grid;grid-template-columns:1fr;gap:clamp(.5rem,1vw,1rem);position:relative;margin-top:clamp(1rem,4vw,3rem)}.hero__brand{position:relative;display:inline-block;font-style:italic;color:var(--paper);text-shadow:0 0 80px rgba(255,122,23,.04),0 0 0 transparent}.hero__brand:first-letter{color:var(--saffron)}.pretext__telemetry{position:absolute;inset-inline-start:.05em;inset-block-start:calc(100% + .4rem);display:flex;flex-wrap:wrap;gap:1rem;font-family:var(--font-mono);font-size:.7rem;letter-spacing:.18em;text-transform:uppercase;color:var(--ash-deep);white-space:nowrap;pointer-events:none;animation:rise 1.1s 1.5s var(--ease-out-expo) both}.pretext__telemetry>span:last-child{color:var(--saffron)}.hero__slash{position:absolute;top:.05em;left:clamp(8.5rem,27vw,22rem);font-style:italic;color:var(--saffron);font-size:.72em;pointer-events:none;animation:rise 1.1s .2s var(--ease-out-expo) both}.hero__sub{display:block;font-style:italic;font-size:.42em;line-height:.95;color:var(--paper-soft);letter-spacing:-.02em;margin-top:-.05em;font-weight:400;animation:rise 1.1s .35s var(--ease-out-expo) both}.hero__sub-em{color:var(--saffron)}.hero__devanagari{position:absolute;inset-inline-end:-3vw;top:clamp(8rem,16vw,14rem);font-family:var(--font-devanagari);font-style:italic;font-size:clamp(15rem,36vw,36rem);color:var(--devanagari-glow);letter-spacing:-.05em;line-height:.9;pointer-events:none;z-index:1;user-select:none;animation:drift 12s ease-in-out infinite;filter:blur(.5px)}.hero__meta{display:grid;gap:clamp(2rem,4vw,3rem);grid-template-columns:1fr;margin-top:clamp(2rem,5vw,4rem)}@media (min-width: 880px){.hero__meta{grid-template-columns:1.1fr .9fr;align-items:end}}.hero__lede{font-family:var(--font-display);font-style:italic;font-size:var(--step-l);line-height:1.25;color:var(--paper-soft);max-width:32em;letter-spacing:-.012em;animation:rise 1s .6s var(--ease-out-expo) both}.hero__lede em{font-style:italic;color:var(--paper);background:linear-gradient(180deg,transparent 60%,var(--saffron-glow) 60%);padding-inline:.05em}.hero__chips{display:grid;grid-template-columns:1fr 1fr;gap:.85rem 1.5rem;list-style:none;margin:0;padding:0;border-top:var(--line-thin);border-bottom:var(--line-thin);padding-block:1.25rem;animation:rise 1s .8s var(--ease-out-expo) both}.hero__chips li{display:grid;grid-template-columns:1fr;gap:.15rem}.hero__chip-key{font-size:var(--step-xxs);letter-spacing:.15em;text-transform:uppercase;color:var(--ash-deep)}.hero__chip-val{font-size:var(--step-s);color:var(--paper);letter-spacing:-.01em}.hero__cta{grid-column:1 / -1;display:flex;flex-wrap:wrap;gap:.6rem;margin-top:clamp(.5rem,2vw,1.25rem);animation:rise 1s 1s var(--ease-out-expo) both}.hero__btn{display:inline-flex;align-items:center;gap:.7em;padding:.95rem 1.4rem .85rem;font-family:var(--font-mono);font-size:var(--step-s);letter-spacing:-.01em;text-decoration:none;border:1px solid var(--ink-edge);background:var(--ink-surface);color:var(--paper);transition:background .22s var(--ease-out-quart),border-color .22s var(--ease-out-quart),color .22s var(--ease-out-quart),transform .22s var(--ease-out-quart)}.hero__btn:hover{background:var(--ink-elevated);border-color:var(--saffron);color:var(--saffron);transform:translateY(-1px)}.hero__btn--primary{background:var(--saffron);color:var(--ink-deep);border-color:var(--saffron)}.hero__btn--primary:hover{background:var(--paper);color:var(--ink-deep);border-color:var(--paper)}.hero__wave{position:absolute;inset-inline:0;bottom:0;height:clamp(70px,9vw,110px);width:100%;z-index:1}.hero__wave path{fill:none;stroke:var(--saffron);stroke-width:1.25;opacity:.7;filter:drop-shadow(0 0 12px var(--saffron-glow));vector-effect:non-scaling-stroke}.premise__shell{display:grid;gap:clamp(2rem,5vw,4rem)}.premise__header{display:grid;gap:.85rem}.premise__title{font-size:var(--step-xl);font-style:italic;line-height:.95;letter-spacing:-.022em;color:var(--paper);max-width:18ch}.premise__columns{display:grid;gap:1.5rem;grid-template-columns:1fr;border-top:var(--line-thin);padding-top:clamp(1.5rem,3vw,2.5rem)}@media (min-width: 880px){.premise__columns{grid-template-columns:1.1fr .95fr;gap:2.75rem}.premise__lede{grid-column:1 / 2;grid-row:1 / 3}.premise__body{grid-column:2 / 3}}.premise__lede{font-family:var(--font-display);font-style:italic;font-size:clamp(1.25rem,1.8vw,1.6rem);line-height:1.32;color:var(--paper);letter-spacing:-.012em}.premise__lede em{font-style:italic;font-family:var(--font-mono);font-size:.86em;color:var(--saffron);padding:0 .15em}.premise__drop{float:left;font-family:var(--font-display);font-style:italic;color:var(--saffron);font-size:clamp(4.2rem,7vw,6.5rem);line-height:.78;margin-right:.18em;margin-top:.06em}.premise__body{font-size:var(--step-m);line-height:1.6;color:var(--paper-soft)}.premise__body strong{color:var(--paper);font-weight:600}.premise__langs{list-style:none;margin:0;padding:0;display:grid;grid-template-columns:repeat(2,1fr);gap:0;border-top:var(--line-thin);border-bottom:var(--line-thin)}@media (min-width: 720px){.premise__langs{grid-template-columns:repeat(5,1fr)}}.premise__langs li{display:grid;gap:.4rem;padding:1.4rem .5rem 1.4rem 0;border-right:var(--line-thin);position:relative}.premise__langs li:last-child{border-right:0}.premise__langs li:before{content:"";position:absolute;inset-block:0;inset-inline-start:-100vw;inset-inline-end:100%;border-bottom:var(--line-thin)}.premise__lang-num{font-size:var(--step-xxs);letter-spacing:.18em;color:var(--ash-deep)}.premise__lang-script{font-family:var(--font-devanagari);font-style:italic;font-size:clamp(2rem,3vw,2.6rem);color:var(--paper);line-height:1}.premise__lang-name{font-size:var(--step-xs);color:var(--ash);letter-spacing:.06em;text-transform:lowercase}.results__shell{display:grid;gap:clamp(2rem,5vw,4rem)}.results__header{display:grid;gap:1rem;max-width:64ch}.results__title{font-size:var(--step-xl);font-style:italic;letter-spacing:-.022em;line-height:.95}.results__title em{color:var(--saffron);font-style:italic}.results__sub{font-size:var(--step-m);color:var(--paper-soft);line-height:1.55;max-width:60ch}.results__grid{display:grid;gap:clamp(1.5rem,3vw,2.5rem);grid-template-columns:1fr}@media (min-width: 980px){.results__grid{grid-template-columns:1.4fr 1fr;grid-template-rows:auto auto;align-items:stretch}.results__chart:nth-of-type(1){grid-column:1 / 2;grid-row:1 / 2}.results__chart:nth-of-type(2){grid-column:1 / 2;grid-row:2 / 3}.results__table{grid-column:2 / 3;grid-row:1 / 3}}.results__chart{display:grid;gap:.85rem;background:var(--ink-surface);border:var(--line-thin);padding:1.5rem}.results__chart-head{display:flex;align-items:baseline;justify-content:space-between;font-size:var(--step-xxs);color:var(--ash)}.results__chart-y{color:var(--saffron);letter-spacing:-.01em}.results__chart-foot{display:flex;justify-content:space-between;font-size:var(--step-xxs);color:var(--ash-deep);letter-spacing:.18em;text-transform:uppercase}.results__curve{width:100%;height:clamp(220px,30vh,320px);display:block}.results__table{width:100%;border-collapse:collapse;background:var(--ink-base);border:var(--line-thin);font-size:var(--step-s)}.results__table th,.results__table td{padding:.95rem 1rem;text-align:left;border-bottom:var(--line-thin);vertical-align:baseline}.results__table thead th{font-family:var(--font-mono);font-weight:400;font-size:var(--step-xxs);letter-spacing:.15em;text-transform:uppercase;color:var(--ash)}.results__th-base{color:var(--ash)}.results__th-trained{color:var(--saffron)}.results__cell-label{color:var(--paper);font-weight:500}.results__cell-base{color:var(--ash)}.results__cell-trained{color:var(--saffron)}.results__cell-delta.is-better{color:var(--rasa-teal)}.results__cell-delta.is-worse{color:var(--saffron-deep)}.results__table tr:last-child th,.results__table tr:last-child td{border-bottom:0}.resources__shell{display:grid;gap:clamp(2rem,5vw,4rem)}.resources__header{display:grid;gap:1rem;max-width:64ch}.resources__title{font-size:var(--step-xl);font-style:italic;letter-spacing:-.022em;line-height:.95}.resources__grid{list-style:none;margin:0;padding:0;display:grid;grid-template-columns:1fr;gap:0;border:var(--line-thin)}@media (min-width: 880px){.resources__grid{grid-template-columns:repeat(2,1fr)}}.resources__tile{position:relative;display:grid;gap:.85rem;padding:clamp(1.5rem,2.5vw,2.25rem);text-decoration:none;background:var(--ink-surface);border-right:var(--line-thin);border-bottom:var(--line-thin);color:var(--paper);transition:background .24s var(--ease-out-quart);isolation:isolate;overflow:hidden}.resources__tile:before{content:"";position:absolute;inset:0;background:linear-gradient(135deg,var(--saffron-glow),transparent 40%);opacity:0;transition:opacity .28s var(--ease-out-quart);pointer-events:none}.resources__tile:hover{background:var(--ink-elevated)}.resources__tile:hover:before{opacity:1}.resources__tile:hover .resources__title-text{color:var(--saffron)}.resources__tile--accent{background:var(--ink-elevated)}.resources__tile--accent .resources__title-text{color:var(--saffron)}.resources__suffix{font-size:var(--step-xxs);letter-spacing:.18em;color:var(--ash);text-transform:uppercase}.resources__label{font-family:var(--font-mono);font-size:var(--step-xxs);letter-spacing:.18em;text-transform:uppercase;color:var(--saffron)}.resources__title-text{font-family:var(--font-display);font-style:italic;font-size:clamp(1.3rem,2vw,1.85rem);color:var(--paper);letter-spacing:-.015em;line-height:1.1;transition:color .22s var(--ease-out-quart)}.resources__desc{font-size:var(--step-s);color:var(--paper-soft);line-height:1.55}.reward__shell{display:grid;gap:clamp(2rem,5vw,4rem)}.reward__header{display:grid;gap:1rem;max-width:50ch}.reward__title{font-size:var(--step-xl);font-style:italic;line-height:.95;letter-spacing:-.022em;color:var(--paper)}.reward__title em{font-style:italic;color:var(--saffron)}.reward__sub{font-size:var(--step-m);color:var(--paper-soft);line-height:1.55;max-width:60ch}.reward__sub em{font-style:italic;color:var(--paper)}.reward__sub code{background:var(--ink-surface);border:var(--line-thin);padding:.05em .4em;font-size:.9em;color:var(--saffron-soft)}.reward__grid{list-style:none;margin:0;padding:0;display:grid;gap:0;grid-template-columns:1fr;border:var(--line-thin)}@media (min-width: 720px){.reward__grid{grid-template-columns:repeat(6,1fr);grid-template-rows:auto auto}.reward__card:nth-child(1){grid-column:span 4;grid-row:1}.reward__card:nth-child(2){grid-column:span 2;grid-row:1}.reward__card:nth-child(3){grid-column:span 2;grid-row:2}.reward__card:nth-child(4){grid-column:span 2;grid-row:2}.reward__card:nth-child(5){grid-column:span 2;grid-row:2}}.reward__card{position:relative;display:grid;gap:1rem;align-content:start;padding:clamp(1.5rem,2.5vw,2.25rem);background:var(--ink-surface);border-right:var(--line-thin);border-bottom:var(--line-thin);transition:background .24s var(--ease-out-quart),transform .24s var(--ease-out-quart);animation:rise .8s var(--ease-out-expo) both}.reward__card:hover{background:var(--ink-elevated);transform:translateY(-1px)}.reward__card:hover:after{content:"";position:absolute;inset:0;pointer-events:none;border-top:2px solid var(--saffron)}.reward__card-head{display:flex;align-items:baseline;justify-content:space-between;gap:1rem}.reward__id{font-family:var(--font-display);font-style:italic;font-size:clamp(2.5rem,4vw,3.5rem);color:var(--saffron);line-height:1}.reward__weight{font-size:var(--step-xs);color:var(--ash);letter-spacing:-.01em}.reward__name{font-family:var(--font-mono);font-style:normal;font-size:clamp(1.2rem,1.8vw,1.55rem);letter-spacing:-.015em;color:var(--paper);line-height:1.1}.reward__blurb{font-size:var(--step-s);line-height:1.55;color:var(--paper-soft)}.reward__impl{margin-top:auto;font-size:var(--step-xxs);color:var(--ash-deep);word-break:break-all;letter-spacing:0}.reward__pipeline{display:flex;flex-wrap:wrap;align-items:center;gap:.6rem .9rem;padding-block:1.5rem;border-top:var(--line-thin);border-bottom:var(--line-thin)}.reward__pipe-step{font-size:var(--step-s);padding:.5rem .85rem;background:var(--ink-base);border:var(--line-thin);color:var(--paper-soft)}.reward__pipe-step--final{background:var(--saffron);color:var(--ink-deep);border-color:var(--saffron)}.reward__pipe-arrow{font-family:var(--font-display);font-style:italic;color:var(--saffron);font-size:var(--step-l);line-height:1}.reward__drift{display:grid;gap:1.25rem}.reward__drift-head{display:flex;align-items:baseline;justify-content:space-between}.reward__drift-count{color:var(--saffron);font-size:var(--step-s)}.reward__drift-list{list-style:none;margin:0;padding:0;display:grid;grid-template-columns:repeat(2,1fr);gap:0;border-top:var(--line-thin)}@media (min-width: 720px){.reward__drift-list{grid-template-columns:repeat(4,1fr)}}@media (min-width: 1080px){.reward__drift-list{grid-template-columns:repeat(5,1fr)}}.reward__drift-list li{display:flex;align-items:baseline;gap:.6rem;padding:.7rem .5rem;border-bottom:var(--line-thin);border-right:var(--line-thin)}.reward__drift-num{font-size:var(--step-xxs);color:var(--ash-deep);letter-spacing:.1em}.reward__drift-name{font-size:var(--step-s);color:var(--paper);letter-spacing:-.01em}.main{display:block}.rail{display:none}@media (min-width: 1180px){.rail{position:fixed;top:0;left:0;bottom:0;width:64px;z-index:20;display:grid;grid-template-rows:auto 1fr auto;align-items:center;justify-items:center;padding-block:1.25rem;border-right:var(--line-thin);background:linear-gradient(180deg,var(--ink-deep),var(--ink-base) 50%,var(--ink-deep));backdrop-filter:blur(4px)}.rail__brand,.rail__foot{writing-mode:vertical-rl;transform:rotate(180deg);font-size:var(--step-xxs);letter-spacing:.32em;text-transform:uppercase;color:var(--ash)}.rail__brand{color:var(--saffron)}.rail__list{list-style:none;margin:0;padding:0;display:grid;gap:1.2rem;align-content:center}.rail__link{display:grid;place-items:center;gap:.4rem;text-decoration:none;color:var(--ash);font-size:var(--step-xxs);transition:color .2s var(--ease-out-quart)}.rail__link:hover{color:var(--saffron)}.rail__num{font-size:var(--step-xxs);color:var(--ash-deep);letter-spacing:.1em}.rail__link:hover .rail__num{color:var(--saffron)}.rail__label{writing-mode:vertical-rl;transform:rotate(180deg);letter-spacing:.18em;text-transform:uppercase}.main,.footer{padding-left:64px}} diff --git a/site/assets/index-D7bqscQM.js b/site/assets/index-D7bqscQM.js new file mode 100644 index 0000000000000000000000000000000000000000..20bb49fff6e6a5177ea33ebcd826b92b3e2037c2 --- /dev/null +++ b/site/assets/index-D7bqscQM.js @@ -0,0 +1,40 @@ +(function(){const t=document.createElement("link").relList;if(t&&t.supports&&t.supports("modulepreload"))return;for(const l of document.querySelectorAll('link[rel="modulepreload"]'))r(l);new MutationObserver(l=>{for(const i of l)if(i.type==="childList")for(const o of i.addedNodes)o.tagName==="LINK"&&o.rel==="modulepreload"&&r(o)}).observe(document,{childList:!0,subtree:!0});function n(l){const i={};return l.integrity&&(i.integrity=l.integrity),l.referrerPolicy&&(i.referrerPolicy=l.referrerPolicy),l.crossOrigin==="use-credentials"?i.credentials="include":l.crossOrigin==="anonymous"?i.credentials="omit":i.credentials="same-origin",i}function r(l){if(l.ep)return;l.ep=!0;const i=n(l);fetch(l.href,i)}})();var Xs={exports:{}},ll={},Ys={exports:{}},L={};/** + * @license React + * react.production.min.js + * + * Copyright (c) Facebook, Inc. and its affiliates. + * + * This source code is licensed under the MIT license found in the + * LICENSE file in the root directory of this source tree. + */var qn=Symbol.for("react.element"),ac=Symbol.for("react.portal"),cc=Symbol.for("react.fragment"),dc=Symbol.for("react.strict_mode"),fc=Symbol.for("react.profiler"),pc=Symbol.for("react.provider"),hc=Symbol.for("react.context"),mc=Symbol.for("react.forward_ref"),vc=Symbol.for("react.suspense"),yc=Symbol.for("react.memo"),gc=Symbol.for("react.lazy"),Io=Symbol.iterator;function _c(e){return e===null||typeof e!="object"?null:(e=Io&&e[Io]||e["@@iterator"],typeof e=="function"?e:null)}var Zs={isMounted:function(){return!1},enqueueForceUpdate:function(){},enqueueReplaceState:function(){},enqueueSetState:function(){}},Js=Object.assign,qs={};function un(e,t,n){this.props=e,this.context=t,this.refs=qs,this.updater=n||Zs}un.prototype.isReactComponent={};un.prototype.setState=function(e,t){if(typeof e!="object"&&typeof e!="function"&&e!=null)throw Error("setState(...): takes an object of state variables to update or a function which returns an object of state variables.");this.updater.enqueueSetState(this,e,t,"setState")};un.prototype.forceUpdate=function(e){this.updater.enqueueForceUpdate(this,e,"forceUpdate")};function bs(){}bs.prototype=un.prototype;function Bi(e,t,n){this.props=e,this.context=t,this.refs=qs,this.updater=n||Zs}var Hi=Bi.prototype=new bs;Hi.constructor=Bi;Js(Hi,un.prototype);Hi.isPureReactComponent=!0;var Ao=Array.isArray,eu=Object.prototype.hasOwnProperty,Wi={current:null},tu={key:!0,ref:!0,__self:!0,__source:!0};function nu(e,t,n){var r,l={},i=null,o=null;if(t!=null)for(r in t.ref!==void 0&&(o=t.ref),t.key!==void 0&&(i=""+t.key),t)eu.call(t,r)&&!tu.hasOwnProperty(r)&&(l[r]=t[r]);var u=arguments.length-2;if(u===1)l.children=n;else if(1>>1,Y=N[V];if(0>>1;Vl(kl,z))xtl(lr,kl)?(N[V]=lr,N[xt]=z,V=xt):(N[V]=kl,N[_t]=z,V=_t);else if(xtl(lr,z))N[V]=lr,N[xt]=z,V=xt;else break e}}return P}function l(N,P){var z=N.sortIndex-P.sortIndex;return z!==0?z:N.id-P.id}if(typeof performance=="object"&&typeof performance.now=="function"){var i=performance;e.unstable_now=function(){return i.now()}}else{var o=Date,u=o.now();e.unstable_now=function(){return o.now()-u}}var a=[],f=[],v=1,m=null,h=3,_=!1,w=!1,x=!1,M=typeof setTimeout=="function"?setTimeout:null,d=typeof clearTimeout=="function"?clearTimeout:null,c=typeof setImmediate<"u"?setImmediate:null;typeof navigator<"u"&&navigator.scheduling!==void 0&&navigator.scheduling.isInputPending!==void 0&&navigator.scheduling.isInputPending.bind(navigator.scheduling);function p(N){for(var P=n(f);P!==null;){if(P.callback===null)r(f);else if(P.startTime<=N)r(f),P.sortIndex=P.expirationTime,t(a,P);else break;P=n(f)}}function y(N){if(x=!1,p(N),!w)if(n(a)!==null)w=!0,xl(k);else{var P=n(f);P!==null&&wl(y,P.startTime-N)}}function k(N,P){w=!1,x&&(x=!1,d(C),C=-1),_=!0;var z=h;try{for(p(P),m=n(a);m!==null&&(!(m.expirationTime>P)||N&&!Ce());){var V=m.callback;if(typeof V=="function"){m.callback=null,h=m.priorityLevel;var Y=V(m.expirationTime<=P);P=e.unstable_now(),typeof Y=="function"?m.callback=Y:m===n(a)&&r(a),p(P)}else r(a);m=n(a)}if(m!==null)var rr=!0;else{var _t=n(f);_t!==null&&wl(y,_t.startTime-P),rr=!1}return rr}finally{m=null,h=z,_=!1}}var j=!1,E=null,C=-1,W=5,T=-1;function Ce(){return!(e.unstable_now()-TN||125V?(N.sortIndex=z,t(f,N),n(a)===null&&N===n(f)&&(x?(d(C),C=-1):x=!0,wl(y,z-V))):(N.sortIndex=Y,t(a,N),w||_||(w=!0,xl(k))),N},e.unstable_shouldYield=Ce,e.unstable_wrapCallback=function(N){var P=h;return function(){var z=h;h=P;try{return N.apply(this,arguments)}finally{h=z}}}})(su);ou.exports=su;var Lc=ou.exports;/** + * @license React + * react-dom.production.min.js + * + * Copyright (c) Facebook, Inc. and its affiliates. + * + * This source code is licensed under the MIT license found in the + * LICENSE file in the root directory of this source tree. + */var Tc=Ae,ye=Lc;function g(e){for(var t="https://reactjs.org/docs/error-decoder.html?invariant="+e,n=1;n"u"||typeof window.document>"u"||typeof window.document.createElement>"u"),Yl=Object.prototype.hasOwnProperty,Rc=/^[:A-Z_a-z\u00C0-\u00D6\u00D8-\u00F6\u00F8-\u02FF\u0370-\u037D\u037F-\u1FFF\u200C-\u200D\u2070-\u218F\u2C00-\u2FEF\u3001-\uD7FF\uF900-\uFDCF\uFDF0-\uFFFD][:A-Z_a-z\u00C0-\u00D6\u00D8-\u00F6\u00F8-\u02FF\u0370-\u037D\u037F-\u1FFF\u200C-\u200D\u2070-\u218F\u2C00-\u2FEF\u3001-\uD7FF\uF900-\uFDCF\uFDF0-\uFFFD\-.0-9\u00B7\u0300-\u036F\u203F-\u2040]*$/,$o={},Bo={};function Mc(e){return Yl.call(Bo,e)?!0:Yl.call($o,e)?!1:Rc.test(e)?Bo[e]=!0:($o[e]=!0,!1)}function Dc(e,t,n,r){if(n!==null&&n.type===0)return!1;switch(typeof t){case"function":case"symbol":return!0;case"boolean":return r?!1:n!==null?!n.acceptsBooleans:(e=e.toLowerCase().slice(0,5),e!=="data-"&&e!=="aria-");default:return!1}}function Oc(e,t,n,r){if(t===null||typeof t>"u"||Dc(e,t,n,r))return!0;if(r)return!1;if(n!==null)switch(n.type){case 3:return!t;case 4:return t===!1;case 5:return isNaN(t);case 6:return isNaN(t)||1>t}return!1}function ue(e,t,n,r,l,i,o){this.acceptsBooleans=t===2||t===3||t===4,this.attributeName=r,this.attributeNamespace=l,this.mustUseProperty=n,this.propertyName=e,this.type=t,this.sanitizeURL=i,this.removeEmptyString=o}var ee={};"children dangerouslySetInnerHTML defaultValue defaultChecked innerHTML suppressContentEditableWarning suppressHydrationWarning style".split(" ").forEach(function(e){ee[e]=new ue(e,0,!1,e,null,!1,!1)});[["acceptCharset","accept-charset"],["className","class"],["htmlFor","for"],["httpEquiv","http-equiv"]].forEach(function(e){var t=e[0];ee[t]=new ue(t,1,!1,e[1],null,!1,!1)});["contentEditable","draggable","spellCheck","value"].forEach(function(e){ee[e]=new ue(e,2,!1,e.toLowerCase(),null,!1,!1)});["autoReverse","externalResourcesRequired","focusable","preserveAlpha"].forEach(function(e){ee[e]=new ue(e,2,!1,e,null,!1,!1)});"allowFullScreen async autoFocus autoPlay controls default defer disabled disablePictureInPicture disableRemotePlayback formNoValidate hidden loop noModule noValidate open playsInline readOnly required reversed scoped seamless itemScope".split(" ").forEach(function(e){ee[e]=new ue(e,3,!1,e.toLowerCase(),null,!1,!1)});["checked","multiple","muted","selected"].forEach(function(e){ee[e]=new ue(e,3,!0,e,null,!1,!1)});["capture","download"].forEach(function(e){ee[e]=new ue(e,4,!1,e,null,!1,!1)});["cols","rows","size","span"].forEach(function(e){ee[e]=new ue(e,6,!1,e,null,!1,!1)});["rowSpan","start"].forEach(function(e){ee[e]=new ue(e,5,!1,e.toLowerCase(),null,!1,!1)});var Qi=/[\-:]([a-z])/g;function Gi(e){return e[1].toUpperCase()}"accent-height alignment-baseline arabic-form baseline-shift cap-height clip-path clip-rule color-interpolation color-interpolation-filters color-profile color-rendering dominant-baseline enable-background fill-opacity fill-rule flood-color flood-opacity font-family font-size font-size-adjust font-stretch font-style font-variant font-weight glyph-name glyph-orientation-horizontal glyph-orientation-vertical horiz-adv-x horiz-origin-x image-rendering letter-spacing lighting-color marker-end marker-mid marker-start overline-position overline-thickness paint-order panose-1 pointer-events rendering-intent shape-rendering stop-color stop-opacity strikethrough-position strikethrough-thickness stroke-dasharray stroke-dashoffset stroke-linecap stroke-linejoin stroke-miterlimit stroke-opacity stroke-width text-anchor text-decoration text-rendering underline-position underline-thickness unicode-bidi unicode-range units-per-em v-alphabetic v-hanging v-ideographic v-mathematical vector-effect vert-adv-y vert-origin-x vert-origin-y word-spacing writing-mode xmlns:xlink x-height".split(" ").forEach(function(e){var t=e.replace(Qi,Gi);ee[t]=new ue(t,1,!1,e,null,!1,!1)});"xlink:actuate xlink:arcrole xlink:role xlink:show xlink:title xlink:type".split(" ").forEach(function(e){var t=e.replace(Qi,Gi);ee[t]=new ue(t,1,!1,e,"http://www.w3.org/1999/xlink",!1,!1)});["xml:base","xml:lang","xml:space"].forEach(function(e){var t=e.replace(Qi,Gi);ee[t]=new ue(t,1,!1,e,"http://www.w3.org/XML/1998/namespace",!1,!1)});["tabIndex","crossOrigin"].forEach(function(e){ee[e]=new ue(e,1,!1,e.toLowerCase(),null,!1,!1)});ee.xlinkHref=new ue("xlinkHref",1,!1,"xlink:href","http://www.w3.org/1999/xlink",!0,!1);["src","href","action","formAction"].forEach(function(e){ee[e]=new ue(e,1,!1,e.toLowerCase(),null,!0,!0)});function Ki(e,t,n,r){var l=ee.hasOwnProperty(t)?ee[t]:null;(l!==null?l.type!==0:r||!(2u||l[o]!==i[u]){var a=` +`+l[o].replace(" at new "," at ");return e.displayName&&a.includes("")&&(a=a.replace("",e.displayName)),a}while(1<=o&&0<=u);break}}}finally{jl=!1,Error.prepareStackTrace=n}return(e=e?e.displayName||e.name:"")?kn(e):""}function Fc(e){switch(e.tag){case 5:return kn(e.type);case 16:return kn("Lazy");case 13:return kn("Suspense");case 19:return kn("SuspenseList");case 0:case 2:case 15:return e=El(e.type,!1),e;case 11:return e=El(e.type.render,!1),e;case 1:return e=El(e.type,!0),e;default:return""}}function bl(e){if(e==null)return null;if(typeof e=="function")return e.displayName||e.name||null;if(typeof e=="string")return e;switch(e){case It:return"Fragment";case Ft:return"Portal";case Zl:return"Profiler";case Xi:return"StrictMode";case Jl:return"Suspense";case ql:return"SuspenseList"}if(typeof e=="object")switch(e.$$typeof){case cu:return(e.displayName||"Context")+".Consumer";case au:return(e._context.displayName||"Context")+".Provider";case Yi:var t=e.render;return e=e.displayName,e||(e=t.displayName||t.name||"",e=e!==""?"ForwardRef("+e+")":"ForwardRef"),e;case Zi:return t=e.displayName||null,t!==null?t:bl(e.type)||"Memo";case et:t=e._payload,e=e._init;try{return bl(e(t))}catch{}}return null}function Ic(e){var t=e.type;switch(e.tag){case 24:return"Cache";case 9:return(t.displayName||"Context")+".Consumer";case 10:return(t._context.displayName||"Context")+".Provider";case 18:return"DehydratedFragment";case 11:return e=t.render,e=e.displayName||e.name||"",t.displayName||(e!==""?"ForwardRef("+e+")":"ForwardRef");case 7:return"Fragment";case 5:return t;case 4:return"Portal";case 3:return"Root";case 6:return"Text";case 16:return bl(t);case 8:return t===Xi?"StrictMode":"Mode";case 22:return"Offscreen";case 12:return"Profiler";case 21:return"Scope";case 13:return"Suspense";case 19:return"SuspenseList";case 25:return"TracingMarker";case 1:case 0:case 17:case 2:case 14:case 15:if(typeof t=="function")return t.displayName||t.name||null;if(typeof t=="string")return t}return null}function ht(e){switch(typeof e){case"boolean":case"number":case"string":case"undefined":return e;case"object":return e;default:return""}}function fu(e){var t=e.type;return(e=e.nodeName)&&e.toLowerCase()==="input"&&(t==="checkbox"||t==="radio")}function Ac(e){var t=fu(e)?"checked":"value",n=Object.getOwnPropertyDescriptor(e.constructor.prototype,t),r=""+e[t];if(!e.hasOwnProperty(t)&&typeof n<"u"&&typeof n.get=="function"&&typeof n.set=="function"){var l=n.get,i=n.set;return Object.defineProperty(e,t,{configurable:!0,get:function(){return l.call(this)},set:function(o){r=""+o,i.call(this,o)}}),Object.defineProperty(e,t,{enumerable:n.enumerable}),{getValue:function(){return r},setValue:function(o){r=""+o},stopTracking:function(){e._valueTracker=null,delete e[t]}}}}function sr(e){e._valueTracker||(e._valueTracker=Ac(e))}function pu(e){if(!e)return!1;var t=e._valueTracker;if(!t)return!0;var n=t.getValue(),r="";return e&&(r=fu(e)?e.checked?"true":"false":e.value),e=r,e!==n?(t.setValue(e),!0):!1}function Dr(e){if(e=e||(typeof document<"u"?document:void 0),typeof e>"u")return null;try{return e.activeElement||e.body}catch{return e.body}}function ei(e,t){var n=t.checked;return B({},t,{defaultChecked:void 0,defaultValue:void 0,value:void 0,checked:n??e._wrapperState.initialChecked})}function Wo(e,t){var n=t.defaultValue==null?"":t.defaultValue,r=t.checked!=null?t.checked:t.defaultChecked;n=ht(t.value!=null?t.value:n),e._wrapperState={initialChecked:r,initialValue:n,controlled:t.type==="checkbox"||t.type==="radio"?t.checked!=null:t.value!=null}}function hu(e,t){t=t.checked,t!=null&&Ki(e,"checked",t,!1)}function ti(e,t){hu(e,t);var n=ht(t.value),r=t.type;if(n!=null)r==="number"?(n===0&&e.value===""||e.value!=n)&&(e.value=""+n):e.value!==""+n&&(e.value=""+n);else if(r==="submit"||r==="reset"){e.removeAttribute("value");return}t.hasOwnProperty("value")?ni(e,t.type,n):t.hasOwnProperty("defaultValue")&&ni(e,t.type,ht(t.defaultValue)),t.checked==null&&t.defaultChecked!=null&&(e.defaultChecked=!!t.defaultChecked)}function Vo(e,t,n){if(t.hasOwnProperty("value")||t.hasOwnProperty("defaultValue")){var r=t.type;if(!(r!=="submit"&&r!=="reset"||t.value!==void 0&&t.value!==null))return;t=""+e._wrapperState.initialValue,n||t===e.value||(e.value=t),e.defaultValue=t}n=e.name,n!==""&&(e.name=""),e.defaultChecked=!!e._wrapperState.initialChecked,n!==""&&(e.name=n)}function ni(e,t,n){(t!=="number"||Dr(e.ownerDocument)!==e)&&(n==null?e.defaultValue=""+e._wrapperState.initialValue:e.defaultValue!==""+n&&(e.defaultValue=""+n))}var Sn=Array.isArray;function Xt(e,t,n,r){if(e=e.options,t){t={};for(var l=0;l"+t.valueOf().toString()+"",t=ur.firstChild;e.firstChild;)e.removeChild(e.firstChild);for(;t.firstChild;)e.appendChild(t.firstChild)}});function Fn(e,t){if(t){var n=e.firstChild;if(n&&n===e.lastChild&&n.nodeType===3){n.nodeValue=t;return}}e.textContent=t}var En={animationIterationCount:!0,aspectRatio:!0,borderImageOutset:!0,borderImageSlice:!0,borderImageWidth:!0,boxFlex:!0,boxFlexGroup:!0,boxOrdinalGroup:!0,columnCount:!0,columns:!0,flex:!0,flexGrow:!0,flexPositive:!0,flexShrink:!0,flexNegative:!0,flexOrder:!0,gridArea:!0,gridRow:!0,gridRowEnd:!0,gridRowSpan:!0,gridRowStart:!0,gridColumn:!0,gridColumnEnd:!0,gridColumnSpan:!0,gridColumnStart:!0,fontWeight:!0,lineClamp:!0,lineHeight:!0,opacity:!0,order:!0,orphans:!0,tabSize:!0,widows:!0,zIndex:!0,zoom:!0,fillOpacity:!0,floodOpacity:!0,stopOpacity:!0,strokeDasharray:!0,strokeDashoffset:!0,strokeMiterlimit:!0,strokeOpacity:!0,strokeWidth:!0},Uc=["Webkit","ms","Moz","O"];Object.keys(En).forEach(function(e){Uc.forEach(function(t){t=t+e.charAt(0).toUpperCase()+e.substring(1),En[t]=En[e]})});function gu(e,t,n){return t==null||typeof t=="boolean"||t===""?"":n||typeof t!="number"||t===0||En.hasOwnProperty(e)&&En[e]?(""+t).trim():t+"px"}function _u(e,t){e=e.style;for(var n in t)if(t.hasOwnProperty(n)){var r=n.indexOf("--")===0,l=gu(n,t[n],r);n==="float"&&(n="cssFloat"),r?e.setProperty(n,l):e[n]=l}}var $c=B({menuitem:!0},{area:!0,base:!0,br:!0,col:!0,embed:!0,hr:!0,img:!0,input:!0,keygen:!0,link:!0,meta:!0,param:!0,source:!0,track:!0,wbr:!0});function ii(e,t){if(t){if($c[e]&&(t.children!=null||t.dangerouslySetInnerHTML!=null))throw Error(g(137,e));if(t.dangerouslySetInnerHTML!=null){if(t.children!=null)throw Error(g(60));if(typeof t.dangerouslySetInnerHTML!="object"||!("__html"in t.dangerouslySetInnerHTML))throw Error(g(61))}if(t.style!=null&&typeof t.style!="object")throw Error(g(62))}}function oi(e,t){if(e.indexOf("-")===-1)return typeof t.is=="string";switch(e){case"annotation-xml":case"color-profile":case"font-face":case"font-face-src":case"font-face-uri":case"font-face-format":case"font-face-name":case"missing-glyph":return!1;default:return!0}}var si=null;function Ji(e){return e=e.target||e.srcElement||window,e.correspondingUseElement&&(e=e.correspondingUseElement),e.nodeType===3?e.parentNode:e}var ui=null,Yt=null,Zt=null;function Ko(e){if(e=tr(e)){if(typeof ui!="function")throw Error(g(280));var t=e.stateNode;t&&(t=al(t),ui(e.stateNode,e.type,t))}}function xu(e){Yt?Zt?Zt.push(e):Zt=[e]:Yt=e}function wu(){if(Yt){var e=Yt,t=Zt;if(Zt=Yt=null,Ko(e),t)for(e=0;e>>=0,e===0?32:31-(Jc(e)/qc|0)|0}var ar=64,cr=4194304;function Nn(e){switch(e&-e){case 1:return 1;case 2:return 2;case 4:return 4;case 8:return 8;case 16:return 16;case 32:return 32;case 64:case 128:case 256:case 512:case 1024:case 2048:case 4096:case 8192:case 16384:case 32768:case 65536:case 131072:case 262144:case 524288:case 1048576:case 2097152:return e&4194240;case 4194304:case 8388608:case 16777216:case 33554432:case 67108864:return e&130023424;case 134217728:return 134217728;case 268435456:return 268435456;case 536870912:return 536870912;case 1073741824:return 1073741824;default:return e}}function Ar(e,t){var n=e.pendingLanes;if(n===0)return 0;var r=0,l=e.suspendedLanes,i=e.pingedLanes,o=n&268435455;if(o!==0){var u=o&~l;u!==0?r=Nn(u):(i&=o,i!==0&&(r=Nn(i)))}else o=n&~l,o!==0?r=Nn(o):i!==0&&(r=Nn(i));if(r===0)return 0;if(t!==0&&t!==r&&!(t&l)&&(l=r&-r,i=t&-t,l>=i||l===16&&(i&4194240)!==0))return t;if(r&4&&(r|=n&16),t=e.entangledLanes,t!==0)for(e=e.entanglements,t&=r;0n;n++)t.push(e);return t}function bn(e,t,n){e.pendingLanes|=t,t!==536870912&&(e.suspendedLanes=0,e.pingedLanes=0),e=e.eventTimes,t=31-Re(t),e[t]=n}function nd(e,t){var n=e.pendingLanes&~t;e.pendingLanes=t,e.suspendedLanes=0,e.pingedLanes=0,e.expiredLanes&=t,e.mutableReadLanes&=t,e.entangledLanes&=t,t=e.entanglements;var r=e.eventTimes;for(e=e.expirationTimes;0=Pn),ns=" ",rs=!1;function Bu(e,t){switch(e){case"keyup":return Ld.indexOf(t.keyCode)!==-1;case"keydown":return t.keyCode!==229;case"keypress":case"mousedown":case"focusout":return!0;default:return!1}}function Hu(e){return e=e.detail,typeof e=="object"&&"data"in e?e.data:null}var At=!1;function Rd(e,t){switch(e){case"compositionend":return Hu(t);case"keypress":return t.which!==32?null:(rs=!0,ns);case"textInput":return e=t.data,e===ns&&rs?null:e;default:return null}}function Md(e,t){if(At)return e==="compositionend"||!io&&Bu(e,t)?(e=Uu(),jr=no=lt=null,At=!1,e):null;switch(e){case"paste":return null;case"keypress":if(!(t.ctrlKey||t.altKey||t.metaKey)||t.ctrlKey&&t.altKey){if(t.char&&1=t)return{node:n,offset:t-e};e=r}e:{for(;n;){if(n.nextSibling){n=n.nextSibling;break e}n=n.parentNode}n=void 0}n=ss(n)}}function Gu(e,t){return e&&t?e===t?!0:e&&e.nodeType===3?!1:t&&t.nodeType===3?Gu(e,t.parentNode):"contains"in e?e.contains(t):e.compareDocumentPosition?!!(e.compareDocumentPosition(t)&16):!1:!1}function Ku(){for(var e=window,t=Dr();t instanceof e.HTMLIFrameElement;){try{var n=typeof t.contentWindow.location.href=="string"}catch{n=!1}if(n)e=t.contentWindow;else break;t=Dr(e.document)}return t}function oo(e){var t=e&&e.nodeName&&e.nodeName.toLowerCase();return t&&(t==="input"&&(e.type==="text"||e.type==="search"||e.type==="tel"||e.type==="url"||e.type==="password")||t==="textarea"||e.contentEditable==="true")}function Hd(e){var t=Ku(),n=e.focusedElem,r=e.selectionRange;if(t!==n&&n&&n.ownerDocument&&Gu(n.ownerDocument.documentElement,n)){if(r!==null&&oo(n)){if(t=r.start,e=r.end,e===void 0&&(e=t),"selectionStart"in n)n.selectionStart=t,n.selectionEnd=Math.min(e,n.value.length);else if(e=(t=n.ownerDocument||document)&&t.defaultView||window,e.getSelection){e=e.getSelection();var l=n.textContent.length,i=Math.min(r.start,l);r=r.end===void 0?i:Math.min(r.end,l),!e.extend&&i>r&&(l=r,r=i,i=l),l=us(n,i);var o=us(n,r);l&&o&&(e.rangeCount!==1||e.anchorNode!==l.node||e.anchorOffset!==l.offset||e.focusNode!==o.node||e.focusOffset!==o.offset)&&(t=t.createRange(),t.setStart(l.node,l.offset),e.removeAllRanges(),i>r?(e.addRange(t),e.extend(o.node,o.offset)):(t.setEnd(o.node,o.offset),e.addRange(t)))}}for(t=[],e=n;e=e.parentNode;)e.nodeType===1&&t.push({element:e,left:e.scrollLeft,top:e.scrollTop});for(typeof n.focus=="function"&&n.focus(),n=0;n=document.documentMode,Ut=null,hi=null,Ln=null,mi=!1;function as(e,t,n){var r=n.window===n?n.document:n.nodeType===9?n:n.ownerDocument;mi||Ut==null||Ut!==Dr(r)||(r=Ut,"selectionStart"in r&&oo(r)?r={start:r.selectionStart,end:r.selectionEnd}:(r=(r.ownerDocument&&r.ownerDocument.defaultView||window).getSelection(),r={anchorNode:r.anchorNode,anchorOffset:r.anchorOffset,focusNode:r.focusNode,focusOffset:r.focusOffset}),Ln&&Hn(Ln,r)||(Ln=r,r=Br(hi,"onSelect"),0Ht||(e.current=wi[Ht],wi[Ht]=null,Ht--)}function O(e,t){Ht++,wi[Ht]=e.current,e.current=t}var mt={},le=yt(mt),de=yt(!1),Pt=mt;function tn(e,t){var n=e.type.contextTypes;if(!n)return mt;var r=e.stateNode;if(r&&r.__reactInternalMemoizedUnmaskedChildContext===t)return r.__reactInternalMemoizedMaskedChildContext;var l={},i;for(i in n)l[i]=t[i];return r&&(e=e.stateNode,e.__reactInternalMemoizedUnmaskedChildContext=t,e.__reactInternalMemoizedMaskedChildContext=l),l}function fe(e){return e=e.childContextTypes,e!=null}function Wr(){I(de),I(le)}function vs(e,t,n){if(le.current!==mt)throw Error(g(168));O(le,t),O(de,n)}function na(e,t,n){var r=e.stateNode;if(t=t.childContextTypes,typeof r.getChildContext!="function")return n;r=r.getChildContext();for(var l in r)if(!(l in t))throw Error(g(108,Ic(e)||"Unknown",l));return B({},n,r)}function Vr(e){return e=(e=e.stateNode)&&e.__reactInternalMemoizedMergedChildContext||mt,Pt=le.current,O(le,e),O(de,de.current),!0}function ys(e,t,n){var r=e.stateNode;if(!r)throw Error(g(169));n?(e=na(e,t,Pt),r.__reactInternalMemoizedMergedChildContext=e,I(de),I(le),O(le,e)):I(de),O(de,n)}var We=null,cl=!1,$l=!1;function ra(e){We===null?We=[e]:We.push(e)}function ef(e){cl=!0,ra(e)}function gt(){if(!$l&&We!==null){$l=!0;var e=0,t=D;try{var n=We;for(D=1;e>=o,l-=o,Ve=1<<32-Re(t)+l|n<C?(W=E,E=null):W=E.sibling;var T=h(d,E,p[C],y);if(T===null){E===null&&(E=W);break}e&&E&&T.alternate===null&&t(d,E),c=i(T,c,C),j===null?k=T:j.sibling=T,j=T,E=W}if(C===p.length)return n(d,E),A&&wt(d,C),k;if(E===null){for(;CC?(W=E,E=null):W=E.sibling;var Ce=h(d,E,T.value,y);if(Ce===null){E===null&&(E=W);break}e&&E&&Ce.alternate===null&&t(d,E),c=i(Ce,c,C),j===null?k=Ce:j.sibling=Ce,j=Ce,E=W}if(T.done)return n(d,E),A&&wt(d,C),k;if(E===null){for(;!T.done;C++,T=p.next())T=m(d,T.value,y),T!==null&&(c=i(T,c,C),j===null?k=T:j.sibling=T,j=T);return A&&wt(d,C),k}for(E=r(d,E);!T.done;C++,T=p.next())T=_(E,d,C,T.value,y),T!==null&&(e&&T.alternate!==null&&E.delete(T.key===null?C:T.key),c=i(T,c,C),j===null?k=T:j.sibling=T,j=T);return e&&E.forEach(function(dn){return t(d,dn)}),A&&wt(d,C),k}function M(d,c,p,y){if(typeof p=="object"&&p!==null&&p.type===It&&p.key===null&&(p=p.props.children),typeof p=="object"&&p!==null){switch(p.$$typeof){case or:e:{for(var k=p.key,j=c;j!==null;){if(j.key===k){if(k=p.type,k===It){if(j.tag===7){n(d,j.sibling),c=l(j,p.props.children),c.return=d,d=c;break e}}else if(j.elementType===k||typeof k=="object"&&k!==null&&k.$$typeof===et&&xs(k)===j.type){n(d,j.sibling),c=l(j,p.props),c.ref=gn(d,j,p),c.return=d,d=c;break e}n(d,j);break}else t(d,j);j=j.sibling}p.type===It?(c=Ct(p.props.children,d.mode,y,p.key),c.return=d,d=c):(y=Mr(p.type,p.key,p.props,null,d.mode,y),y.ref=gn(d,c,p),y.return=d,d=y)}return o(d);case Ft:e:{for(j=p.key;c!==null;){if(c.key===j)if(c.tag===4&&c.stateNode.containerInfo===p.containerInfo&&c.stateNode.implementation===p.implementation){n(d,c.sibling),c=l(c,p.children||[]),c.return=d,d=c;break e}else{n(d,c);break}else t(d,c);c=c.sibling}c=Xl(p,d.mode,y),c.return=d,d=c}return o(d);case et:return j=p._init,M(d,c,j(p._payload),y)}if(Sn(p))return w(d,c,p,y);if(pn(p))return x(d,c,p,y);yr(d,p)}return typeof p=="string"&&p!==""||typeof p=="number"?(p=""+p,c!==null&&c.tag===6?(n(d,c.sibling),c=l(c,p),c.return=d,d=c):(n(d,c),c=Kl(p,d.mode,y),c.return=d,d=c),o(d)):n(d,c)}return M}var rn=sa(!0),ua=sa(!1),Kr=yt(null),Xr=null,Qt=null,co=null;function fo(){co=Qt=Xr=null}function po(e){var t=Kr.current;I(Kr),e._currentValue=t}function Ni(e,t,n){for(;e!==null;){var r=e.alternate;if((e.childLanes&t)!==t?(e.childLanes|=t,r!==null&&(r.childLanes|=t)):r!==null&&(r.childLanes&t)!==t&&(r.childLanes|=t),e===n)break;e=e.return}}function qt(e,t){Xr=e,co=Qt=null,e=e.dependencies,e!==null&&e.firstContext!==null&&(e.lanes&t&&(ce=!0),e.firstContext=null)}function je(e){var t=e._currentValue;if(co!==e)if(e={context:e,memoizedValue:t,next:null},Qt===null){if(Xr===null)throw Error(g(308));Qt=e,Xr.dependencies={lanes:0,firstContext:e}}else Qt=Qt.next=e;return t}var Nt=null;function ho(e){Nt===null?Nt=[e]:Nt.push(e)}function aa(e,t,n,r){var l=t.interleaved;return l===null?(n.next=n,ho(t)):(n.next=l.next,l.next=n),t.interleaved=n,Ye(e,r)}function Ye(e,t){e.lanes|=t;var n=e.alternate;for(n!==null&&(n.lanes|=t),n=e,e=e.return;e!==null;)e.childLanes|=t,n=e.alternate,n!==null&&(n.childLanes|=t),n=e,e=e.return;return n.tag===3?n.stateNode:null}var tt=!1;function mo(e){e.updateQueue={baseState:e.memoizedState,firstBaseUpdate:null,lastBaseUpdate:null,shared:{pending:null,interleaved:null,lanes:0},effects:null}}function ca(e,t){e=e.updateQueue,t.updateQueue===e&&(t.updateQueue={baseState:e.baseState,firstBaseUpdate:e.firstBaseUpdate,lastBaseUpdate:e.lastBaseUpdate,shared:e.shared,effects:e.effects})}function Ge(e,t){return{eventTime:e,lane:t,tag:0,payload:null,callback:null,next:null}}function ct(e,t,n){var r=e.updateQueue;if(r===null)return null;if(r=r.shared,R&2){var l=r.pending;return l===null?t.next=t:(t.next=l.next,l.next=t),r.pending=t,Ye(e,n)}return l=r.interleaved,l===null?(t.next=t,ho(r)):(t.next=l.next,l.next=t),r.interleaved=t,Ye(e,n)}function Cr(e,t,n){if(t=t.updateQueue,t!==null&&(t=t.shared,(n&4194240)!==0)){var r=t.lanes;r&=e.pendingLanes,n|=r,t.lanes=n,bi(e,n)}}function ws(e,t){var n=e.updateQueue,r=e.alternate;if(r!==null&&(r=r.updateQueue,n===r)){var l=null,i=null;if(n=n.firstBaseUpdate,n!==null){do{var o={eventTime:n.eventTime,lane:n.lane,tag:n.tag,payload:n.payload,callback:n.callback,next:null};i===null?l=i=o:i=i.next=o,n=n.next}while(n!==null);i===null?l=i=t:i=i.next=t}else l=i=t;n={baseState:r.baseState,firstBaseUpdate:l,lastBaseUpdate:i,shared:r.shared,effects:r.effects},e.updateQueue=n;return}e=n.lastBaseUpdate,e===null?n.firstBaseUpdate=t:e.next=t,n.lastBaseUpdate=t}function Yr(e,t,n,r){var l=e.updateQueue;tt=!1;var i=l.firstBaseUpdate,o=l.lastBaseUpdate,u=l.shared.pending;if(u!==null){l.shared.pending=null;var a=u,f=a.next;a.next=null,o===null?i=f:o.next=f,o=a;var v=e.alternate;v!==null&&(v=v.updateQueue,u=v.lastBaseUpdate,u!==o&&(u===null?v.firstBaseUpdate=f:u.next=f,v.lastBaseUpdate=a))}if(i!==null){var m=l.baseState;o=0,v=f=a=null,u=i;do{var h=u.lane,_=u.eventTime;if((r&h)===h){v!==null&&(v=v.next={eventTime:_,lane:0,tag:u.tag,payload:u.payload,callback:u.callback,next:null});e:{var w=e,x=u;switch(h=t,_=n,x.tag){case 1:if(w=x.payload,typeof w=="function"){m=w.call(_,m,h);break e}m=w;break e;case 3:w.flags=w.flags&-65537|128;case 0:if(w=x.payload,h=typeof w=="function"?w.call(_,m,h):w,h==null)break e;m=B({},m,h);break e;case 2:tt=!0}}u.callback!==null&&u.lane!==0&&(e.flags|=64,h=l.effects,h===null?l.effects=[u]:h.push(u))}else _={eventTime:_,lane:h,tag:u.tag,payload:u.payload,callback:u.callback,next:null},v===null?(f=v=_,a=m):v=v.next=_,o|=h;if(u=u.next,u===null){if(u=l.shared.pending,u===null)break;h=u,u=h.next,h.next=null,l.lastBaseUpdate=h,l.shared.pending=null}}while(!0);if(v===null&&(a=m),l.baseState=a,l.firstBaseUpdate=f,l.lastBaseUpdate=v,t=l.shared.interleaved,t!==null){l=t;do o|=l.lane,l=l.next;while(l!==t)}else i===null&&(l.shared.lanes=0);Tt|=o,e.lanes=o,e.memoizedState=m}}function ks(e,t,n){if(e=t.effects,t.effects=null,e!==null)for(t=0;tn?n:4,e(!0);var r=Hl.transition;Hl.transition={};try{e(!1),t()}finally{D=n,Hl.transition=r}}function Ca(){return Ee().memoizedState}function lf(e,t,n){var r=ft(e);if(n={lane:r,action:n,hasEagerState:!1,eagerState:null,next:null},Pa(e))za(t,n);else if(n=aa(e,t,n,r),n!==null){var l=oe();Me(n,e,r,l),La(n,t,r)}}function of(e,t,n){var r=ft(e),l={lane:r,action:n,hasEagerState:!1,eagerState:null,next:null};if(Pa(e))za(t,l);else{var i=e.alternate;if(e.lanes===0&&(i===null||i.lanes===0)&&(i=t.lastRenderedReducer,i!==null))try{var o=t.lastRenderedState,u=i(o,n);if(l.hasEagerState=!0,l.eagerState=u,De(u,o)){var a=t.interleaved;a===null?(l.next=l,ho(t)):(l.next=a.next,a.next=l),t.interleaved=l;return}}catch{}finally{}n=aa(e,t,l,r),n!==null&&(l=oe(),Me(n,e,r,l),La(n,t,r))}}function Pa(e){var t=e.alternate;return e===$||t!==null&&t===$}function za(e,t){Tn=Jr=!0;var n=e.pending;n===null?t.next=t:(t.next=n.next,n.next=t),e.pending=t}function La(e,t,n){if(n&4194240){var r=t.lanes;r&=e.pendingLanes,n|=r,t.lanes=n,bi(e,n)}}var qr={readContext:je,useCallback:te,useContext:te,useEffect:te,useImperativeHandle:te,useInsertionEffect:te,useLayoutEffect:te,useMemo:te,useReducer:te,useRef:te,useState:te,useDebugValue:te,useDeferredValue:te,useTransition:te,useMutableSource:te,useSyncExternalStore:te,useId:te,unstable_isNewReconciler:!1},sf={readContext:je,useCallback:function(e,t){return Fe().memoizedState=[e,t===void 0?null:t],e},useContext:je,useEffect:Ns,useImperativeHandle:function(e,t,n){return n=n!=null?n.concat([e]):null,zr(4194308,4,ka.bind(null,t,e),n)},useLayoutEffect:function(e,t){return zr(4194308,4,e,t)},useInsertionEffect:function(e,t){return zr(4,2,e,t)},useMemo:function(e,t){var n=Fe();return t=t===void 0?null:t,e=e(),n.memoizedState=[e,t],e},useReducer:function(e,t,n){var r=Fe();return t=n!==void 0?n(t):t,r.memoizedState=r.baseState=t,e={pending:null,interleaved:null,lanes:0,dispatch:null,lastRenderedReducer:e,lastRenderedState:t},r.queue=e,e=e.dispatch=lf.bind(null,$,e),[r.memoizedState,e]},useRef:function(e){var t=Fe();return e={current:e},t.memoizedState=e},useState:Ss,useDebugValue:So,useDeferredValue:function(e){return Fe().memoizedState=e},useTransition:function(){var e=Ss(!1),t=e[0];return e=rf.bind(null,e[1]),Fe().memoizedState=e,[t,e]},useMutableSource:function(){},useSyncExternalStore:function(e,t,n){var r=$,l=Fe();if(A){if(n===void 0)throw Error(g(407));n=n()}else{if(n=t(),J===null)throw Error(g(349));Lt&30||ha(r,t,n)}l.memoizedState=n;var i={value:n,getSnapshot:t};return l.queue=i,Ns(va.bind(null,r,i,e),[e]),r.flags|=2048,Zn(9,ma.bind(null,r,i,n,t),void 0,null),n},useId:function(){var e=Fe(),t=J.identifierPrefix;if(A){var n=Qe,r=Ve;n=(r&~(1<<32-Re(r)-1)).toString(32)+n,t=":"+t+"R"+n,n=Xn++,0<\/script>",e=e.removeChild(e.firstChild)):typeof r.is=="string"?e=o.createElement(n,{is:r.is}):(e=o.createElement(n),n==="select"&&(o=e,r.multiple?o.multiple=!0:r.size&&(o.size=r.size))):e=o.createElementNS(e,n),e[Ie]=t,e[Qn]=r,$a(e,t,!1,!1),t.stateNode=e;e:{switch(o=oi(n,r),n){case"dialog":F("cancel",e),F("close",e),l=r;break;case"iframe":case"object":case"embed":F("load",e),l=r;break;case"video":case"audio":for(l=0;lsn&&(t.flags|=128,r=!0,_n(i,!1),t.lanes=4194304)}else{if(!r)if(e=Zr(o),e!==null){if(t.flags|=128,r=!0,n=e.updateQueue,n!==null&&(t.updateQueue=n,t.flags|=4),_n(i,!0),i.tail===null&&i.tailMode==="hidden"&&!o.alternate&&!A)return ne(t),null}else 2*Q()-i.renderingStartTime>sn&&n!==1073741824&&(t.flags|=128,r=!0,_n(i,!1),t.lanes=4194304);i.isBackwards?(o.sibling=t.child,t.child=o):(n=i.last,n!==null?n.sibling=o:t.child=o,i.last=o)}return i.tail!==null?(t=i.tail,i.rendering=t,i.tail=t.sibling,i.renderingStartTime=Q(),t.sibling=null,n=U.current,O(U,r?n&1|2:n&1),t):(ne(t),null);case 22:case 23:return zo(),r=t.memoizedState!==null,e!==null&&e.memoizedState!==null!==r&&(t.flags|=8192),r&&t.mode&1?he&1073741824&&(ne(t),t.subtreeFlags&6&&(t.flags|=8192)):ne(t),null;case 24:return null;case 25:return null}throw Error(g(156,t.tag))}function mf(e,t){switch(uo(t),t.tag){case 1:return fe(t.type)&&Wr(),e=t.flags,e&65536?(t.flags=e&-65537|128,t):null;case 3:return ln(),I(de),I(le),go(),e=t.flags,e&65536&&!(e&128)?(t.flags=e&-65537|128,t):null;case 5:return yo(t),null;case 13:if(I(U),e=t.memoizedState,e!==null&&e.dehydrated!==null){if(t.alternate===null)throw Error(g(340));nn()}return e=t.flags,e&65536?(t.flags=e&-65537|128,t):null;case 19:return I(U),null;case 4:return ln(),null;case 10:return po(t.type._context),null;case 22:case 23:return zo(),null;case 24:return null;default:return null}}var _r=!1,re=!1,vf=typeof WeakSet=="function"?WeakSet:Set,S=null;function Gt(e,t){var n=e.ref;if(n!==null)if(typeof n=="function")try{n(null)}catch(r){H(e,t,r)}else n.current=null}function Mi(e,t,n){try{n()}catch(r){H(e,t,r)}}var Os=!1;function yf(e,t){if(vi=Ur,e=Ku(),oo(e)){if("selectionStart"in e)var n={start:e.selectionStart,end:e.selectionEnd};else e:{n=(n=e.ownerDocument)&&n.defaultView||window;var r=n.getSelection&&n.getSelection();if(r&&r.rangeCount!==0){n=r.anchorNode;var l=r.anchorOffset,i=r.focusNode;r=r.focusOffset;try{n.nodeType,i.nodeType}catch{n=null;break e}var o=0,u=-1,a=-1,f=0,v=0,m=e,h=null;t:for(;;){for(var _;m!==n||l!==0&&m.nodeType!==3||(u=o+l),m!==i||r!==0&&m.nodeType!==3||(a=o+r),m.nodeType===3&&(o+=m.nodeValue.length),(_=m.firstChild)!==null;)h=m,m=_;for(;;){if(m===e)break t;if(h===n&&++f===l&&(u=o),h===i&&++v===r&&(a=o),(_=m.nextSibling)!==null)break;m=h,h=m.parentNode}m=_}n=u===-1||a===-1?null:{start:u,end:a}}else n=null}n=n||{start:0,end:0}}else n=null;for(yi={focusedElem:e,selectionRange:n},Ur=!1,S=t;S!==null;)if(t=S,e=t.child,(t.subtreeFlags&1028)!==0&&e!==null)e.return=t,S=e;else for(;S!==null;){t=S;try{var w=t.alternate;if(t.flags&1024)switch(t.tag){case 0:case 11:case 15:break;case 1:if(w!==null){var x=w.memoizedProps,M=w.memoizedState,d=t.stateNode,c=d.getSnapshotBeforeUpdate(t.elementType===t.type?x:ze(t.type,x),M);d.__reactInternalSnapshotBeforeUpdate=c}break;case 3:var p=t.stateNode.containerInfo;p.nodeType===1?p.textContent="":p.nodeType===9&&p.documentElement&&p.removeChild(p.documentElement);break;case 5:case 6:case 4:case 17:break;default:throw Error(g(163))}}catch(y){H(t,t.return,y)}if(e=t.sibling,e!==null){e.return=t.return,S=e;break}S=t.return}return w=Os,Os=!1,w}function Rn(e,t,n){var r=t.updateQueue;if(r=r!==null?r.lastEffect:null,r!==null){var l=r=r.next;do{if((l.tag&e)===e){var i=l.destroy;l.destroy=void 0,i!==void 0&&Mi(t,n,i)}l=l.next}while(l!==r)}}function pl(e,t){if(t=t.updateQueue,t=t!==null?t.lastEffect:null,t!==null){var n=t=t.next;do{if((n.tag&e)===e){var r=n.create;n.destroy=r()}n=n.next}while(n!==t)}}function Di(e){var t=e.ref;if(t!==null){var n=e.stateNode;switch(e.tag){case 5:e=n;break;default:e=n}typeof t=="function"?t(e):t.current=e}}function Wa(e){var t=e.alternate;t!==null&&(e.alternate=null,Wa(t)),e.child=null,e.deletions=null,e.sibling=null,e.tag===5&&(t=e.stateNode,t!==null&&(delete t[Ie],delete t[Qn],delete t[xi],delete t[qd],delete t[bd])),e.stateNode=null,e.return=null,e.dependencies=null,e.memoizedProps=null,e.memoizedState=null,e.pendingProps=null,e.stateNode=null,e.updateQueue=null}function Va(e){return e.tag===5||e.tag===3||e.tag===4}function Fs(e){e:for(;;){for(;e.sibling===null;){if(e.return===null||Va(e.return))return null;e=e.return}for(e.sibling.return=e.return,e=e.sibling;e.tag!==5&&e.tag!==6&&e.tag!==18;){if(e.flags&2||e.child===null||e.tag===4)continue e;e.child.return=e,e=e.child}if(!(e.flags&2))return e.stateNode}}function Oi(e,t,n){var r=e.tag;if(r===5||r===6)e=e.stateNode,t?n.nodeType===8?n.parentNode.insertBefore(e,t):n.insertBefore(e,t):(n.nodeType===8?(t=n.parentNode,t.insertBefore(e,n)):(t=n,t.appendChild(e)),n=n._reactRootContainer,n!=null||t.onclick!==null||(t.onclick=Hr));else if(r!==4&&(e=e.child,e!==null))for(Oi(e,t,n),e=e.sibling;e!==null;)Oi(e,t,n),e=e.sibling}function Fi(e,t,n){var r=e.tag;if(r===5||r===6)e=e.stateNode,t?n.insertBefore(e,t):n.appendChild(e);else if(r!==4&&(e=e.child,e!==null))for(Fi(e,t,n),e=e.sibling;e!==null;)Fi(e,t,n),e=e.sibling}var q=null,Le=!1;function qe(e,t,n){for(n=n.child;n!==null;)Qa(e,t,n),n=n.sibling}function Qa(e,t,n){if(Ue&&typeof Ue.onCommitFiberUnmount=="function")try{Ue.onCommitFiberUnmount(il,n)}catch{}switch(n.tag){case 5:re||Gt(n,t);case 6:var r=q,l=Le;q=null,qe(e,t,n),q=r,Le=l,q!==null&&(Le?(e=q,n=n.stateNode,e.nodeType===8?e.parentNode.removeChild(n):e.removeChild(n)):q.removeChild(n.stateNode));break;case 18:q!==null&&(Le?(e=q,n=n.stateNode,e.nodeType===8?Ul(e.parentNode,n):e.nodeType===1&&Ul(e,n),$n(e)):Ul(q,n.stateNode));break;case 4:r=q,l=Le,q=n.stateNode.containerInfo,Le=!0,qe(e,t,n),q=r,Le=l;break;case 0:case 11:case 14:case 15:if(!re&&(r=n.updateQueue,r!==null&&(r=r.lastEffect,r!==null))){l=r=r.next;do{var i=l,o=i.destroy;i=i.tag,o!==void 0&&(i&2||i&4)&&Mi(n,t,o),l=l.next}while(l!==r)}qe(e,t,n);break;case 1:if(!re&&(Gt(n,t),r=n.stateNode,typeof r.componentWillUnmount=="function"))try{r.props=n.memoizedProps,r.state=n.memoizedState,r.componentWillUnmount()}catch(u){H(n,t,u)}qe(e,t,n);break;case 21:qe(e,t,n);break;case 22:n.mode&1?(re=(r=re)||n.memoizedState!==null,qe(e,t,n),re=r):qe(e,t,n);break;default:qe(e,t,n)}}function Is(e){var t=e.updateQueue;if(t!==null){e.updateQueue=null;var n=e.stateNode;n===null&&(n=e.stateNode=new vf),t.forEach(function(r){var l=Ef.bind(null,e,r);n.has(r)||(n.add(r),r.then(l,l))})}}function Pe(e,t){var n=t.deletions;if(n!==null)for(var r=0;rl&&(l=o),r&=~i}if(r=l,r=Q()-r,r=(120>r?120:480>r?480:1080>r?1080:1920>r?1920:3e3>r?3e3:4320>r?4320:1960*_f(r/1960))-r,10e?16:e,it===null)var r=!1;else{if(e=it,it=null,tl=0,R&6)throw Error(g(331));var l=R;for(R|=4,S=e.current;S!==null;){var i=S,o=i.child;if(S.flags&16){var u=i.deletions;if(u!==null){for(var a=0;aQ()-Co?Et(e,0):Eo|=n),pe(e,t)}function ba(e,t){t===0&&(e.mode&1?(t=cr,cr<<=1,!(cr&130023424)&&(cr=4194304)):t=1);var n=oe();e=Ye(e,t),e!==null&&(bn(e,t,n),pe(e,n))}function jf(e){var t=e.memoizedState,n=0;t!==null&&(n=t.retryLane),ba(e,n)}function Ef(e,t){var n=0;switch(e.tag){case 13:var r=e.stateNode,l=e.memoizedState;l!==null&&(n=l.retryLane);break;case 19:r=e.stateNode;break;default:throw Error(g(314))}r!==null&&r.delete(t),ba(e,n)}var ec;ec=function(e,t,n){if(e!==null)if(e.memoizedProps!==t.pendingProps||de.current)ce=!0;else{if(!(e.lanes&n)&&!(t.flags&128))return ce=!1,pf(e,t,n);ce=!!(e.flags&131072)}else ce=!1,A&&t.flags&1048576&&la(t,Gr,t.index);switch(t.lanes=0,t.tag){case 2:var r=t.type;Lr(e,t),e=t.pendingProps;var l=tn(t,le.current);qt(t,n),l=xo(null,t,r,e,l,n);var i=wo();return t.flags|=1,typeof l=="object"&&l!==null&&typeof l.render=="function"&&l.$$typeof===void 0?(t.tag=1,t.memoizedState=null,t.updateQueue=null,fe(r)?(i=!0,Vr(t)):i=!1,t.memoizedState=l.state!==null&&l.state!==void 0?l.state:null,mo(t),l.updater=fl,t.stateNode=l,l._reactInternals=t,Ei(t,r,e,n),t=zi(null,t,r,!0,i,n)):(t.tag=0,A&&i&&so(t),ie(null,t,l,n),t=t.child),t;case 16:r=t.elementType;e:{switch(Lr(e,t),e=t.pendingProps,l=r._init,r=l(r._payload),t.type=r,l=t.tag=Pf(r),e=ze(r,e),l){case 0:t=Pi(null,t,r,e,n);break e;case 1:t=Rs(null,t,r,e,n);break e;case 11:t=Ls(null,t,r,e,n);break e;case 14:t=Ts(null,t,r,ze(r.type,e),n);break e}throw Error(g(306,r,""))}return t;case 0:return r=t.type,l=t.pendingProps,l=t.elementType===r?l:ze(r,l),Pi(e,t,r,l,n);case 1:return r=t.type,l=t.pendingProps,l=t.elementType===r?l:ze(r,l),Rs(e,t,r,l,n);case 3:e:{if(Ia(t),e===null)throw Error(g(387));r=t.pendingProps,i=t.memoizedState,l=i.element,ca(e,t),Yr(t,r,null,n);var o=t.memoizedState;if(r=o.element,i.isDehydrated)if(i={element:r,isDehydrated:!1,cache:o.cache,pendingSuspenseBoundaries:o.pendingSuspenseBoundaries,transitions:o.transitions},t.updateQueue.baseState=i,t.memoizedState=i,t.flags&256){l=on(Error(g(423)),t),t=Ms(e,t,r,n,l);break e}else if(r!==l){l=on(Error(g(424)),t),t=Ms(e,t,r,n,l);break e}else for(me=at(t.stateNode.containerInfo.firstChild),ve=t,A=!0,Te=null,n=ua(t,null,r,n),t.child=n;n;)n.flags=n.flags&-3|4096,n=n.sibling;else{if(nn(),r===l){t=Ze(e,t,n);break e}ie(e,t,r,n)}t=t.child}return t;case 5:return da(t),e===null&&Si(t),r=t.type,l=t.pendingProps,i=e!==null?e.memoizedProps:null,o=l.children,gi(r,l)?o=null:i!==null&&gi(r,i)&&(t.flags|=32),Fa(e,t),ie(e,t,o,n),t.child;case 6:return e===null&&Si(t),null;case 13:return Aa(e,t,n);case 4:return vo(t,t.stateNode.containerInfo),r=t.pendingProps,e===null?t.child=rn(t,null,r,n):ie(e,t,r,n),t.child;case 11:return r=t.type,l=t.pendingProps,l=t.elementType===r?l:ze(r,l),Ls(e,t,r,l,n);case 7:return ie(e,t,t.pendingProps,n),t.child;case 8:return ie(e,t,t.pendingProps.children,n),t.child;case 12:return ie(e,t,t.pendingProps.children,n),t.child;case 10:e:{if(r=t.type._context,l=t.pendingProps,i=t.memoizedProps,o=l.value,O(Kr,r._currentValue),r._currentValue=o,i!==null)if(De(i.value,o)){if(i.children===l.children&&!de.current){t=Ze(e,t,n);break e}}else for(i=t.child,i!==null&&(i.return=t);i!==null;){var u=i.dependencies;if(u!==null){o=i.child;for(var a=u.firstContext;a!==null;){if(a.context===r){if(i.tag===1){a=Ge(-1,n&-n),a.tag=2;var f=i.updateQueue;if(f!==null){f=f.shared;var v=f.pending;v===null?a.next=a:(a.next=v.next,v.next=a),f.pending=a}}i.lanes|=n,a=i.alternate,a!==null&&(a.lanes|=n),Ni(i.return,n,t),u.lanes|=n;break}a=a.next}}else if(i.tag===10)o=i.type===t.type?null:i.child;else if(i.tag===18){if(o=i.return,o===null)throw Error(g(341));o.lanes|=n,u=o.alternate,u!==null&&(u.lanes|=n),Ni(o,n,t),o=i.sibling}else o=i.child;if(o!==null)o.return=i;else for(o=i;o!==null;){if(o===t){o=null;break}if(i=o.sibling,i!==null){i.return=o.return,o=i;break}o=o.return}i=o}ie(e,t,l.children,n),t=t.child}return t;case 9:return l=t.type,r=t.pendingProps.children,qt(t,n),l=je(l),r=r(l),t.flags|=1,ie(e,t,r,n),t.child;case 14:return r=t.type,l=ze(r,t.pendingProps),l=ze(r.type,l),Ts(e,t,r,l,n);case 15:return Da(e,t,t.type,t.pendingProps,n);case 17:return r=t.type,l=t.pendingProps,l=t.elementType===r?l:ze(r,l),Lr(e,t),t.tag=1,fe(r)?(e=!0,Vr(t)):e=!1,qt(t,n),Ta(t,r,l),Ei(t,r,l,n),zi(null,t,r,!0,e,n);case 19:return Ua(e,t,n);case 22:return Oa(e,t,n)}throw Error(g(156,t.tag))};function tc(e,t){return Pu(e,t)}function Cf(e,t,n,r){this.tag=e,this.key=n,this.sibling=this.child=this.return=this.stateNode=this.type=this.elementType=null,this.index=0,this.ref=null,this.pendingProps=t,this.dependencies=this.memoizedState=this.updateQueue=this.memoizedProps=null,this.mode=r,this.subtreeFlags=this.flags=0,this.deletions=null,this.childLanes=this.lanes=0,this.alternate=null}function Se(e,t,n,r){return new Cf(e,t,n,r)}function To(e){return e=e.prototype,!(!e||!e.isReactComponent)}function Pf(e){if(typeof e=="function")return To(e)?1:0;if(e!=null){if(e=e.$$typeof,e===Yi)return 11;if(e===Zi)return 14}return 2}function pt(e,t){var n=e.alternate;return n===null?(n=Se(e.tag,t,e.key,e.mode),n.elementType=e.elementType,n.type=e.type,n.stateNode=e.stateNode,n.alternate=e,e.alternate=n):(n.pendingProps=t,n.type=e.type,n.flags=0,n.subtreeFlags=0,n.deletions=null),n.flags=e.flags&14680064,n.childLanes=e.childLanes,n.lanes=e.lanes,n.child=e.child,n.memoizedProps=e.memoizedProps,n.memoizedState=e.memoizedState,n.updateQueue=e.updateQueue,t=e.dependencies,n.dependencies=t===null?null:{lanes:t.lanes,firstContext:t.firstContext},n.sibling=e.sibling,n.index=e.index,n.ref=e.ref,n}function Mr(e,t,n,r,l,i){var o=2;if(r=e,typeof e=="function")To(e)&&(o=1);else if(typeof e=="string")o=5;else e:switch(e){case It:return Ct(n.children,l,i,t);case Xi:o=8,l|=8;break;case Zl:return e=Se(12,n,t,l|2),e.elementType=Zl,e.lanes=i,e;case Jl:return e=Se(13,n,t,l),e.elementType=Jl,e.lanes=i,e;case ql:return e=Se(19,n,t,l),e.elementType=ql,e.lanes=i,e;case du:return ml(n,l,i,t);default:if(typeof e=="object"&&e!==null)switch(e.$$typeof){case au:o=10;break e;case cu:o=9;break e;case Yi:o=11;break e;case Zi:o=14;break e;case et:o=16,r=null;break e}throw Error(g(130,e==null?e:typeof e,""))}return t=Se(o,n,t,l),t.elementType=e,t.type=r,t.lanes=i,t}function Ct(e,t,n,r){return e=Se(7,e,r,t),e.lanes=n,e}function ml(e,t,n,r){return e=Se(22,e,r,t),e.elementType=du,e.lanes=n,e.stateNode={isHidden:!1},e}function Kl(e,t,n){return e=Se(6,e,null,t),e.lanes=n,e}function Xl(e,t,n){return t=Se(4,e.children!==null?e.children:[],e.key,t),t.lanes=n,t.stateNode={containerInfo:e.containerInfo,pendingChildren:null,implementation:e.implementation},t}function zf(e,t,n,r,l){this.tag=t,this.containerInfo=e,this.finishedWork=this.pingCache=this.current=this.pendingChildren=null,this.timeoutHandle=-1,this.callbackNode=this.pendingContext=this.context=null,this.callbackPriority=0,this.eventTimes=Pl(0),this.expirationTimes=Pl(-1),this.entangledLanes=this.finishedLanes=this.mutableReadLanes=this.expiredLanes=this.pingedLanes=this.suspendedLanes=this.pendingLanes=0,this.entanglements=Pl(0),this.identifierPrefix=r,this.onRecoverableError=l,this.mutableSourceEagerHydrationData=null}function Ro(e,t,n,r,l,i,o,u,a){return e=new zf(e,t,n,u,a),t===1?(t=1,i===!0&&(t|=8)):t=0,i=Se(3,null,null,t),e.current=i,i.stateNode=e,i.memoizedState={element:r,isDehydrated:n,cache:null,transitions:null,pendingSuspenseBoundaries:null},mo(i),e}function Lf(e,t,n){var r=3"u"||typeof __REACT_DEVTOOLS_GLOBAL_HOOK__.checkDCE!="function"))try{__REACT_DEVTOOLS_GLOBAL_HOOK__.checkDCE(ic)}catch(e){console.error(e)}}ic(),iu.exports=ge;var Of=iu.exports,oc,Qs=Of;oc=Qs.createRoot,Qs.hydrateRoot;const Ff=[{name:"no drift",len:70},{name:"single drift",len:100},{name:"compound",len:70}],If=[.2,.2,.2,.2375,.2,.2,.2,.2375,.2,.2,.2375,.2,.2375,.2375,.2,.2375,.2,.2,.275,.2375,.2375,.2125,.2,.2375,.2375,.2,.2375,.2,.2375,.2375,.2375,.2375,.2375,.2,.2,.275,.2375,.2375,.2,.2,.2,.2375,.2,.175,.2375,.2,.2,.2375,.2,.275,.2,.2375,.2,.2,.2375,.2,.2,.2375,.275,.2,.2,.2,.2,.2375,.2,.2375,.2125,.203,.2,.2,.2375,.225,.2,.225,.2,.275,.225,.2375,.225,.275,.225,.2375,.2,.2625,.2375,.225,.2375,.2,.2625,.225,.2,.2625,.2,.225,.2,.25,.225,.25,.225,.225,.2,.2,.25,.225,.25,.2375,.2625,.2,.2375,.2625,.2,.275,.2625,.2,.2,.225,.2625,.2375,.225,.25,.2,.25,.2375,.225,.25,.225,.2,.2875,.25,.225,.2,.2375,.275,.2,.2625,.225,.2,.203,.225,.2375,.2875,.2,.25,.275,.2,.2375,.2375,.2,.2375,.25,.25,.275,.25,.275,.25,.275,.2,.225,.2375,.275,.225,.2,.25,.2,.25,.2625,.25,.2375,.3,.25,.2375,.25,.225,.225,.2375,.25,.2,.225,.275,.2,.2625,.2875,.275,.25,.225,.2625,.25,.2,.2,.225,.2875,.2375,.275,.225,.225,.2,.275,.25,.25,.275,.225,.2375,.2875,.2875,.2375,.2625,.2625,.2,.225,.2,.2625,.225,.2315,.2625,.2625,.2,.2875,.275,.225,.2375,.2,.2375,.2375,.225,.2875,.2,.2375,.2375,.2,.2375,.275,.2375,.225,.2875,.25,.2,.2,.2625,.2375,.2875],Af=[0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0],Uf=[.5,.5,.5,.5,.5,.5,.5,.5,.5,.5,.5,.5,.5,.5,.5,.5,.5,.5,.5,.5,.5,.5,.5,.5,.5,.5,.5,.5,.5,.5,.5,.5,.5,.5,.5,.5,.5,.5,.5,.5,.5,.5,.5,.5,.5,.5,.5,.5,.5,.5,.5,.5,.5,.5,.5,.5,.5,.5,.5,.5,.5,.5,.5,.5,.5,.5,.5,.5,.5,.5,.5,.5,.5,.5,.5,.5,.5,.5,.5,.5,.5,.5,.5,.5,.5,.5,.5,.5,.5,.5,.5,.5,.5,.5,.5,.5,.5,.5,.5,.5,.5,.5,.5,.5,.5,.5,.5,.5,.5,.5,.5,.5,.5,.5,.5,.5,.5,.5,.5,.5,.5,.5,.5,.5,.5,.5,.5,.5,.5,.5,.5,.5,.5,.5,.5,.5,.5,.5,.5,.5,.5,.5,.5,.5,.5,.5,.5,.5,.5,.5,.5,.5,.5,.5,.5,.5,.5,.5,.5,.5,.5,.5,.5,.5,.5,.5,.5,.5,.5,.5,.5,.5,.5,.5,.5,.5,.5,.5,.5,.5,.5,.5,.5,.5,.5,.5,.5,.5,.5,.5,.5,.5,.5,.5,.5,.5,.5,.5,.5,.5,.5,.5,.5,.5,.5,.5,.5,.5,.5,.5,.5,.5,.5,.5,.5,.5,.5,.5,.5,.5,.5,.5,.5,.5,.5,.5,.5,.5,.5,.5,.5,.5,.5,.5,.5,.5,.5,.5,.5,.5],$f=[0,0,0,.25,0,0,0,.25,0,0,.25,0,.25,.25,0,.25,0,0,.5,.25,.25,.25,0,.25,.25,0,.25,0,.25,.25,.25,.25,.25,0,0,.5,.25,.25,0,0,0,.25,0,0,.25,0,0,.25,0,.5,0,.25,0,0,.25,0,0,.25,.5,0,0,0,0,.25,0,.25,.25,.25,0,0,.25,.1667,0,.1667,0,.5,.1667,.25,.1667,.5,.1667,.25,0,.4167,.25,.1667,.25,0,.4167,.1667,0,.4167,0,.1667,0,.3333,.1667,.3333,.1667,.1667,0,0,.3333,.1667,.3333,.25,.4167,0,.25,.4167,0,.5,.4167,0,0,.1667,.4167,.25,.1667,.3333,0,.3333,.25,.1667,.3333,.1667,0,.5833,.3333,.1667,0,.25,.5,0,.4167,.1667,0,.25,.1667,.25,.5833,0,.3333,.5,0,.25,.25,0,.25,.3333,.3333,.5,.3333,.5,.3333,.5,0,.1667,.25,.5,.1667,0,.3333,0,.3333,.4167,.3333,.25,.6667,.3333,.25,.3333,.1667,.1667,.25,.3333,0,.1667,.5,0,.4167,.5833,.5,.3333,.1667,.4167,.3333,0,0,.1667,.5833,.25,.5,.1667,.1667,0,.5,.3333,.3333,.5,.1667,.25,.5833,.5833,.25,.4167,.4167,0,.1667,0,.4167,.1667,.4167,.4167,.4167,0,.5833,.5,.1667,.25,0,.25,.25,.1667,.5833,0,.25,.25,0,.25,.5,.25,.1667,.5833,.3333,.1667,0,.4167,.25,.5833],Bf=[1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1],Hf=[0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0],Wf={stages:Ff,reward_mean:If,r1:Af,r2:Uf,r3:$f,r4:Bf,r5:Hf},ke={devanagari:"ड्रिफ़्ट",loraRepo:"DGXAI/gemma-3n-e2b-driftcall-lora",envSpace:"DGXAI/driftcall-env",demoSpace:"DGXAI/driftcall-demo",github:"https://github.com/saumilyagupta/openenv-DGXAI",hackathon:"DGX Hackathon 2026 — Indic Voice + RL track"},Vf=[{id:"R1",name:"task_completion",weight:.4,blurb:"did the agent actually book the cab, complete the payment, hold the reservation. final state checked against the brief.",impl:"cells.step_08_rewards:task_completion"},{id:"R2",name:"drift_detection",weight:.2,blurb:"mid-episode the schema mutates. did the agent notice, retry, and adapt — or keep firing the dead old payload.",impl:"cells.step_08_rewards:drift_detection"},{id:"R3",name:"constraint_adherence",weight:.2,blurb:"user said budget ₹800. user said veg. user said before 9 pm. we check.",impl:"cells.step_08_rewards:constraint_adherence"},{id:"R4",name:"format_compliance",weight:.1,blurb:"tool args parse cleanly against the (possibly drifted) JSON schema. no half-formed objects, no hallucinated fields.",impl:"cells.step_08_rewards:format_compliance"},{id:"R5",name:"anti_hack_penalty",weight:.1,blurb:"200-episode probe set of known reward-hacking patterns. agents that exploit get docked. no LLM judge — pure deterministic checks.",impl:"cells.step_08_rewards:anti_hack_penalty"}],Qf=[{code:"hi",name:"Hindi",script:"हिन्दी"},{code:"ta",name:"Tamil",script:"தமிழ்"},{code:"kn",name:"Kannada",script:"ಕನ್ನಡ"},{code:"en",name:"English",script:"English"},{code:"hi-en",name:"Hinglish",script:"हिंEnglish"}],Gf=[{name:"cab",glyph:"▮▮",role:"ride-hail booking"},{name:"hotel",glyph:"▤▤",role:"stay reservation"},{name:"airline",glyph:"▷▷",role:"flight booking"},{name:"restaurant",glyph:"▣▣",role:"table + order"},{name:"payment",glyph:"◐◑",role:"transaction settlement"}],Gs=["field_renamed","field_removed","type_changed","enum_added","enum_pruned","required_added","required_dropped","auth_rotated","rate_limit_lowered","endpoint_versioned","currency_switched","tax_added","service_fee_added","cancel_window_shrunk","policy_text_changed","tnc_addendum","geo_restriction","hours_changed","inventory_relocated","compound_drift"],be={baseline:{mean_reward:.2,drift_detection_rate:.05,constraint_adherence:.32,avg_turns_to_complete:14.6},trained:{mean_reward:.71,drift_detection_rate:.78,constraint_adherence:.81,avg_turns_to_complete:8.4}},Be=Wf;function Kf(){return s.jsx("section",{className:"section arch",id:"architecture",children:s.jsxs("div",{className:"shell arch__shell",children:[s.jsxs("header",{className:"arch__header",children:[s.jsx("span",{className:"eyebrow",children:"§05 — architecture"}),s.jsxs("h2",{className:"arch__title",children:[s.jsx("em",{children:"Three"})," deployable artefacts.",s.jsx("br",{}),"One canonical source."]}),s.jsxs("p",{className:"arch__sub",children:["The repo at the root is the source of truth. Each deploy target — env Space, demo Space, inference client — is regenerated from it on every push via ",s.jsx("code",{className:"mono",children:"deploy/build_all.sh"}),". The trained LoRA stays on HF Hub; the Spaces stay small."]})]}),s.jsx("div",{className:"arch__diagram","aria-label":"DriftCall deployment topology",children:s.jsxs("svg",{viewBox:"0 0 1200 640",preserveAspectRatio:"xMidYMid meet",children:[s.jsxs("defs",{children:[s.jsx("marker",{id:"arrow",viewBox:"0 0 10 10",refX:"9",refY:"5",markerWidth:"7",markerHeight:"7",orient:"auto",children:s.jsx("path",{d:"M0,0 L10,5 L0,10 z",fill:"var(--saffron)"})}),s.jsx("pattern",{id:"dots",x:"0",y:"0",width:"14",height:"14",patternUnits:"userSpaceOnUse",children:s.jsx("circle",{cx:"1",cy:"1",r:"0.6",fill:"var(--ink-edge)"})})]}),s.jsx("rect",{x:"0",y:"0",width:"1200",height:"640",fill:"url(#dots)",opacity:"0.5"}),s.jsxs("g",{className:"arch__node arch__node--accent",children:[s.jsx("rect",{x:"430",y:"50",width:"340",height:"86"}),s.jsx("text",{x:"450",y:"80",className:"arch__node-kicker",children:"01 · MODEL ARTEFACT"}),s.jsx("text",{x:"450",y:"110",className:"arch__node-title",children:"DGXAI/gemma-3n-e2b-driftcall-lora"}),s.jsx("text",{x:"450",y:"128",className:"arch__node-sub",children:"pushed by cells.step_24_deploy_hf · adapter only · 84.6 MB"})]}),s.jsxs("g",{className:"arch__node",children:[s.jsx("rect",{x:"80",y:"240",width:"380",height:"160"}),s.jsx("text",{x:"100",y:"270",className:"arch__node-kicker",children:"02 · OPENENV SPACE"}),s.jsx("text",{x:"100",y:"306",className:"arch__node-title",children:"DGXAI/driftcall-env"}),s.jsx("text",{x:"100",y:"330",className:"arch__node-line",children:"/reset · /step · /state · /close · /healthz"}),s.jsx("text",{x:"100",y:"352",className:"arch__node-line",children:"cells/step_10_env · DriftCallEnv"}),s.jsx("text",{x:"100",y:"374",className:"arch__node-line",children:"cells/step_08_rewards · 5 components"}),s.jsx("text",{x:"100",y:"386",className:"arch__node-foot",children:"docker · cpu basic · < 2 GB"})]}),s.jsxs("g",{className:"arch__node",children:[s.jsx("rect",{x:"740",y:"240",width:"380",height:"160"}),s.jsx("text",{x:"760",y:"270",className:"arch__node-kicker",children:"03 · DEMO SPACE"}),s.jsx("text",{x:"760",y:"306",className:"arch__node-title",children:"DGXAI/driftcall-demo"}),s.jsx("text",{x:"760",y:"330",className:"arch__node-line",children:"gradio · mic → asr → env → lora → tts → speaker"}),s.jsx("text",{x:"760",y:"352",className:"arch__node-line",children:"kokoro tts · faster-whisper asr"}),s.jsx("text",{x:"760",y:"374",className:"arch__node-line",children:"base ↔ trained toggle"}),s.jsx("text",{x:"760",y:"386",className:"arch__node-foot",children:"gradio sdk · zerogpu / a10g"})]}),s.jsxs("g",{className:"arch__node arch__node--ghost",children:[s.jsx("rect",{x:"430",y:"500",width:"340",height:"100"}),s.jsx("text",{x:"450",y:"530",className:"arch__node-kicker",children:"04 · OPENENV GYM CLIENT"}),s.jsx("text",{x:"450",y:"558",className:"arch__node-title",children:"deploy/inference/run.py"}),s.jsx("text",{x:"450",y:"582",className:"arch__node-line",children:"DriftCallGymClient + GemmaPolicy"})]}),s.jsx("path",{className:"arch__edge",d:"M520 136 C 520 200, 270 220, 270 240",fill:"none",markerEnd:"url(#arrow)"}),s.jsx("path",{className:"arch__edge",d:"M680 136 C 680 200, 930 220, 930 240",fill:"none",markerEnd:"url(#arrow)"}),s.jsx("path",{className:"arch__edge",d:"M270 400 C 270 460, 520 470, 600 500",fill:"none",markerEnd:"url(#arrow)"}),s.jsx("path",{className:"arch__edge arch__edge--soft",d:"M740 320 C 600 320, 460 320, 460 320",fill:"none",strokeDasharray:"4 6"}),s.jsx("text",{x:"600",y:"318",className:"arch__edge-label",children:"shared cells/ + data/"}),s.jsx("text",{x:"375",y:"180",className:"arch__edge-label",children:"lora pulled at runtime"}),s.jsx("text",{x:"828",y:"180",className:"arch__edge-label",children:"lora pulled at runtime"})]})}),s.jsxs("div",{className:"arch__vendors",children:[s.jsx("span",{className:"kicker",children:"vendor surface · 5 mock APIs"}),s.jsx("ul",{children:Gf.map(e=>s.jsxs("li",{children:[s.jsx("span",{className:"mono arch__vendor-glyph",children:e.glyph}),s.jsx("span",{className:"arch__vendor-name",children:e.name}),s.jsx("span",{className:"arch__vendor-role",children:e.role})]},e.name))})]})]})})}function Xf(){const e=`https://huggingface.co/spaces/${ke.demoSpace}`,t=`https://${ke.demoSpace.replace("/","-").toLowerCase()}.hf.space`;return s.jsx("section",{className:"section demo",id:"demo",children:s.jsxs("div",{className:"shell demo__shell",children:[s.jsxs("header",{className:"demo__header",children:[s.jsxs("div",{children:[s.jsx("span",{className:"eyebrow",children:"§03 — live demo"}),s.jsxs("h2",{className:"demo__title",children:["Speak to it.",s.jsx("br",{}),s.jsx("em",{children:"Watch it adapt."})]})]}),s.jsxs("p",{className:"demo__sub",children:["Press ",s.jsx("span",{className:"mono demo__kbd",children:"⏺"}),", ask in any of the five languages, and the agent will walk through the full tool-calling chain. Use the ",s.jsx("em",{children:"drift dropdown"})," mid-episode to inject one of twenty schema mutations and watch the trace recover. Toggle ",s.jsx("em",{children:"base"})," vs ",s.jsx("em",{children:"trained"})," to A/B the LoRA."]})]}),s.jsxs("div",{className:"demo__layout",children:[s.jsxs("aside",{className:"demo__prompts","aria-label":"example prompts",children:[s.jsx("span",{className:"kicker",children:"try one"}),s.jsxs("ul",{children:[s.jsxs("li",{children:[s.jsx("span",{className:"devanagari",children:"9 बजे से पहले एक वेज थाली ₹500 के अंदर मिलनी चाहिए"}),s.jsx("span",{className:"mono demo__prompt-tag",children:"restaurant · drift: tax_added"})]}),s.jsxs("li",{children:[s.jsx("span",{className:"devanagari",children:"कल सुबह 8 बजे की दिल्ली से बेंगलुरु फ्लाइट"}),s.jsx("span",{className:"mono demo__prompt-tag",children:"airline · drift: field_renamed"})]}),s.jsxs("li",{children:["Book me a non-AC cab from Indiranagar to MG Road for ₹250.",s.jsx("span",{className:"mono demo__prompt-tag",children:"cab · drift: enum_pruned"})]}),s.jsxs("li",{children:[s.jsx("span",{className:"devanagari",children:"होटल चाहिए, ₹3000 के अंदर, कल चेक-इन"}),s.jsx("span",{className:"mono demo__prompt-tag",children:"hotel · drift: cancel_window_shrunk"})]})]}),s.jsx("a",{className:"demo__hf-link mono",href:e,target:"_blank",rel:"noopener noreferrer",children:"open in huggingface ↗"})]}),s.jsxs("div",{className:"demo__frame",role:"region","aria-label":"DriftCall live demo",children:[s.jsxs("div",{className:"demo__bezel",children:[s.jsx("span",{className:"demo__bezel-dot","aria-hidden":!0}),s.jsx("span",{className:"mono demo__bezel-id",children:ke.demoSpace}),s.jsxs("span",{className:"mono demo__bezel-rec",children:[s.jsx("span",{className:"demo__bezel-rec-dot"})," rec"]})]}),s.jsx("iframe",{className:"demo__iframe",src:t,title:"DriftCall Gradio demo",loading:"lazy",allow:"microphone; clipboard-read; clipboard-write"}),s.jsx("div",{className:"demo__scanlines","aria-hidden":!0})]})]})]})})}function Yf(){return s.jsx("footer",{className:"footer",children:s.jsxs("div",{className:"shell footer__shell",children:[s.jsxs("div",{className:"footer__top",children:[s.jsxs("span",{className:"footer__brand",children:["DriftCall ",s.jsx("em",{className:"footer__deva",children:"ड्रिफ़्ट"})]}),s.jsx("span",{className:"mono footer__hack",children:ke.hackathon})]}),s.jsxs("div",{className:"footer__grid",children:[s.jsxs("p",{className:"footer__about",children:["DriftCall is built on Gemma 3n E2B (Unsloth quantised) plus a custom native PyTorch GRPO loop. Five reward components, twenty drift patterns, five Indic languages, no LLM judges. The repo, the adapter, the env, and the demo are all public — the entire pipeline is reproducible from a single ",s.jsx("code",{className:"mono",children:"build_all.sh"}),"."]}),s.jsxs("ul",{className:"footer__credits",children:[s.jsxs("li",{children:[s.jsx("span",{className:"footer__credit-key mono",children:"env spec"}),s.jsx("span",{className:"footer__credit-val",children:"DESIGN.md (54 KB) · 14 module docs"})]}),s.jsxs("li",{children:[s.jsx("span",{className:"footer__credit-key mono",children:"trainer"}),s.jsx("span",{className:"footer__credit-val",children:"scripts/train_driftcall_grpo.py"})]}),s.jsxs("li",{children:[s.jsx("span",{className:"footer__credit-key mono",children:"eval"}),s.jsx("span",{className:"footer__credit-val",children:"cells/step_18..20 · 50-ep + 200-probe"})]}),s.jsxs("li",{children:[s.jsx("span",{className:"footer__credit-key mono",children:"demo"}),s.jsx("span",{className:"footer__credit-val",children:"demo/app_gradio.py · 28 KB"})]})]})]}),s.jsx("div",{className:"footer__rule"}),s.jsxs("div",{className:"footer__bottom",children:[s.jsx("span",{className:"mono",children:"© 2026 · DriftCall · apache-2.0"}),s.jsx("span",{className:"mono",children:"type: instrument serif × geist · drift: 0.000"})]})]})})}const Zf="modulepreload",Jf=function(e){return"/"+e},Ks={},qf=function(t,n,r){let l=Promise.resolve();if(n&&n.length>0){document.getElementsByTagName("link");const o=document.querySelector("meta[property=csp-nonce]"),u=o?.nonce||o?.getAttribute("nonce");l=Promise.allSettled(n.map(a=>{if(a=Jf(a),a in Ks)return;Ks[a]=!0;const f=a.endsWith(".css"),v=f?'[rel="stylesheet"]':"";if(document.querySelector(`link[href="${a}"]${v}`))return;const m=document.createElement("link");if(m.rel=f?"stylesheet":Zf,f||(m.as="script"),m.crossOrigin="",m.href=a,u&&m.setAttribute("nonce",u),document.head.appendChild(m),f)return new Promise((h,_)=>{m.addEventListener("load",h),m.addEventListener("error",()=>_(new Error(`Unable to preload CSS for ${a}`)))})}))}function i(o){const u=new Event("vite:preloadError",{cancelable:!0});if(u.payload=o,window.dispatchEvent(u),!u.defaultPrevented)throw o}return l.then(o=>{for(const u of o||[])u.status==="rejected"&&i(u.reason);return t().catch(i)})};let wn;async function bf(){if(wn!==void 0)return wn;try{wn=await qf(()=>import("./layout-C5Ii8faq.js"),[])}catch{wn=null}return wn}function e0(e){const t=window.getComputedStyle(e),n=t.fontStyle||"normal",r=t.fontWeight||"400",l=t.fontSize||"16px",i=t.fontFamily||"serif";return`${n} ${r} ${l} ${i}`}function t0({children:e,className:t,style:n,font:r,stagger:l,delay:i=0,showTelemetry:o=!0}){const u=Ae.useRef(null),[a,f]=Ae.useState(null);Ae.useEffect(()=>{const h=u.current;if(!h||typeof e!="string")return;let _=!1;return(async()=>{const x=await bf();if(_||!x||!h.isConnected)return;const M=r??e0(h),d=h.getBoundingClientRect().width||800,c=parseFloat(window.getComputedStyle(h).lineHeight)||64;try{const p=x.prepare(h.textContent??"",M),y=x.layout(p,d,c),k=x.prepareWithSegments(h.textContent??"",M),j=x.measureNaturalWidth(k);if(_)return;f({width:j,height:y.height,lineCount:y.lineCount,font:M})}catch{}})(),()=>{_=!0}},[e,r]);const v=typeof e=="string"?e:Ae.Children.toArray(e).join(""),m={display:"inline-block",whiteSpace:"pre",...n};return s.jsxs("span",{ref:u,className:t,style:m,"aria-label":v,children:[l?Array.from(v).map((h,_)=>s.jsx("span",{"aria-hidden":!0,style:{display:"inline-block",animation:"rise 800ms cubic-bezier(0.16, 1, 0.3, 1) both",animationDelay:`${i+_*32}ms`,whiteSpace:"pre"},children:h},`${h}-${_}`)):e,o&&a?s.jsxs("span",{className:"pretext__telemetry","aria-hidden":!0,children:[s.jsxs("span",{children:["w ",Math.round(a.width),"px"]}),s.jsxs("span",{children:["h ",Math.round(a.height),"px"]}),s.jsxs("span",{children:[a.lineCount," ln"]}),s.jsx("span",{children:"· @chenglou/pretext"})]}):null]})}function n0(){const e=Ae.useRef(null);return Ae.useEffect(()=>{const t=e.current;if(!t)return;let n=0,r=0;const l=1600,i=100,o=240,u=()=>{n+=.012;const a=[];for(let f=0;f<=o;f++){const v=f/o*l,m=i/2+Math.sin(f*.04+n)*14+Math.sin(f*.013-n*1.4)*22+Math.sin(f*.27+n*.7)*4;a.push(`${f===0?"M":"L"}${v.toFixed(1)} ${m.toFixed(1)}`)}t.setAttribute("d",a.join(" ")),r=requestAnimationFrame(u)};return u(),()=>cancelAnimationFrame(r)},[]),s.jsxs("header",{className:"hero",children:[s.jsx("span",{className:"hero__devanagari","aria-hidden":!0,children:ke.devanagari}),s.jsxs("div",{className:"shell hero__shell",children:[s.jsxs("div",{className:"hero__top",children:[s.jsx("span",{className:"kicker",children:"DGX × OpenEnv · Hackathon 2026"}),s.jsx("span",{className:"mono hero__coord",children:"28.6° N, 77.2° E"})]}),s.jsxs("h1",{className:"hero__title",children:[s.jsx(t0,{stagger:!0,className:"hero__brand",children:"DriftCall"}),s.jsx("span",{className:"hero__slash",children:"/"}),s.jsxs("em",{className:"hero__sub",children:["voice concierge under",s.jsx("br",{}),s.jsx("span",{className:"hero__sub-em",children:"schema drift."})]})]}),s.jsxs("div",{className:"hero__meta",children:[s.jsxs("p",{className:"hero__lede",children:["An OpenEnv-compliant RL environment where a voice-first agent must book the cab, hold the room, settle the payment — in Hindi, Tamil, Kannada, Hinglish — while the vendor APIs ",s.jsx("em",{children:"mutate mid-episode"}),". Five reward components. No LLM judges. Deterministic."]}),s.jsxs("ul",{className:"hero__chips","aria-label":"quick facts",children:[s.jsxs("li",{children:[s.jsx("span",{className:"mono hero__chip-key",children:"model"}),s.jsx("span",{className:"mono hero__chip-val",children:"gemma-3n-E2B + LoRA"})]}),s.jsxs("li",{children:[s.jsx("span",{className:"mono hero__chip-key",children:"trainer"}),s.jsx("span",{className:"mono hero__chip-val",children:"native GRPO · g=2"})]}),s.jsxs("li",{children:[s.jsx("span",{className:"mono hero__chip-key",children:"curriculum"}),s.jsx("span",{className:"mono hero__chip-val",children:"3 stages · drift→compound"})]}),s.jsxs("li",{children:[s.jsx("span",{className:"mono hero__chip-key",children:"eval"}),s.jsx("span",{className:"mono hero__chip-val",children:"held-out · 200-ep probe"})]})]}),s.jsxs("div",{className:"hero__cta",children:[s.jsxs("a",{className:"hero__btn hero__btn--primary",href:"#demo",children:[s.jsx("span",{children:"live demo"}),s.jsx("span",{"aria-hidden":!0,children:"→"})]}),s.jsxs("a",{className:"hero__btn hero__btn--ghost",href:`https://huggingface.co/spaces/${ke.envSpace}`,target:"_blank",rel:"noopener noreferrer",children:[s.jsx("span",{children:"openenv gym"}),s.jsx("span",{"aria-hidden":!0,children:"↗"})]}),s.jsxs("a",{className:"hero__btn hero__btn--ghost",href:ke.github,target:"_blank",rel:"noopener noreferrer",children:[s.jsx("span",{children:"source"}),s.jsx("span",{"aria-hidden":!0,children:"↗"})]})]})]})]}),s.jsx("svg",{className:"hero__wave",viewBox:"0 0 1600 100",preserveAspectRatio:"none","aria-hidden":!0,children:s.jsx("path",{ref:e,d:""})})]})}function r0(){return s.jsx("section",{className:"section premise",id:"premise",children:s.jsxs("div",{className:"shell premise__shell",children:[s.jsxs("header",{className:"premise__header",children:[s.jsx("span",{className:"eyebrow",children:"§01 — premise"}),s.jsxs("h2",{className:"premise__title",children:["Production APIs",s.jsx("br",{}),"don't hold still."]})]}),s.jsxs("div",{className:"premise__columns",children:[s.jsxs("p",{className:"premise__lede",children:[s.jsx("span",{className:"premise__drop",children:"A"}),"n agent that books a flight on Tuesday confidently fires the same JSON payload on Thursday and gets",s.jsx("em",{children:" 422 "}),"back. The endpoint moved. ",s.jsx("em",{children:"price"})," is now",s.jsx("em",{children:" total"}),". ",s.jsx("em",{children:"seat_class"})," is split into ",s.jsx("em",{children:"cabin "}),"and ",s.jsx("em",{children:"fare_brand"}),". The cancel window shrank from 24h to 6h. Auth tokens rotate every 90 minutes now."]}),s.jsxs("p",{className:"premise__body",children:["Every benchmark in the open assumes static schemas, English-only briefs, and a friendly oracle in the loop. Real concierge work is the opposite. Tasks arrive in Hindi mixed with Tamil mixed with English numerals. Vendors deprecate fields without changelog. The agent has to ",s.jsx("strong",{children:"notice the drift"}),", retry against the new shape, and keep its promise to the user — “under ₹800, before 9 pm, vegetarian, no haldi” — through the whole thing."]}),s.jsx("p",{className:"premise__body",children:"DriftCall is an environment built around that gap. It speaks five ways. It mutates schemas mid-episode. It scores reward deterministically — no LLM judges anywhere in the pipeline — across five independent components. And it ships as an OpenEnv-compliant Space, so any agent that talks the protocol can train against it."})]}),s.jsx("ul",{className:"premise__langs","aria-label":"languages exercised",children:Qf.map((e,t)=>s.jsxs("li",{children:[s.jsx("span",{className:"mono premise__lang-num",children:String(t+1).padStart(2,"0")}),s.jsx("span",{className:"premise__lang-script",children:e.script}),s.jsx("span",{className:"mono premise__lang-name",children:e.name})]},e.code))})]})})}function l0({data:e,stages:t,yMin:n=0,yMax:r=1}){const l=Ae.useId(),i=800,o=260,u=28,a=r-n,f=e.map((d,c)=>u+c/Math.max(e.length-1,1)*(i-u*2)),v=e.map(d=>{const c=(d-n)/a;return o-u-Math.max(0,Math.min(1,c))*(o-u*2)}),m=f.map((d,c)=>`${c===0?"M":"L"}${d.toFixed(1)} ${v[c].toFixed(1)}`).join(" "),h=`${m} L${(i-u).toFixed(1)} ${(o-u).toFixed(1)} L${u.toFixed(1)} ${(o-u).toFixed(1)} Z`,_=e.length;let w=0;const x=t.map(d=>(w+=d.len,{name:d.name,edge:w})),M=[0,.25,.5,.75,1].filter(d=>d>=n&&d<=r);return s.jsxs("svg",{viewBox:`0 0 ${i} ${o}`,className:"results__curve",preserveAspectRatio:"none",children:[s.jsx("defs",{children:s.jsxs("linearGradient",{id:`grad-${l}`,x1:"0",x2:"0",y1:"0",y2:"1",children:[s.jsx("stop",{offset:"0%",stopColor:"var(--saffron)",stopOpacity:"0.4"}),s.jsx("stop",{offset:"100%",stopColor:"var(--saffron)",stopOpacity:"0"})]})}),M.map(d=>{const c=o-u-(d-n)/a*(o-u*2);return s.jsxs("g",{children:[s.jsx("line",{x1:u,x2:i-u,y1:c,y2:c,stroke:"var(--ink-edge)",strokeWidth:"1"}),s.jsx("text",{x:u-6,y:c+3,fill:"var(--ash-deep)",fontFamily:"var(--font-mono)",fontSize:"9",textAnchor:"end",children:d.toFixed(2)})]},d)}),x.slice(0,-1).map(d=>{const c=u+d.edge/_*(i-u*2);return s.jsx("g",{children:s.jsx("line",{x1:c,x2:c,y1:u,y2:o-u,stroke:"var(--saffron)",strokeOpacity:"0.35",strokeDasharray:"2 4"})},d.name)}),t.map((d,c)=>{const p=c===0?0:x[c-1].edge,y=u+(p+d.len/2)/_*(i-u*2);return s.jsx("text",{x:y,y:u-8,fill:"var(--ash)",fontFamily:"var(--font-mono)",fontSize:"9",letterSpacing:"0.18em",textAnchor:"middle",children:`STAGE ${c+1} · ${d.name.toUpperCase()}`},d.name+c)}),s.jsx("path",{d:h,fill:`url(#grad-${l})`}),s.jsx("path",{d:m,fill:"none",stroke:"var(--saffron)",strokeWidth:"1.6"})]})}function i0({series:e,yMax:t}){return Math.max(...e.map(i=>i.data.length)),s.jsxs("svg",{viewBox:"0 0 800 200",className:"results__curve",preserveAspectRatio:"none",children:[[.25,.5,.75,1].map(i=>{const o=172-i/1*144;return s.jsx("line",{x1:28,x2:772,y1:o,y2:o,stroke:"var(--ink-edge)",strokeWidth:"1"},i)}),e.map(i=>{const o=i.data.map((u,a)=>{const f=28+a/Math.max(i.data.length-1,1)*744,v=172-Math.min(u/t,1)*(200-28*2);return`${a===0?"M":"L"}${f.toFixed(1)} ${v.toFixed(1)}`}).join(" ");return s.jsx("path",{d:o,fill:"none",stroke:i.color,strokeWidth:"1.4",opacity:"0.9"},i.label)}),s.jsx("text",{x:28,y:18,fill:"var(--ash)",fontFamily:"var(--font-mono)",fontSize:"9",letterSpacing:"0.15em",children:`240 STEPS · ${e.length} SERIES · max(y)=${t.toFixed(2)}`}),e.map((i,o)=>s.jsxs("g",{transform:`translate(682, ${32+o*14})`,children:[s.jsx("line",{x1:"0",x2:"14",y1:"0",y2:"0",stroke:i.color,strokeWidth:"1.6"}),s.jsx("text",{x:"20",y:"3",fill:"var(--paper-soft)",fontFamily:"var(--font-mono)",fontSize:"10",letterSpacing:"-0.01em",children:i.label})]},i.label)),void 0]})}function o0(e,t){const n=(t-e)/Math.max(e,1e-6)*100;return`${n>=0?"+":""}${n.toFixed(0)}%`}function s0(){const e=[{label:"mean reward",base:be.baseline.mean_reward,trained:be.trained.mean_reward,better:"higher"},{label:"drift detection rate",base:be.baseline.drift_detection_rate,trained:be.trained.drift_detection_rate,better:"higher"},{label:"constraint adherence",base:be.baseline.constraint_adherence,trained:be.trained.constraint_adherence,better:"higher"},{label:"avg turns to complete",base:be.baseline.avg_turns_to_complete,trained:be.trained.avg_turns_to_complete,better:"lower"}];return s.jsx("section",{className:"section results",id:"results",children:s.jsxs("div",{className:"shell results__shell",children:[s.jsxs("header",{className:"results__header",children:[s.jsx("span",{className:"eyebrow",children:"§04 — results"}),s.jsxs("h2",{className:"results__title",children:["Before / after,",s.jsx("br",{}),s.jsx("em",{children:"same 50 seeds."})]}),s.jsxs("p",{className:"results__sub",children:["Held-out evaluation set. Same prompts, same seeds, same drift schedule. Only the LoRA changes. Numbers are placeholder shapes until the live training run finishes —"," ",s.jsx("a",{className:"inline",href:"#resources",children:"wandb dashboard"})," ","has the live curves."]})]}),s.jsxs("div",{className:"results__grid",children:[s.jsxs("div",{className:"results__chart",children:[s.jsxs("header",{className:"results__chart-head",children:[s.jsx("span",{className:"kicker",children:"reward_mean · 240 steps · live data"}),s.jsx("span",{className:"mono results__chart-y",children:"y ∈ [0, 0.4]"})]}),s.jsx(l0,{data:Be.reward_mean,stages:Be.stages,yMin:0,yMax:.4}),s.jsxs("footer",{className:"results__chart-foot mono",children:[s.jsx("span",{children:"step 0"}),s.jsx("span",{children:Be.reward_mean.length>0?`step ${Be.reward_mean.length-1}`:"step –"})]})]}),s.jsxs("div",{className:"results__chart",children:[s.jsxs("header",{className:"results__chart-head",children:[s.jsx("span",{className:"kicker",children:"5 reward components · per step"}),s.jsx("span",{className:"mono results__chart-y",children:"R₁..R₅"})]}),s.jsx(i0,{yMax:.4,series:[{label:"R1 task",color:"var(--saffron)",data:Be.r1},{label:"R2 drift",color:"var(--rasa-teal)",data:Be.r2},{label:"R3 cnstr",color:"var(--saffron-soft)",data:Be.r3},{label:"R4 fmt",color:"var(--paper-soft)",data:Be.r4},{label:"R5 hack",color:"var(--ash)",data:Be.r5}]})]}),s.jsxs("table",{className:"results__table",children:[s.jsx("thead",{children:s.jsxs("tr",{children:[s.jsx("th",{scope:"col",children:"metric"}),s.jsx("th",{scope:"col",className:"results__th-base",children:"base"}),s.jsx("th",{scope:"col",className:"results__th-trained",children:"trained"}),s.jsx("th",{scope:"col",children:"Δ"})]})}),s.jsx("tbody",{children:e.map(t=>{const n=t.better==="higher"&&t.trained>t.base||t.better==="lower"&&t.traineds.jsx("li",{children:s.jsxs("a",{className:`resources__tile${e.accent?" resources__tile--accent":""}`,href:e.href,target:"_blank",rel:"noopener noreferrer",children:[s.jsxs("span",{className:"resources__suffix mono",children:[e.suffix," ↗"]}),s.jsx("span",{className:"resources__label",children:e.label}),s.jsx("span",{className:"resources__title-text",children:e.title}),s.jsx("span",{className:"resources__desc",children:e.desc})]})},e.title))})]})})}function c0(){return s.jsx("section",{className:"section reward",id:"rewards",children:s.jsxs("div",{className:"shell reward__shell",children:[s.jsxs("header",{className:"reward__header",children:[s.jsx("span",{className:"eyebrow",children:"§02 — reward function"}),s.jsxs("h2",{className:"reward__title",children:["Five components.",s.jsx("br",{}),s.jsx("em",{children:"Zero LLM judges."})]}),s.jsxs("p",{className:"reward__sub",children:["Every bit of reward traces to a deterministic check against the episode trace and the (possibly drifted) JSON schema. Calibrated with a Brier penalty against the agent's own confidence; an",s.jsx("em",{children:" uncertain floor "})," at 0.50 prevents pathological high-confidence wrong answers from gaming the score. Source:"," ",s.jsx("code",{className:"mono",children:"cells/step_08_rewards.py"}),"."]})]}),s.jsx("ol",{className:"reward__grid",children:Vf.map((e,t)=>s.jsxs("li",{className:"reward__card",style:{animationDelay:`${t*80}ms`},children:[s.jsxs("div",{className:"reward__card-head",children:[s.jsx("span",{className:"reward__id",children:e.id}),s.jsxs("span",{className:"reward__weight mono",children:["w = ",e.weight.toFixed(2)]})]}),s.jsx("h3",{className:"reward__name",children:s.jsx("span",{className:"mono",children:e.name})}),s.jsx("p",{className:"reward__blurb",children:e.blurb}),s.jsx("code",{className:"reward__impl mono",children:e.impl})]},e.id))}),s.jsxs("div",{className:"reward__pipeline","aria-label":"reward pipeline",children:[s.jsx("span",{className:"mono reward__pipe-step",children:"combine_quality"}),s.jsx("span",{className:"reward__pipe-arrow","aria-hidden":!0,children:"→"}),s.jsx("span",{className:"mono reward__pipe-step",children:"brier_penalty"}),s.jsx("span",{className:"reward__pipe-arrow","aria-hidden":!0,children:"→"}),s.jsx("span",{className:"mono reward__pipe-step",children:"apply_uncertain_floor"}),s.jsx("span",{className:"reward__pipe-arrow","aria-hidden":!0,children:"→"}),s.jsx("span",{className:"mono reward__pipe-step reward__pipe-step--final",children:"final_reward"})]}),s.jsxs("div",{className:"reward__drift",children:[s.jsxs("header",{className:"reward__drift-head",children:[s.jsx("span",{className:"kicker",children:"drift catalogue"}),s.jsxs("span",{className:"mono reward__drift-count",children:[Gs.length," / 20"]})]}),s.jsx("ul",{className:"reward__drift-list",children:Gs.map((e,t)=>s.jsxs("li",{children:[s.jsx("span",{className:"mono reward__drift-num",children:String(t+1).padStart(2,"0")}),s.jsx("span",{className:"reward__drift-name",children:e.replace(/_/g," ")})]},e))})]})]})})}const d0=[{id:"premise",label:"premise"},{id:"rewards",label:"reward"},{id:"demo",label:"demo"},{id:"results",label:"results"},{id:"architecture",label:"arch"},{id:"resources",label:"links"}];function f0(){return s.jsxs(s.Fragment,{children:[s.jsxs("nav",{className:"rail","aria-label":"section index",children:[s.jsx("span",{className:"rail__brand mono",children:"drift / call"}),s.jsx("ol",{className:"rail__list",children:d0.map((e,t)=>s.jsx("li",{children:s.jsxs("a",{href:`#${e.id}`,className:"rail__link",children:[s.jsx("span",{className:"rail__num mono",children:String(t+1).padStart(2,"0")}),s.jsx("span",{className:"rail__label",children:e.label})]})},e.id))}),s.jsx("span",{className:"rail__foot mono",children:"v0.1.0"})]}),s.jsxs("main",{className:"main",children:[s.jsx(n0,{}),s.jsx(r0,{}),s.jsx(c0,{}),s.jsx(Xf,{}),s.jsx(s0,{}),s.jsx(Kf,{}),s.jsx(a0,{})]}),s.jsx(Yf,{})]})}const sc=document.getElementById("root");if(!sc)throw new Error("DriftCall: #root not found in DOM");oc(sc).render(s.jsx(Ae.StrictMode,{children:s.jsx(f0,{})})); diff --git a/site/assets/layout-C5Ii8faq.js b/site/assets/layout-C5Ii8faq.js new file mode 100644 index 0000000000000000000000000000000000000000..7483dbf5f7629dfceec32ccb1a53a812efbe3be9 --- /dev/null +++ b/site/assets/layout-C5Ii8faq.js @@ -0,0 +1,4 @@ +const Ye=["BN","BN","BN","BN","BN","BN","BN","BN","BN","S","B","S","WS","B","BN","BN","BN","BN","BN","BN","BN","BN","BN","BN","BN","BN","BN","BN","B","B","B","S","WS","ON","ON","ET","ET","ET","ON","ON","ON","ON","ON","ES","CS","ES","CS","CS","EN","EN","EN","EN","EN","EN","EN","EN","EN","EN","CS","ON","ON","ON","ON","ON","ON","L","L","L","L","L","L","L","L","L","L","L","L","L","L","L","L","L","L","L","L","L","L","L","L","L","L","ON","ON","ON","ON","ON","ON","L","L","L","L","L","L","L","L","L","L","L","L","L","L","L","L","L","L","L","L","L","L","L","L","L","L","ON","ON","ON","ON","BN","BN","BN","BN","BN","BN","B","BN","BN","BN","BN","BN","BN","BN","BN","BN","BN","BN","BN","BN","BN","BN","BN","BN","BN","BN","BN","BN","BN","BN","BN","BN","BN","CS","ON","ET","ET","ET","ET","ON","ON","ON","ON","L","ON","ON","BN","ON","ON","ET","ET","EN","EN","ON","L","ON","ON","ON","EN","L","ON","ON","ON","ON","ON","L","L","L","L","L","L","L","L","L","L","L","L","L","L","L","L","L","L","L","L","L","L","L","ON","L","L","L","L","L","L","L","L","L","L","L","L","L","L","L","L","L","L","L","L","L","L","L","L","L","L","L","L","L","L","L","ON","L","L","L","L","L","L","L","L"],Ce=[[697,698,"ON"],[706,719,"ON"],[722,735,"ON"],[741,749,"ON"],[751,767,"ON"],[768,879,"NSM"],[884,885,"ON"],[894,894,"ON"],[900,901,"ON"],[903,903,"ON"],[1014,1014,"ON"],[1155,1161,"NSM"],[1418,1418,"ON"],[1421,1422,"ON"],[1423,1423,"ET"],[1424,1424,"R"],[1425,1469,"NSM"],[1470,1470,"R"],[1471,1471,"NSM"],[1472,1472,"R"],[1473,1474,"NSM"],[1475,1475,"R"],[1476,1477,"NSM"],[1478,1478,"R"],[1479,1479,"NSM"],[1480,1535,"R"],[1536,1541,"AN"],[1542,1543,"ON"],[1544,1544,"AL"],[1545,1546,"ET"],[1547,1547,"AL"],[1548,1548,"CS"],[1549,1549,"AL"],[1550,1551,"ON"],[1552,1562,"NSM"],[1563,1610,"AL"],[1611,1631,"NSM"],[1632,1641,"AN"],[1642,1642,"ET"],[1643,1644,"AN"],[1645,1647,"AL"],[1648,1648,"NSM"],[1649,1749,"AL"],[1750,1756,"NSM"],[1757,1757,"AN"],[1758,1758,"ON"],[1759,1764,"NSM"],[1765,1766,"AL"],[1767,1768,"NSM"],[1769,1769,"ON"],[1770,1773,"NSM"],[1774,1775,"AL"],[1776,1785,"EN"],[1786,1808,"AL"],[1809,1809,"NSM"],[1810,1839,"AL"],[1840,1866,"NSM"],[1867,1957,"AL"],[1958,1968,"NSM"],[1969,1983,"AL"],[1984,2026,"R"],[2027,2035,"NSM"],[2036,2037,"R"],[2038,2041,"ON"],[2042,2044,"R"],[2045,2045,"NSM"],[2046,2069,"R"],[2070,2073,"NSM"],[2074,2074,"R"],[2075,2083,"NSM"],[2084,2084,"R"],[2085,2087,"NSM"],[2088,2088,"R"],[2089,2093,"NSM"],[2094,2136,"R"],[2137,2139,"NSM"],[2140,2143,"R"],[2144,2191,"AL"],[2192,2193,"AN"],[2194,2198,"AL"],[2199,2207,"NSM"],[2208,2249,"AL"],[2250,2273,"NSM"],[2274,2274,"AN"],[2275,2306,"NSM"],[2362,2362,"NSM"],[2364,2364,"NSM"],[2369,2376,"NSM"],[2381,2381,"NSM"],[2385,2391,"NSM"],[2402,2403,"NSM"],[2433,2433,"NSM"],[2492,2492,"NSM"],[2497,2500,"NSM"],[2509,2509,"NSM"],[2530,2531,"NSM"],[2546,2547,"ET"],[2555,2555,"ET"],[2558,2558,"NSM"],[2561,2562,"NSM"],[2620,2620,"NSM"],[2625,2626,"NSM"],[2631,2632,"NSM"],[2635,2637,"NSM"],[2641,2641,"NSM"],[2672,2673,"NSM"],[2677,2677,"NSM"],[2689,2690,"NSM"],[2748,2748,"NSM"],[2753,2757,"NSM"],[2759,2760,"NSM"],[2765,2765,"NSM"],[2786,2787,"NSM"],[2801,2801,"ET"],[2810,2815,"NSM"],[2817,2817,"NSM"],[2876,2876,"NSM"],[2879,2879,"NSM"],[2881,2884,"NSM"],[2893,2893,"NSM"],[2901,2902,"NSM"],[2914,2915,"NSM"],[2946,2946,"NSM"],[3008,3008,"NSM"],[3021,3021,"NSM"],[3059,3064,"ON"],[3065,3065,"ET"],[3066,3066,"ON"],[3072,3072,"NSM"],[3076,3076,"NSM"],[3132,3132,"NSM"],[3134,3136,"NSM"],[3142,3144,"NSM"],[3146,3149,"NSM"],[3157,3158,"NSM"],[3170,3171,"NSM"],[3192,3198,"ON"],[3201,3201,"NSM"],[3260,3260,"NSM"],[3276,3277,"NSM"],[3298,3299,"NSM"],[3328,3329,"NSM"],[3387,3388,"NSM"],[3393,3396,"NSM"],[3405,3405,"NSM"],[3426,3427,"NSM"],[3457,3457,"NSM"],[3530,3530,"NSM"],[3538,3540,"NSM"],[3542,3542,"NSM"],[3633,3633,"NSM"],[3636,3642,"NSM"],[3647,3647,"ET"],[3655,3662,"NSM"],[3761,3761,"NSM"],[3764,3772,"NSM"],[3784,3790,"NSM"],[3864,3865,"NSM"],[3893,3893,"NSM"],[3895,3895,"NSM"],[3897,3897,"NSM"],[3898,3901,"ON"],[3953,3966,"NSM"],[3968,3972,"NSM"],[3974,3975,"NSM"],[3981,3991,"NSM"],[3993,4028,"NSM"],[4038,4038,"NSM"],[4141,4144,"NSM"],[4146,4151,"NSM"],[4153,4154,"NSM"],[4157,4158,"NSM"],[4184,4185,"NSM"],[4190,4192,"NSM"],[4209,4212,"NSM"],[4226,4226,"NSM"],[4229,4230,"NSM"],[4237,4237,"NSM"],[4253,4253,"NSM"],[4957,4959,"NSM"],[5008,5017,"ON"],[5120,5120,"ON"],[5760,5760,"WS"],[5787,5788,"ON"],[5906,5908,"NSM"],[5938,5939,"NSM"],[5970,5971,"NSM"],[6002,6003,"NSM"],[6068,6069,"NSM"],[6071,6077,"NSM"],[6086,6086,"NSM"],[6089,6099,"NSM"],[6107,6107,"ET"],[6109,6109,"NSM"],[6128,6137,"ON"],[6144,6154,"ON"],[6155,6157,"NSM"],[6158,6158,"BN"],[6159,6159,"NSM"],[6277,6278,"NSM"],[6313,6313,"NSM"],[6432,6434,"NSM"],[6439,6440,"NSM"],[6450,6450,"NSM"],[6457,6459,"NSM"],[6464,6464,"ON"],[6468,6469,"ON"],[6622,6655,"ON"],[6679,6680,"NSM"],[6683,6683,"NSM"],[6742,6742,"NSM"],[6744,6750,"NSM"],[6752,6752,"NSM"],[6754,6754,"NSM"],[6757,6764,"NSM"],[6771,6780,"NSM"],[6783,6783,"NSM"],[6832,6877,"NSM"],[6880,6891,"NSM"],[6912,6915,"NSM"],[6964,6964,"NSM"],[6966,6970,"NSM"],[6972,6972,"NSM"],[6978,6978,"NSM"],[7019,7027,"NSM"],[7040,7041,"NSM"],[7074,7077,"NSM"],[7080,7081,"NSM"],[7083,7085,"NSM"],[7142,7142,"NSM"],[7144,7145,"NSM"],[7149,7149,"NSM"],[7151,7153,"NSM"],[7212,7219,"NSM"],[7222,7223,"NSM"],[7376,7378,"NSM"],[7380,7392,"NSM"],[7394,7400,"NSM"],[7405,7405,"NSM"],[7412,7412,"NSM"],[7416,7417,"NSM"],[7616,7679,"NSM"],[8125,8125,"ON"],[8127,8129,"ON"],[8141,8143,"ON"],[8157,8159,"ON"],[8173,8175,"ON"],[8189,8190,"ON"],[8192,8202,"WS"],[8203,8205,"BN"],[8207,8207,"R"],[8208,8231,"ON"],[8232,8232,"WS"],[8233,8233,"B"],[8234,8238,"BN"],[8239,8239,"CS"],[8240,8244,"ET"],[8245,8259,"ON"],[8260,8260,"CS"],[8261,8286,"ON"],[8287,8287,"WS"],[8288,8303,"BN"],[8304,8304,"EN"],[8308,8313,"EN"],[8314,8315,"ES"],[8316,8318,"ON"],[8320,8329,"EN"],[8330,8331,"ES"],[8332,8334,"ON"],[8352,8399,"ET"],[8400,8432,"NSM"],[8448,8449,"ON"],[8451,8454,"ON"],[8456,8457,"ON"],[8468,8468,"ON"],[8470,8472,"ON"],[8478,8483,"ON"],[8485,8485,"ON"],[8487,8487,"ON"],[8489,8489,"ON"],[8494,8494,"ET"],[8506,8507,"ON"],[8512,8516,"ON"],[8522,8525,"ON"],[8528,8543,"ON"],[8585,8587,"ON"],[8592,8721,"ON"],[8722,8722,"ES"],[8723,8723,"ET"],[8724,9013,"ON"],[9083,9108,"ON"],[9110,9257,"ON"],[9280,9290,"ON"],[9312,9351,"ON"],[9352,9371,"EN"],[9450,9899,"ON"],[9901,10239,"ON"],[10496,11123,"ON"],[11126,11263,"ON"],[11493,11498,"ON"],[11503,11505,"NSM"],[11513,11519,"ON"],[11647,11647,"NSM"],[11744,11775,"NSM"],[11776,11869,"ON"],[11904,11929,"ON"],[11931,12019,"ON"],[12032,12245,"ON"],[12272,12287,"ON"],[12288,12288,"WS"],[12289,12292,"ON"],[12296,12320,"ON"],[12330,12333,"NSM"],[12336,12336,"ON"],[12342,12343,"ON"],[12349,12351,"ON"],[12441,12442,"NSM"],[12443,12444,"ON"],[12448,12448,"ON"],[12539,12539,"ON"],[12736,12773,"ON"],[12783,12783,"ON"],[12829,12830,"ON"],[12880,12895,"ON"],[12924,12926,"ON"],[12977,12991,"ON"],[13004,13007,"ON"],[13175,13178,"ON"],[13278,13279,"ON"],[13311,13311,"ON"],[19904,19967,"ON"],[42128,42182,"ON"],[42509,42511,"ON"],[42607,42610,"NSM"],[42611,42611,"ON"],[42612,42621,"NSM"],[42622,42623,"ON"],[42654,42655,"NSM"],[42736,42737,"NSM"],[42752,42785,"ON"],[42888,42888,"ON"],[43010,43010,"NSM"],[43014,43014,"NSM"],[43019,43019,"NSM"],[43045,43046,"NSM"],[43048,43051,"ON"],[43052,43052,"NSM"],[43064,43065,"ET"],[43124,43127,"ON"],[43204,43205,"NSM"],[43232,43249,"NSM"],[43263,43263,"NSM"],[43302,43309,"NSM"],[43335,43345,"NSM"],[43392,43394,"NSM"],[43443,43443,"NSM"],[43446,43449,"NSM"],[43452,43453,"NSM"],[43493,43493,"NSM"],[43561,43566,"NSM"],[43569,43570,"NSM"],[43573,43574,"NSM"],[43587,43587,"NSM"],[43596,43596,"NSM"],[43644,43644,"NSM"],[43696,43696,"NSM"],[43698,43700,"NSM"],[43703,43704,"NSM"],[43710,43711,"NSM"],[43713,43713,"NSM"],[43756,43757,"NSM"],[43766,43766,"NSM"],[43882,43883,"ON"],[44005,44005,"NSM"],[44008,44008,"NSM"],[44013,44013,"NSM"],[64285,64285,"R"],[64286,64286,"NSM"],[64287,64296,"R"],[64297,64297,"ES"],[64298,64335,"R"],[64336,64450,"AL"],[64451,64466,"ON"],[64467,64829,"AL"],[64830,64847,"ON"],[64848,64911,"AL"],[64912,64913,"ON"],[64914,64967,"AL"],[64968,64975,"ON"],[64976,65007,"BN"],[65008,65020,"AL"],[65021,65023,"ON"],[65024,65039,"NSM"],[65040,65049,"ON"],[65056,65071,"NSM"],[65072,65103,"ON"],[65104,65104,"CS"],[65105,65105,"ON"],[65106,65106,"CS"],[65108,65108,"ON"],[65109,65109,"CS"],[65110,65118,"ON"],[65119,65119,"ET"],[65120,65121,"ON"],[65122,65123,"ES"],[65124,65126,"ON"],[65128,65128,"ON"],[65129,65130,"ET"],[65131,65131,"ON"],[65136,65278,"AL"],[65279,65279,"BN"],[65281,65282,"ON"],[65283,65285,"ET"],[65286,65290,"ON"],[65291,65291,"ES"],[65292,65292,"CS"],[65293,65293,"ES"],[65294,65295,"CS"],[65296,65305,"EN"],[65306,65306,"CS"],[65307,65312,"ON"],[65339,65344,"ON"],[65371,65381,"ON"],[65504,65505,"ET"],[65506,65508,"ON"],[65509,65510,"ET"],[65512,65518,"ON"],[65520,65528,"BN"],[65529,65533,"ON"],[65534,65535,"BN"],[65793,65793,"ON"],[65856,65932,"ON"],[65936,65948,"ON"],[65952,65952,"ON"],[66045,66045,"NSM"],[66272,66272,"NSM"],[66273,66299,"EN"],[66422,66426,"NSM"],[67584,67870,"R"],[67871,67871,"ON"],[67872,68096,"R"],[68097,68099,"NSM"],[68100,68100,"R"],[68101,68102,"NSM"],[68103,68107,"R"],[68108,68111,"NSM"],[68112,68151,"R"],[68152,68154,"NSM"],[68155,68158,"R"],[68159,68159,"NSM"],[68160,68324,"R"],[68325,68326,"NSM"],[68327,68408,"R"],[68409,68415,"ON"],[68416,68863,"R"],[68864,68899,"AL"],[68900,68903,"NSM"],[68904,68911,"AL"],[68912,68921,"AN"],[68922,68927,"AL"],[68928,68937,"AN"],[68938,68968,"R"],[68969,68973,"NSM"],[68974,68974,"ON"],[68975,69215,"R"],[69216,69246,"AN"],[69247,69290,"R"],[69291,69292,"NSM"],[69293,69311,"R"],[69312,69327,"AL"],[69328,69336,"ON"],[69337,69369,"AL"],[69370,69375,"NSM"],[69376,69423,"R"],[69424,69445,"AL"],[69446,69456,"NSM"],[69457,69487,"AL"],[69488,69505,"R"],[69506,69509,"NSM"],[69510,69631,"R"],[69633,69633,"NSM"],[69688,69702,"NSM"],[69714,69733,"ON"],[69744,69744,"NSM"],[69747,69748,"NSM"],[69759,69761,"NSM"],[69811,69814,"NSM"],[69817,69818,"NSM"],[69826,69826,"NSM"],[69888,69890,"NSM"],[69927,69931,"NSM"],[69933,69940,"NSM"],[70003,70003,"NSM"],[70016,70017,"NSM"],[70070,70078,"NSM"],[70089,70092,"NSM"],[70095,70095,"NSM"],[70191,70193,"NSM"],[70196,70196,"NSM"],[70198,70199,"NSM"],[70206,70206,"NSM"],[70209,70209,"NSM"],[70367,70367,"NSM"],[70371,70378,"NSM"],[70400,70401,"NSM"],[70459,70460,"NSM"],[70464,70464,"NSM"],[70502,70508,"NSM"],[70512,70516,"NSM"],[70587,70592,"NSM"],[70606,70606,"NSM"],[70608,70608,"NSM"],[70610,70610,"NSM"],[70625,70626,"NSM"],[70712,70719,"NSM"],[70722,70724,"NSM"],[70726,70726,"NSM"],[70750,70750,"NSM"],[70835,70840,"NSM"],[70842,70842,"NSM"],[70847,70848,"NSM"],[70850,70851,"NSM"],[71090,71093,"NSM"],[71100,71101,"NSM"],[71103,71104,"NSM"],[71132,71133,"NSM"],[71219,71226,"NSM"],[71229,71229,"NSM"],[71231,71232,"NSM"],[71264,71276,"ON"],[71339,71339,"NSM"],[71341,71341,"NSM"],[71344,71349,"NSM"],[71351,71351,"NSM"],[71453,71453,"NSM"],[71455,71455,"NSM"],[71458,71461,"NSM"],[71463,71467,"NSM"],[71727,71735,"NSM"],[71737,71738,"NSM"],[71995,71996,"NSM"],[71998,71998,"NSM"],[72003,72003,"NSM"],[72148,72151,"NSM"],[72154,72155,"NSM"],[72160,72160,"NSM"],[72193,72198,"NSM"],[72201,72202,"NSM"],[72243,72248,"NSM"],[72251,72254,"NSM"],[72263,72263,"NSM"],[72273,72278,"NSM"],[72281,72283,"NSM"],[72330,72342,"NSM"],[72344,72345,"NSM"],[72544,72544,"NSM"],[72546,72548,"NSM"],[72550,72550,"NSM"],[72752,72758,"NSM"],[72760,72765,"NSM"],[72850,72871,"NSM"],[72874,72880,"NSM"],[72882,72883,"NSM"],[72885,72886,"NSM"],[73009,73014,"NSM"],[73018,73018,"NSM"],[73020,73021,"NSM"],[73023,73029,"NSM"],[73031,73031,"NSM"],[73104,73105,"NSM"],[73109,73109,"NSM"],[73111,73111,"NSM"],[73459,73460,"NSM"],[73472,73473,"NSM"],[73526,73530,"NSM"],[73536,73536,"NSM"],[73538,73538,"NSM"],[73562,73562,"NSM"],[73685,73692,"ON"],[73693,73696,"ET"],[73697,73713,"ON"],[78912,78912,"NSM"],[78919,78933,"NSM"],[90398,90409,"NSM"],[90413,90415,"NSM"],[92912,92916,"NSM"],[92976,92982,"NSM"],[94031,94031,"NSM"],[94095,94098,"NSM"],[94178,94178,"ON"],[94180,94180,"NSM"],[113821,113822,"NSM"],[113824,113827,"BN"],[117760,117973,"ON"],[118e3,118009,"EN"],[118010,118012,"ON"],[118016,118451,"ON"],[118458,118480,"ON"],[118496,118512,"ON"],[118528,118573,"NSM"],[118576,118598,"NSM"],[119143,119145,"NSM"],[119155,119162,"BN"],[119163,119170,"NSM"],[119173,119179,"NSM"],[119210,119213,"NSM"],[119273,119274,"ON"],[119296,119361,"ON"],[119362,119364,"NSM"],[119365,119365,"ON"],[119552,119638,"ON"],[120513,120513,"ON"],[120539,120539,"ON"],[120571,120571,"ON"],[120597,120597,"ON"],[120629,120629,"ON"],[120655,120655,"ON"],[120687,120687,"ON"],[120713,120713,"ON"],[120745,120745,"ON"],[120771,120771,"ON"],[120782,120831,"EN"],[121344,121398,"NSM"],[121403,121452,"NSM"],[121461,121461,"NSM"],[121476,121476,"NSM"],[121499,121503,"NSM"],[121505,121519,"NSM"],[122880,122886,"NSM"],[122888,122904,"NSM"],[122907,122913,"NSM"],[122915,122916,"NSM"],[122918,122922,"NSM"],[123023,123023,"NSM"],[123184,123190,"NSM"],[123566,123566,"NSM"],[123628,123631,"NSM"],[123647,123647,"ET"],[124140,124143,"NSM"],[124398,124399,"NSM"],[124643,124643,"NSM"],[124646,124646,"NSM"],[124654,124655,"NSM"],[124661,124661,"NSM"],[124928,125135,"R"],[125136,125142,"NSM"],[125143,125251,"R"],[125252,125258,"NSM"],[125259,126063,"R"],[126064,126143,"AL"],[126144,126207,"R"],[126208,126287,"AL"],[126288,126463,"R"],[126464,126703,"AL"],[126704,126705,"ON"],[126706,126719,"AL"],[126720,126975,"R"],[126976,127019,"ON"],[127024,127123,"ON"],[127136,127150,"ON"],[127153,127167,"ON"],[127169,127183,"ON"],[127185,127221,"ON"],[127232,127242,"EN"],[127243,127247,"ON"],[127279,127279,"ON"],[127338,127343,"ON"],[127405,127405,"ON"],[127584,127589,"ON"],[127744,128728,"ON"],[128732,128748,"ON"],[128752,128764,"ON"],[128768,128985,"ON"],[128992,129003,"ON"],[129008,129008,"ON"],[129024,129035,"ON"],[129040,129095,"ON"],[129104,129113,"ON"],[129120,129159,"ON"],[129168,129197,"ON"],[129200,129211,"ON"],[129216,129217,"ON"],[129232,129240,"ON"],[129280,129623,"ON"],[129632,129645,"ON"],[129648,129660,"ON"],[129664,129674,"ON"],[129678,129734,"ON"],[129736,129736,"ON"],[129741,129756,"ON"],[129759,129770,"ON"],[129775,129784,"ON"],[129792,129938,"ON"],[129940,130031,"ON"],[130032,130041,"EN"],[130042,130042,"ON"],[131070,131071,"BN"],[196606,196607,"BN"],[262142,262143,"BN"],[327678,327679,"BN"],[393214,393215,"BN"],[458750,458751,"BN"],[524286,524287,"BN"],[589822,589823,"BN"],[655358,655359,"BN"],[720894,720895,"BN"],[786430,786431,"BN"],[851966,851967,"BN"],[917502,917759,"BN"],[917760,917999,"NSM"],[918e3,921599,"BN"],[983038,983039,"BN"],[1048574,1048575,"BN"],[1114110,1114111,"BN"]];function et(e){if(e<=255)return Ye[e];let t=0,n=Ce.length-1;for(;t<=n;){const s=t+n>>1,r=Ce[s];if(er[1]){t=s+1;continue}return r[2]}return"L"}function tt(e){const t=e.length;if(t===0)return null;const n=new Array(t);let s=!1;for(let l=0;l=55296&&u<=56319&&l+1=56320&&O<=57343&&(f=(u-55296<<10)+(O-56320)+65536,c=2)}const d=et(f);(d==="R"||d==="AL"||d==="AN")&&(s=!0);for(let O=0;O=0&&n[u]==="ET";u--)n[u]="EN";for(u=l+1;u0?n[l-1]:a,c=u0&&t.charCodeAt(t.length-1)===32&&(t=t.slice(0,-1)),t}function ut(e){return/[\r\f]/.test(e)?e.replace(/\r\n/g,` +`).replace(/[\r\f]/g,` +`):e}let $=null,oe;function ot(){return $===null&&($=new Intl.Segmenter(oe,{granularity:"word"})),$}function ct(){$=null}function Nt(e){const t=e&&e.length>0?e:void 0;oe!==t&&(oe=t,$=null)}const at=/\p{Script=Arabic}/u,ie=/\p{M}/u,Fe=/\p{Nd}/u;function Ae(e){return at.test(e)}function Be(e){return e>=19968&&e<=40959||e>=13312&&e<=19903||e>=131072&&e<=173791||e>=173824&&e<=177983||e>=177984&&e<=178207||e>=178208&&e<=183983||e>=183984&&e<=191471||e>=191472&&e<=192093||e>=194560&&e<=195103||e>=196608&&e<=201551||e>=201552&&e<=205743||e>=205744&&e<=210041||e>=63744&&e<=64255||e>=12288&&e<=12351||e>=12352&&e<=12447||e>=12448&&e<=12543||e>=12592&&e<=12687||e>=44032&&e<=55215||e>=65280&&e<=65519}function j(e){for(let t=0;t=55296&&n<=56319&&t+1=56320&&s<=57343){const r=(n-55296<<10)+(s-56320)+65536;if(Be(r))return!0;t++;continue}}if(Be(n))return!0}}return!1}function ft(e){const t=q(e);return t!==null&&(he.has(t)||J.has(t))}const St=new Set([" "," ","⁠","\uFEFF"]),ht=new Set(["-","‐","–","—"]);function dt(e){return j(e)}function Mt(e){const t=q(e);return t!==null&&St.has(t)}function gt(e){const t=q(e);return t!==null&&ht.has(t)}function Te(e,t){return Mt(e)?!1:t?!(ft(e)||gt(e)):!0}const he=new Set(["，","．","！","：","；","？","、","。","・","）","〕","〉","》","」","』","】","〗","〙","〛","ー","々","〻","ゝ","ゞ","ヽ","ヾ"]),re=new Set(['"',"(","[","{","“","‘","«","‹","（","〔","〈","《","「","『","【","〖","〘","〚"]),de=new Set(["'","’"]),J=new Set([".",",","!","?",":",";","،","؛","؟","।","॥","၊","။","၌","၍","၏",")","]","}","%",'"',"”","’","»","›","…"]),pt=new Set([":",".","،","؛"]),Lt=new Set(["၏"]),mt=new Set(["”","’","»","›","」","』","】","》","〉","〕","）"]);function Ot(e){if(Me(e))return!0;let t=!1;for(const n of e){if(J.has(n)){t=!0;continue}if(!(t&&ie.test(n)))return!1}return t}function kt(e){for(const t of e)if(!he.has(t)&&!J.has(t))return!1;return e.length>0}function xt(e){if(Me(e))return!0;for(const t of e)if(!re.has(t)&&!de.has(t)&&!ie.test(t))return!1;return e.length>0}function Me(e){let t=!1;for(const n of e)if(!(n==="\\"||ie.test(n))){if(re.has(n)||J.has(n)||de.has(n)){t=!0;continue}return!1}return t}function Pe(e,t){const n=t-1;if(n<=0)return Math.max(n,0);const s=e.charCodeAt(n);if(s<56320||s>57343)return n;const r=n-1;if(r<0)return n;const i=e.charCodeAt(r);return i>=55296&&i<=56319?r:n}function q(e){if(e.length===0)return null;const t=Pe(e,e.length);return e.slice(t)}function Et(e){const t=Array.from(e);let n=t.length;for(;n>0;){const s=t[n-1];if(ie.test(s)){n--;continue}if(re.has(s)||de.has(s)){n--;continue}break}return n<=0||n===t.length?null:{head:t.slice(0,n).join(""),tail:t.slice(n).join("")}}function Ct(e,t,n){return n==="text"&&!t&&e.length===1&&e!=="-"&&e!=="—"?e:null}function be(e,t,n,s){const r=t[s],i=e[s];if(r==null)return i;const o=n[s];if(i.length===o)return i;const a=r.repeat(o);return e[s]=a,a}function We(e,t){return e&&t!==null&&pt.has(t)}function At(e){const t=q(e);return t!==null&&Lt.has(t)}function Bt(e){if(e.length<2||e[0]!==" ")return null;const t=e.slice(1);return/^\p{M}+$/u.test(t)?{space:" ",marks:t}:null}function ce(e){let t=e.length;for(;t>0;){const n=Pe(e,t),s=e.slice(n,t);if(mt.has(s))return!0;if(!J.has(s))return!1;t=n}return!1}function bt(e,t){if(t.preserveOrdinarySpaces||t.preserveHardBreaks){if(e===" ")return"preserved-space";if(e===" ")return"tab";if(t.preserveHardBreaks&&e===` +`)return"hard-break"}return e===" "?"space":e===" "||e===" "||e==="⁠"||e==="\uFEFF"?"glue":e==="​"?"zero-width-break":e==="­"?"soft-hyphen":"text"}const Wt=/[\x20\t\n\xA0\xAD\u200B\u202F\u2060\uFEFF]/;function G(e){return e.length===1?e[0]:e.join("")}function wt(e,t){const n=[];for(let s=e.length-1;s>=0;s--)n.push(e[s]);return n.push(t),G(n)}function It(e,t,n,s){if(!Wt.test(e))return[{text:e,isWordLike:t,kind:"text",start:n}];const r=[];let i=null,o=[],a=n,N=!1,l=0;for(const u of e){const f=bt(u,s),c=f==="text"&&t;if(i!==null&&f===i&&c===N){o.push(u),l+=u.length;continue}i!==null&&r.push({text:G(o),isWordLike:N,kind:i,start:a}),i=f,o=[u],a=n+l,N=c,l+=u.length}return i!==null&&r.push({text:G(o),isWordLike:N,kind:i,start:a}),r}function Ne(e){return e==="space"||e==="preserved-space"||e==="zero-width-break"||e==="hard-break"}const yt=/^[A-Za-z][A-Za-z0-9+.-]*:$/;function vt(e,t){const n=e.texts[t];return n.startsWith("www.")?!0:yt.test(n)&&t+1=e.len||Ne(e.kinds[a]))continue;const N=[],l=e.starts[a];let u=a;for(;u0&&(t.push(G(N)),n.push(!0),s.push("text"),r.push(l),i=u-1)}return{len:t.length,texts:t,isWordLike:n,kinds:s,starts:r}}const Pt=new Set([":","-","/","×",",",".","+","–","—"]),we=/^[A-Za-z0-9_]+[.,:;]*$/,Ie=/[.,:;]+$/;function Ge(e){for(const t of e)if(Fe.test(t))return!0;return!1}function ee(e){if(e.length===0)return!1;for(const t of e)if(!(Fe.test(t)||Pt.has(t)))return!1;return!0}function Gt(e){const t=[],n=[],s=[],r=[];for(let i=0;i1;for(let l=0;l0&&N[S]==="text"&&W&&c[S]&&O[S]||B&&r>0&&N[S]==="text"&&kt(L.text)&&c[S]||B&&r>0&&N[S]==="text"&&p[S]?b():B&&r>0&&N[S]==="text"&&L.isWordLike&&M&&x[S]?(b(),a[S]=!0):C!==null&&r>0&&N[S]==="text"&&u[S]===C?f[S]=(f[S]??1)+1:B&&!L.isWordLike&&r>0&&N[S]==="text"&&!c[S]&&(Ot(L.text)||L.text==="-"&&a[S])?b():(i[r]=L.text,o[r]=[L.text],a[r]=L.isWordLike,N[r]=L.kind,l[r]=L.start,u[r]=C,f[r]=C===null?0:1,c[r]=W,d[r]=M,O[r]=y,p[r]=m,x[r]=We(M,k),r++)}for(let h=0;hnull);let v=-1;for(let h=r-1;h>=0;h--){const L=i[h];if(L.length!==0){if(N[h]==="text"&&!a[h]&&xt(L)&&v>=0&&N[v]==="text"){const b=A[v]??[];b.push(L),A[v]=b,l[v]=l[h],i[h]="";continue}v=h}}for(let h=0;h=0&&!Te(t.texts[c-1],n)&&f(c),a<0&&(a=c),N=N||dt(d);continue}f(c),s.push(d),r.push(t.isWordLike[c]),i.push(O),o.push(t.starts[c])}return f(t.len),{len:s.length,texts:s,isWordLike:r,kinds:i,starts:o}}function Dt(e,t,n="normal",s="normal"){const r=st(n),i=r.mode==="pre-wrap"?ut(e):lt(e);if(i.length===0)return{normalized:i,chunks:[],len:0,texts:[],isWordLike:[],kinds:[],starts:[]};const o=Jt(i,t,r),a=s==="keep-all"?Qt(i,o,t.breakKeepAllAfterPunctuation):o;return{normalized:i,chunks:Ut(a,r),...a}}let Q=null;const ae=new Map;let D=null;const _t=96,$t=/\p{Emoji_Presentation}/u,qt=/[\p{Emoji_Presentation}\p{Extended_Pictographic}\p{Regional_Indicator}\uFE0F\u20E3]/u;let X=null;const fe=new Map;function ge(){if(Q!==null)return Q;if(typeof OffscreenCanvas<"u")return Q=new OffscreenCanvas(1,1).getContext("2d"),Q;if(typeof document<"u")return Q=document.createElement("canvas").getContext("2d"),Q;throw new Error("Text measurement requires OffscreenCanvas or a DOM canvas context.")}function Zt(e){let t=ae.get(e);return t||(t=new Map,ae.set(e,t)),t}function z(e,t){let n=t.get(e);return n===void 0&&(n={width:ge().measureText(e).width,containsCJK:j(e)},t.set(e,n)),n}function _(){if(D!==null)return D;if(typeof navigator>"u")return D={lineFitEpsilon:.005,carryCJKAfterClosingQuote:!1,breakKeepAllAfterPunctuation:!0,preferPrefixWidthsForBreakableRuns:!1,preferEarlySoftHyphenBreak:!1},D;const e=navigator.userAgent,n=navigator.vendor==="Apple Computer, Inc."&&e.includes("Safari/")&&!e.includes("Chrome/")&&!e.includes("Chromium/")&&!e.includes("CriOS/")&&!e.includes("FxiOS/")&&!e.includes("EdgiOS/"),s=e.includes("Chrome/")||e.includes("Chromium/")||e.includes("CriOS/")||e.includes("Edg/");return D={lineFitEpsilon:n?1/64:.005,carryCJKAfterClosingQuote:s,breakKeepAllAfterPunctuation:!n,preferPrefixWidthsForBreakableRuns:n,preferEarlySoftHyphenBreak:n},D}function Xt(e){const t=e.match(/(\d+(?:\.\d+)?)\s*px/);return t?parseFloat(t[1]):16}function Ke(){return X===null&&(X=new Intl.Segmenter(void 0,{granularity:"grapheme"})),X}function Vt(e){return $t.test(e)||e.includes("️")}function Yt(e){return qt.test(e)}function en(e,t){let n=fe.get(e);if(n!==void 0)return n;const s=ge();s.font=e;const r=s.measureText("😀").width;if(n=0,r>t+.5&&typeof document<"u"&&document.body!==null){const i=document.createElement("span");i.style.font=e,i.style.display="inline-block",i.style.visibility="hidden",i.style.position="absolute",i.textContent="😀",document.body.appendChild(i);const o=i.getBoundingClientRect().width;document.body.removeChild(i),r-o>.5&&(n=r-o)}return fe.set(e,n),n}function tn(e){let t=0;const n=Ke();for(const s of n.segment(e))Vt(s.segment)&&t++;return t}function nn(e,t){return t.emojiCount===void 0&&(t.emojiCount=tn(e)),t.emojiCount}function H(e,t,n){return n===0?t.width:t.width-nn(e,t)*n}function rn(e,t,n,s,r){if(t.breakableFitAdvances!==void 0&&t.breakableFitMode===r)return t.breakableFitAdvances;t.breakableFitMode=r;const i=Ke(),o=[];for(const u of i.segment(e))o.push(u.segment);if(o.length<=1)return t.breakableFitAdvances=null,t.breakableFitAdvances;if(r==="sum-graphemes"){const u=[];for(const f of o){const c=z(f,n);u.push(H(f,c,s))}return t.breakableFitAdvances=u,t.breakableFitAdvances}if(r==="pair-context"||o.length>_t){const u=[];let f=null,c=0;for(const d of o){const O=z(d,n),p=H(d,O,s);if(f===null)u.push(p);else{const x=f+d,A=z(x,n);u.push(H(x,A,s)-c)}f=d,c=p}return t.breakableFitAdvances=u,t.breakableFitAdvances}const a=[];let N="",l=0;for(const u of o){N+=u;const f=z(N,n),c=H(N,f,s);a.push(c-l),l=c}return t.breakableFitAdvances=a,t.breakableFitAdvances}function sn(e,t){const n=ge();n.font=e;const s=Zt(e),r=Xt(e),i=t?en(e,r):0;return{cache:s,fontSize:r,emojiCorrection:i}}function ln(){ae.clear(),fe.clear(),X=null}function un(e){return e==="space"||e==="zero-width-break"||e==="soft-hyphen"}function se(e){return e==="space"||e==="preserved-space"||e==="tab"||e==="zero-width-break"||e==="soft-hyphen"}function pe(e,t,n=e.widths.length){for(;t0?e.letterSpacing:0}function Le(e,t){return t===0?0:e+t}function on(e,t){return e.letterSpacing!==0&&e.spacingGraphemeCounts[t]>0?e.letterSpacing:0}function He(e,t,n,s,r){const i=t==="tab"?r+on(e,n):e.lineEndFitAdvances[n];return Le(s,i)}function te(e,t,n,s){const r=t==="tab"?0:e.lineEndFitAdvances[n];return Le(s,r)}function ne(e,t,n,s,r){const i=t==="tab"?r:e.lineEndPaintAdvances[n];return Le(s,i)}function Je(e,t,n){return e.letterSpacing!==0&&t?n+e.letterSpacing:n}function Ue(e,t){return e.letterSpacing===0?t:t+e.letterSpacing}function Qe(e,t,n,s,r,i){let o=0,a=t;for(;on+s)break;a=N,o++}return{fitCount:o,fittedWidth:a}}function cn(e,t){let n=0,s=e.chunks.length;for(;n0)return t;const r=e.chunks[t];return r.startSegmentIndex===r.endSegmentIndex&&s===r.startSegmentIndex||(s=e.widths.length?-1:(n.segmentIndex=r.consumedEndSegmentIndex,n.graphemeIndex=0,t+1)}function me(e,t){if(t.segmentIndex>=e.widths.length)return-1;const n=cn(e,t.segmentIndex);return n<0?-1:De(e,n,t)}function Nn(e,t,n){if(n.segmentIndex>=e.widths.length)return-1;let s=t;for(;s=e.chunks[s].consumedEndSegmentIndex;)s++;return s>=e.chunks.length?-1:De(e,s,n)}function _e(e,t){const n={segmentIndex:t.segmentIndex,graphemeIndex:t.graphemeIndex};return me(e,n)<0?null:n}function an(e,t){return le(e,t)}function fn(e,t,n){const{widths:s,kinds:r,breakableFitAdvances:i}=e;if(s.length===0)return 0;const a=_().lineFitEpsilon,N=t+a;let l=0,u=0,f=!1,c=0,d=0,O=0,p=0,x=-1,A=0;function v(){x=-1,A=0}function I(B=O,C=p,W=u){l++,n?.(W,c,d,B,C),u=0,f=!1,v()}function R(B,C){f=!0,c=B,d=0,O=B+1,p=0,u=C}function E(B,C,W){f=!0,c=B,d=C,O=B,p=C+1,u=W}function h(B,C){if(!f){R(B,C);return}u+=C,O=B+1,p=0}function L(B,C){const W=i[B];for(let M=C;MN?(I(),E(B,M,k)):(u+=k,O=B,p=M+1):E(B,M,k)}f&&O===B&&p===W.length&&(O=B+1,p=0)}let b=0;for(;b=s.length));){const B=s[b],C=r[b],W=se(C);if(!f){B>N&&i[b]!==null?L(b,0):R(b,B),W&&(x=b+1,A=u-B),b++;continue}if(u+B>N){if(W){h(b,B),I(b+1,0,u-B),b++;continue}if(x>=0){if(O>x||O===x&&p>0){I();continue}I(x,0,A);continue}if(B>N&&i[b]!==null){I(),L(b,0),b++;continue}I();continue}h(b,B),W&&(x=b+1,A=u-B),b++}return f&&I(),l}function le(e,t,n){if(e.simpleLineWalkFastPath)return fn(e,t,n);const{widths:s,kinds:r,breakableFitAdvances:i,discretionaryHyphenWidth:o,chunks:a}=e;if(s.length===0||a.length===0)return 0;const N=_(),l=N.lineFitEpsilon,u=t+l;let f=0,c=0,d=!1,O=0,p=0,x=0,A=0,v=-1,I=0,R=0,E=null;function h(){v=-1,I=0,R=0,E=null}function L(m=x,S=A,g=c){f++,n?.(g,O,p,m,S),c=0,d=!1,h()}function b(m,S){d=!0,O=m,p=0,x=m+1,A=0,c=S}function B(m,S,g){d=!0,O=m,p=S,x=m,A=S+1,c=g}function C(m,S){if(!d){b(m,S);return}c+=S,x=m+1,A=0}function W(m,S,g,w,T,P){if(!S)return;const F=te(e,m,g,T),K=ne(e,m,g,T,w);v=g+1,I=c-P+F,R=c-P+K,E=m}function M(m,S){const g=i[m];for(let w=S;wu?(L(),B(m,w,T)):(c=F,x=m,A=w+1)}}d&&x===m&&A===g.length&&(x=m+1,A=0)}function k(m){if(E!=="soft-hyphen")return!1;const S=i[m];if(S==null)return!1;const{fitCount:g,fittedWidth:w}=Qe(S,c,t,l,o,e.letterSpacing);return g===0?!1:(c=w,x=m,A=g,h(),g===S.length?(x=m+1,A=0,!0):(L(m,g,w+o),M(m,g),!0))}function y(m){f++,n?.(0,m.startSegmentIndex,0,m.consumedEndSegmentIndex,0),h()}for(let m=0;m=S.endSegmentIndex));){const w=r[g],T=se(w),P=je(e,d,g),F=w==="tab"?ze(c+P,e.tabStopAdvance):s[g],K=P+F,U=He(e,w,g,P,F);if(w==="soft-hyphen"){d&&(x=g+1,A=0,v=g+1,I=c+o,R=c+o,E=w),g++;continue}if(!d){U>u&&i[g]!==null?M(g,0):b(g,F),W(w,T,g,F,P,K),g++;continue}if(c+U>u){const Z=c+te(e,w,g,P),Ve=c+ne(e,w,g,P,F);if(E==="soft-hyphen"&&N.preferEarlySoftHyphenBreak&&I<=u){L(v,0,R);continue}if(E==="soft-hyphen"&&k(g)){g++;continue}if(T&&Z<=u){C(g,K),L(g+1,0,Ve),g++;continue}if(v>=0&&I<=u){if(x>v||x===v&&A>0){L();continue}const Ee=v;L(Ee,0,R),g=Ee;continue}if(U>u&&i[g]!==null){L(),M(g,0),g++;continue}L();continue}C(g,K),W(w,T,g,F,P,K),g++}if(d){const w=v===S.consumedEndSegmentIndex?R:c;L(S.consumedEndSegmentIndex,0,w)}}return f}function $e(e,t,n,s){const r=e.chunks[n];if(r.startSegmentIndex===r.endSegmentIndex)return t.segmentIndex=r.consumedEndSegmentIndex,t.graphemeIndex=0,0;const{widths:i,kinds:o,breakableFitAdvances:a,discretionaryHyphenWidth:N}=e,l=_(),u=l.lineFitEpsilon,f=s+u;let c=0,d=!1,O=t.segmentIndex,p=t.graphemeIndex,x=-1,A=0,v=0,I=null;function R(){x=-1,A=0,v=0,I=null}function E(M=O,k=p,y=c){return d?(t.segmentIndex=M,t.graphemeIndex=k,y):null}function h(M,k){d=!0,O=M+1,p=0,c=k}function L(M,k,y){d=!0,O=M,p=k+1,c=y}function b(M,k){if(!d){h(M,k);return}c+=k,O=M+1,p=0}function B(M,k,y,m,S,g){if(!k)return;const w=te(e,M,y,S),T=ne(e,M,y,S,m);x=y+1,A=c-g+w,v=c-g+T,I=M}function C(M,k){const y=a[M];for(let m=k;mf)return E();c=w,O=M,p=m+1}}return d&&O===M&&p===y.length&&(O=M+1,p=0),null}function W(M){if(I!=="soft-hyphen"||x<0)return null;const k=a[M]??null;if(k!==null){const{fitCount:y,fittedWidth:m}=Qe(k,c,s,u,N,e.letterSpacing);if(y===k.length)return c=m,O=M+1,p=0,R(),null;if(y>0)return E(M,y,m+N)}return A<=f?E(x,0,v):null}for(let M=t.segmentIndex;M0){const F=C(M,m);if(F!==null)return F}else if(T>f&&a[M]!==null){const F=C(M,0);if(F!==null)return F}else h(M,g);B(k,y,M,g,S,w);continue}if(c+T>f){const F=c+te(e,k,M,S),K=c+ne(e,k,M,S,g);if(I==="soft-hyphen"&&l.preferEarlySoftHyphenBreak&&A<=f)return E(x,0,v);const U=W(M);if(U!==null)return U;if(y&&F<=f)return b(M,w),E(M+1,0,K);if(x>=0&&A<=f)return O>x||O===x&&p>0?E():E(x,0,v);if(T>f&&a[M]!==null){const ue=E();if(ue!==null)return ue;const Z=C(M,0);if(Z!==null)return Z}return E()}b(M,w),B(k,y,M,g,S,w)}return x===r.consumedEndSegmentIndex&&p===0?E(r.consumedEndSegmentIndex,0,v):E(r.consumedEndSegmentIndex,0,c)}function Sn(e,t,n){const{widths:s,kinds:r,breakableFitAdvances:i}=e,a=_().lineFitEpsilon,N=n+a;let l=0,u=!1,f=t.segmentIndex,c=t.graphemeIndex,d=-1,O=0;for(let p=t.segmentIndex;p0||R>N&&I!==null){const E=I,h=E[v];u=!0,l=h,f=p,c=v+1;for(let L=v+1;LN)return t.segmentIndex=f,t.graphemeIndex=c,l;l+=b,f=p,c=L+1}f===p&&c===E.length&&(f=p+1,c=0)}else u=!0,l=R,f=p+1,c=0;A&&(d=p+1,O=l-R);continue}if(l+R>N)return A?(t.segmentIndex=p+1,t.graphemeIndex=0,l):d>=0?f>d||f===d&&c>0?(t.segmentIndex=f,t.graphemeIndex=c,l):(t.segmentIndex=d,t.graphemeIndex=0,O):(t.segmentIndex=f,t.graphemeIndex=c,l);l+=R,f=p+1,c=0,A&&(d=p+1,O=l-R)}return u?(t.segmentIndex=f,t.graphemeIndex=c,l):null}function Oe(e,t,n){const s=me(e,t);return s<0?null:e.simpleLineWalkFastPath?Sn(e,t,n):$e(e,t,s,n)}function hn(e,t){if(e.widths.length===0)return{lineCount:0,maxLineWidth:0};const n={segmentIndex:0,graphemeIndex:0};let s=0,r=0;if(!e.simpleLineWalkFastPath){let i=me(e,n);for(;i>=0;){const o=$e(e,n,i,t);if(o===null)return{lineCount:s,maxLineWidth:r};s++,o>r&&(r=o),i=Nn(e,i,n)}return{lineCount:s,maxLineWidth:r}}for(;;){const i=Oe(e,n,t);if(i===null)return{lineCount:s,maxLineWidth:r};s++,i>r&&(r=i)}}let V=null,Se=new WeakMap;function dn(){return V===null&&(V=new Intl.Segmenter(void 0,{granularity:"grapheme"})),V}function ye(e,t,n){let s=n.get(e);if(s!==void 0)return s;s=[];const r=dn();for(const i of r.segment(t[e]))s.push(i.segment);return n.set(e,s),s}function Mn(e,t,n,s){return s>0&&e[s-1]==="soft-hyphen"&&!(t===s&&n>0)}function ve(e,t,n,s){for(let r=n;r0){const l=ye(N,e.segments,t);o=ve(o,l,s,l.length)}else o+=e.segments[N];if(i>0){a&&(o+="-");const N=ye(r,e.segments,t);o=ve(o,N,n===r?s:0,i)}else a&&(o+="-");return o}function pn(){V=null,Se=new WeakMap}let Y=null;function qe(){return Y===null&&(Y=new Intl.Segmenter(void 0,{granularity:"grapheme"})),Y}function Ln(e){return e?{widths:[],lineEndFitAdvances:[],lineEndPaintAdvances:[],kinds:[],simpleLineWalkFastPath:!0,segLevels:null,breakableFitAdvances:[],letterSpacing:0,spacingGraphemeCounts:[],discretionaryHyphenWidth:0,tabStopAdvance:0,chunks:[],segments:[]}:{widths:[],lineEndFitAdvances:[],lineEndPaintAdvances:[],kinds:[],simpleLineWalkFastPath:!0,segLevels:null,breakableFitAdvances:[],letterSpacing:0,spacingGraphemeCounts:[],discretionaryHyphenWidth:0,tabStopAdvance:0,chunks:[]}}function mn(e,t){const n=[];let s=[],r=0,i=!1,o=!1,a=!1;function N(){s.length!==0&&(n.push({text:s.length===1?s[0]:s.join(""),start:r}),s=[],i=!1,o=!1,a=!1)}function l(f,c,d){s=[f],r=c,i=d,o=ce(f),a=re.has(f)}function u(f,c){s.push(f),i=i||c;const d=ce(f);f.length===1&&J.has(f)?o=o||d:o=d,a=!1}for(const f of qe().segment(e)){const c=f.segment,d=j(c);if(s.length===0){l(c,f.index,d);continue}if(a||he.has(c)||J.has(c)||t.carryCJKAfterClosingQuote&&d&&o){u(c,d);continue}if(!i&&!d){u(c,d);continue}N(),l(c,f.index,d)}return N(),n}function On(e,t,n){if(t.length<=1)return t;const s=[];let r=-1,i=!1;function o(N,l){const u=t[N].start,f=l=0&&!Te(t[N-1].text,n)&&a(N),r<0&&(r=N),i=i||j(l.text)}return a(t.length),s}function Re(e,t){if(t==="zero-width-break"||t==="soft-hyphen"||t==="hard-break")return 0;if(t==="tab")return 1;let n=0;const s=qe();for(const r of s.segment(e))n++;return n}function kn(e,t,n){return t>1?e+(t-1)*n:e}function xn(e,t,n,s,r){const i=_(),{cache:o,emojiCorrection:a}=sn(t,Yt(e.normalized)),N=H("-",z("-",o),a)+(r===0?0:r),u=H(" ",z(" ",o),a)*8,f=r!==0;if(e.len===0)return Ln(n);const c=[],d=[],O=[],p=[];let x=e.chunks.length<=1&&!f;const A=n?[]:null,v=[],I=[],R=n?[]:null,E=Array.from({length:e.len});function h(C,W,M,k,y,m,S,g){y!=="text"&&y!=="space"&&y!=="zero-width-break"&&(x=!1),c.push(W),d.push(M),O.push(k),p.push(y),A?.push(m),v.push(S),f&&I.push(g),R!==null&&R.push(C)}function L(C,W,M,k,y){const m=z(C,o),S=f?Re(C,W):0,g=kn(H(C,m,a),S,r),w=W==="space"||W==="preserved-space"||W==="zero-width-break"?0:g,T=w===0?0:w+(S>0?r:0),P=W==="space"||W==="zero-width-break"?0:g;if(y&&k&&C.length>1){let F="sum-graphemes";r!==0?F="segment-prefixes":ee(C)?F="pair-context":i.preferPrefixWidthsForBreakableRuns&&(F="segment-prefixes");const K=rn(C,m,o,a,F);h(C,g,T,P,W,M,K,S);return}h(C,g,T,P,W,M,null,S)}for(let C=0;C{n(Xe(s,r,i,o,a))})}function In(e,t){return hn(e,t)}function yn(e){let t=0;return le(e,Number.POSITIVE_INFINITY,n=>{n>t&&(t=n)}),t}function vn(e,t,n){const s=e,r=_e(s,t);if(r===null)return null;const i={segmentIndex:r.segmentIndex,graphemeIndex:r.graphemeIndex},o=Oe(s,i,n);return o===null?null:xe(e,ke(e),o,r.segmentIndex,r.graphemeIndex,i.segmentIndex,i.graphemeIndex)}function Rn(e,t,n){const s=e,r=_e(s,t);if(r===null)return null;const i={segmentIndex:r.segmentIndex,graphemeIndex:r.graphemeIndex},o=Oe(s,i,n);return o===null?null:Xe(o,r.segmentIndex,r.graphemeIndex,i.segmentIndex,i.graphemeIndex)}function Fn(e,t,n){const s=[];if(e.widths.length===0)return{lineCount:0,height:0,lines:s};const r=ke(e),i=le(e,t,(o,a,N,l,u)=>{s.push(xe(e,r,o,a,N,l,u))});return{lineCount:i,height:i*n,lines:s}}function Cn(){ct(),Y=null,pn(),ln()}function Tn(e){Nt(e),Cn()}export{Cn as clearCache,bn as layout,vn as layoutNextLine,Rn as layoutNextLineRange,Fn as layoutWithLines,Wn as materializeLineRange,In as measureLineStats,yn as measureNaturalWidth,An as prepare,Bn as prepareWithSegments,Tn as setLocale,wn as walkLineRanges}; diff --git a/site/index.html b/site/index.html new file mode 100644 index 0000000000000000000000000000000000000000..9e8cc742c8a86e5f27fc630e76a70940f4487c9c --- /dev/null +++ b/site/index.html @@ -0,0 +1,34 @@ + + + + + + + + DriftCall — Voice Concierge under Schema Drift + + + + + + + + + + + + + + + + +
+ + diff --git a/unified_app.py b/unified_app.py new file mode 100644 index 0000000000000000000000000000000000000000..3fd75862ffdccd916f43d4ccb0ea3ab5fcac014a --- /dev/null +++ b/unified_app.py @@ -0,0 +1,62 @@ +"""Unified DriftCall Space — single FastAPI ASGI app combining: + +- canonical OpenEnv routes at root (/reset, /step, /state, /close, /healthz) + imported as-is from app.py so the env behaviour matches the standalone + env Space byte-for-byte. +- the project frontend (Vite-built dist/) served as static files at /, + with a SPA fallback so deep links work. +- a /demo redirect to the dedicated Gradio demo Space (kept separate + because it's GPU-heavy and benefits from independent scaling). + +This file lives only inside the unified Space build dir; the canonical +sources at the repo root are unchanged. +""" + +from __future__ import annotations + +from pathlib import Path +from typing import Any + +from fastapi import FastAPI +from fastapi.responses import FileResponse, RedirectResponse +from fastapi.staticfiles import StaticFiles + +# Reuse the canonical OpenEnv FastAPI app — same router, same auth, same +# error envelope, same session pool. We just wrap it to add the static +# mount and the /demo redirect. +from app import app as openenv_app # type: ignore[import-not-found] + +DEMO_SPACE_URL = "https://dgxai-driftcall-demo.hf.space" +SITE_DIR = Path(__file__).parent / "site" + + +def build_unified_app() -> FastAPI: + # The canonical app already has all OpenEnv routes registered. We + # extend it rather than wrap, so route ordering + middleware all + # apply unchanged to /reset, /step, /state, /close, /healthz. + app: FastAPI = openenv_app + + @app.get("/demo", include_in_schema=False) + async def demo_redirect() -> RedirectResponse: + return RedirectResponse(url=DEMO_SPACE_URL, status_code=302) + + @app.get("/openenv.yaml", include_in_schema=False) + async def serve_manifest() -> Any: + manifest = Path(__file__).parent / "openenv.yaml" + if manifest.exists(): + return FileResponse(manifest, media_type="text/yaml") + return {"error": "openenv.yaml not found"} + + # SPA static mount — must come LAST so OpenEnv routes (/reset, /step, + # /state, /close, /healthz) take precedence over a same-named asset. + if SITE_DIR.exists(): + app.mount( + "/", + StaticFiles(directory=SITE_DIR, html=True), + name="frontend", + ) + + return app + + +app = build_unified_app()