optivibe-reference 0.2.0__tar.gz → 0.2.1__tar.gz

{optivibe_reference-0.2.0 → optivibe_reference-0.2.1}/PKG-INFO

@@ -1,11 +1,10 @@
 Metadata-Version: 2.4
 Name: optivibe-reference
-Version: 0.2.0
+Version: 0.2.1
 Summary: OptiVibe reference layer: lookup tables + RAG + intent->ZOS-API grounding
-License: Apache-2.0
+License-Expression: 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

{optivibe_reference-0.2.0 → optivibe_reference-0.2.1}/pyproject.toml

@@ -20,18 +20,17 @@
 # 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"]
+requires = ["setuptools>=77"]
 build-backend = "setuptools.build_meta"
 
 [project]
 name = "optivibe-reference"
-version = "0.2.0"
+version = "0.2.1"
 description = "OptiVibe reference layer: lookup tables + RAG + intent->ZOS-API grounding"
 requires-python = ">=3.11"
 readme = "README.md"
-license = {text = "Apache-2.0"}
+license = "Apache-2.0"
 classifiers = [
-    "License :: OSI Approved :: Apache Software License",
     "Programming Language :: Python :: 3.11",
 ]
 dependencies = []

{optivibe_reference-0.2.0 → optivibe_reference-0.2.1}/src/optivibe_reference/__init__.py

@@ -11,4 +11,4 @@ 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"
+__version__ = "0.2.1"

{optivibe_reference-0.2.0 → optivibe_reference-0.2.1}/src/optivibe_reference/build_data.py

@@ -69,8 +69,18 @@ def _say(text):
     print(_ascii(text))
 
 
+_NOT_WRITABLE_HINT = (
+    " (if the install location is not writable -- the build writes into the "
+    "package's data and captures directories, so install optivibe-mcp into a virtual "
+    "environment, or use `pip install --user`, then re-run.)"
+)
+
+
 def _error_text(exc):
-    return _ascii("%s: %s" % (type(exc).__name__, exc))
+    text = "%s: %s" % (type(exc).__name__, exc)
+    if isinstance(exc, PermissionError):
+        text += _NOT_WRITABLE_HINT
+    return _ascii(text)
 
 
 def _captures_present(names, captures=None):
@@ -91,6 +101,16 @@ def probed_count(capture_path):
     return count if isinstance(count, int) and not isinstance(count, bool) else None
 
 
+def _capture_incomplete(capture_path):
+    """True iff the capture reads and says ``ok: false``: a probe that failed after its first
+    step writes its capture early (so the count matches the new inventory) but never marks it ok."""
+    try:
+        with open(capture_path, encoding="utf-8") as fh:
+            return json.load(fh).get("ok") is False
+    except (OSError, ValueError, AttributeError):
+        return False
+
+
 def catalog_step_blocker(captures, captures_dir=None):
     """Why this operand/tolerance catalog cannot be built for the probed install, or None.
 
@@ -102,8 +122,12 @@ def catalog_step_blocker(captures, captures_dir=None):
     """
     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]))
+    capture = os.path.join(captures_dir, captures[1])
+    probed = probed_count(capture)
     if probed is None or probed == curated:
+        if _capture_incomplete(capture):
+            return ("the last live probe did not finish (%s is marked incomplete), so this "
+                    "catalog is not built from it; re-run `optivibe-build-data --probe`." % captures[1])
         return None
     kind = "tolerance" if captures[0].startswith("tolerance") else "merit"
     return ("your OpticStudio exposes %d %s operands; the curated data shipped with "
@@ -112,11 +136,20 @@ def catalog_step_blocker(captures, captures_dir=None):
             "change that)." % (probed, kind, curated))
 
 
-def _run_probe(label, probe_main):
-    """Run one live probe; return 1 iff it FAILED (a missing pythonnet included)."""
+def _run_probe(label, module_name):
+    """Run one live probe; return 1 iff it FAILED (a missing pythonnet included).
+
+    The probe module is imported INSIDE the guard, so a broken import is that probe's
+    FAILED report and the other probe still runs.
+    """
     # 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:
+        from ._probe_common import PROBE_EXTRA_HINT, PythonnetMissing
+        probe_main = importlib.import_module("." + module_name, __package__).main
+    except Exception as exc:  # noqa: BLE001 — report per-step, keep going
+        _say("[%s] FAILED - cannot import the probe: %s" % (label, _error_text(exc)))
+        return 1
     try:
         rc = probe_main()
     except PythonnetMissing:
@@ -134,12 +167,11 @@ def _run_probe(label, probe_main):
 
 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())
+    failures += _run_probe("probe-operands", "probe_operands")
     _say("=== [probe 2/2] tolerance operand surface (boots a headless OpticStudio) ===")
