"""Config loading: one YAML file, validated into a model. The boilerplate's shape with roledesk's keys. A typo in a key is an error naming the key, because every section forbids extras: a setting you believe you have changed and have not is the expensive kind of typo. `sources` stays a dict: one block per plugin, whose keys only the plugin knows. The path comes from `app --config`, else `APP_CONFIG`, else `config.yaml` beside the checkout. The Dockerfile sets `APP_CONFIG=/data/config.yaml`. **A missing file is not an error.** Every field has a default that runs, so `uv run app serve` works on a fresh clone. The committed `config.yaml` adds the starter agents; `config.example.yaml` documents every key. """ from __future__ import annotations import os import sys from pathlib import Path from typing import Any import yaml from pydantic import Field, ValidationError, field_validator, model_validator from app.models import Gate, Limits, Prompts, Weights from auth import AuthConfig from desk.config import AgentConfig, ModelTaskConfig, Section, WorkersConfig #: Where `load()` looks when nobody says. Read at import so a test can set the #: variable first, and `app --config` overrides it after. DEFAULT_PATH = Path(os.environ.get("APP_CONFIG", "config.yaml")) class ServerConfig(Section): """Where uvicorn binds. Anything but a loopback address makes `auth.enabled: auto` lock the app.""" host: str = "127.0.0.1" port: int = 8790 class ExtractConfig(ModelTaskConfig): """Turning a posting's title and text into the gate columns. See app/jobs/extract.py. Off by default, so nobody is billed by surprise: on the API backend every batch is a paid call. On, it reads only the roles in the cut of an enabled agent (`app.jobs.score`), so the cost follows the agents rather than the boards.""" enabled: bool = False model: str = "claude-haiku-4-5-20251001" batch_size: int = Field(20, ge=1) class SummariseConfig(ModelTaskConfig): """About 60 words on a role, for the list and the read page. See app/jobs/summarise.py. Off by default like extract; on, a pull summarises the top `summarise_top` (its `limits`) of each enabled agent's want order and of its match order, so the cost is bounded whatever the backlog, and every role that is saved or liked, whatever its rank. The read page's Summarise button asks for one role whether this is on or not.""" enabled: bool = False model: str = "claude-haiku-4-5-20251001" #: A description is capped at 8000 characters per role, so ten is about #: 20k tokens of input per call. batch_size: int = Field(10, ge=1) class JudgeConfig(ModelTaskConfig): """Each search agent's cut read against its CV, as three numbers and a total. See app/jobs/judge.py. Off by default like extract; on, a pull judges the cut of each enabled agent with a CV and a prompt, and only the roles whose judgement is missing or was read from another CV or text.""" enabled: bool = False model: str = "claude-haiku-4-5-20251001" #: A posting is capped at 8000 characters and the CV rides in the system #: prompt of every call, so batches stay small. batch_size: int = Field(5, ge=1) class FetchTextConfig(Section): """Reading roles on their own pages after scoring, for the hosts whose list carries no text. See app/jobs/fetch_text.py. A role is read when it has no text and is in the cut of an enabled agent (`app.jobs.score`), so every role the model reads has its text first.""" enabled: bool = True #: Reads per board and per run. Per board is the cap the pull had; the #: boards are read in parallel on the `http` pool. per_board: int = Field(200, ge=0) per_run: int = Field(1000, ge=0) #: Days before a page that gave no text is read again. retry_days: int = Field(7, ge=1) class Calibration(Section): """Where one embedding model's cosines sit, as `(lo, hi)` for fit, for taste and for a role's closeness to a CV (`cv`, fit's when not given): `score.scale` maps `lo` to 0 and `hi` to 1 and clips outside, so a term is a level rather than a rank within the run.""" fit: tuple[float, float] taste: tuple[float, float] cv: tuple[float, float] | None = None @field_validator("fit", "taste", "cv") @classmethod def _lo_below_hi(cls, band: tuple[float, float] | None) -> tuple[float, float] | None: if band is None: return band lo, hi = band if not -1 <= lo < hi <= 1: raise ValueError(f"needs -1 <= lo < hi <= 1, got [{lo}, {hi}]") return band @property def cv_band(self) -> tuple[float, float]: """The band `cv_fit` is scaled with: `cv`, else fit's.""" return self.cv or self.fit #: The built-in calibration, by embedding model. Measured on a copy of the #: live database, 16,841 open roles (see docs/decisions.md). fit: pooled over #: five intents the raw cosine has p1 0.753 and p99.9 0.871; hi sits above #: every single intent's p99.9, so only about 5 of the starter agent's 4,156 #: ungated roles clip to 1. taste: from synthetic votes, 30 liked and 30 #: passed roles for each of three intents, since the copy had none (pooled p1 #: -0.140, p99.9 0.192); re-measure it once real votes exist. cv: the best #: cosine over the chunks of the one CV in the copy of 2026-10-03, over that #: agent's 7,270 ungated roles: p1 0.770, median 0.832, p99.9 0.891, max #: 0.902. A CV chunk is a longer text than a prompt and sits closer to every #: posting, so fit's band clipped 88 of them to 1 and the 50 closest tied; #: with this one, 1 clips. Re-measure it once more agents hold a CV. CALIBRATION: dict[str, Calibration] = { "intfloat/multilingual-e5-small": Calibration(fit=(0.75, 0.88), taste=(-0.14, 0.19), cv=(0.77, 0.90)), } class EmbedConfig(Section): """Turning a role into a vector for `fit`. Needs sentence-transformers; without it `embed` says so and does nothing, and `score` leaves fit out. See app/jobs/embed.py. `intfloat/multilingual-e5-small`, not the English-only `sentence-transformers/all-MiniLM-L6-v2` roledesk started with: measured on the live roles against the "Copenhagen engineering" agent's intent, MiniLM separates engineering from non-engineering roles with an AUC of 0.68 (0.74 restricted to Danish-country roles), multilingual-e5-small with an AUC of 0.70 (1.00 restricted to Danish-country roles), for about 3x the CPU time. See docs/decisions.md. """ #: Recorded on every vector. Changing it drops the old vectors, which are #: a different geometry and never comparable. An e5 model needs its #: "query: " / "passage: " prefixes, which app/jobs/embed.py adds by #: matching this name, not a separate setting. model: str = "intfloat/multilingual-e5-small" #: Roles embedded per run at most, newest first. per_run: int = Field(50_000, ge=1) #: `{model: {fit: [lo, hi], taste: [lo, hi]}}`, over `CALIBRATION`: an #: entry replaces the built-in one for that model. Keyed by model, so a #: change of `model` cannot carry another geometry's constants along. A #: model with neither is min-max scaled per run, with a warning in the log. calibration: dict[str, Calibration] = Field(default_factory=dict) def calibrated(self) -> Calibration | None: """The configured model's calibration, or None when it has none.""" return self.calibration.get(self.model) or CALIBRATION.get(self.model) class AgentSeed(Section): """A search agent as `config.yaml` lists it. Imported into an empty `agents` table once; after that the table is the answer. `prompts` is a list of `{name, text}`; without it, `intent` is the one prompt, named after the agent.""" name: str prompts: Prompts | None = None intent: str = "" gates: list[Gate] = Field(default_factory=list) weights: Weights = Field(default_factory=Weights) limits: Limits = Field(default_factory=Limits) enabled: bool = True class SearchSeed(Section): """A saved search as `config.yaml` lists it: one `search` subscription, imported once like the agents. `params` are the provider's own, see plugins/search.py: `q`, `area` and `pages` for jobindex; `q`, `country`, `where` and `pages` for adzuna; `q` and `region` for platsbanken; `q`, `country` and `remote` for freehire; `q` and `region` for jobnet; `q`, `region` and `remote` for jobbank. The provider is any reader of `scope="search"`, so a new one needs no edit here.""" name: str provider: str params: dict[str, Any] = Field(default_factory=dict) @field_validator("provider") @classmethod def _a_search_provider(cls, provider: str) -> str: # `plugins` is a top-level folder beside `app` and is not on the path # when this module is imported first, so it is reached the way # `app.models` reaches it (`_declared_posted`), and only when a seed # is validated. root = str(Path(__file__).resolve().parents[1]) if root not in sys.path: sys.path.insert(0, root) from plugins.readers import PROVIDERS if provider not in PROVIDERS: raise ValueError(f"provider is one of {', '.join(PROVIDERS)}, not {provider!r}") return provider class Config(Section): """The whole file.""" server: ServerConfig = Field(default_factory=ServerConfig) #: One SQLite file for the lot: roles and companies, the jobs table, the #: notice log, the schedules, and auth's `auth_*` tables. One file is one #: thing to back up. database: Path = Path("roledesk.db") #: What a clock on screen means, and what a `daily at 06:00` schedule is #: 06:00 in. `every 6h` is six elapsed hours in any zone. timezone: str = "Europe/Berlin" log_level: str = "INFO" #: The door, auth's own model. See auth/README.md. auth: AuthConfig = Field(default_factory=AuthConfig) #: Directories searched for `Source` plugins. A plugin imports `desk` only. plugin_paths: list[str] = Field(default_factory=lambda: ["plugins"]) #: Workers per resource class. `http` is wide because a fetch is mostly waiting. workers: WorkersConfig = Field(default_factory=WorkersConfig) #: Who answers when a job needs a model. See desk/tools/agent.py. agent: AgentConfig = Field(default_factory=AgentConfig) extract: ExtractConfig = Field(default_factory=ExtractConfig) summarise: SummariseConfig = Field(default_factory=SummariseConfig) judge: JudgeConfig = Field(default_factory=JudgeConfig) embed: EmbedConfig = Field(default_factory=EmbedConfig) fetch_text: FetchTextConfig = Field(default_factory=FetchTextConfig) #: Starter agents, imported once into an empty table. agents: list[AgentSeed] = Field(default_factory=list) #: Starter searches, imported once into an empty set of `search` #: subscriptions. searches: list[SearchSeed] = Field(default_factory=list) #: One block per plugin: `enabled`, and whatever that plugin reads. sources: dict[str, Any] = Field(default_factory=dict) #: Where this came from, or None for the defaults. Never written back. path: Path | None = Field(default=None, exclude=True) @model_validator(mode="after") def _credentials_live_in_the_database(self) -> Config: """`desk.tools.agent` reads a stored token from the app's database.""" self.agent.credentials_database = str(self.database) return self class ConfigError(ValueError): """A config file that exists but does not validate. The message names every bad key, for the CLI to print as it is.""" def load(path: str | os.PathLike[str] | None = None) -> Config: """Read the YAML file into a `Config`, or return the defaults. An empty file is the same as no file. A file that is not a mapping, or that does not validate, is a `ConfigError`. """ where = Path(path).expanduser() if path else DEFAULT_PATH if not where.exists(): return Config() raw: Any = yaml.safe_load(where.read_text(encoding="utf-8")) if raw is None: return Config(path=where) if not isinstance(raw, dict): raise ConfigError(f"{where}: expected a mapping of settings, " f"got {type(raw).__name__}") try: return Config(**raw, path=where) except ValidationError as exc: raise ConfigError(f"{where}:\n{_explain(exc)}") from None def _explain(exc: ValidationError) -> str: lines = [] for err in exc.errors(): where = ".".join(str(p) for p in err["loc"]) or "(top level)" detail = err["msg"] if err["type"] == "extra_forbidden": detail = "unknown setting, check the spelling against config.example.yaml" lines.append(f" {where}: {detail}") return "\n".join(lines)