"""Whether the three model stages of a pull, `extract`, `summarise` and `judge`, and the `enrich` stage run. `extract.enabled`, `summarise.enabled` and `judge.enabled` in config.yaml are read at startup and say nothing on the page, so the switch lives in the database as well: the `state` keys `stage:extract`, `stage:summarise` and `stage:judge`, "on" or "off". A stored value beats the file; with none, the file applies, so config.yaml is the default for a fresh database and a deployment that never uses the switch behaves as it did. `stage_on` is the one place that decides, and the tasks' finders ask it (`extract.extract_task`, `summarise.summarise_task`, `judge.judge_task`). `enrich` (reading the best roles on their own pages, `app/jobs/enrich.py`) asks no model and is on by default (`enrich.enabled`); its switch is `stage:enrich`, set the same way as the others: by the Runs page (`PUT /api/stages/enrich`) and by `app stages enrich on|off`. `describe` is what `GET /api/stages` and `app stages` show: for each stage with a switch, the model stages and `enrich`, whether it is on, where that comes from, the model it uses, and who would answer. The model is the one a call is made with: `agent.model` when set, since it overrides the per-task model everywhere (`desk/modeltask.py`), else the stage's own. """ from __future__ import annotations from typing import Literal from pydantic import BaseModel from app.config import Config from app.storage import Store from desk.tools import agent NAMES = ("extract", "summarise", "judge") #: Every stage with a switch: the model stages and `enrich`. SWITCHES = (*NAMES, "enrich") #: What `describe_one` says of a stage that asks no model. NO_ASK = "reads role pages, asks no model" NO_MODEL = ("no model is reachable: set ANTHROPIC_API_KEY or CLAUDE_CODE_OAUTH_TOKEN, " "see docs/llm-backends.md") ANSWERS = { "api": "answered by the Claude API", "claude_code": "answered by the Claude Code sign-in on this machine", } class Stage(BaseModel): """One stage as the page shows it. `source` is "stored" when the switch set it and "config" when it is still config.yaml's default. `backend` is `agent.backend`'s answer, "" for nobody, and `answer` says it in words.""" name: Literal["extract", "summarise", "judge", "enrich"] on: bool source: Literal["stored", "config"] model: str backend: str answer: str def _key(name: str) -> str: return f"stage:{name}" def stored(store: Store, name: str) -> bool | None: """The switch's value, or None while nobody has used it.""" value = store.state.get(_key(name)) return {"on": True, "off": False}.get(value or "") def stage_on(config: Config, store: Store, name: str) -> bool: """Whether stage `name` runs: the stored setting, else config.yaml's.""" value = stored(store, name) return getattr(config, name).enabled if value is None else value def set_stage(store: Store, name: str, on: bool) -> None: """Store the switch. A `KeyError` for a name that is not a stage.""" if name not in SWITCHES: raise KeyError(name) store.state[_key(name)] = "on" if on else "off" def answer(config: Config) -> tuple[str, str]: """Who would answer a model call, as `(backend, sentence)`.""" backend = agent.backend(config.agent) if backend: return backend, ANSWERS.get(backend, f"answered by {backend}") if config.agent.backend == "off": return "", "no model is reachable: `agent.backend` is `off` in config.yaml" return "", NO_MODEL def describe_one(config: Config, store: Store, name: str) -> Stage: if name not in NAMES: return Stage(name=name, on=stage_on(config, store, name), source="config" if stored(store, name) is None else "stored", model="", backend="", answer=NO_ASK) backend, said = answer(config) return Stage(name=name, on=stage_on(config, store, name), source="config" if stored(store, name) is None else "stored", model=config.agent.model or getattr(config, name).model, backend=backend, answer=said) def describe(config: Config, store: Store) -> list[Stage]: return [describe_one(config, store, name) for name in SWITCHES]