-    failures += _run_probe("probe-tolerances", lambda: probe_tolerances.main())
+    failures += _run_probe("probe-tolerances", "probe_tolerances")
     return failures
 
 

{optivibe_reference-0.2.0 → optivibe_reference-0.2.1}/src/optivibe_reference/catalog_build.py

@@ -519,6 +519,9 @@ def build_catalog_json(
     """
     inventory = _load_json(inventory_path)
     probe = _load_json(probe_capture_path)
+    _require(probe.get("ok") is not False,
+             "the probe capture %s is marked incomplete (ok: false): the last live probe did not "
+             "finish; re-run `optivibe-build-data --probe`" % probe_capture_path)
 
     synonyms = load_synonyms_rows(synonyms_path) if synonyms_path else {}
     # The verbatim-local descriptions (gitignored). ``None`` (path absent or not

{optivibe_reference-0.2.0 → optivibe_reference-0.2.1}/src/optivibe_reference/glass_build.py

@@ -25,6 +25,7 @@ CLOSED unless the ``.agf``-derivation ledger row is on file in ``PROVENANCE.md``
 """
 import json
 import os
+import re
 import sqlite3
 
 from . import _paths
@@ -42,7 +43,7 @@ from .glass_dispersion import (
 )
 from .glass_parse import find_catalogs, iter_glass_records
 
-SCHEMA_VERSION = 1
+SCHEMA_VERSION = 2
 BUILDER_VERSION = 1
 
 # A computed value whose |nF-nC| denominator is below this floor is a near-flat-
@@ -108,6 +109,11 @@ def in_band(min_wave, max_wave, line):
             and min_wave <= line <= max_wave)
 
 
+# NM status code -> name (the five names; any other code or None reads None).
+STATUS_NAMES = {0: "standard", 1: "preferred", 2: "obsolete", 3: "special", 4: "melt"}
+_BUILD_KEYS = ("tce", "relative_cost", "climate", "stain", "acid", "alkali", "phosphate")
+
+
 def _build_row(rec):
     """Recompute one parsed record into a committed-JSON row dict (§5/§6)."""
     formula = rec["formula"]
@@ -169,6 +175,9 @@ def _build_row(rec):
         "nd_valid": nd_valid,
         "pg_f_valid": pg_f_valid,
         "provenance": "agf_recompute",
+        "status": STATUS_NAMES.get(rec.get("status_code")),
+        **{k: rec.get(k) for k in _BUILD_KEYS},
+        "it": rec.get("it") or [],
     }
 
 
@@ -289,6 +298,9 @@ def write_glass_catalog_json(out_path, catalog):
     """
     os.makedirs(os.path.dirname(out_path), exist_ok=True)
     text = json.dumps(catalog, indent=2, ensure_ascii=True)
+    # each row's ``it`` list on ONE line (it would otherwise take one line per number)
+    text = re.sub(r'(?<="it": )\[\n.*?\n      \]',
+                  lambda m: json.dumps(json.loads(m.group(0))), text, flags=re.DOTALL)
     with open(out_path, "w", encoding="utf-8", newline="\n") as fh:
         fh.write(text)
         fh.write("\n")
@@ -321,6 +333,15 @@ CREATE TABLE glass (
     nd_valid      INTEGER NOT NULL,
     pg_f_valid    INTEGER NOT NULL,
     provenance    TEXT,
+    status        TEXT,
+    tce           REAL,
+    relative_cost REAL,
+    climate       REAL,
+    stain         REAL,
+    acid          REAL,
+    alkali        REAL,
+    phosphate     REAL,
+    it            TEXT,
     PRIMARY KEY (catalog, name)
 )
 """
@@ -354,7 +375,8 @@ def build_glass_db(catalog_json_path, conn):
     in use — YAGNI).
 
     The SQL ``PRIMARY KEY (catalog, name)`` raises ``IntegrityError`` on a
