simcon-toolkit 0.1.0__py3-none-any.whl

simcon_toolkit/_kit/templates/quoting/main.py

@@ -0,0 +1,484 @@
+"""Driver for an agentic quote: geometry -> gating study -> costing -> lessons.
+
+Four stages, each a subcommand, each resumable:
+
+    python main.py intake --cavities 4         # uses sample/clip_frame.stl
+    python main.py intake --part my.stl --cavities 4
+    python main.py study  --part my.stl        # cloud: the gating decision
+    python main.py cost   --part my.stl        # price every gating option
+    python main.py learn  --quote <key>        # apply the estimator's corrections
+
+The geometry is named rather than positional, and the same way in every template: these
+workflows will grow inputs, and a flag keeps that from reordering anyone's command. The
+subcommand stays positional - it is a verb, not an input.
+
+**A quote is keyed on the part's contents, not its file name.** Re-export a part and it
+becomes a new quote, because the mesh, the uploaded geometry and the decisions already on
+file describe the previous revision. ``quoting.state.part_key`` is where that is decided.
+The last stage takes ``--quote`` rather than ``--part`` for the same reason: it corrects a
+quote that already exists, and it never opens the geometry.
+
+Two folders, both created on demand and both safe to delete:
+
+* ``cache/<key>/`` - ours. The mesh, the cloud ids, ``state.json`` and the decision log.
+  Deleting it costs a re-mesh and a re-upload, never a wrong answer.
+* ``output/<key>/`` - yours. ``quote.json`` and the simulation results behind it.
+
+The quote itself lands in ``output/<key>/quote.json``. The kit writes no document: hand that
+file to your assistant and ask for the quotation in whatever form your customer expects.
+
+``intake`` and ``cost`` are fully offline; only ``study`` needs a licence and cloud access. Add
+``--offline`` to ``study`` to substitute rule-of-thumb gating so the whole flow is demonstrable
+without credentials - every artefact it produces is then marked as estimated.
+
+The agent drives these; the stages exist so that each decision is written down before the next
+one depends on it. See ``METHOD.md`` for how to run the flow.
+"""
+
+from __future__ import annotations
+
+import argparse
+import contextlib
+import json
+import sys
+from pathlib import Path
+
+from quoting import costing, geometry, shop, state
+
+HERE = Path(__file__).resolve().parent
+# Written by the generator, so this path resolves in your project and not in ours.
+DEFAULT_PART = HERE / "sample" / "clip_frame.stl"
+
+
+def _utf8_stdout() -> None:
+    # Windows consoles default to cp1252 and choke on the odd non-ASCII glyph.
+    with contextlib.suppress(Exception):
+        sys.stdout.reconfigure(encoding="utf-8")
+
+
+def _part(args: argparse.Namespace, *, resuming: bool = False) -> Path:
+    """The geometry this stage acts on, checked before anything is written.
+
+    A resuming stage refuses to guess which quote it continues; see
+    ``quoting.state.part_for_stage``.
+    """
+    try:
+        chosen = state.part_for_stage(args.part, DEFAULT_PART) if resuming else Path(args.part)
+    except state.AmbiguousQuote as exc:
+        raise SystemExit(str(exc)) from None
+    part = Path(chosen).resolve()
+    if not part.is_file():
+        where = "the bundled sample is missing" if part == DEFAULT_PART else f"no such geometry: {part}"
+        raise SystemExit(f"{where}\nPass your own STL with --part, or put one back at {DEFAULT_PART}.")
+    return part
+
+
+def _open_quote(part: Path) -> state.QuoteState:
+    """The quote for this part, which must already have been through `intake`."""
+    quote = state.QuoteState.for_part(part)
+    if not quote.path.exists():
+        known = state.quotes_on_file()
+        listed = "\n  ".join(known) if known else "(none yet)"
+        raise SystemExit(
+            f"no quote on file for {part.name} as it stands today (key {quote.key}).\n"
+            f"Run `intake` first. Quotes that do exist:\n  {listed}\n"
+            "A quote is keyed on the part's contents, so a re-exported part starts a new one."
+        )
+    return quote
+
+
+def _load_geo(part: Path, st: state.QuoteState) -> geometry.PartGeometry:
+    """Re-derive the PartGeometry from the STL, with the draw direction chosen at intake."""
+    facts = st.get("geometry")
+    if not facts:
+        raise SystemExit("no geometry on file - run `intake` first")
+    return geometry.analyse(part, draw_axis="xyz".index(facts["draw_axis"]))
+
+
+def _material_note(st: state.QuoteState) -> str:
+    """The catalogue-substitution sentence, if the house grade was not in the catalogue."""
+    mat = st.get("material") or {}
+    if not mat.get("substituted"):
+        return ""
+    from quoting.study import MaterialResolution
+
+    fields = {f: mat[f] for f in MaterialResolution.__dataclass_fields__ if f in mat}
+    return MaterialResolution(**fields).note()
+
+
+def _options(st: state.QuoteState):
+    from quoting.study import GateOption
+
+    raw = st.get("gate_options")
+    if not raw:
+        raise SystemExit("no gating options on file - run `study` first")
+    return [GateOption(**o) for o in raw]
+
+
+# ==========================================================================
+# 0. setup - make the shop context this user's shop, not the example one
+# ==========================================================================
+EXAMPLE_MARKERS = [
+    ("shop-profile.md", "name", lambda ctx: ctx.shop.get("name")),
+    ("machines.md", "first press", lambda ctx: (ctx.machines.get("machines") or [{}])[0].get("name")),
+    ("materials.md", "default grade", lambda ctx: ctx.materials.get("default_grade")),
+    ("commercial.md", "labour rate", lambda ctx: ctx.commercial.get("labour_rate_eur_h")),
+    ("tooling.md", "cavity base price", lambda ctx: (ctx.tooling.get("cavity") or {}).get("fixed_eur_per_cavity")),
+]
+EXAMPLE_VALUES = {
+    "name": shop.EXAMPLE_SHOP_NAME,
+    "first press": "Engel e-mac 50",
+    "default grade": "PP TV20",
+    "labour rate": 38.0,
+    "cavity base price": 2500,
+}
+
+
+def cmd_setup(args: argparse.Namespace) -> int:
+    """Report how much of the shop context is still the shipped example, or confirm it is ours."""
+    ctx = shop.load()
+    still_example = [(f, what) for f, what, get in EXAMPLE_MARKERS if get(ctx) == EXAMPLE_VALUES[what]]
+
+    if not args.confirm:
+        print(f"\nshop context: {ctx.summary()}")
+        print(f"provenance:   {ctx.shop.get('provenance', 'example')}")
+        if still_example:
+            print("\nstill at the shipped example values:")
+            for f, what in still_example:
+                print(f"  - {f:18s} {what}")
+        else:
+            print("\nno obvious example values left.")
+        print(
+            "\nWork through INTERVIEW.md with the estimator and edit the shop/ files directly.\n"
+            "Then record whose shop this is:\n"
+            '  python main.py setup --confirm "<Your Shop GmbH>"\n'
+            "Until then every quote is watermarked as built on example data."
+        )
+        return 1 if ctx.is_example else 0
+
+    if still_example and not args.force:
+        print("\nrefusing to confirm - these are still the shipped example values:")
+        for f, what in still_example:
+            print(f"  - {f:18s} {what}")
+        print(
+            "\nThe point of the interview is that these change. Fix them, or pass --force if a "
+            "value genuinely matches the example by coincidence."
+        )
+        return 1
+
+    profile = ctx.root / "shop-profile.md"
+    block = shop.read_block(profile, "shop")
+    block["provenance"] = args.confirm
+    block["name"] = args.confirm
+    shop.write_block(profile, "shop", block)
+    print(f"\n  shop context is now '{args.confirm}'. Quotes are no longer watermarked as example data.")
+    print("  Re-run the interview whenever a press, a rate or the margin changes.")
+    return 0
+
+
+# ==========================================================================
+# 1. intake - everything the geometry alone can decide
+# ==========================================================================
+def cmd_intake(args: argparse.Namespace) -> int:
+    ctx = shop.load()
+    print(f"\nshop context: {ctx.summary()}")
+    if ctx.is_example:
+        print("\n" + ctx.example_warning() + "\n")
+    stl = _part(args)
+
+    print(f"\n1. reading the geometry ({stl.name})")
+    geo = geometry.analyse(stl, draw_axis=None if args.draw_axis is None else "xyz".index(args.draw_axis))
+    print(geo.report())
+
+    st = state.QuoteState.for_part(stl)
+    grade = ctx.find_grade(args.material)
+    st.update(
+        part=stl.stem,
+        cavities=args.cavities,
+        geometry=geo.as_dict(),
+        grade=grade,
+        material_specified=bool(args.material),
+    )
+
+    print(f"\n2. material: {grade['name']} ({'specified' if args.material else 'shop default proposal'})")
+    if not args.material:
+        print(
+            "   NOTE: no material was specified. Ask the customer before the quote goes out - "
+            f"the ask is scripted in shop/materials.md. Quoting {grade['name']} as an assumption."
+        )
+    st.decide(
+        "Material",
+        grade["name"],
+        (
+            "specified by the customer"
+            if args.material
+            else f"no grade given; house default from shop/materials.md ({grade['family']}, "
+            f"{grade['price_eur_kg']} {ctx.currency()}/kg, {grade['stock']})"
+        ),
+    )
+    st.decide(
+        "Draw direction and cavity count",
+        f"draw along {'xyz'[geo.draw_axis]}, {args.cavities} cavities",
+        f"draw axis taken as the largest projected area ({geo.projected_area_cm2:.1f} cm2); "
+        "the cavity count is the customer's and is not ours to change",
+    )
+    print(f"\n   state -> {st.path}")
+    print(f"   next:  python main.py study --part {stl}")
+    return 0
+
+
+# ==========================================================================
+# 2. study - buy the decisions that move the price
+# ==========================================================================
+def cmd_study(args: argparse.Namespace) -> int:
+    from quoting import study as S
+
+    stl = _part(args, resuming=True)
+    st = _open_quote(stl)
+    geo = _load_geo(stl, st)
+    grade = st.get("grade")
+    counts = [int(c) for c in args.gate_counts.split(",")]
+
+    if args.offline:
+        print("\n  OFFLINE: no cloud runs. Gating and pressure are rule-of-thumb estimates.")
+        options = S.estimate_options(
+            geo.volume_cm3,
+            geo.nominal_wall_mm,
+            max(geo.bbox_mm),
+            counts,
+            grade,
+            fill_time_s=max(0.5, geo.nominal_wall_mm),
+        )
+        thermal = S.FAMILY_THERMAL.get(grade.get("family", ""), S.DEFAULT_THERMAL)
+        melt_K, mold_K = 513.15, 313.15
+        material = {"house_name": grade["name"], "source": "offline estimate"}
+        for o in options:
+            print(o.row())
+    else:
+        cfex = st.dir / f"{stl.stem}.cfex"
+        print(f"\n1. meshing {geo.path.name} (cadmould SDK - needs a licence)")
+        part = S.mesh_part(geo.path, cfex)
+        st.update(mesh={"cfex": str(cfex), "nodes": part.n_nodes, "sdk_fill_time_s": part.sdk_fill_time_s})
+
+        print("\n2. connecting to the cloud")
+        study = S.QuotingStudy(
+            f"QUOTE {st.key}",
+            part,
+            st.output_dir / "results",
+            geometry_id=st.get("geometry_id"),
+            project_id=st.get("project_id"),
+        )
+        try:
+            mat = study.resolve_material(grade)
+            study.upload_geometry()
+            st.update(project_id=study.project_id, geometry_id=study.geometry_id, material=mat.as_dict())
+            study.note(
+                f"Quoting {stl.stem} in {grade['name']} ({mat.catalogue_name}), {st.get('cavities')} cavities. "
+                f"Gate-count options simulated: {counts}.",
+                title="Quotation study",
+            )
+
+            flow = study.nominal_flow_cm3_s(geo.nominal_wall_mm)
+            print(f"\n3. gate-count study at {flow:.1f} cm3/s (fill ~{geo.volume_cm3 / flow:.2f} s)")
+            options = study.gate_count_batch(counts, flow)
+            if not options:
+                raise SystemExit("every simulation failed - check the token and the endpoint, then retry")
+
+            if args.process_sweep:
+                best = min(options, key=lambda o: o.max_pressure_bar)
+                flows = [flow * f for f in (0.6, 0.8, 1.0, 1.3, 1.7)]
+                print("\n4. process window at the lowest-pressure gating")
+                options += study.process_batch(best.gates_mm, flows)
+            material = mat.as_dict()
+            thermal, melt_K, mold_K = mat.thermal, mat.melt_K, mat.wall_K
+        finally:
+            study.close()
+
+    st.update(
+        gate_options=[o.as_dict() for o in options],
+        thermal=thermal,
+        melt_K=melt_K,
+        mold_K=mold_K,
+        material=material,
+        study_source="estimated" if args.offline else "cloud",
+    )
+    print(f"\n   {len(options)} option(s) on file -> {st.path}")
+    print(f"   next:  python main.py cost --part {stl}")
+    return 0
+
+
+# ==========================================================================
+# 3. cost - price every option and pick on money
+# ==========================================================================
+def cmd_cost(args: argparse.Namespace) -> int:
+    ctx = shop.load()
+    stl = _part(args, resuming=True)
+    st = _open_quote(stl)
+    geo = _load_geo(stl, st)
+    options = _options(st)
+    grade = st.get("grade")
+    ladder = ctx.volume_ladder()
+    reference = args.reference or ladder[len(ladder) // 2]
+
+    # Only the gate-count options compete for the gating decision; process-sweep runs share a
+    # gate count and would otherwise look like duplicate options.
+    by_count = {}
+    for o in options:
+        keep = by_count.get(o.n_gates)
+        if keep is None or o.max_pressure_bar < keep.max_pressure_bar:
+            by_count[o.n_gates] = o
+
+    quotes = costing.compare_options(
+        ctx,
+        geo,
+        sorted(by_count.values(), key=lambda o: o.n_gates),
+        cavities=int(st.get("cavities")),
+        grade=grade,
+        thermal=st.get("thermal"),
+        melt_K=float(st.get("melt_K")),
+        mold_K=float(st.get("mold_K")),
+        finish=args.finish,
+        material_note=_material_note(st),
+    )
+    print(f"\n  gating options priced (reference volume {reference:,} parts/year):\n")
+    print(costing.comparison_table(quotes, reference))
+
+    chosen = quotes[0]
+    print("\n  chosen:\n")
+    print(chosen.summary())
+
+    runner_up = quotes[1] if len(quotes) > 1 else None
+    st.decide(
+        "Gate count",
+        f"{chosen.option.n_gates} gate(s) per cavity",
+        (
+            f"lowest total cost of ownership at {reference:,} parts/year "
+            f"({chosen.total_cost_of_ownership(reference):,.0f} {chosen.currency}); "
+            f"{chosen.option.max_pressure_bar:.0f} bar peak cavity pressure, {chosen.option.n_welds} weld line(s); "
+            f"press {chosen.machine.name}"
+        ),
+        alternatives=(
+            f"{runner_up.option.n_gates} gate(s): {runner_up.total_cost_of_ownership(reference):,.0f} "
+            f"{runner_up.currency} - "
+            + (
+                "cheaper tool, higher pressure"
+                if runner_up.option.n_gates < chosen.option.n_gates
+                else "lower pressure, more nozzles and welds"
+            )
+            if runner_up
+            else "none - only one gating option was simulated"
+        ),
+    )
+    st.decide(
+        "Press and cycle",
+        f"{chosen.machine.name}, cycle {chosen.cycle.total_s:.1f} s",
+        f"clamp {chosen.machine.required_clamp_kN:.0f} kN required, basis '{chosen.machine.clamp_basis}'; "
+        f"cooling {chosen.cycle.cool_s:.1f} s from the {chosen.cycle.governing_wall_mm:.2f} mm governing wall",
+    )
+    st.update(
+        quote=chosen.as_dict(),
+        all_quotes=[q.as_dict() for q in quotes],
+        reference_parts=reference,
+        finish=args.finish,
+    )
+    # The chosen quote's own fields sit at the top level, and the comparison rides beside
+    # them. Since the kit writes no document, this file is the deliverable: whoever writes
+    # the quotation must be able to state what was chosen, what it beat and at what volume,
+    # without also opening state.json.
+    quote_payload = {
+        **chosen.as_dict(),
+        "reference_parts": reference,
+        "finish": args.finish,
+        "alternatives": [q.as_dict() for q in quotes if q is not chosen],
+    }
+    st.output_dir.mkdir(parents=True, exist_ok=True)
+    (st.output_dir / "quote.json").write_text(json.dumps(quote_payload, indent=2, default=str), encoding="utf-8")
+    print(f"\n   quote -> {st.output_dir / 'quote.json'}")
+    print(f"   next:  review quote.json, then: python main.py learn --quote {st.key}")
+    return 0
+
+
+# ==========================================================================
+# 4. learn - the loop that makes the next quote better
+# ==========================================================================
+def cmd_learn(args: argparse.Namespace) -> int:
+    try:
+        st = state.QuoteState.open_existing(args.quote)
+    except state.NoSuchQuote as exc:
+        # A traceback here would bury the list of quotes that do exist, which is the
+        # only thing the reader needs.
+        raise SystemExit(str(exc.args[0])) from None
+    path = Path(args.corrections) if args.corrections else st.dir / "corrections.json"
+    if not path.exists():
+        path.write_text(json.dumps({**state.CORRECTIONS_TEMPLATE, "quote": args.quote}, indent=2), encoding="utf-8")
+        print(f"\n  wrote a template to {path}")
+        print("  Fill it in from the review conversation (the estimator's own words in 'why'), then re-run.")
+        return 1
+    corrections = json.loads(path.read_text(encoding="utf-8"))
+    added = state.apply_corrections(corrections)
+    print(f"\n  recorded {len(added)} lesson(s) in shop/lessons.md: {', '.join(added)}")
+    print("  The calibration block is updated, so the next quote already reflects this.")
+    st.update(lessons=added)
+    return 0
+
+
+# ==========================================================================
+def main() -> int:
+    _utf8_stdout()
+    ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
+    sub = ap.add_subparsers(dest="cmd", required=True)
+
+    p = sub.add_parser("setup", help="check/confirm that shop/ is this shop, not the shipped example")
+    p.add_argument(
+        "--confirm", default=None, metavar="SHOP", help="record whose shop this is, once the values are yours"
+    )
+    p.add_argument("--force", action="store_true", help="confirm even though example values remain")
+    p.set_defaults(func=cmd_setup)
+
+    # The geometry is `--part` in every template, and every stage that works on a geometry
+    # takes it: the quote is keyed on the file's contents, so a stage that never sees the
+    # file cannot tell that the part changed underneath it.
+    def part_option(parser: argparse.ArgumentParser, *, resuming: bool = False) -> None:
+        # A resuming stage defaults to None rather than to the sample, so it can tell
+        # "the user said nothing" from "the user asked for the sample" and refuse to
+        # guess between quotes instead of silently re-pricing the wrong part.
+        parser.add_argument(
+            "--part",
+            default=None if resuming else str(DEFAULT_PART),
+            help="path to the geometry (default: the bundled sample)",
+        )
+
+    p = sub.add_parser("intake", help="read the geometry, pick a material, open the quote")
+    part_option(p)
+    p.add_argument("--cavities", type=int, required=True, help="cavity count (the customer's, not ours)")
+    p.add_argument("--material", default=None, help="house grade; omitted = shop default + an assumption")
+    p.add_argument("--draw-axis", choices=list("xyz"), default=None, help="force the draw direction")
+    p.set_defaults(func=cmd_intake)
+
+    p = sub.add_parser("study", help="run the gating study on the cloud")
+    part_option(p, resuming=True)
+    p.add_argument("--gate-counts", default="1,2,3", help="gate counts per cavity to simulate")
+    p.add_argument("--process-sweep", action="store_true", help="also sweep the flow rate")
+    p.add_argument("--offline", action="store_true", help="rule-of-thumb gating instead of cloud runs")
+    p.set_defaults(func=cmd_study)
+
+    p = sub.add_parser("cost", help="price every gating option and choose")
+    part_option(p, resuming=True)
+    p.add_argument("--reference", type=int, default=None, help="volume the options are compared at")
+    p.add_argument("--finish", default="technical", choices=["technical", "polished", "textured"])
+    p.set_defaults(func=cmd_cost)
+
+    # `--quote`, not `--part`: this stage corrects a quote that already exists and never
+    # opens the geometry. Demanding the STL back would also refuse the correction whenever
+    # the part had been re-exported since - exactly when a lesson is worth recording.
+    p = sub.add_parser("learn", help="apply the estimator's corrections to shop/lessons.md")
+    p.add_argument("--quote", required=True, help="the quote key printed by intake and cost")
+    p.add_argument("--corrections", default=None, help="path to corrections.json")
+    p.set_defaults(func=cmd_learn)
+
+    args = ap.parse_args()
+    return args.func(args)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

simcon_toolkit/_kit/templates/quoting/quoting/__init__.py

@@ -0,0 +1,11 @@
+"""Quoting toolkit: geometry -> gating decision -> cost model -> lessons.
+
+The shared ``cadmould_*`` packages are imported by name: in a generated project they sit
+beside this folder, and in the kit's own repository ``PYTHONPATH=packages`` supplies them.
+Nothing here edits ``sys.path``. The offline half (``shop``, ``geometry``, ``costing``,
+``state``) needs neither a cadmould licence nor cloud access.
+"""
+
+from __future__ import annotations
+
+__all__ = ["costing", "geometry", "shop", "state", "study", "toolkit"]