simcon-toolkit 0.1.0__py3-none-any.whl

simcon_toolkit/_kit/templates/process-window/process_window/test_design.py

@@ -0,0 +1,113 @@
+"""Checks on the Sobol generator, before spending 1 024 cloud runs on its output.
+
+Verifies the properties the campaign actually relies on rather than reimplementing a
+reference: extensibility (the reason Sobol was chosen over LHS), prefix balance, and
+projection uniformity. Run:  python -m process_window.test_design
+"""
+
+from __future__ import annotations
+
+import numpy as np
+
+from .design import epsilon_design, sobol
+
+FAILED: list[str] = []
+
+
+def check(name: str, cond: bool, detail: str = "") -> None:
+    print(f"  {'PASS' if cond else 'FAIL'}  {name}{'  ' + detail if detail else ''}")
+    if not cond:
+        FAILED.append(name)
+
+
+def main() -> int:
+    print("Sobol generator")
+
+    # The property that makes the sweep stoppable and extensible: a longer draw must begin
+    # with the shorter one. Without this, "continue the sweep" would mean "start over".
+    a, b = sobol(256, 3), sobol(1024, 3)
+    check(
+        "extensible: sobol(1024)[:256] == sobol(256)",
+        np.allclose(a, b[:256]),
+        f"max diff {np.abs(a - b[:256]).max():.2e}",
+    )
+
+    pts = sobol(1024, 3)
+    check("shape", pts.shape == (1024, 3), str(pts.shape))
+    check("inside [0,1)", bool(pts.min() >= 0.0 and pts.max() < 1.0), f"[{pts.min():.4f}, {pts.max():.4f}]")
+
+    # Balance: for a 2^k prefix, each of the 2^k equal bins of every 1-D projection holds
+    # exactly one point. This is the defining Sobol property and a strong correctness test —
+    # a wrong direction-number table fails it immediately.
+    ok = True
+    for k in (4, 6, 8, 10):
+        n = 2**k
+        p = sobol(n, 3)
+        for d in range(3):
+            counts = np.bincount((p[:, d] * n).astype(int), minlength=n)
+            ok &= bool((counts == 1).all())
+    check("every 2^k prefix is 1-per-bin in each projection", ok)
+
+    # And confirm the documented cost of dropping index 0, so the choice of skip=0 stays a
+    # measured decision rather than a preference.
+    p = sobol(64, 3, skip=1)
+    c = np.bincount((p[:, 0] * 64).astype(int), minlength=64)
+    check(
+        "skip=1 costs exactly one empty and one doubled bin",
+        int((c == 0).sum()) == 1 and int(c.max()) == 2,
+        f"empty {(c == 0).sum()}, max {c.max()}",
+    )
+
+    # 2-D projections should be far more even than random. Compare worst-cell occupancy of a
+    # 16x16 grid against uniform random draws.
+    g = 16
+    worst_sobol = 0
+    for d0, d1 in ((0, 1), (0, 2), (1, 2)):
+        h, _, _ = np.histogram2d(pts[:, d0], pts[:, d1], bins=g, range=[[0, 1], [0, 1]])
+        worst_sobol = max(worst_sobol, int(h.max()))
+    rng = np.random.default_rng(0)
+    worst_rand = max(
+        int(np.histogram2d(*rng.random((2, 1024)), bins=g, range=[[0, 1], [0, 1]])[0].max()) for _ in range(5)
+    )
+    expected = 1024 / (g * g)
+    check(
+        "2-D projections more even than random",
+        worst_sobol < worst_rand,
+        f"sobol {worst_sobol} vs random {worst_rand} (mean {expected:.0f}/cell)",
+    )
+
+    check("no duplicate points", len(np.unique(pts, axis=0)) == 1024)
+    check("dimension guard raises", _raises(lambda: sobol(8, 99)))
+
+    print("\nEpsilon design")
+    centre = {"melt_C": 240.0, "wall_C": 40.0, "flow_cm3_s": 8.93}
+    eps = epsilon_design(centre)
+    check("count", len(eps) == 17, f"{len(eps)} points")
+    check("exactly one nominal", sum(p["kind"] == "nominal" for p in eps) == 1)
+    # Every perturbation must be physically meaningless: two orders of magnitude below what a
+    # machine can hold. If one were not, the "floor" would include a real process effect.
+    check("melt perturbations <= 0.1 K", max(abs(p["melt_C"] - centre["melt_C"]) for p in eps) <= 0.1 + 1e-9)
+    check("wall perturbations <= 0.1 K", max(abs(p["wall_C"] - centre["wall_C"]) for p in eps) <= 0.1 + 1e-9)
+    check(
+        "flow perturbations <= 0.1 %",
+        max(abs(p["flow_cm3_s"] / centre["flow_cm3_s"] - 1.0) for p in eps) <= 1e-3 + 1e-12,
+    )
+    # Distinct inputs, or the deterministic solver would return identical results and the
+    # measured spread would be a meaningless zero.
+    keys = {(round(p["melt_C"], 6), round(p["wall_C"], 6), round(p["flow_cm3_s"], 6)) for p in eps}
+    check("all epsilon points are distinct inputs", len(keys) == len(eps))
+
+    print(f"\n{'ALL PASS' if not FAILED else 'FAILURES: ' + ', '.join(FAILED)}")
+    return 1 if FAILED else 0
+
+
+def _raises(fn) -> bool:
+    try:
+        fn()
+    except Exception:
+        return True
+    return False
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