-    duplicate (the storage-layer dedupe). ``cd`` is stored as a JSON string. The
+    duplicate (the storage-layer dedupe). ``cd`` and ``it`` are stored as JSON strings (a schema-1
+    JSON has no buildability keys: those columns read NULL). The
     ``*_valid`` flags are stored as 0/1 INTEGERs. Returns ``conn``.
     """
     # One-shot precondition: a pre-existing ``glass`` table means this connection
@@ -374,8 +396,9 @@ def build_glass_db(catalog_json_path, conn):
         conn.execute(
             "INSERT INTO glass (catalog, name, formula, formula_name, cd, "
             "min_wave, max_wave, nd_stored, vd_stored, delta_pg_f, nd, ng, nf, "
-            "nc, vd, pg_f, nd_valid, pg_f_valid, provenance) "
-            "VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)",
+            "nc, vd, pg_f, nd_valid, pg_f_valid, provenance, status, tce, "
+            "relative_cost, climate, stain, acid, alkali, phosphate, it) "
+            "VALUES (" + ", ".join("?" * 28) + ")",
             (
                 row["catalog"],
                 row["name"],
@@ -396,6 +419,9 @@ def build_glass_db(catalog_json_path, conn):
                 1 if row.get("nd_valid") else 0,
                 1 if row.get("pg_f_valid") else 0,
                 row.get("provenance"),
+                row.get("status"),
+                *(row.get(k) for k in _BUILD_KEYS),
+                json.dumps(row["it"]) if row.get("it") is not None else None,
             ),
         )
     conn.commit()

{optivibe_reference-0.2.0 → optivibe_reference-0.2.1}/src/optivibe_reference/glass_parse.py

@@ -19,11 +19,15 @@ glass names are committed).
 Record grammar (opened by ``NM``):
     name=NM[1], formula=parse_formula_field(NM[2]), nd_stored=NM[4], vd_stored=NM[5];
     density=ED[3], dpgf=ED[4]; cd=CD[1:]; min_wave=LD[1], max_wave=LD[2].
+    Also (-1 or absent reads None): status_code=NM[7], tce=ED[1] (0 reads None), OD[1..6], IT rows.
 """
 import glob
 import os
 
 
+_OD_KEYS = ("relative_cost", "climate", "stain", "acid", "alkali", "phosphate")
+
+
 def parse_formula_field(tok):
     """Parse NM field 3 robustly (handles '1.00000000E+00' sci-notation -> 1).
 
@@ -54,6 +58,14 @@ def parse_float(tok):
         return None
 
 
+def _field(p, i):
+    """Float of split field ``i``, or None when absent, unparseable or the file's unset marker -1."""
+    v = parse_float(p[i]) if len(p) > i else None
+    if v is None or abs(v + 1.0) < 1e-9:
+        return None
+    return v
+
+
 def _decode_agf(raw):
     """Decode raw .agf bytes: BOM sniff -> BOM-less UTF-8 attempt -> latin-1.
 
@@ -105,6 +117,9 @@ def iter_glass_records(path):
     minw = maxw = None
     have = False
     formula_is_sci = False
+    status_code = tce = None
+    od = {}
+    it = []
 
     def emit():
         return {
@@ -112,6 +127,7 @@ def iter_glass_records(path):
             "density": density, "dpgf": dpgf, "cd": cd,
             "min_wave": minw, "max_wave": maxw, "catalog": os.path.basename(path),
             "formula_is_sci": formula_is_sci,
+            "status_code": status_code, "tce": tce, "it": it, **od,
         }
 
     with open(path, "rb") as fh:
@@ -131,14 +147,28 @@ def iter_glass_records(path):
             density = dpgf = None
             cd = None
             minw = maxw = None
+            status_code = _field(p, 7)
+            status_code = int(status_code) if status_code is not None and status_code.is_integer() else None
+            tce = None
+            od = dict.fromkeys(_OD_KEYS)
+            it = []
             have = True
         elif ln.startswith("ED ") and have:
             # ED tce1 tce2 density dPgF ...  (dPgF = ED field 4 -> token[4])
             p = ln.split()
             density = parse_float(p[3]) if len(p) > 3 else None
             dpgf = parse_float(p[4]) if len(p) > 4 else None
+            tce = _field(p, 1) or None
         elif ln.startswith("CD ") and have:
             cd = [parse_float(x) for x in ln.split()[1:]]
+        elif ln.startswith("OD ") and have:
+            p = ln.split()
+            od = {k: _field(p, i) for i, k in enumerate(_OD_KEYS, 1)}
+        elif ln.startswith("IT ") and have:
+            p = ln.split()
+            w, t, d = _field(p, 1), _field(p, 2), _field(p, 3)
+            if None not in (w, t, d) and d > 0:
+                it.append([w, t, d])
         elif ln.startswith("LD ") and have:
             p = ln.split()
             minw = parse_float(p[1]) if len(p) > 1 else None

{optivibe_reference-0.2.0 → optivibe_reference-0.2.1}/src/optivibe_reference/manual_enrich.py

@@ -38,8 +38,8 @@ MERIT_INVENTORY_PATH = os.path.join(
 def load_merit_operand_inventory(path=MERIT_INVENTORY_PATH):
     """Return the merit operand code set (a ``frozenset``) from the user-built inventory.
 
-    A missing file names its PRODUCER: the capture is written by ``scripts/probe_operands.py``
-    (a live probe).
+    A missing file names its PRODUCER: the capture is written by the live probe
+    (``optivibe-build-data --probe``; in a clone also ``scripts/probe_operands.py``).
 
     Raises loudly (``OSError`` / ``KeyError`` / ``ValueError``) on a missing or
     malformed file — the caller must never silently fall back to the ungated pairer.
