optivibe-reference 0.2.0__tar.gz

optivibe_reference-0.2.0/PKG-INFO

@@ -0,0 +1,44 @@
+Metadata-Version: 2.4
+Name: optivibe-reference
+Version: 0.2.0
+Summary: OptiVibe reference layer: lookup tables + RAG + intent->ZOS-API grounding
+License: Apache-2.0
+Project-URL: Homepage, https://github.com/chuang44-tiff/optivibe-mcp
+Project-URL: Issues, https://github.com/chuang44-tiff/optivibe-mcp/issues
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3.11
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Provides-Extra: manual
+Requires-Dist: pymupdf; extra == "manual"
+Provides-Extra: probe
+Requires-Dist: pythonnet; extra == "probe"
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+
+# optivibe-reference
+
+The grounding layer for optivibe-mcp: deterministic lookup tables, a SQLite
+**FTS5** full-text store over the OpticStudio manual, and an intent→operand
+grounding index. It lets the agent consult operand meanings, glass properties,
+and manual passages so its choices are grounded rather than guessed.
+
+It is composed **in-process** by `optivibe-mcp` (not a standalone server) and
+exposes five tools: `lookup_operand`, `search_reference`, `lookup_glass`,
+`find_glasses`, and `find_glass_pair`.
+
+## Data is built locally
+
+No vendor data is committed. The glass catalog (recomputed from your install's
+`.agf` files), the manual FTS5 corpus (indexed from your manual PDF), and the
+description-bearing operand/tolerance catalogs are all **built on your machine
+from your own licensed OpticStudio install** and are gitignored. Only the
+author's own sources ship — the `*_synonyms.json` intent vocabularies and
+`operand_semantics.json`. Build the data with the `optivibe-build-data` command that
+comes with the package; the [repository README](https://github.com/chuang44-tiff/optivibe-mcp#readme) has the
+steps and `PROVENANCE.md` the data-source ledger.
+
+Any tool whose data has not been built degrades to a typed "unavailable" result
+instead of failing — the rest of the server keeps working.
+
+See `AGENTS.md` for more detail. Python 3.11.

optivibe_reference-0.2.0/README.md

@@ -0,0 +1,26 @@
+# optivibe-reference
+
+The grounding layer for optivibe-mcp: deterministic lookup tables, a SQLite
+**FTS5** full-text store over the OpticStudio manual, and an intent→operand
+grounding index. It lets the agent consult operand meanings, glass properties,
+and manual passages so its choices are grounded rather than guessed.
+
+It is composed **in-process** by `optivibe-mcp` (not a standalone server) and
+exposes five tools: `lookup_operand`, `search_reference`, `lookup_glass`,
+`find_glasses`, and `find_glass_pair`.
+
+## Data is built locally
+
+No vendor data is committed. The glass catalog (recomputed from your install's
+`.agf` files), the manual FTS5 corpus (indexed from your manual PDF), and the
+description-bearing operand/tolerance catalogs are all **built on your machine
+from your own licensed OpticStudio install** and are gitignored. Only the
+author's own sources ship — the `*_synonyms.json` intent vocabularies and
+`operand_semantics.json`. Build the data with the `optivibe-build-data` command that
+comes with the package; the [repository README](https://github.com/chuang44-tiff/optivibe-mcp#readme) has the
+steps and `PROVENANCE.md` the data-source ledger.
+
+Any tool whose data has not been built degrades to a typed "unavailable" result
+instead of failing — the rest of the server keeps working.
+
+See `AGENTS.md` for more detail. Python 3.11.

optivibe_reference-0.2.0/pyproject.toml

@@ -0,0 +1,60 @@
+# pyproject.toml — minimal packaging metadata for optivibe_reference.
+#
+# Exists so the harness env can `pip install -e ../optivibe-reference` and import
+# optivibe_reference in-process (the single OptiVibe MCP composes both tool sets;
+# the harness imports the reference one-way). setuptools src-layout.
+#
+# Runtime `dependencies = []`: the reference glass/operand path is pure-stdlib
+# (sqlite + FTS5 are stdlib), so the editable install pulls CODE only and adds zero
+# dep surface to the harness env (it never competes for the single-seat license).
+# The manual-PDF ingest dep (pymupdf) and the test runner (pytest) are OPTIONAL
+# extras so the runtime install stays lean.
+#
+# package-data is an EXPLICIT list of the committed files that are ours (resolved via
+# __file__-relative anchors, which an editable install preserves). Never a glob: the
+# data folder also holds the files a user builds from their own licensed install, and
+# none of those may enter a wheel. It also ships provenance_grants.txt, the ledger-row
+# markers the two fail-closed build gates read in an installed package.
+#
+# `optivibe-build-data` rebuilds every vendor-derived plane from the user's own
+# licensed install, with no clone. The `probe` extra adds pythonnet for
+# `optivibe-build-data --probe`; the optivibe-mcp install already carries it.
+[build-system]
+requires = ["setuptools>=61"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "optivibe-reference"
+version = "0.2.0"
+description = "OptiVibe reference layer: lookup tables + RAG + intent->ZOS-API grounding"
+requires-python = ">=3.11"
+readme = "README.md"
+license = {text = "Apache-2.0"}
+classifiers = [
+    "License :: OSI Approved :: Apache Software License",
+    "Programming Language :: Python :: 3.11",
+]
+dependencies = []
+
+[project.optional-dependencies]
+manual = ["pymupdf"]
+probe = ["pythonnet"]
+dev = ["pytest"]
+
+[project.scripts]
+optivibe-build-data = "optivibe_reference.build_data:main"
+
+[project.urls]
+Homepage = "https://github.com/chuang44-tiff/optivibe-mcp"
+Issues = "https://github.com/chuang44-tiff/optivibe-mcp/issues"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+optivibe_reference = [
+    "data/operand_semantics.json",
+    "data/operand_synonyms.json",
+    "data/tolerance_operand_synonyms.json",
+    "data/provenance_grants.txt",
+]

optivibe_reference-0.2.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

optivibe_reference-0.2.0/src/optivibe_reference/__init__.py

@@ -0,0 +1,14 @@
+"""optivibe_reference — lookup tables + RAG + intent->ZOS-API grounding index.
+
+The grounding layer that makes a smaller local orchestrator viable: an FTS5 RAG
+over reference material plus an intent->ZOS-API mapping index the agent consults
+FIRST (probe-first).
+
+Layer 1 (this increment): the ``MeritOperandType`` operand catalog (438 live
+codes, authored/manual descriptions pending, live-probed parameter-cell layout
+battery) + the typed, session-free, never-raise ``lookup_operand`` MCP tool that
+grounds design intent onto a merit-function operand. The catalog is built from a
+gitignored, user-built normalized-LF JSON at runtime; the ``.db`` is never committed.
+"""
+
+__version__ = "0.2.0"

optivibe_reference-0.2.0/src/optivibe_reference/_envelope.py

@@ -0,0 +1,19 @@
+"""_envelope.py — the reference-layer expected-failure envelope.
+
+Re-implemented (NOT imported) from the harness ``_analysis_common.error_envelope``
+shape so the reference package stays decoupled. A handler constructs this for an
+EXPECTED failure class (unknown operand, malformed FTS query); it does NOT raise
+past its own boundary for those.
+"""
+
+
+def error_envelope(tool, error_family, error, **extra):
+    """Build the locked expected-failure envelope (never raised past boundary).
+
+    ``{"ok": False, "tool": tool, "error_family": error_family, "error": error}``
+    plus any tool-specific diagnostic fields in ``extra`` (e.g. ``query=...``).
+    Mirrors the harness 4-key+extra shape exactly.
+    """
+    env = {"ok": False, "tool": tool, "error_family": error_family, "error": error}
+    env.update(extra)
+    return env

optivibe_reference-0.2.0/src/optivibe_reference/_paths.py

@@ -0,0 +1,66 @@
+"""_paths.py — the ONE resolver for where build inputs live (clone vs installed wheel).
+
+Two locations used to be derived from ``__file__`` as ``<package root>/scripts/...`` and
+``<repo root>/PROVENANCE.md``. Both exist in a source checkout and NEITHER exists in an
+installed wheel (``site-packages/optivibe_reference`` has no ``scripts/`` sibling and no
+repo root), so every reader and writer routes through this module instead:
+
+* ``captures_dir()`` — the live-probe captures + verbatim raw oracles. A source checkout
+  keeps them at ``packages/optivibe-reference/scripts/captures`` (unchanged, gitignored);
+  an installed package keeps them at ``<package>/data/captures`` (created on first write).
+* ``provenance_ledger_path()`` — the file the two fail-closed provenance gates
+  (``glass_build.assert_agf_grant_on_file``, ``manual_build.assert_manual_grant_on_file``)
+  read. A source checkout reads the repo-root ledger and ONLY that — deleting it, or the
+  row in it, still refuses, exactly as before. An installed package has no repo ledger, so
+  it reads the marker file shipped beside the code (``data/provenance_grants.txt``). The
+  marker check itself is unchanged; this only chooses which file it reads.
+
+"Source checkout" is decided by the CLONE LAYOUT (``pyproject.toml`` + ``scripts/`` at the
+package root), never by whether ``scripts/captures`` exists: that dir is gitignored and
+absent on a fresh clone until the probes run, and keying on it would send a fresh clone's
+probe output into the package's ``data/`` tree instead.
+
+Stdlib only; imports nothing from this package (every build module imports it).
+"""
+import os
+
+_HERE = os.path.dirname(os.path.abspath(__file__))  # .../optivibe_reference
+# packages/optivibe-reference in a clone (src/optivibe_reference -> ../..); some unrelated
+# dir (e.g. ``<venv>/Lib``) in an installed wheel, which is why it is CHECKED, not trusted.
+_PKG_ROOT = os.path.dirname(os.path.dirname(_HERE))
+_REPO_ROOT = os.path.dirname(os.path.dirname(_PKG_ROOT))
+
+# The repo-root provenance ledger a source checkout must carry.
+LEDGER_NAME = "PROVENANCE.md"
+# The marker file an installed package ships (package-data) in place of the ledger. It
+# holds the ledger-row marker strings the two gates look for, one per line.
+PROVENANCE_MARKER_NAME = "provenance_grants.txt"
+
+
+def is_source_checkout(pkg_root=_PKG_ROOT):
+    """True iff ``pkg_root`` is a package root in a clone (pyproject + scripts/ beside src)."""
+    return (os.path.isfile(os.path.join(pkg_root, "pyproject.toml"))
+            and os.path.isdir(os.path.join(pkg_root, "scripts")))
+
+
+def captures_dir(pkg_root=_PKG_ROOT, package_dir=_HERE):
+    """Return the live-probe captures dir (NOT created here — writers create it).
+
+    Clone: ``<pkg_root>/scripts/captures`` (the historic location, unchanged).
+    Installed: ``<package_dir>/data/captures``.
+    """
+    if is_source_checkout(pkg_root):
+        return os.path.join(pkg_root, "scripts", "captures")
+    return os.path.join(package_dir, "data", "captures")
+
+
+def provenance_ledger_path(pkg_root=_PKG_ROOT, repo_root=_REPO_ROOT, package_dir=_HERE):
+    """Return the file the provenance gates read (fail-closed either way).
+
+    Clone: the repo-root ledger, whether or not it exists — a missing ledger in a clone
+    must refuse, never fall through to the shipped marker. Installed: the shipped marker
+    file; if that is missing too the returned path does not exist and the gate refuses.
+    """
+    if is_source_checkout(pkg_root):
+        return os.path.join(repo_root, LEDGER_NAME)
+    return os.path.join(package_dir, "data", PROVENANCE_MARKER_NAME)

optivibe_reference-0.2.0/src/optivibe_reference/_probe_common.py

@@ -0,0 +1,142 @@
+"""_probe_common.py — the shared plumbing of the two live operand probes.
+
+``probe_operands`` (MeritOperandType) and ``probe_tolerances`` (ToleranceOperandType)
+each boot a headless OpticStudio, dump an enum surface to the captures dir, and reap the
+session. This module holds what they share: loading pythonnet, resolving the ZOS-API
+assemblies without a hardcoded install path, the never-raise ``capture`` helper, and the
+JSON writer.
+
+Importing this module (or either probe) needs NO pythonnet: ``clr`` is imported inside
+``load_clr`` only, and the ``PYTHONNET_RUNTIME`` selector is set there too, so the
+harness publication suite (which imports every shipped module) never touches .NET.
+It imports nothing from optivibe_harness (zero cross-package coupling).
+"""
+import glob
+import json
+import os
+
+from . import _paths
+
+# The install hint a missing pythonnet names: the probes are an OPTIONAL extra.
+PROBE_EXTRA_HINT = 'install optivibe-reference[probe] (pip install "optivibe-reference[probe]")'
+
+
+class PythonnetMissing(ImportError):
+    """pythonnet (``clr``) is not importable, so no live probe can run."""
+
+
+def load_clr():
+    """Select the .NET Framework runtime, then import and return ``clr``.
+
+    The runtime selector MUST be set before ``import clr``. Raises ``PythonnetMissing``
+    (an ``ImportError``) naming the ``[probe]`` extra when pythonnet is absent.
+    """
+    os.environ.setdefault("PYTHONNET_RUNTIME", "netfx")
+    try:
+        import clr  # noqa: E402  (pythonnet; after the runtime selector is set)
+    except ImportError as exc:
+        raise PythonnetMissing(
+            "pythonnet is not installed, so the live probes cannot run - "
+            + PROBE_EXTRA_HINT) from exc
+    return clr
+
+
+def out_dir():
+    """Where the probes write: the captures dir (``_paths.captures_dir``)."""
+    return _paths.captures_dir()
+
+
+def find_nethelper():
+    """Resolve ZOSAPI_NetHelper.dll without hardcoding an install path."""
+    override = os.environ.get("ZOSAPI_NETHELPER")
+    if override and os.path.isfile(override):
+        return override
+    docs = os.path.join(os.path.expanduser("~"), "Documents", "Zemax", "ZOS-API", "Libraries")
+    candidate = os.path.join(docs, "ZOSAPI_NetHelper.dll")
+    if os.path.isfile(candidate):
+        return candidate
+    root = os.path.join(os.path.expanduser("~"), "Documents", "Zemax")
+    hits = glob.glob(os.path.join(root, "**", "ZOSAPI_NetHelper.dll"), recursive=True)
+    if hits:
+        return hits[0]
+    raise FileNotFoundError(
+        "ZOSAPI_NetHelper.dll not found; set ZOSAPI_NETHELPER to its path."
+    )
+
+
+def resolve_zemax_dir(initializer):
+    """Resolve the OpticStudio install dir (holding ZOSAPI.dll) without hardcoding."""
+    def has_dll(d):
+        return bool(d) and os.path.isfile(os.path.join(d, "ZOSAPI.dll"))
+
+    override = os.environ.get("ZEMAX_DIR")
+    if has_dll(override):
+        initializer.Initialize(override)
+        return override, "env:ZEMAX_DIR"
+    if initializer.Initialize():
+        d = initializer.GetZemaxDirectory()
+        if has_dll(d):
+            return d, "registry-autodetect"
+    candidates = []
+    for base in (os.environ.get("ProgramFiles", r"C:\Program Files"),
+                 os.environ.get("ProgramFiles(x86)", r"C:\Program Files (x86)")):
+        candidates += glob.glob(os.path.join(base, "*Zemax OpticStudio*"))
+    candidates = sorted((c for c in candidates if has_dll(c)), reverse=True)
+    if candidates:
+        d = candidates[0]
+        initializer.Initialize(d)
+        return d, "program-files-scan"
+    raise RuntimeError("Could not resolve an OpticStudio install dir with ZOSAPI.dll.")
+
+
+def load_zosapi(clr):
+    """Reference the NetHelper + ZOS-API assemblies; return the ``ZOSAPI`` namespace."""
+    nethelper = find_nethelper()
+    print(f"[probe] NetHelper: {nethelper}")
+    clr.AddReference(nethelper)
+    import ZOSAPI_NetHelper  # noqa: E402
+
+    zemax_dir, how = resolve_zemax_dir(ZOSAPI_NetHelper.ZOSAPI_Initializer)
+    print(f"[probe] Zemax directory: {zemax_dir}  (via {how})")
+    clr.AddReference(os.path.join(zemax_dir, "ZOSAPI.dll"))
+    clr.AddReference(os.path.join(zemax_dir, "ZOSAPI_Interfaces.dll"))
+    import ZOSAPI  # noqa: E402
+    return ZOSAPI
+
+
+def enum_members(enum_type):
+    """Member names of a .NET enum via System.Enum.GetNames (the live truth)."""
+    from System import Enum  # noqa: E402
+    return [str(n) for n in Enum.GetNames(enum_type)]
+
+
+def public_members(obj):
+    """Non-underscore attribute names on a live object (defensive discovery)."""
+    try:
+        return sorted(n for n in dir(obj) if not n.startswith("_"))
+    except Exception as exc:  # noqa: BLE001
+        return f"<unavailable: {type(exc).__name__}: {exc}>"
+
+
+def capture(fn):
+    """Call fn(), returning its value or a recorded failure string (never raises)."""
+    try:
+        v = fn()
+        # keep JSON-serializable
+        if isinstance(v, (str, int, float, bool)) or v is None:
+            return v
+        return str(v)
+    except Exception as exc:  # noqa: BLE001
+        return f"<err: {type(exc).__name__}: {exc}>"[:200]
+
+
+def write_json(name, payload):
+    """Write ``payload`` to ``<captures>/<name>`` (dir created on write); return the path."""
+    target = out_dir()
+    os.makedirs(target, exist_ok=True)
+    path = os.path.join(target, name)
+    with open(path, "w", encoding="utf-8", newline="\n") as fh:
+        json.dump(payload, fh, indent=2)
+        fh.write("\n")
+    print(f"[probe] wrote {path}")
+    return path

optivibe_reference-0.2.0/src/optivibe_reference/build_data.py

@@ -0,0 +1,271 @@
+"""build_data.py — one-shot local rebuild of all user-side vendor data (``optivibe-build-data``).
+
+OptiVibe ships code only: the glass catalog, the manual FTS5 corpus, and the merit +
+tolerance operand catalogs are built LOCALLY from YOUR licensed Zemax OpticStudio install
+and are never committed. Run this once after install (and again after upgrading
+OpticStudio):
+
+    optivibe-build-data              # installed (pip install optivibe-mcp)
+    optivibe-build-data --probe      # first run: probe the operand surfaces, then build
+
+It is the in-package equivalent of the published ``scripts/build_vendor_data.py`` and
+needs no clone. Steps (each calls the package-level builder; nothing is duplicated here):
+
+0. (``--probe`` only) the live operand + tolerance probes (``probe_operands.main``,
+   ``probe_tolerances.main``): boot a headless OpticStudio, write the captures steps 2-4
+   need, reap the engine. They need pythonnet (``optivibe-reference[probe]``; the
+   optivibe-mcp install already has it). A missing pythonnet or a probe error FAILS
+   that probe, and the build steps still run.
+1. Glass catalog  — ``build_steps.build_glass_catalog``: the ``.agf`` files from your
+   install's Glasscat dir (``ZEMAX_GLASSCAT`` env override, else
+   ``~/Documents/Zemax/Glasscat``) -> ``data/glass_catalog.json``.
+2. Manual corpus  — ``build_steps.build_manual_corpus``: your install's
+   ``OpticStudio_UserManual_en.pdf`` (``OPTIVIBE_MANUAL_PDF`` env override, else the
+   standard install dir) -> the local ``data/manual_corpus.db`` + text-free
+   ``data/manual_manifest.json``, plus (``--emit-raw``) the verbatim raw
+   operand/tolerance oracles steps 3-4 merge as local descriptions. Needs PyMuPDF
+   (``optivibe-reference[manual]``).
+3. Merit operand catalog     — ``catalog_build.main`` -> ``data/operand_catalog.json``.
+4. Tolerance operand catalog — ``tolerance_build.main`` ->
+   ``data/tolerance_operand_catalog.json``.
+
+A missing input (no Glasscat dir, no manual PDF, no PyMuPDF, no live-probe captures) is
+reported and SKIPPED: that tool family answers a typed ``*_unavailable`` envelope until
+the build runs. An unexpected error FAILS the step. Exit code = number of FAILED (not
+skipped) steps. ASCII status output only.
+"""
+import argparse
+import importlib.util
+import json
+import os
+import re
+import sys
+
+from . import _paths, build_steps, catalog_build, tolerance_build
+
+# The live-probe captures each operand-catalog build REQUIRES (regenerated from the
+# user's OpticStudio install); absent -> that step is a fresh-install SKIP.
+OPERAND_CAPTURES = ("operand_inventory_438.json", "probe_operands_capture.json")
+TOLERANCE_CAPTURES = ("tolerance_inventory_62.json", "probe_tolerances_capture.json")
+# The capture the manual step's ``--emit-raw`` opens unconditionally (tolerance oracle).
+TOLERANCE_INVENTORY_CAPTURE = "tolerance_inventory_62.json"
+# ``--emit-raw`` opens BOTH inventories: the merit one for the glued-code gate, the
+# tolerance one for the tolerance oracle. Either absent -> no ``--emit-raw``.
+EMIT_RAW_CAPTURES = (OPERAND_CAPTURES[0], TOLERANCE_INVENTORY_CAPTURE)
+
+_DESCRIPTION = (
+    "Build the OptiVibe reference data (glass catalog, manual corpus, merit and "
+    "tolerance operand catalogs) locally from your licensed OpticStudio install. "
+    "A missing input is SKIPPED; the exit code is the number of FAILED steps."
+)
+
+
+def _ascii(text):
+    """``text`` with every non-ASCII character replaced (status output is ASCII-only)."""
+    return str(text).encode("ascii", "replace").decode("ascii")
+
+
+def _say(text):
+    print(_ascii(text))
+
+
+def _error_text(exc):
+    return _ascii("%s: %s" % (type(exc).__name__, exc))
+
+
+def _captures_present(names, captures=None):
+    captures = _paths.captures_dir() if captures is None else captures
+    return all(os.path.isfile(os.path.join(captures, n)) for n in names)
+
+
+def probed_count(capture_path):
+    """The ``inventory_count`` a probe recorded in its capture, or None.
+
+    None when the capture is absent, unreadable, or carries no integer count.
+    """
+    try:
+        with open(capture_path, encoding="utf-8") as fh:
+            count = json.load(fh).get("inventory_count")
+    except (OSError, ValueError, AttributeError):
+        return None
+    return count if isinstance(count, int) and not isinstance(count, bool) else None
+
+
+def catalog_step_blocker(captures, captures_dir=None):
+    """Why this operand/tolerance catalog cannot be built for the probed install, or None.
+
+    ``captures`` is ``(<kind>_inventory_<N>.json, probe_<kind>s_capture.json)``; N is the
+    operand count the shipped curated data (sign conventions, run-verdict buckets) was
+    built against. The probe names its inventory by the LIVE count, so an OpticStudio
+    with a different operand list writes a different file and the curated data does not
+    cover it. That is not a missing probe, so it must not be reported as one.
+    """
+    captures_dir = _paths.captures_dir() if captures_dir is None else captures_dir
+    curated = int(re.search(r"_(\d+)\.json$", captures[0]).group(1))
+    probed = probed_count(os.path.join(captures_dir, captures[1]))
+    if probed is None or probed == curated:
+        return None
+    kind = "tolerance" if captures[0].startswith("tolerance") else "merit"
+    return ("your OpticStudio exposes %d %s operands; the curated data shipped with "
+            "this release covers the %d it was built against, so this catalog cannot "
+            "be built for your OpticStudio version yet (re-running the probes will not "
+            "change that)." % (probed, kind, curated))
+
+
+def _run_probe(label, probe_main):
+    """Run one live probe; return 1 iff it FAILED (a missing pythonnet included)."""
+    # Lazy: importing the probe modules is cheap and clr-free, but keep them off the
+    # import path of a plain build run.
+    from ._probe_common import PROBE_EXTRA_HINT, PythonnetMissing
+    try:
+        rc = probe_main()
+    except PythonnetMissing:
+        _say("[%s] FAILED - pythonnet is not installed, so the live probe cannot run. "
+             "%s." % (label, PROBE_EXTRA_HINT))
+        return 1
+    except Exception as exc:  # noqa: BLE001 — report per-step, keep going
+        _say("[%s] FAILED - %s" % (label, _error_text(exc)))
+        return 1
+    if rc:
+        _say("[%s] FAILED - probe returned exit code %d (see messages above)." % (label, rc))
+        return 1
+    return 0
+
+
+def run_probes():
+    """Step 0: the two live probes, merit first. Returns the number that FAILED."""
+    from . import probe_operands, probe_tolerances
+    failures = 0
+    _say("=== [probe 1/2] merit operand surface (boots a headless OpticStudio) ===")
+    failures += _run_probe("probe-operands", lambda: probe_operands.main())
+    _say("=== [probe 2/2] tolerance operand surface (boots a headless OpticStudio) ===")
+    failures += _run_probe("probe-tolerances", lambda: probe_tolerances.main())
+    return failures
+
+
+def _run_catalog_step(label, captures, build_main):
+    """Run a user-built operand/tolerance catalog build; return 1 iff it FAILED.
+
+    Absent live-probe captures = a fresh install that has not probed yet -> SKIP
+    (that domain's operand tools answer operand_catalog_unavailable until built).
+    Present captures + a raised error OR a nonzero build exit code -> FAILED.
+    """
+    blocker = catalog_step_blocker(captures)
+    if blocker is not None:
+        _say("[%s] SKIPPED - %s" % (label, blocker))
+        _say("[%s] this operand family answers operand_catalog_unavailable."
+             % label)
+        return 0
+    if not _captures_present(captures):
+        _say("[%s] SKIPPED - live-probe captures not present in %s. Run the probes "
+             "against your OpticStudio first: optivibe-build-data --probe"
+             % (label, _paths.captures_dir()))
+        _say("[%s] this operand family answers operand_catalog_unavailable until "
+             "the build runs." % label)
+        return 0
+    try:
+        rc = build_main()
+    except Exception as exc:  # noqa: BLE001 — report per-step, keep going
+        _say("[%s] FAILED - %s" % (label, _error_text(exc)))
+        return 1
+    if rc:
+        _say("[%s] FAILED - build returned exit code %d (see messages above)."
+             % (label, rc))
+        return 1
+    return 0
+
+
+def _run_glass_step():
+    """Step 1; return 1 iff it FAILED. No Glasscat dir -> SKIPPED."""
+    try:
+        build_steps.build_glass_catalog()
+    except FileNotFoundError as exc:
+        _say("[glass-build] SKIPPED - %s" % _ascii(exc))
+        _say("[glass-build] glass tools answer glass_catalog_unavailable until "
+             "this build runs.")
+        return 0
+    except Exception as exc:  # noqa: BLE001 — report per-step, keep going
+        _say("[glass-build] FAILED - %s" % _error_text(exc))
+        return 1
+    return 0
+
+
+def _run_manual_step():
+    """Step 2; return 1 iff it FAILED. No PDF or no PyMuPDF -> SKIPPED."""
+    pdf = build_steps.find_manual_pdf()
+    if pdf is None:
+        _say("[manual-build] SKIPPED - manual PDF not present (set OPTIVIBE_MANUAL_PDF "
+             "or install OpticStudio).")
+        _say("[manual-build] search_reference answers corpus_unavailable until this "
+             "build runs.")
+        return 0
+    if importlib.util.find_spec("fitz") is None:
+        _say("[manual-build] SKIPPED - PyMuPDF is not installed, so the manual PDF "
+             "cannot be read. install optivibe-reference[manual] "
+             '(pip install "optivibe-reference[manual]").')
+        return 0
+    try:
+        # --emit-raw ALSO writes the gitignored operand/tolerance raw oracles that
+        # steps 3-4 merge as verbatim-local descriptions. It opens BOTH inventory
+        # captures unconditionally (merit for the glued-code gate, tolerance for the
+        # tolerance oracle) — either absent, --emit-raw raises FileNotFoundError mid-run
+        # and the whole manual step is mis-reported FAILED. Preflight both: emit the
+        # oracles only when both are present, else build the corpus WITHOUT --emit-raw —
+        # the SAME fresh-install degrade steps 3-4 take (operand/tolerance stay
+        # synonyms-only / unavailable), never a FAIL.
+        if _captures_present(EMIT_RAW_CAPTURES):
+            emit_args = ["--emit-raw"]
+        else:
+            emit_args = []
+            _say("[manual-build] NOTE: an operand inventory capture is absent -> building "
+                 "corpus WITHOUT --emit-raw; operand/tolerance catalogs stay "
+                 "synonyms-only until the live-probe captures are regenerated.")
+        build_steps.build_manual_corpus(emit_args, find_pdf=lambda: pdf)
+    except Exception as exc:  # noqa: BLE001 — report per-step, keep going
+        _say("[manual-build] FAILED - %s" % _error_text(exc))
+        return 1
+    return 0
+
+
+def parse_args(argv):
+    parser = argparse.ArgumentParser(prog="optivibe-build-data", description=_DESCRIPTION)
+    parser.add_argument(
+        "--probe", action="store_true",
+        help="first run the live operand + tolerance probes (boots a headless "
+             "OpticStudio; needs pythonnet: optivibe-reference[probe])")
+    return parser.parse_args(argv)
+
+
+def main(argv=None):
+    """Run every step; return the number of FAILED steps (``--help`` exits 0)."""
+    args = parse_args(list(sys.argv[1:] if argv is None else argv))
+    failures = 0
+
+    if args.probe:
+        failures += run_probes()
+
+    _say("=== [1/4] glass catalog (from your install's .agf Glasscat) ===")
+    failures += _run_glass_step()
+
+    _say("=== [2/4] manual corpus + verbatim raw oracles (from your install's PDF) ===")
+    failures += _run_manual_step()
+
+    _say("=== [3/4] merit operand catalog (user-built; synonyms + local oracle) ===")
+    failures += _run_catalog_step(
+        "operand-build", OPERAND_CAPTURES, lambda: catalog_build.main()
+    )
+
+    _say("=== [4/4] tolerance operand catalog (user-built; synonyms + local oracle) ===")
+    failures += _run_catalog_step(
+        "tolerance-build", TOLERANCE_CAPTURES, lambda: tolerance_build.main()
+    )
+
+    if failures:
+        _say("done with %d FAILED step(s) - see messages above." % failures)
+    else:
+        _say("done. Built data is local-only and gitignored - never commit it.")
+    return failures
+
+
+if __name__ == "__main__":
+    sys.exit(main())