simcon_toolkit/_kit/templates/process-window/process_window/test_guardrails.py

@@ -0,0 +1,157 @@
+"""The guardrails must actually fire. A lint that never rejects anything is decoration.
+
+Run:  python -m process_window.test_guardrails
+"""
+
+from __future__ import annotations
+
+from .guardrails import (
+    GuardrailViolation,
+    check_absolute_claim_has_caveats,
+    check_criteria,
+    check_criterion,
+    check_forbidden_kpi,
+    check_noise_floor_derived,
+    lint_spec,
+)
+
+FAILED: list[str] = []
+
+
+def check(name: str, cond: bool, detail: str = "") -> None:
+    print(f"  {'PASS' if cond else 'FAIL'}  {name}{'  ' + detail if detail else ''}")
+    if not cond:
+        FAILED.append(name)
+
+
+def rejects(fn) -> bool:
+    try:
+        fn()
+    except GuardrailViolation:
+        return True
+    except Exception:
+        return False
+    return False
+
+
+def main() -> int:
+    print("Guardrail 1 — absolute pressure must never screen")
+    for expr in (
+        "p80 < 250 bar",
+        "p80_bar <= 300",
+        "max_pressure > 1.5e7 Pa",
+        "peak_pressure >= 200bar",
+        "cavity_pressure < 180",
+        "p_max > 250 mbar",
+    ):
+        check(f"rejects {expr!r}", rejects(lambda e=expr: check_criterion("t", e)))
+
+    print("\n  relative forms must be allowed through")
+    for expr in (
+        "p80_rank <= 0.70",
+        "p80_ratio < 1.2",
+        "p80_percentile <= 0.8",
+        "p80 / p80_centre < 1.15",
+        "hotspot_rank <= 0.9",
+        "(T_front - no_flow) / (melt - no_flow) >= 0.15",
+    ):
+        ok = True
+        try:
+            check_criterion("t", expr)
+        except GuardrailViolation:
+            ok = False
+        check(f"allows {expr!r}", ok)
+
+    print("\nKind and absolute flags")
+    check(
+        "rejects kind='threshold'",
+        rejects(lambda: check_criteria([{"name": "x", "expression": "a_rank<0.5", "kind": "threshold"}])),
+    )
+    check(
+        "rejects absolute:true on a criterion",
+        rejects(lambda: check_criteria([{"name": "x", "expression": "a_rank<0.5", "kind": "rank", "absolute": True}])),
+    )
+    check(
+        "accepts a clean rank criterion",
+        not rejects(lambda: check_criteria([{"name": "x", "expression": "p80_rank<=0.7", "kind": "rank"}])),
+    )
+
+    print("\nForbidden KPI — fill race")
+    check(
+        "rejects a fill-race criterion",
+        rejects(
+            lambda: check_forbidden_kpi([{"name": "race_gate", "kpi": "race_anomaly_tail", "expression": "race < 0.2"}])
+        ),
+    )
+    check(
+        "rejects fill_time_diff",
+        rejects(lambda: check_forbidden_kpi([{"name": "x", "expression": "fill_time_diff<0.1"}])),
+    )
+
+    print("\nGuardrail 2 — noise floor derived, not imported")
+    check(
+        "rejects an imported floor",
+        rejects(lambda: check_noise_floor_derived({"p80": {"basis": "imported", "n_runs": 16}})),
+    )
+    check(
+        "rejects a floor with no run count", rejects(lambda: check_noise_floor_derived({"p80": {"basis": "derived"}}))
+    )
+    check("rejects an empty floor", rejects(lambda: check_noise_floor_derived({})))
+    check(
+        "accepts a derived floor",
+        not rejects(lambda: check_noise_floor_derived({"p80": {"basis": "derived", "n_runs": 17, "floor": 1.8}})),
+    )
+
+    print("\nGuardrail 3 — absolute claims carry caveats")
+    check(
+        "rejects an uncaveated machine limit",
+        rejects(
+            lambda: check_absolute_claim_has_caveats(
+                "machine_limits", {"max_injection_pressure_bar": 1500, "absolute": True}
+            )
+        ),
+    )
+    check(
+        "accepts a caveated machine limit",
+        not rejects(
+            lambda: check_absolute_claim_has_caveats(
+                "machine_limits",
+                {"max_injection_pressure_bar": 1500, "absolute": True, "caveats": ["cavities_1_of_32"]},
+            )
+        ),
+    )
+
+    print("\nFull spec lint")
+    good = {
+        "acceptance_criteria": [
+            {"name": "pressure_ordering", "expression": "p80_rank <= 0.70", "kind": "rank", "kpi": "p80"},
+            {
+                "name": "no_flow_guard",
+                "expression": "(T_front - no_flow) / (melt - no_flow) >= 0.15",
+                "kind": "ratio",
+                "kpi": "no_flow_margin",
+            },
+        ],
+        "noise_floor": {"per_kpi": {"p80": {"basis": "derived", "n_runs": 17, "floor": 1.8}}},
+        "provenance": {
+            "machine_limits": {"max_injection_pressure_bar": 1500.0, "absolute": True, "caveats": ["cavities_1_of_32"]}
+        },
+    }
+    try:
+        passed = lint_spec(good)
+        check("clean spec passes", True, f"{len(passed)} checks")
+    except GuardrailViolation as exc:
+        check("clean spec passes", False, str(exc))
+
+    bad = dict(good)
+    bad["acceptance_criteria"] = good["acceptance_criteria"] + [
+        {"name": "sneaky", "expression": "p80 < 250 bar", "kind": "comparison"}
+    ]
+    check("spec with an absolute threshold fails", rejects(lambda: lint_spec(bad)))
+
+    print(f"\n{'ALL PASS' if not FAILED else 'FAILURES: ' + ', '.join(FAILED)}")
+    return 1 if FAILED else 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

