modelroom 0.1.0__py3-none-any.whl

modelroom/__init__.py

@@ -0,0 +1,9 @@
+"""modelroom: which local model packages exist for your model families, and which fit your machine."""
+
+from importlib.metadata import version
+
+# The only version source is [project] version in pyproject.toml; the package has to be
+# installed (uv sync) for this to resolve, which is also how the tests run.
+__version__ = version("modelroom")
+
+__all__ = ["__version__"]

modelroom/answers.py

@@ -0,0 +1,55 @@
+"""The answer file: `modelroom --answers <file>` takes the dialog's answers from TOML.
+
+One key per question, as CONTRACTS.md, "Guided mode", lists them; `schema_version = 1` on top.
+A question the file has no answer for ends the run with exit `2` and names the question, so a
+self-test or a CI run never silently answers something it did not mean to
+(`dialog.FileAsker`). Nothing else about the guided mode changes: the same steps run in the
+same order and print the same lines.
+"""
+
+from __future__ import annotations
+
+import tomllib
+from pathlib import Path
+
+from .contracts import SchemaVersionError, check_schema_version
+
+ANSWERS_SCHEMA_VERSION = 1
+# Half-open, same convention as every other reader in this package.
+ANSWERS_SCHEMA_RANGE: tuple[int, int] = (1, 2)
+
+
+class AnswerFileError(Exception):
+    """The answer file does not read, or one of its answers is not a shape a question can take."""
+
+
+def _is_answer(value: object) -> bool:
+    """The four shapes a question's answer can have: text, a choice, a switch, a list of choices."""
+    if isinstance(value, bool) or isinstance(value, str):
+        return True
+    if isinstance(value, int):
+        return True
+    return isinstance(value, list) and all(isinstance(entry, str) for entry in value)
+
+
+def read_answers(path: Path) -> dict[str, object]:
+    """Every answer in the file at `path`, by question key; `schema_version` is not an answer.
+
+    Raises `AnswerFileError` when the file cannot be read or holds an answer of another shape,
+    and `SchemaVersionError` when its `schema_version` is missing or outside the accepted range.
+    """
+    try:
+        raw = tomllib.loads(path.read_text(encoding="utf-8"))
+    except (OSError, tomllib.TOMLDecodeError, UnicodeDecodeError) as exc:
+        raise AnswerFileError(f"{path}: cannot read the answer file: {exc}") from exc
+    version = raw.get("schema_version")
+    if not isinstance(version, int) or isinstance(version, bool):
+        raise SchemaVersionError(f"{path}: schema_version is missing or not an integer: {version!r}")
+    check_schema_version(version, ANSWERS_SCHEMA_RANGE, str(path))
+    answers = {key: value for key, value in raw.items() if key != "schema_version"}
+    for key, value in answers.items():
+        if not _is_answer(value):
+            raise AnswerFileError(
+                f"{path}: the answer {key!r} is not text, a whole number, true/false or a list of texts"
+            )
+    return answers

modelroom/binding.py