@@ -49,9 +49,11 @@ def load_merit_operand_inventory(path=MERIT_INVENTORY_PATH):
             inventory = json.load(fh)
     except FileNotFoundError as exc:
         raise FileNotFoundError(
-            f"merit operand inventory {path} is missing -- it is written by "
-            f"packages/optivibe-reference/scripts/probe_operands.py (a live probe; "
-            f"operand_inventory_<N>.json under scripts/captures/)") from exc
+            f"merit operand inventory {path} is missing -- it is written by the live "
+            f"probe: run `optivibe-build-data --probe` (searched captures dir: "
+            f"{os.path.dirname(os.path.abspath(path))}). In a clone the same probe is "
+            f"packages/optivibe-reference/scripts/probe_operands.py "
+            f"(operand_inventory_<N>.json under scripts/captures/)") from exc
     codes = frozenset(m["code"] for m in inventory["members"])
     if len(codes) != inventory["total_members"]:
         raise ValueError(
@@ -75,9 +77,11 @@ def load_tolerance_operand_inventory(path=None):
             inventory = json.load(fh)
     except FileNotFoundError as exc:
         raise FileNotFoundError(
-            f"tolerance operand inventory {path} is missing -- it is written by "
-            f"packages/optivibe-reference/scripts/probe_tolerances.py (a live probe; "
-            f"tolerance_inventory_<N>.json under scripts/captures/)") from exc
+            f"tolerance operand inventory {path} is missing -- it is written by the "
+            f"live probe: run `optivibe-build-data --probe` (searched captures dir: "
+            f"{os.path.dirname(os.path.abspath(path))}). In a clone the same probe is "
+            f"packages/optivibe-reference/scripts/probe_tolerances.py "
+            f"(tolerance_inventory_<N>.json under scripts/captures/)") from exc
     codes = frozenset(m["code"] for m in inventory["members"])
     if len(codes) != inventory["total_members"]:
         raise ValueError(

{optivibe_reference-0.2.0 → optivibe_reference-0.2.1}/src/optivibe_reference/probe_operands.py

@@ -198,6 +198,10 @@ def main():
         }
         report["inventory_count"] = n
         report["inventory_file"] = write_json(f"operand_inventory_{n}.json", inventory)
+        # Write the capture NOW (ok False = incomplete) so its inventory_count matches the
+        # inventory just written even if P2-P4 or the teardown raises; the final write
+        # below overwrites it.
+        write_json("probe_operands_capture.json", report)
 
         # --- P2: live-label existence ---
         print("[probe] P2 — live-label existence (TypeName/RowTypeName/AvailableOperandTypes)")

{optivibe_reference-0.2.0 → optivibe_reference-0.2.1}/src/optivibe_reference/probe_tolerances.py

@@ -341,6 +341,10 @@ def main():
         }
         report["inventory_count"] = n
         report["inventory_file"] = write_json(f"tolerance_inventory_{n}.json", inventory)
+        # Write the capture NOW (ok False = incomplete) so its inventory_count matches the
+        # inventory just written even if P2-P4 or the teardown raises; the final write
+        # below overwrites it.
+        write_json("probe_tolerances_capture.json", report)
 
         # --- P2: live-label existence ---
         print("[probe] P2 — live-label existence (TypeName/RowTypeName/Comment/...)")

{optivibe_reference-0.2.0 → optivibe_reference-0.2.1}/src/optivibe_reference/tolerance_build.py

