hugpy-curation 0.2.0a0__py3-none-any.whl

hugpy_curation/__init__.py

@@ -0,0 +1,64 @@
+"""hugpy_curation — discovery dossiers and the HF model review pipeline.
+
+Two subpackages, one lifecycle:
+
+* :mod:`hugpy_curation.review` — search, screen, download (through
+  ``hugpy_storage``), smoke-load, judge; the on-box review record and the
+  worker->central push.
+* :mod:`hugpy_curation.dossier` — the comprehensive per-model dossier the
+  review files for every survivor (card digest, weights, research,
+  community, trial, verdict) and the gem radar.
+
+Seams:
+
+* :mod:`hugpy_curation.config` — every state root, env-overridable.
+* :mod:`hugpy_curation.providers` — the fleet doctrine the dossier judge
+  reads (``DoctrineSource``; null default).
+* :mod:`hugpy_curation.dossier.oracle_source` — the dossier store as the
+  oracle's ``DossierSource``; :func:`install_providers` registers it.
+
+This ``__init__`` is deliberately light: nothing heavy (huggingface_hub,
+llama_cpp, the review sqlite, the job mirror) is imported here.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Optional
+
+try:  # the installed distribution's version: the workspace tag/commit, never a literal
+    from importlib.metadata import version as _dist_version
+    __version__ = _dist_version("hugpy-curation")
+except Exception:  # noqa: BLE001 — source tree without metadata
+    __version__ = "0.0.0+unknown"
+
+__all__ = ["__version__", "install_providers"]
+
+
+def install_providers(doctrine_source: Optional[Any] = None,
+                      dossier_root: Optional[str] = None) -> dict[str, Any]:
+    """Wire curation's seams in this process; returns what was wired.
+
+    * Installs :class:`~hugpy_curation.dossier.oracle_source.DossierStoreSource`
+      into ``hugpy_oracle.providers`` (``set_dossier_source``) so the oracle's
+      interim ledger can list discovery dossiers.
+    * Installs ``doctrine_source`` (anything with ``latest()``) into
+      :mod:`hugpy_curation.providers` when given; the server passes the
+      fleet's ``hugpy_fleet.doctrine`` adapter here. Without one, the
+      doctrine falls back to whatever the oracle has installed, else null.
+
+    Called by ``hugpy_server`` at startup and by
+    ``hugpy-curation install-providers``.
+    """
+    from hugpy_curation.dossier.oracle_source import install_dossier_source
+    from hugpy_curation.providers import set_doctrine_source
+
+    report: dict[str, Any] = {}
+    source = install_dossier_source(dossier_root)
+    report["dossier_source"] = {"installed": True, "root": source.root()}
+    if doctrine_source is not None:
+        set_doctrine_source(doctrine_source)
+        report["doctrine_source"] = {"installed": True,
+                                     "impl": type(doctrine_source).__name__}
+    else:
+        report["doctrine_source"] = {"installed": False, "impl": "default"}
+    return report

hugpy_curation/cli.py

@@ -0,0 +1,142 @@
+"""``hugpy-curation`` — the package's command line.
+
+Subcommands:
+
+``review ...``
+    The review pipeline's own CLI (``hugpy_curation.review.__main__``):
+    ``screen``, ``review``, ``run <criteria>``, ``criteria``, ``reports``,
+    ``push``. Everything after ``review`` is handed to it untouched, so the
+    systemd units run ``hugpy-curation review run %i --report ...``.
+
+``dossier list [criteria]``
+    The discovery dossiers the store holds — every criteria, or one — as the
+    compact summary rows the console lists, newest first.
+
+``install-providers``
+    Wire this process's seams: the dossier store into
+    ``hugpy_oracle.providers`` (``set_dossier_source``) and, when a fleet
+    doctrine source is importable, the doctrine into
+    ``hugpy_curation.providers``. Prints what was wired as JSON.
+
+No pathlib; os.path only (project discipline).
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from typing import Any, Optional, Sequence
+
+__all__ = ["main", "build_parser"]
+
+
+def build_parser() -> argparse.ArgumentParser:
+    from hugpy_curation import __version__
+
+    parser = argparse.ArgumentParser(
+        prog="hugpy-curation",
+        description="Hugpy curation: discovery dossiers and the HF model review pipeline.")
+    parser.add_argument("--version", action="version",
+                        version=f"hugpy-curation {__version__}")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    review = sub.add_parser(
+        "review", help="the review pipeline (screen / review / run / criteria / reports / push)",
+        description="Arguments are passed to the review pipeline's CLI; "
+                    "`hugpy-curation review --help` lists them.")
+    review.add_argument("args", nargs=argparse.REMAINDER,
+                        help="review pipeline arguments")
+    review.set_defaults(func=_cmd_review)
+
+    dossier = sub.add_parser("dossier", help="discovery dossiers")
+    dsub = dossier.add_subparsers(dest="dossier_command", required=True)
+    dlist = dsub.add_parser("list", help="list stored dossiers (summary rows)")
+    dlist.add_argument("criteria", nargs="?", default=None,
+                       help="one criteria name (default: every criteria)")
+    dlist.add_argument("--limit", type=int, default=50,
+                       help="rows per criteria (default 50)")
+    dlist.add_argument("--json", action="store_true", help="JSON instead of a table")
+    dlist.set_defaults(func=_cmd_dossier_list)
+
+    providers = sub.add_parser(
+        "install-providers",
+        help="install curation's dossier source in the oracle (and a doctrine source when available)")
+    providers.set_defaults(func=_cmd_install_providers)
+    return parser
+
+
+# ---------------------------------------------------------------------------
+# review
+# ---------------------------------------------------------------------------
+
+def _cmd_review(args: argparse.Namespace) -> int:
+    from hugpy_curation.review.__main__ import main as review_main
+    rest = list(args.args)
+    if rest and rest[0] == "--":
+        rest = rest[1:]
+    return int(review_main(rest or ["--help"]) or 0)
+
+
+# ---------------------------------------------------------------------------
+# dossier list
+# ---------------------------------------------------------------------------
+
+def dossier_rows(criteria: Optional[str] = None, limit: int = 50) -> list[dict[str, Any]]:
+    """Summary rows for the stored dossiers, newest first per criteria."""
+    import os
+    from hugpy_curation.dossier import store as dstore
+
+    if criteria:
+        names = [criteria]
+    else:
+        root = dstore.root_dir()
+        try:
+            names = sorted(n for n in os.listdir(root)
+                           if os.path.isdir(os.path.join(root, n)))
+        except OSError:
+            names = []
+    rows: list[dict[str, Any]] = []
+    for name in names:
+        for path in dstore.list_for(name)[:max(1, int(limit))]:
+            dossier = dstore.load_path(path)
+            if dossier is not None:
+                rows.append(dstore.summary(dossier, path))
+    return rows
+
+
+def _cmd_dossier_list(args: argparse.Namespace) -> int:
+    rows = dossier_rows(args.criteria, args.limit)
+    if args.json:
+        print(json.dumps(rows, indent=2, default=str))
+        return 0
+    if not rows:
+        from hugpy_curation.dossier import store as dstore
+        print(f"(no dossiers under {dstore.root_dir()})")
+        return 0
+    for r in rows:
+        verdict = r.get("verdict") or "-"
+        print(f"{r.get('criteria')}\t{r.get('hub_id')}\t{verdict}\t"
+              f"{r.get('best_quant') or '-'}\t{r.get('generated_at') or ''}")
+    return 0
+
+
+# ---------------------------------------------------------------------------
+# install-providers
+# ---------------------------------------------------------------------------
+
+def _cmd_install_providers(args: argparse.Namespace) -> int:
+    from hugpy_curation import install_providers
+    report = install_providers()
+    print(json.dumps(report, indent=2, default=str))
+    return 0
+
+
+def main(argv: Optional[Sequence[str]] = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(list(argv) if argv is not None else None)
+    return int(args.func(args) or 0)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

hugpy_curation/config.py

@@ -0,0 +1,161 @@
+"""Where curation keeps its own state — one place, every root injectable.
+
+Curation is the sole owner of the review record (sqlite), the discovery
+dossiers (one JSON file per criteria/repo, verdict included), the trial
+artifacts a dossier's sample battery writes, the saved review criteria and the
+dossier fetch cache (``PARTITION.md`` "State ownership"). Every module that
+used to derive its root on its own — from ``hugpy_platform.constants
+.DEFAULT_ROOT``, ``~/.config``, ``~/.cache`` or, for trials, the ORACLE's
+benchmark run root — now asks here, so an operator (or a test conftest) can
+move the whole set with one variable and still override any single root with
+the env var that module always honoured.
+
+Resolution order for every root:
+
+1. the module's own env var (``REVIEW_DB``, ``DOSSIER_DIR``,
+   ``DOSSIER_TRIAL_ROOT``, ``REVIEW_CRITERIA_DIR``, ``DOSSIER_CACHE_DIR``) —
+   kept verbatim, so existing deployments (the ``hugpy-review@`` units set
+   ``REVIEW_DB``) and the tests keep working;
+2. the package-wide ``HUGPY_CURATION_ROOT`` (state) / ``HUGPY_CURATION_CACHE``;
+3. the platform's per-OS application directories (``hugpy_platform.app_dirs``):
+   ``models_root()/review`` for the record, dossiers and trials — the tree the
+   review has always written under (``<DEFAULT_ROOT>/review``), so a box that
+   upgrades finds its history where it left it — ``config_dir()/review`` for
+   the saved criteria and ``cache_dir()/discovery-dossier`` for the fetch
+   cache (both byte-identical to the historical ``~/.config/hugpy/review`` and
+   ``~/.cache/hugpy/discovery-dossier`` on Linux).
+
+Trials used to fall back to ``hugpy_oracle.benchmark.default_run_root()``;
+that is the oracle's state and curation must not write into it, so the
+default is now ``<review_root>/trials``. ``DOSSIER_TRIAL_ROOT`` still wins.
+
+Env reads are plain ``os.environ`` on purpose: a state root must not depend
+on a ``.env`` loader having run, and a test that sets ``monkeypatch.setenv``
+must see the change immediately. Nothing here creates directories except
+:func:`ensure_dir`; callers that write call it, callers that read do not.
+
+No pathlib; os.path only (project discipline).
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+from typing import Optional
+
+logger = logging.getLogger(__name__)
+
+__all__ = [
+    "CURATION_ROOT_ENV",
+    "CURATION_CACHE_ENV",
+    "REVIEW_DB_ENV",
+    "DOSSIER_DIR_ENV",
+    "TRIAL_ROOT_ENV",
+    "CRITERIA_DIR_ENV",
+    "FETCH_CACHE_ENV",
+    "review_root",
+    "review_db_path",
+    "dossiers_root",
+    "trials_root",
+    "criteria_dir",
+    "fetch_cache_dir",
+    "ensure_dir",
+]
+
+CURATION_ROOT_ENV = "HUGPY_CURATION_ROOT"
+CURATION_CACHE_ENV = "HUGPY_CURATION_CACHE"
+
+# Per-store env vars, unchanged from the modules that introduced them.
+REVIEW_DB_ENV = "REVIEW_DB"
+DOSSIER_DIR_ENV = "DOSSIER_DIR"
+TRIAL_ROOT_ENV = "DOSSIER_TRIAL_ROOT"
+CRITERIA_DIR_ENV = "REVIEW_CRITERIA_DIR"
+FETCH_CACHE_ENV = "DOSSIER_CACHE_DIR"
+
+
+def _env(name: str) -> Optional[str]:
+    value = os.environ.get(name)
+    value = value.strip() if value else ""
+    return value or None
+
+
+def _home_fallback(*parts: str) -> str:
+    return os.path.join(os.path.expanduser("~"), ".local", "share", "hugpy", *parts)
+
+
+def _platform_models_root() -> str:
+    try:
+        from hugpy_platform.app_dirs import models_root
+        return models_root()
+    except Exception as exc:  # noqa: BLE001 — a root must always resolve
+        logger.warning("curation config: models_root unreadable (%s: %s); "
+                       "using ~/.local/share/hugpy", type(exc).__name__, exc)
+        return _home_fallback()
+
+
+def _platform_config_dir() -> str:
+    try:
+        from hugpy_platform.app_dirs import config_dir
+        return config_dir()
+    except Exception as exc:  # noqa: BLE001
+        logger.warning("curation config: config_dir unreadable (%s: %s); "
+                       "using ~/.config/hugpy", type(exc).__name__, exc)
+        return os.path.join(os.path.expanduser("~"), ".config", "hugpy")
+
+
+def _platform_cache_dir() -> str:
+    try:
+        from hugpy_platform.app_dirs import cache_dir
+        return cache_dir()
+    except Exception as exc:  # noqa: BLE001
+        logger.warning("curation config: cache_dir unreadable (%s: %s); "
+                       "using ~/.cache/hugpy", type(exc).__name__, exc)
+        base = os.environ.get("XDG_CACHE_HOME") or os.path.join(os.path.expanduser("~"), ".cache")
+        return os.path.join(base, "hugpy")
+
+
+def ensure_dir(path: str) -> str:
+    """``makedirs`` that never raises — a state root that cannot be created is
+    reported by the write that follows, not by the path lookup."""
+    try:
+        os.makedirs(path, exist_ok=True)
+    except OSError as exc:
+        logger.warning("curation config: cannot create %s (%s)", path, exc)
+    return path
+
+
+def review_root() -> str:
+    """The review record, dossiers and trials live under this tree.
+    ``HUGPY_CURATION_ROOT`` else ``<models_root>/review`` (historically
+    ``<DEFAULT_ROOT>/review``)."""
+    return _env(CURATION_ROOT_ENV) or os.path.join(_platform_models_root(), "review")
+
+
+def review_db_path() -> str:
+    """The on-box review record (sqlite). ``REVIEW_DB`` wins."""
+    return _env(REVIEW_DB_ENV) or os.path.join(review_root(), "reviews.db")
+
+
+def dossiers_root() -> str:
+    """``<dossiers_root>/<criteria>/<org__repo>.json``. ``DOSSIER_DIR`` wins."""
+    return _env(DOSSIER_DIR_ENV) or os.path.join(review_root(), "dossiers")
+
+
+def trials_root() -> str:
+    """Sample artifacts of a dossier's trial battery. ``DOSSIER_TRIAL_ROOT``
+    wins; otherwise ``<review_root>/trials`` (curation's own tree, never the
+    oracle's benchmark root)."""
+    return _env(TRIAL_ROOT_ENV) or os.path.join(review_root(), "trials")
+
+
+def criteria_dir() -> str:
+    """Saved review criteria (``<name>.json``). ``REVIEW_CRITERIA_DIR`` wins;
+    otherwise ``<config_dir>/review``."""
+    return _env(CRITERIA_DIR_ENV) or os.path.join(_platform_config_dir(), "review")
+
+
+def fetch_cache_dir() -> str:
+    """The dossier fetch cache. ``DOSSIER_CACHE_DIR`` wins, then
+    ``HUGPY_CURATION_CACHE``, then ``<cache_dir>/discovery-dossier``."""
+    return (_env(FETCH_CACHE_ENV) or _env(CURATION_CACHE_ENV)
+            or os.path.join(_platform_cache_dir(), "discovery-dossier"))

hugpy_curation/dossier/__init__.py

@@ -0,0 +1,88 @@
+"""k120 — comprehensive model-discovery dossiers.
+
+The nightly reviewer (``review/``) has run since July: screen HF on metadata,
+download the best few, load-test them on the GPU, ask an agent for a verdict.
+It works, and what it hands the operator is a MODEL NAME with a score. The
+operator's read of that, verbatim:
+
+    "just model names… this needs to be comprehensive in nature and allow for
+    that complexity to be dictated. specializations and overall weights,
+    research outside of the download sources themselves, trial download and
+    sample data to compare various models. this needs to be genuinely useful."
+
+    "scraping social media, AI forums, reddits, youtube transcriptions — all of
+    these things to keep the edge on a gem that exists."
+
+This package is the answer, in eight sections and one rule.
+
+    dossier.py      the types. Every field SOURCED or None; model-generated
+                    text labelled as such, everywhere it appears.
+    cards.py        the README read like a reviewer — benchmark tables as
+                    CLAIMS, limitations, the author's own purpose sentences,
+                    and a 0..1 weight per specialization with its evidence.
+    weights.py      params, every quant, and a VRAM number for EACH of them at
+                    the same target context. The KV maths is ``review.screen``'s,
+                    imported — two estimators that disagree is a 3am bug.
+    fetch.py        the only way out to the network: never raises, polite
+                    (real UA, one request per host per 2s), disk-cached for 20h.
+    research.py     model card + linked papers + a written summary from a
+                    catalog-resolved model, with its sources cited.
+    community.py    Reddit / HN / HF discussions as typed Mentions, claims
+                    extracted with the QUOTE that supports them, and a
+                    recency-weighted heat. YouTube is wired and honest about
+                    needing a dependency it will never hard-require (k121).
+    radar.py        GEM RADAR: a second pass over the SAME cached pulls looking
+                    for models no card is asking about yet.
+    trial.py        k109b's stationary battery, borrowed whole. The candidate
+                    does the SAME fixed work the incumbent in the routing
+                    matrix was scored on, so subtracting the two means something.
+    verdicts.py     THE RULE: no evidence, no verdict. A blocked trial can only
+                    produce "screened only — trial blocked: <cause>".
+    build.py        the orchestrator; a section that cannot be built leaves a
+                    note and the other seven still arrive.
+    store.py        the full dossier is a file; the review row carries a
+                    compact summary and the path.
+
+Nothing here is on the request path and nothing here is required: every entry
+point degrades to an honest ``unavailable`` record rather than failing the
+review that called it.
+"""
+from __future__ import annotations
+
+from hugpy_curation.dossier.build import build_dossier
+from hugpy_curation.dossier.dossier import (
+    BenchmarkClaim,
+    CardDigest,
+    Claim,
+    Community,
+    EmphasisWeight,
+    ExternalResearch,
+    Identity,
+    IncumbentComparison,
+    Mention,
+    ModelDossier,
+    PaperRef,
+    QuantFact,
+    SCHEMA_VERSION,
+    SampleOutput,
+    SampleScore,
+    Source,
+    Specialization,
+    TRIAL_DEPTHS,
+    TrialEvidence,
+    TrustSignals,
+    VERDICTS,
+    Verdict,
+    WeightsFacts,
+)
+from hugpy_curation.dossier.radar import RadarHit, scan as radar_scan
+from hugpy_curation.dossier.verdicts import decide, rule_verdict
+
+__all__ = [
+    "BenchmarkClaim", "CardDigest", "Claim", "Community", "EmphasisWeight",
+    "ExternalResearch", "Identity", "IncumbentComparison", "Mention",
+    "ModelDossier", "PaperRef", "QuantFact", "RadarHit", "SCHEMA_VERSION",
+    "SampleOutput", "SampleScore", "Source", "Specialization", "TRIAL_DEPTHS",
+    "TrialEvidence", "TrustSignals", "VERDICTS", "Verdict", "WeightsFacts",
+    "build_dossier", "decide", "radar_scan", "rule_verdict",
+]