simcon_toolkit/_kit/templates/process-window/process_window/test_surrogate.py

@@ -0,0 +1,127 @@
+"""Validate the surrogate and the effect-share estimator against known answers.
+
+A surrogate that is wrong invalidates the screening, the boundary and the centre point, so it is
+checked against analytic functions whose Sobol indices are known in closed form before it is
+trusted with 1 024 cloud runs. Run:  python -m process_window.test_surrogate
+"""
+
+from __future__ import annotations
+
+import numpy as np
+
+from .surrogate import effect_shares, effect_span, fit, sobol_indices
+
+FAILED: list[str] = []
+
+
+def check(name: str, cond: bool, detail: str = "") -> None:
+    print(f"  {'PASS' if cond else 'FAIL'}  {name}{'  ' + detail if detail else ''}")
+    if not cond:
+        FAILED.append(name)
+
+
+def main() -> int:
+    rng = np.random.default_rng(0)
+    box = np.array([[0.0, 1.0]] * 3)
+
+    print("Interpolation accuracy (smooth 3-D function)")
+
+    def f(X):
+        return np.sin(2 * X[:, 0]) + 0.5 * X[:, 1] ** 2 + 0.3 * X[:, 0] * X[:, 2]
+
+    Xtr = rng.random((300, 3))
+    s = fit(Xtr, f(Xtr), box)
+    Xte = rng.random((200, 3))
+    err = np.abs(s.predict(Xte) - f(Xte))
+    rng_y = f(Xtr).max() - f(Xtr).min()
+    check(
+        "test NRMSE < 2 %",
+        float(np.sqrt((err**2).mean()) / rng_y) < 0.02,
+        f"{np.sqrt((err**2).mean()) / rng_y * 100:.3f} %",
+    )
+    check(
+        "reproduces training data",
+        float(np.abs(s.predict(Xtr) - f(Xtr)).max()) < 0.02 * rng_y,
+        f"max {np.abs(s.predict(Xtr) - f(Xtr)).max():.4f}",
+    )
+    loo = s.loo_error()
+    check("LOO NRMSE < 3 %", loo["nrmse_range"] < 0.03, f"{loo['nrmse_range'] * 100:.3f} %")
+
+    print("\nPosterior variance behaves (drives G3 adaptive sampling)")
+    v_at = s.variance_unit(s.Xn[:20])
+    Xsparse = rng.random((12, 3)) * 0.2  # data only in a corner
+    s2 = fit(Xsparse, f(Xsparse), box)
+    v_near = float(s2.variance_unit(np.array([[0.1, 0.1, 0.1]]))[0])
+    v_away = float(s2.variance_unit(np.array([[0.9, 0.9, 0.9]]))[0])
+    check("variance ~0 at training points", float(v_at.max()) < 0.05, f"max {v_at.max():.2e}")
+    check("variance grows away from data", v_away > 10 * max(v_near, 1e-12), f"near {v_near:.2e} vs away {v_away:.2e}")
+
+    print("\nSobol indices vs closed form — Ishigami (the standard benchmark)")
+    # Ishigami on [-pi,pi]^3 with a=7,b=0.1 has analytic first-order/total indices.
+    a, b = 7.0, 0.1
+
+    def ishigami_unit(U):
+        X = -np.pi + 2 * np.pi * np.asarray(U)
+        return np.sin(X[:, 0]) + a * np.sin(X[:, 1]) ** 2 + b * X[:, 2] ** 4 * np.sin(X[:, 0])
+
+    V1 = 0.5 * (1 + b * np.pi**4 / 5) ** 2
+    V2 = a**2 / 8
+    V13 = b**2 * np.pi**8 * (1 / 18 - 1 / 50)
+    V = V1 + V2 + V13
+    exp_S1 = np.array([V1 / V, V2 / V, 0.0])
+    exp_ST = np.array([(V1 + V13) / V, V2 / V, V13 / V])
+    got = sobol_indices(ishigami_unit, 3, n=200_000, seed=1)
+    s1, st = np.array(got["S1"]), np.array(got["ST"])
+    print(f"    S1 exact {np.round(exp_S1, 4)}  got {np.round(s1, 4)}")
+    print(f"    ST exact {np.round(exp_ST, 4)}  got {np.round(st, 4)}")
+    check(
+        "first-order indices within 0.02",
+        float(np.abs(s1 - exp_S1).max()) < 0.02,
+        f"max err {np.abs(s1 - exp_S1).max():.4f}",
+    )
+    check(
+        "total indices within 0.02", float(np.abs(st - exp_ST).max()) < 0.02, f"max err {np.abs(st - exp_ST).max():.4f}"
+    )
+    check(
+        "detects x3 has zero first-order but nonzero total",
+        s1[2] < 0.02 and st[2] > 0.1,
+        f"S1={s1[2]:.4f} ST={st[2]:.4f}",
+    )
+
+    print("\nInert-variable detection (the guardrail-2 mechanism)")
+
+    # x1 matters, x2 matters less, x3 is pure noise-level -> must show a tiny span.
+    def g(X):
+        return 10.0 * X[:, 0] + 2.0 * X[:, 1] + 0.001 * X[:, 2]
+
+    Xtr = rng.random((400, 3))
+    sg = fit(Xtr, g(Xtr), box, noise_floor=0.05)
+    span = effect_span(sg, 3)
+    print(f"    spans (y units): {np.round(span, 4)}   true: [10, 2, 0.001]")
+    check("ranks x1 > x2 > x3 by span", span[0] > span[1] > span[2])
+    check("x3 span below a 0.05 floor", span[2] < 0.05, f"{span[2]:.5f}")
+    check("x1 span above the floor", span[0] > 0.05, f"{span[0]:.3f}")
+    sh = effect_shares(sg, n=8192)
+    check("share ordering matches", sh["share"][0] > sh["share"][1] > sh["share"][2], f"{np.round(sh['share'], 4)}")
+
+    print("\nQuantised data (what the real KPIs look like — F8)")
+    # Emulate the measured lattice: quantise to a relative step, then confirm the nugget keeps
+    # the fit from chasing lattice steps as signal.
+    step_rel = 1.2e-3
+    y_true = 50.0 + 8.0 * Xtr[:, 0] + 1.5 * Xtr[:, 1]
+    y_q = np.round(y_true / (y_true * step_rel)) * (y_true * step_rel)
+    floor = float(np.abs(y_q - y_true).max() * 2)
+    sq = fit(Xtr, y_q, box, noise_floor=floor)
+    resid = np.abs(sq.predict(Xtr) - y_true)
+    check(
+        "quantised fit recovers the smooth truth within the floor",
+        float(resid.max()) < max(floor * 3, 0.1),
+        f"max resid {resid.max():.4f} (floor {floor:.4f})",
+    )
+
+    print(f"\n{'ALL PASS' if not FAILED else 'FAILURES: ' + ', '.join(FAILED)}")
+    return 1 if FAILED else 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