@@ -0,0 +1,209 @@
+"""Which profile is "this machine": the pointer file in the home folder and the takeover rule.
+
+The pointer file (`~/.modelroom/guided.json`) remembers the results folder the guided mode
+last used and, per results folder, the `profile_id` of this machine's own profile there (the
+local binding). `resolve_profile_target` decides, without any I/O, which profile a measurement
+of this machine writes to (CONTRACTS.md, "Profile binding").
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Literal
+
+from pydantic import BaseModel, ConfigDict, Field, ValidationError, field_validator, model_validator
+
+from .contracts import PROFILE_ID_RE, SchemaVersionError, check_schema_version
+from .state import atomic_write_json
+
+POINTER_SCHEMA_VERSION = 1
+POINTER_SCHEMA_RANGE: tuple[int, int] = (1, 2)
+
+
+class PointerFileError(Exception):
+    """The pointer file exists but is not valid JSON or does not match `GuidedPointer`."""
+
+
+def default_pointer_path() -> Path:
+    """`~/.modelroom/guided.json` of the current user."""
+    return Path.home() / ".modelroom" / "guided.json"
+
+
+class GuidedPointer(BaseModel):
+    """The pointer file: last results folder and, per results folder, this machine's profile.
+
+    Keys of `bindings` and `current` are absolute folder paths as the guided mode resolved them.
+    """
+
+    model_config = ConfigDict(extra="forbid")
+
+    schema_version: int
+    current: str | None = None
+    bindings: dict[str, str] = Field(default_factory=dict)
+
+    @field_validator("bindings")
+    @classmethod
+    def _check_bindings(cls, value: dict[str, str]) -> dict[str, str]:
+        for folder, profile_id in value.items():
+            if not Path(folder).is_absolute():
+                raise ValueError(f"bindings keys are absolute results folders: {folder!r}")
+            if not PROFILE_ID_RE.fullmatch(profile_id):
+                raise ValueError(f"bindings values are profile_ids of 16 lowercase hex characters: {profile_id!r}")
+        return value
+
+    @field_validator("current")
+    @classmethod
+    def _check_current(cls, value: str | None) -> str | None:
+        if value is not None and not Path(value).is_absolute():
+            raise ValueError(f"current must be an absolute results folder: {value!r}")
+        return value
+
+    @model_validator(mode="after")
+    def _check_schema_version(self) -> "GuidedPointer":
+        if self.schema_version != POINTER_SCHEMA_VERSION:
+            raise ValueError(f"schema_version must be {POINTER_SCHEMA_VERSION}, got {self.schema_version}")
+        return self
+
+    def binding_for(self, results_dir: Path) -> str | None:
+        return self.bindings.get(str(results_dir))
+
+    def with_binding(self, results_dir: Path, profile_id: str) -> "GuidedPointer":
+        """A copy that binds `profile_id` to `results_dir` and makes it the current folder."""
+        return GuidedPointer.model_validate(
+            {
+                "schema_version": POINTER_SCHEMA_VERSION,
+                "current": str(results_dir),
+                "bindings": {**self.bindings, str(results_dir): profile_id},
+            }
+        )
+
+    def with_current(self, results_dir: Path) -> "GuidedPointer":
+        """A copy whose `current` is `results_dir`; the bindings stay as they are.
+
+        The guided mode remembers the folder it wrote a configuration in before anything has
+        been measured there, so the next run finds it without asking again; the binding follows
+        only when a measurement really produced a profile (`with_binding`).
+        """
+        return GuidedPointer.model_validate(
+            {
+                "schema_version": POINTER_SCHEMA_VERSION,
+                "current": str(results_dir),
+                "bindings": dict(self.bindings),
+            }
+        )
+
+
+def read_pointer(path: Path) -> GuidedPointer:
+    """The pointer file at `path`; an empty pointer when it does not exist yet.
+
+    A version outside the accepted range raises `SchemaVersionError`; broken content raises
+    `PointerFileError` naming the file.
+    """
+    if not path.exists():
+        return GuidedPointer(schema_version=POINTER_SCHEMA_VERSION)
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, ValueError) as exc:  # ValueError: bad UTF-8/JSON and over-long integers
+        raise PointerFileError(f"{path}: cannot read pointer file: {exc}") from exc
+    if not isinstance(data, dict):
+        raise PointerFileError(f"{path}: expected a JSON object at the root")
+    version = data.get("schema_version")
+    if not isinstance(version, int) or isinstance(version, bool):
+        raise SchemaVersionError(f"{path}: schema_version is missing or not an integer: {version!r}")
+    check_schema_version(version, POINTER_SCHEMA_RANGE, str(path))
+    try:
+        return GuidedPointer.model_validate(data)
+    except ValidationError as exc:
+        raise PointerFileError(f"{path}: invalid pointer file: {exc}") from exc
+
+
+def write_pointer(path: Path, pointer: GuidedPointer) -> None:
+    """Replace the pointer file atomically (it belongs to one user; no shared lock needed)."""
+    atomic_write_json(path, pointer.model_dump(mode="json"))
+
+
+@dataclass(frozen=True)
+class KnownProfile:
+    """What the takeover rule needs to know about a profile file in the results folder."""
+
+    profile_id: str
+    os_fingerprint: str
+
+
+@dataclass(frozen=True)
+class ProfileTarget:
+    """The decision: which profile a measurement of this machine goes to, and why.
+
+    `bound` -- the home binding holds; `adopt_config` -- `[machines.<name>].profile` becomes the
+    binding (no new profile); `new` -- a new profile, bound and written to the configuration;
+    `rewrite` -- that missing or foreign profile is measured again under its own id, because the
+    answer was "the same machine"; `ask_clone` -- the bound or configured profile is missing or
+    its fingerprint differs: the guided mode asks "same machine or a clone?", automation stops
+    and points to `hardware --same-machine` and `hardware --new-identity`.
+    """
+
+    action: Literal["bound", "adopt_config", "new", "rewrite", "ask_clone"]
+    profile_id: str
+    reason: str
+
+
+def _fingerprints_agree(known: KnownProfile, local_fingerprint: str) -> bool:
+    # A profile without a fingerprint (migrated, or unreadable on its machine) cannot disagree.
+    return "none" in (known.os_fingerprint, local_fingerprint) or known.os_fingerprint == local_fingerprint
+
+
+def resolve_profile_target(
+    home_binding: str | None,
+    config_profile: str | None,
+    profiles: dict[str, KnownProfile],
+    local_fingerprint: str,
+    fresh_profile_id: str,
+    new_identity: bool = False,
+    same_machine: bool = False,
+) -> ProfileTarget:
+    """Pick the profile "this machine" writes to, in the order of the takeover rule.
+
+    (0) `new_identity` (`hardware --new-identity`, or "a clone" in the guided mode): a new
+    profile, replacing the binding. (1) The home binding for this results folder. (2) Else the
+    selected configuration machine's `profile`, adopted as the binding. (3) Else a new profile.
+    A binding or configured profile that is missing from `profiles` (the profile files found in
+    the results folder), or whose `os_fingerprint` differs from `local_fingerprint`, is
+    `ask_clone`. `local_fingerprint` is `none` when this machine's OS identifier is unreadable.
+
+    `same_machine` (`hardware --same-machine`, or "the same machine" in the guided mode) is the
+    answer to exactly that question: the `ask_clone` case becomes `rewrite`, a measurement under
+    the very id the binding names, so a results folder someone emptied is measured into again
+    (decided 2026-09-24). It changes nothing where the rule does not ask. The two switches are
+    two answers to one question and are never both given.
+    """
+    if new_identity and same_machine:
+        raise ValueError("new_identity and same_machine are two answers to one question; pass one of them")
+    if not PROFILE_ID_RE.fullmatch(fresh_profile_id) or fresh_profile_id in profiles:
+        raise ValueError(f"fresh_profile_id must be a new profile_id: {fresh_profile_id!r}")
+    if new_identity:
+        return ProfileTarget("new", fresh_profile_id, "new identity requested")
+    for candidate, action, source in (
+        (home_binding, "bound", "home binding"),
+        (config_profile, "adopt_config", "configuration"),
+    ):
+        if candidate is None:
+            continue
+        known = profiles.get(candidate)
+        if known is None:
+            missing = f"profile from {source} is missing in the results folder"
+            if same_machine:
+                return ProfileTarget("rewrite", candidate, f"{missing}; measured again under the same id")
+            return ProfileTarget("ask_clone", candidate, missing)
+        if not _fingerprints_agree(known, local_fingerprint):
+            differs = f"profile from {source} has another os_fingerprint"
+            if same_machine:
+                return ProfileTarget(
+                    "rewrite",
+                    candidate,
+                    f"{differs}; measured again under the same id, the answer was that it is the same machine",
+                )
+            return ProfileTarget("ask_clone", candidate, differs)
+        return ProfileTarget(action, candidate, f"profile from {source}")
+    return ProfileTarget("new", fresh_profile_id, "no binding and no configured profile")

modelroom/catalog.py

@@ -0,0 +1,185 @@
+"""The shipped catalog (`catalog.toml`): publishers, current models, successors, Ollama names.
+
+The search uses it to tell a publisher from a packager, to call a model `latest` or `legacy`
+when the repo itself says nothing (`new_version`), and to know an Ollama name. Every model row
+names its evidence; nothing in it is inferred (CONTRACTS.md, "Catalog rules").
+"""
+
+from __future__ import annotations
+
+import tomllib
+from datetime import date
+from pathlib import Path
+from typing import Literal
+from urllib.parse import urlsplit
+
+from pydantic import BaseModel, ConfigDict, Field, ValidationError, field_validator, model_validator
+
+from .contracts import SchemaVersionError, check_schema_version, validate_hf_repo, validate_ollama_pair
+
+CATALOG_FILE = Path(__file__).with_name("catalog.toml")
+CATALOG_SCHEMA_VERSION = 1
+CATALOG_SCHEMA_RANGE: tuple[int, int] = (1, 2)
+
+Age = Literal["latest", "legacy", "unknown"]
+_HUB = "https://huggingface.co/"
+# `urlsplit(...).hostname` is lowercase and without the port.
+_HUB_HOSTS = frozenset({"huggingface.co", "www.huggingface.co", "hf.co"})
+
+
+class CatalogError(Exception):
+    """The catalog file cannot be read or does not validate."""
+
+
+class CatalogModel(BaseModel):
+    """One publisher base model: current (`latest`), superseded (`successor`), or neither.
+
+    `latest` is a statement about this one model, never derived from a line or a number: it
+    carries the publisher page or collection that says so (`latest_source`) and the day the
+    maintainer checked it (`latest_checked`). Without them the model's age is `unknown`.
+    """
+
+    model_config = ConfigDict(extra="forbid")
+
+    hf_repo: str
+    latest: bool = False
+    latest_source: str | None = None
+    latest_checked: date | None = None
+    successor: str | None = None
+    ollama_base: str | None = None
+    ollama_tag: str | None = None
+    source: str
+
+    @field_validator("hf_repo")
+    @classmethod
+    def _check_hf_repo(cls, value: str) -> str:
+        return validate_hf_repo(value)
+
+    @field_validator("source")
+    @classmethod
+    def _check_source(cls, value: str) -> str:
+        if not value.startswith(_HUB):
+            raise ValueError(f"source must be a https://huggingface.co/ page: {value!r}")
+        return value
+
+    @field_validator("latest_source")
+    @classmethod
+    def _check_latest_source(cls, value: str | None) -> str | None:
+        if value is not None:
+            parts = urlsplit(value)
+            if parts.scheme != "https" or not parts.hostname:
+                raise ValueError(f"latest_source must be an https page with a host: {value!r}")
+        return value
+
+    @model_validator(mode="after")
+    def _check_fields(self) -> "CatalogModel":
+        validate_ollama_pair(self.ollama_base, self.ollama_tag)
+        evidence = (self.latest_source, self.latest_checked)
+        if self.latest and None in evidence:
+            raise ValueError(f"{self.hf_repo}: latest needs latest_source and latest_checked")
+        if not self.latest and evidence != (None, None):
+            raise ValueError(f"{self.hf_repo}: latest_source and latest_checked belong to a latest model")
+        if self.successor is not None:
+            validate_hf_repo(self.successor)
+            if self.latest:
+                raise ValueError(f"{self.hf_repo}: a model with a successor is not latest")
+            if self.successor == self.hf_repo:
+                raise ValueError(f"{self.hf_repo}: successor must be another model")
+        return self
+
+
+class CatalogFamily(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    name: str = Field(min_length=1)
+    publisher: str = Field(min_length=1)
+    models: list[CatalogModel] = Field(min_length=1)
+
+    @model_validator(mode="after")
+    def _check_models(self) -> "CatalogFamily":
+        repos = [model.hf_repo for model in self.models]
+        if len(repos) != len(set(repos)):
+            raise ValueError(f"family {self.name}: hf_repo listed twice")
+        for model in self.models:
+            for repo in (model.hf_repo, model.successor):
+                if repo is not None and repo.split("/", 1)[0] != self.publisher:
+                    raise ValueError(f"family {self.name}: {repo} is not under publisher {self.publisher}")
+            if model.latest_source is not None and not _is_publisher_evidence(model.latest_source, self.publisher):
+                raise ValueError(
+                    f"family {self.name}: latest_source of {model.hf_repo} on the Hub must be the page or a "
+                    f"collection of publisher {self.publisher}: {model.latest_source}"
+                )
+        _check_no_successor_cycle(self.models, f"family {self.name}")
+        return self
+
+
+def _is_publisher_evidence(url: str, publisher: str) -> bool:
+    """A Hub page proves `latest` only as the publisher's own page or one of its collections; a
+    page off the Hub (the publisher's site) is taken as the maintainer confirmed it."""
+    parts = urlsplit(url)
+    if parts.hostname not in _HUB_HOSTS:
+        return True
+    path = parts.path.strip("/")
+    return path == publisher or path.startswith(f"collections/{publisher}/")
+
+
+def _check_no_successor_cycle(models: list[CatalogModel], label: str) -> None:
+    successor_of = {model.hf_repo: model.successor for model in models}
+    for start in successor_of:
+        seen = {start}
+        current = successor_of.get(start)
+        while current is not None:
+            if current in seen:
+                raise ValueError(f"{label}: successor cycle through {current}")
+            seen.add(current)
+            current = successor_of.get(current)
+
+
+class Catalog(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    schema_version: int
+    families: list[CatalogFamily] = Field(default_factory=list)
+
+    @model_validator(mode="after")
+    def _check(self) -> "Catalog":
+        if self.schema_version != CATALOG_SCHEMA_VERSION:
+            raise ValueError(f"schema_version must be {CATALOG_SCHEMA_VERSION}, got {self.schema_version}")
+        names = [family.name for family in self.families]
+        repos = [model.hf_repo for family in self.families for model in family.models]
+        if len(names) != len(set(names)) or len(repos) != len(set(repos)):
+            raise ValueError("family names and hf_repo entries must be unique across the catalog")
+        _check_no_successor_cycle([m for family in self.families for m in family.models], "catalog")
+        return self
+
+    def model_for(self, hf_repo: str) -> CatalogModel | None:
+        return next((m for f in self.families for m in f.models if m.hf_repo == hf_repo), None)
+
+    def is_publisher(self, owner: str) -> bool:
+        return any(family.publisher == owner for family in self.families)
+
+    def age_of(self, hf_repo: str) -> tuple[Age, str | None]:
+        """`(age, successor)` from the catalog alone: `latest`, `legacy` with its successor, or
+        `unknown` when the model is not listed or listed without either statement."""
+        model = self.model_for(hf_repo)
+        if model is None:
+            return "unknown", None
+        if model.successor is not None:
+            return "legacy", model.successor
+        return ("latest", None) if model.latest else ("unknown", None)
+
+
+def load_catalog(path: Path = CATALOG_FILE) -> Catalog:
+    """Read and validate a catalog file; the default is the one shipped with the package."""
+    try:
+        data = tomllib.loads(path.read_text(encoding="utf-8"))
+    except (OSError, tomllib.TOMLDecodeError) as exc:
+        raise CatalogError(f"{path}: cannot read catalog: {exc}") from exc
+    version = data.get("schema_version")
+    if not isinstance(version, int) or isinstance(version, bool):
+        raise SchemaVersionError(f"{path}: schema_version is missing or not an integer: {version!r}")
+    check_schema_version(version, CATALOG_SCHEMA_RANGE, str(path))
+    try:
+        return Catalog.model_validate(data)
+    except ValidationError as exc:
+        raise CatalogError(f"{path}: invalid catalog: {exc}") from exc