@@ -255,6 +255,9 @@ def build_tolerance_catalog_json(
     """
     inventory = _load_json(inventory_path)
     capture = _load_json(capture_path)
+    catalog_build._require(capture.get("ok") is not False,
+                           "the probe capture %s is marked incomplete (ok: false): the last live probe did not "
+                           "finish; re-run `optivibe-build-data --probe`" % capture_path)
 
     synonyms = (
         catalog_build.load_synonyms_rows(synonyms_path, tolerance=True)

{optivibe_reference-0.2.0 → optivibe_reference-0.2.1}/src/optivibe_reference/tools/find_glass_pair.py

@@ -184,7 +184,7 @@ def _load_pair_eligible(db_conn, catalogs):
         where += f" AND LOWER(catalog) IN ({marks})"
         sql_params.extend(c.lower() for c in catalogs)
     sql = (
-        "SELECT catalog, name, vd, pg_f, nd FROM glass "
+        "SELECT catalog, name, vd, pg_f, nd, tce FROM glass "
         f"WHERE {where} ORDER BY pg_f, catalog, name"
     )
     return db_conn.execute(sql, sql_params).fetchall()
@@ -226,7 +226,7 @@ def _resolve_anchor(db_conn, anchor, anchor_catalog, catalogs):
         sql_params.append(anchor_catalog)
     rows = db_conn.execute(
         "SELECT catalog, name, vd, pg_f, nd, pg_f_valid, "
-        "(vd IS NOT NULL), nd_valid FROM glass "
+        "(vd IS NOT NULL), nd_valid, tce FROM glass "
         f"WHERE {where} ORDER BY catalog",
         sql_params,
     ).fetchall()
@@ -298,18 +298,22 @@ def _pair_numbers(a, b):
     }
 
 
-def _pair_dict(a, b, delta_vd, delta_pg_f, score):
+def _pair_dict(a, b, delta_vd, delta_pg_f, score, anchor_row=None):
     """Build one result pair dict with the HIGHER-Vd glass as ``a`` for stability."""
     # Canonical orientation: the higher-Vd (crown-ish) glass first is a stable,
     # readable convention. a/b are (catalog, name, vd, pg_f, nd) tuples.
     if a[2] < b[2]:
         a, b = b, a
+    # delta_tce = tce(second) - tce(first), the anchor first when there is one; None if either is unknown.
+    first, second = (b, a) if anchor_row and (b[0], b[1]) == anchor_row[:2] else (a, b)
+    delta_tce = None if None in (first[5], second[5]) else round(second[5] - first[5], 3)
     return {
         "a": {"catalog": a[0], "name": a[1], "vd": a[2], "pg_f": a[3], "nd": a[4]},
         "b": {"catalog": b[0], "name": b[1], "vd": b[2], "pg_f": b[3], "nd": b[4]},
         "delta_vd": delta_vd,
         "delta_pg_f": delta_pg_f,
         "score": score,
+        "delta_tce": delta_tce,
         **_pair_numbers(a, b),
     }
 
@@ -334,14 +338,14 @@ def _emit_pairs(eligible, cluster_ids, max_delta_pg_f, min_delta_vd, anchor_row)
     # so an emitted (A, B) never re-appears as (B, A).
     hi = 0
     for i in range(n):
-        cat_i, name_i, vd_i, pgf_i, nd_i = eligible[i]
+        cat_i, name_i, vd_i, pgf_i, nd_i = eligible[i][:5]
         cid_i = cluster_ids[i]
         if hi < i + 1:
             hi = i + 1
         while hi < n and (eligible[hi][3] - pgf_i) <= max_delta_pg_f:
             hi += 1
         for j in range(i + 1, hi):
-            cat_j, name_j, vd_j, pgf_j, nd_j = eligible[j]
+            cat_j, name_j, vd_j, pgf_j, nd_j = eligible[j][:5]
             cid_j = cluster_ids[j]
             # Self-pair exclusion: same physical glass (same cluster) OR the exact
             # same (catalog, name) row. A same-name-but-DIFFERENT-properties pair
@@ -365,7 +369,7 @@ def _emit_pairs(eligible, cluster_ids, max_delta_pg_f, min_delta_vd, anchor_row)
                     continue
             score = _score(delta_vd, delta_pg_f)
             pair = _pair_dict(
-                eligible[i], eligible[j], delta_vd, delta_pg_f, score
+                eligible[i], eligible[j], delta_vd, delta_pg_f, score, anchor_row
             )
             # Stash the unordered physical-identity key for the dedup step.
             pair["_cluster_key"] = frozenset((cid_i, cid_j))
@@ -492,7 +496,7 @@ def find_glass_pair(db_conn, params):
                     "dispersion) - no pairs"
                 ),
             }
-        anchor_row = (resolved[0], resolved[1], resolved[2], resolved[3], resolved[4])
+        anchor_row = (resolved[0], resolved[1], resolved[2], resolved[3], resolved[4], resolved[8])
 
     eligible, left_out_kinds, unclassified = _build_pool(
         db_conn, catalogs, excluded, anchor_row, max_delta_pg_f, min_delta_vd
@@ -555,7 +559,8 @@ FIND_GLASS_PAIR_SPEC = ToolSpec(
         "heuristic prefilter, and cut at limit; a smaller max_delta_pg_f brings "
         "low secondary-colour pairs to the top. Each pair also carries "
         "secondary_per_focal, power_sum and petzval_per_power for a thin cemented "
-        "doublet of the pair; read caveat in the result. Gotcha: an ambiguous bare anchor name returns an "
+        "doublet of the pair, and delta_tce (thermal expansion of the second glass minus "
+        "the first, the anchor first; null when either is unknown); read caveat in the result. Gotcha: an ambiguous bare anchor name returns an "
         "ambiguous_glass candidate list - qualify the catalog. See find_glasses to "
         "window-search single glasses. See lookup_glass for one glass's full data."
     ),

{optivibe_reference-0.2.0 → optivibe_reference-0.2.1}/src/optivibe_reference/tools/find_glasses.py

@@ -20,7 +20,7 @@ NEVER-RAISE contract (mirrors ``lookup_glass`` / §7):
 - a ``min > max`` window is a ``ToolParamError`` (an empty-by-construction window
   is a caller mistake, not a legitimately-empty result);
 - AT LEAST ONE window bound is required (a bare ``find_glasses`` with no window
-  would dump the whole 4783-row catalog — refuse it as a ``ToolParamError``).
+  would dump the whole 4782-row catalog — refuse it as a ``ToolParamError``).
 
 THE VALIDITY GATE (the cardinal defense surfaced at the window boundary): a
 computed field (``vd``, ``pg_f``, ``nd``) is NULL in the row when it was NOT
@@ -45,14 +45,26 @@ see ``_glass_kind``) leaves rows of those kinds out; the result carries ``left_o
 (always), ``left_out_kinds`` (only when > 0) and ``unclassified`` (only when > 0).
 Rows are classified in Python BEFORE the limit, so the counts cover every match.
 
+COPIES: one glass redistributed by several catalogs (same name, ``_same_physical_glass``) is
+listed once, after the kind and opt-in screens and before the limit. The first copy in the sort
+order stays and names the catalogs of the removed copies in ``also_in``. A copy is removed only
+when it adds nothing: the optical values (nd, vd, pg_f, and the ``pg_f_anomaly`` computed from
+them) match within the identity tolerance, and every other listed value other than ``catalog`` plus
+the stored transmission data is equal; otherwise both stay. The kept row's ``pg_f_anomaly`` is its
+own. Two nulls are equal, a null against a known value differs. ``matched`` counts
+the rows after removal, ``duplicates_removed`` the rows removed; ``left_out``, ``screened_out``
+and ``unknown_kept`` count before removal. ``dedupe=False`` lists every copy.
+
 An empty result over a WELL-FORMED window is ``ok: True`` with an empty
 ``candidates`` list — a valid window can legitimately match nothing.
 """
+import bisect
+import json
 import math
 
 from ..errors import ToolParamError
 from ..server import ToolSpec
-from ._glass_common import check_catalogs_exist, normalize_catalogs
+from ._glass_common import _same_physical_glass, check_catalogs_exist, normalize_catalogs
 from ._glass_kind import material_kind, parse_exclude
 
 _TOOL = "find_glasses"
@@ -83,8 +95,21 @@ _RESULT_COLUMNS = (
     "formula_name",
     "min_wave",
     "max_wave",
-    "pg_f_anomaly",
+    "status",
+    "relative_cost",
+    "climate",
+    "stain",
+    "acid",
+    "tce",
+    "pg_f_anomaly",     # stays the last key
 )
+# A copy is removed only when every one of these (plus the stored transmission data) equals the kept row's.
+_COPY_COLUMNS = ("delta_pg_f", "formula", "formula_name", "min_wave", "max_wave", "status",
+                 "relative_cost", "climate", "stain", "acid", "tce")
+_STATUS_NAMES = ("standard", "preferred", "obsolete", "special", "melt")
+# Opt-in caps: param -> result column.
+_MAX_FILTERS = (("max_relative_cost", "relative_cost"), ("max_climate", "climate"),
+                ("max_stain", "stain"))
 
 # The window params: each maps the public ``<field>_min`` / ``<field>_max`` pair
 # onto a real glass column. ``valid_only=True`` adds the ``<col> IS NOT NULL``
@@ -144,6 +169,39 @@ def _validate_bound(name, value):
     return float(value)
 
 
+def _resolve_dedupe(params):
+    """Resolve ``dedupe`` (default True); a bool only, so 0 / 1 / "true" are refused."""
+    value = params.get("dedupe", True)
+    if not isinstance(value, bool):
+        raise ToolParamError(f"'dedupe' must be a bool; got {type(value).__name__}")
+    return value
+
+
+def _remove_copies(rows):
+    """Drop later copies of one glass; return ``(kept, also_in, removed)``.
+
+    A row is a copy of a kept row of the same name when ``_same_physical_glass`` says so AND its
+    every other served column and the stored transmission data equal the kept row's (two nulls are
+    equal, a null against a known value is not). ``also_in[i]`` lists the catalogs removed into ``kept[i]``, in the order met.
+    """
+    col = _RESULT_COLUMNS.index
+    key = lambda r: (r[0], r[1], r[col("vd")], r[col("pg_f")], r[col("nd")])   # noqa: E731
+    same_data = [col(c) for c in _COPY_COLUMNS] + [-1]    # -1: the fetched "it" transmission data
+    same = lambda a, b: all(a[i] == b[i] for i in same_data)   # noqa: E731
+    kept, also_in, by_name, removed = [], [], {}, 0
+    for r in rows:
+        twin = next((i for i in by_name.get(r[1], ())
+                     if _same_physical_glass(key(kept[i]), key(r)) and same(kept[i], r)), None)
+        if twin is None:
+            by_name.setdefault(r[1], []).append(len(kept))
+            kept.append(r)
+            also_in.append([])
+        else:
+            also_in[twin].append(r[0])
+            removed += 1
+    return kept, also_in, removed
+
+
 def _resolve_limit(params):
     """Resolve the effective candidate cap (default 50, hard cap 200).
 
@@ -208,6 +266,51 @@ def _row_to_dict(row):
     return dict(zip(_RESULT_COLUMNS, row))
 
 
+def _transmission(it_json, wavelength):
+    """10 mm internal transmission at ``wavelength`` (um): rows rescaled by t ** (10 / d), linear
+    between neighbours, None outside the rows' range or with no rows."""
+    if not it_json:
+        return None
+    pts = sorted((w, t ** (10.0 / d)) for w, t, d in json.loads(it_json))
+    if not pts or not pts[0][0] <= wavelength <= pts[-1][0]:
+        return None
+    i = bisect.bisect_left([w for w, _ in pts], wavelength)
+    w1, t1 = pts[i]
+    if w1 == wavelength or i == 0:
+        return round(t1, 4)
+    w0, t0 = pts[i - 1]
+    return round(t0 + (t1 - t0) * (wavelength - w0) / (w1 - w0), 4)
+
+
+def _resolve_buildability(params):
+    """Validate the opt-in params; return ``(rules, wavelength)``, rules = ``(column, test)`` pairs
+    (a glass passes when the value is unknown or the test holds)."""
+    rules = []
+    if "status" in params:
+        raw = params["status"]
+        names = {x.strip().lower() for x in raw.split(",")} if isinstance(raw, str) else set()
+        if not names or not names <= set(_STATUS_NAMES):
+            raise ToolParamError(
+                f"'status' must be a comma-separated list of {', '.join(_STATUS_NAMES)}; got {raw!r}"
+            )
+        rules.append(("status", names.__contains__))
+    rules += [(col, lambda v, b=_validate_bound(key, params[key]): v <= b)
+              for key, col in _MAX_FILTERS if key in params]
+    wavelength = None
+    if "transmission_wavelength" in params:
+        wavelength = _validate_bound("transmission_wavelength", params["transmission_wavelength"])
+        if wavelength <= 0:
+            raise ToolParamError("'transmission_wavelength' must be > 0 (micrometres)")
+    if "min_transmission" in params:
+        low = _validate_bound("min_transmission", params["min_transmission"])
+        if not 0.0 <= low <= 1.0:
+            raise ToolParamError(f"'min_transmission' must be in [0, 1]; got {low}")
+        if wavelength is None:
+            raise ToolParamError("'min_transmission' needs 'transmission_wavelength'")
+        rules.append(("transmission", lambda v: v >= low))
+    return rules, wavelength
+
+
 def find_glasses(db_conn, params):
     """Window-search the glass catalog by Vd / Pg,F / Nd / ΔPg,F (never raises).
 
@@ -216,8 +319,10 @@ def find_glasses(db_conn, params):
     catalogs = normalize_catalogs(params.get("catalog"))
     excluded = parse_exclude(params.get("exclude"))
     limit = _resolve_limit(params)
+    dedupe = _resolve_dedupe(params)
     sort, order = _resolve_sort(params)
     clauses, sql_params, queried_fields = _collect_windows(params)
+    rules, t_wave = _resolve_buildability(params)
 
     if not queried_fields:
         raise ToolParamError(
@@ -239,7 +344,7 @@ def find_glasses(db_conn, params):
     # left out covers the whole match set), ordered by the sort field (vd by default, a
     # stable key for crown/flint scanning; a null field last in either direction) with
     # catalog and name as tiebreakers for determinism.
-    cols = ", ".join(_RESULT_COLUMNS)
+    cols = ", ".join(_RESULT_COLUMNS + ("it",))   # "it": fetched, never returned
     direction = " DESC" if order == "descending" else ""
     sql = (
         f"SELECT {cols} FROM {_FROM} WHERE {where_sql} "
@@ -250,6 +355,7 @@ def find_glasses(db_conn, params):
     rows = []
     left_out_kinds = {}
     unclassified = 0
+    screened_out = unknown_kept = 0
     for r in all_rows:
         kind = material_kind(r[0], r[1])
         if kind in excluded:
@@ -257,18 +363,37 @@ def find_glasses(db_conn, params):
             continue
         if kind == "unclassified":
             unclassified += 1
+        if rules:
+            vals = [(_transmission(r[-1], t_wave) if c == "transmission"
+                     else r[_RESULT_COLUMNS.index(c)], ok) for c, ok in rules]
+            if any(v is not None and not ok(v) for v, ok in vals):
+                screened_out += 1
+                continue
+            unknown_kept += any(v is None for v, _ in vals)
         rows.append(r)
 
+    # Copy removal runs after the kind and opt-in screens and BEFORE the limit.
+    if dedupe:
+        rows, also_in, duplicates_removed = _remove_copies(rows)
+    else:
+        also_in, duplicates_removed = [[] for _ in rows], 0
     matched = len(rows)
     truncated = matched > limit
-    rows = rows[:limit]
+    rows, also_in = rows[:limit], also_in[:limit]
     candidates = [_row_to_dict(r) for r in rows]
+    for cand, r, others in zip(candidates, rows, also_in):
+        anomaly = cand.pop("pg_f_anomaly")
+        cand["also_in"] = others
+        cand["transmission"] = None if t_wave is None else _transmission(r[-1], t_wave)
+        cand["pg_f_anomaly"] = anomaly
 
     result = {
         "ok": True,
         "candidates": candidates,
         "candidate_count": len(candidates),
         "matched": matched,
+        "duplicates_removed": duplicates_removed,
+        "dedupe": dedupe,
         "truncated": truncated,
         "sort": sort,
         "order": order,
@@ -285,6 +410,10 @@ def find_glasses(db_conn, params):
         result["left_out_kinds"] = left_out_kinds
     if unclassified:
         result["unclassified"] = unclassified
+    if rules:
+        result["screened_out"] = screened_out
+    if unknown_kept:
+        result["unknown_kept"] = unknown_kept
     if "delta_pg_f" in queried_fields:
         # Flag the caveat: delta_pg_f is raw, unvalidated .agf data.
         result["delta_pg_f_unvalidated"] = True
@@ -315,10 +444,21 @@ FIND_GLASSES_SPEC = ToolSpec(
         "order=descending reverses; sort=pg_f_anomaly ranks by pg_f minus the normal line "
         "0.6438 - 0.001682*vd, null when either is null, window pg_f_anomaly_min/max; a "
         "truncated list carries truncated_note saying what is hidden and how to see it) and cut at limit; matched counts the glasses in the "
-        "window that are not left out, so truncated means only the first limit of matched are listed. Gotcha: a glass whose computed "
+        "window that are not left out, after copies are removed (left_out, screened_out and unknown_kept count before removal), so truncated means only the first limit of matched are listed. Gotcha: a glass whose computed "
         "field is out-of-band (null) never matches that window, and the delta-Pg,F "
         "bounds are raw manufacturer data (unvalidated); a stored delta-Pg,F beyond "
-        "+-0.1 reads as null. See find_glass_pair for "
+        "+-0.1 reads as null. Every candidate also carries status (standard, preferred, "
+        "obsolete, special, melt), relative_cost, climate, stain, acid, tce and transmission "
+        "(internal, 10 mm path, at transmission_wavelength in micrometres, else null). "
+        "Opt-in filters, none applied by default: status (comma list), max_relative_cost, "
+        "max_climate, max_stain, min_transmission (needs transmission_wavelength); a glass "
+        "whose value is unknown is kept and counted in unknown_kept, screened_out counts "
+        "the rest, and the thresholds are the caller's. "
+        "One glass that several catalogs carry (same name, same optics) is listed once and "
+        "the kept row names the other catalogs in also_in; a copy is removed only when "
+        "its optical values (nd, vd, pg_f and the pg_f_anomaly computed from them) match "
+        "within a small tolerance and every other listed value and the transmission data are "
+        "equal, otherwise both stay, and dedupe=false lists every copy. See find_glass_pair for "
         "matched apochromat pairs. See lookup_glass for one glass's full data."
     ),
     kind="glass",
@@ -326,6 +466,7 @@ FIND_GLASSES_SPEC = ToolSpec(
         "catalog": "string",
         "exclude": "string",
         "limit": "integer",
+        "dedupe": "boolean",
         "sort": "string",
         "order": "string",
         "vd_min": "number", "vd_max": "number",
@@ -333,6 +474,9 @@ FIND_GLASSES_SPEC = ToolSpec(
         "nd_min": "number", "nd_max": "number",
         "delta_pg_f_min": "number", "delta_pg_f_max": "number",
         "pg_f_anomaly_min": "number", "pg_f_anomaly_max": "number",
+        "status": "string", "max_relative_cost": "number", "max_climate": "number",
+        "max_stain": "number", "min_transmission": "number",
+        "transmission_wavelength": "number",
     },
 )
 

{optivibe_reference-0.2.0 → optivibe_reference-0.2.1}/src/optivibe_reference.egg-info/PKG-INFO

@@ -1,11 +1,10 @@
 Metadata-Version: 2.4
 Name: optivibe-reference
-Version: 0.2.0
+Version: 0.2.1
 Summary: OptiVibe reference layer: lookup tables + RAG + intent->ZOS-API grounding
-License: Apache-2.0
+License-Expression: 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