simcon_toolkit/_kit/templates/process-window/process_window/units.py

@@ -0,0 +1,152 @@
+"""Unit-checked wrappers for every value that crosses an API boundary.
+
+The cloud AI endpoint takes **Kelvin**; the local SDK rm1 builder takes **Celsius**.
+That is this project's most dangerous boundary — a silent confusion between them
+shifts every temperature by 273.15 K and quietly invalidates every conclusion while
+still producing plausible-looking results.
+
+So: nothing here accepts a bare number and guesses. A conversion states its input unit
+explicitly, and the result is range-checked against what is physically possible for
+thermoplastic injection moulding. A melt temperature of 245 (K) is not a warning, it is
+an error — 245 K is -28 C, which is not a melt.
+
+Design rules:
+  * fail loudly, never coerce and never clamp;
+  * plausibility bands are deliberately wide (they catch unit errors, not process errors
+    — narrowing them to the material card's window is the material card's job);
+  * `Process` is the only object handed to a solver call, and it validates on construction.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+ZERO_C_IN_K = 273.15
+
+# Plausibility bands. Wide on purpose: these exist to catch a 273.15 shift or a
+# Pa/bar mix-up, not to enforce processability.
+MELT_C = (100.0, 430.0)  # thermoplastics: PE ~160 C .. PEEK ~400 C
+WALL_C = (-20.0, 250.0)  # chilled tooling .. hot tooling for high-temp resins
+FLOW_CM3_S = (0.01, 5000.0)
+PRESSURE_BAR = (0.0, 100_000.0)
+
+
+class UnitError(ValueError):
+    """A value failed its unit or plausibility check. Never caught to coerce."""
+
+
+def _check(value: float, band: tuple[float, float], what: str, unit: str) -> float:
+    try:
+        v = float(value)
+    except (TypeError, ValueError) as exc:
+        raise UnitError(f"{what}: {value!r} is not a number") from exc
+    if v != v:  # NaN
+        raise UnitError(f"{what}: NaN")
+    lo, hi = band
+    if not (lo <= v <= hi):
+        raise UnitError(
+            f"{what}: {v:g} {unit} is outside the plausible band {lo:g}..{hi:g} {unit}. "
+            f"This is almost always a unit error — check K vs degC and Pa vs bar."
+        )
+    return v
+
+
+# --- temperature ---------------------------------------------------------------
+def degC_to_K(value_C: float, *, what: str = "temperature") -> float:
+    """Celsius -> Kelvin. The input is validated as Celsius before converting."""
+    band = MELT_C if "melt" in what.lower() else WALL_C
+    return _check(value_C, band, what, "degC") + ZERO_C_IN_K
+
+
+def K_to_degC(value_K: float, *, what: str = "temperature") -> float:
+    """Kelvin -> Celsius. The *result* is validated as Celsius."""
+    try:
+        v = float(value_K)
+    except (TypeError, ValueError) as exc:
+        raise UnitError(f"{what}: {value_K!r} is not a number") from exc
+    if v < 0.0:
+        raise UnitError(f"{what}: {v:g} K is below absolute zero — a Celsius value was passed as Kelvin")
+    out = v - ZERO_C_IN_K
+    band = MELT_C if "melt" in what.lower() else WALL_C
+    _check(out, band, f"{what} (converted from {v:g} K)", "degC")
+    return out
+
+
+# --- pressure ------------------------------------------------------------------
+def Pa_to_bar(value_Pa: float, *, what: str = "pressure") -> float:
+    return _check(float(value_Pa) / 1.0e5, PRESSURE_BAR, what, "bar")
+
+
+def bar_to_Pa(value_bar: float, *, what: str = "pressure") -> float:
+    return _check(value_bar, PRESSURE_BAR, what, "bar") * 1.0e5
+
+
+def pressure_field_to_bar(values, unit_attr: str, *, what: str = "Pressure field"):
+    """Convert a result-file pressure array to bar using its own ``unit`` attribute.
+
+    Cloud results store Pa; older files store bar. Guessing from magnitude is exactly
+    the mistake this module exists to prevent, so the attribute is required.
+    """
+    u = (unit_attr.decode() if isinstance(unit_attr, bytes) else str(unit_attr)).strip().lower()
+    if u in ("pa", "pascal"):
+        return values / 1.0e5
+    if u == "bar":
+        return values
+    raise UnitError(
+        f"{what}: unit attribute is {unit_attr!r}, expected 'Pa' or 'bar'. Refusing to infer the unit from the values."
+    )
+
+
+# --- the object handed to a solver call ----------------------------------------
+@dataclass(frozen=True)
+class Process:
+    """One AI-solver process point, validated on construction.
+
+    Stored in Celsius because that is what an engineer reads; the ``*_K`` properties
+    are what the API is given. Both are always available, so no caller ever converts
+    by hand.
+
+    ``fill_time_s`` is **derived** from volume / flow, never supplied independently:
+    an inconsistent (flow, fill_time) pair is a self-contradictory process state that
+    the solver treats as a scaling hint and silently absorbs.
+    """
+
+    melt_C: float
+    wall_C: float
+    flow_cm3_s: float
+    volume_cm3: float
+
+    def __post_init__(self) -> None:
+        _check(self.melt_C, MELT_C, "melt temperature", "degC")
+        _check(self.wall_C, WALL_C, "mould wall temperature", "degC")
+        _check(self.flow_cm3_s, FLOW_CM3_S, "flow rate", "cm3/s")
+        _check(self.volume_cm3, (1e-6, 1e7), "cavity volume", "cm3")
+        if self.wall_C >= self.melt_C:
+            raise UnitError(
+                f"mould wall ({self.wall_C:g} C) is not below melt ({self.melt_C:g} C) — "
+                "check that the two were not swapped"
+            )
+
+    @property
+    def melt_K(self) -> float:
+        return degC_to_K(self.melt_C, what="melt temperature")
+
+    @property
+    def wall_K(self) -> float:
+        return degC_to_K(self.wall_C, what="wall temperature")
+
+    @property
+    def fill_time_s(self) -> float:
+        return round(self.volume_cm3 / self.flow_cm3_s, 4)
+
+    def api_kwargs(self) -> dict:
+        """Exactly the process arguments the AI filling endpoint takes, in its units."""
+        return {
+            "melt_temperature_K": self.melt_K,
+            "wall_temperature_K": self.wall_K,
+            "flow_rate_cm3_s": self.flow_cm3_s,
+            "estimated_filling_time_s": self.fill_time_s,
+        }
+
+    def label(self) -> str:
+        return f"melt{self.melt_C:.0f}C wall{self.wall_C:.0f}C Q{self.flow_cm3_s:.2f}"

simcon_toolkit/_kit/templates/quoting/.gitignore

@@ -0,0 +1,24 @@
+# What this template writes when it runs. A generated project receives THIS file, not the
+# starter kit's root one, so the rules have to live here too or a customer's first commit
+# carries their own quotes and a meshed geometry.
+#
+# cache/ is ours: the mesh, the cloud ids, the resumable state and the decision log. Safe
+# to delete - it costs a re-mesh and a re-upload, never a wrong answer.
+# output/ is yours: quote.json and the simulation results behind it.
+cache/
+output/
+
+# parts/ is where you drop your own geometry. The folder is documented in PROMPT.md so it
+# is kept, but what lands in it is yours and is not ours to commit. sample/ is deliberately
+# NOT ignored: it is the geometry this project ships with.
+parts/*
+!parts/.gitkeep
+
+.venv/
+__pycache__/
+*.pyc
+.pytest_cache/
+
+# never commit credentials
+*token*.json
+.env

simcon_toolkit/_kit/templates/quoting/AGENTS.md

@@ -0,0 +1,58 @@
+# Quoting — how to drive this template
+
+You have been asked to quote an injection-moulded part. This file is the map; the method is
+in [`METHOD.md`](METHOD.md), and you should read that before running anything.
+
+## Read these first, in this order
+
+1. **[`METHOD.md`](METHOD.md)** — the procedure, stage by stage. What each stage decides, what
+   it needs from you, and what it writes down.
+2. **[`shop/`](shop/)** — the shop you are quoting as. Its presses, its material bias, how it
+   estimates a mould, what it declines. Quote as *that* shop, not in general.
+3. **[`QUOTING_PLAYBOOK.md`](QUOTING_PLAYBOOK.md)** — the cost model and its formulas. Read it
+   when a number needs justifying or the method has to be adapted.
+
+## The stages
+
+```
+python main.py setup                              # is shop/ this shop, or still the example?
+python main.py intake --part <file> --cavities N  # what the geometry alone decides
+python main.py study  --part <file>               # cloud: the gating decision
+python main.py cost   --part <file>               # price every option, choose on money
+python main.py learn  --quote <key>               # fold the estimator's corrections back in
+```
+
+`--part` defaults to the bundled sample, so every stage runs without it. **`intake` still needs
+`--cavities N`**, which has no default on purpose: the cavity count is the customer's commercial
+decision and inventing one puts a made-up number into a quotation. Ask for it.
+
+Only `study` needs a licence and cloud access; add `--offline` to it and the whole flow is
+demonstrable without credentials, with every artefact marked as estimated.
+
+## Four things to get right
+
+**Quote as this shop.** The numbers in `shop/` are the whole point. A quote that ignores them
+is a generic calculation the customer could have done themselves.
+
+**Never invent a cavity count.** It is the customer's commercial decision. Ask.
+
+**A quote is keyed on the part's contents.** `intake` prints a key like
+`clip_frame-655b895fd2b5`. Re-export the part and it becomes a *different* quote, deliberately:
+the mesh, the uploaded geometry and the decisions on file describe the previous revision. If a
+stage says there is no quote on file for a part you have already run, the part changed.
+
+**The shipped `shop/` is fictional.** Until someone works through [`INTERVIEW.md`](INTERVIEW.md)
+and confirms it, every quote is watermarked as example data. Say so rather than presenting a
+watermarked quote as a price.
+
+## Where things land
+
+| Path | Whose | What |
+|---|---|---|
+| `cache/<key>/` | ours | `state.json`, `decisions.md`, the mesh. Deleting costs a re-mesh. |
+| `output/<key>/` | the customer's | `quote.json` and the simulation results behind it. |
+| `parts/` | the customer's | Where they drop their own geometry. |
+| `sample/` | shipped | The default geometry, written when the project is generated. |
+
+The kit writes no document. `quote.json` is the deliverable — turn it into the quotation in
+whatever form the customer expects.