simcon-toolkit 0.1.0__py3-none-any.whl

simcon_toolkit/_kit/templates/quoting/QUOTING_PLAYBOOK.md

@@ -0,0 +1,245 @@
+# Quoting playbook — the method, the cost model, and every gotcha
+
+How this example turns a geometry and a cavity count into a defensible tool price and piece price,
+what each number rests on, and what breaks. Read this before adapting it to your own shop.
+
+> TL;DR: read the shop context → derive the cost drivers from the geometry (projected area, wall,
+> undercuts) → simulate the gating options on the cloud → price each one end to end → pick on total
+> cost of ownership → write the quote → take the estimator's corrections back into `shop/lessons.md`.
+
+---
+
+## 0. Why a quote needs a simulation at all
+
+A moldmaker's quote is decided long before anyone runs a mold-flow analysis, and three of the
+decisions that set the price are exactly the ones a filling simulation answers:
+
+| Decision | What it costs | Who normally decides it | When |
+|---|---|---|---|
+| **Gate count** | one hot-runner nozzle **per cavity**, plus a weld line each | the mold designer | after the order |
+| **Cavity pressure** | clamp force → press class → hourly rate for the tool's whole life | a rule of thumb | at quotation |
+| **Fill time** | the fill share of the cycle; the shear ceiling | a guess | at quotation |
+
+The second one is the expensive one. Press class is a decision you live with for 500k shots, and
+it is normally taken from a number somebody remembered. A filling run costs about nine seconds.
+
+The point of this example is not that the simulation is more accurate than the estimator — on
+absolute pressure it demonstrably is not (§5.2). It is that the *ranking* it provides is sound, and
+ranking is what a gate-count decision needs.
+
+---
+
+## 1. What the geometry alone decides (`quoting/geometry.py`)
+
+All offline, all free, all in seconds.
+
+| Quantity | How | Feeds |
+|---|---|---|
+| **Projected area** | summed \|projected\| facet area / 2 (exact for a closed surface) | clamp force |
+| **Draw direction** | the axis with the largest shadow | projected area, undercuts |
+| **Wall thickness** | largest sphere that fits inside the material, touching each sampled facet | cooling time, complexity |
+| **Undercuts** | facets that release in neither draw direction, clustered | slides / lifters |
+| **Shape factor** | part surface ÷ bounding-box surface | cavity machining complexity |
+| **Volume** | closed-surface volume | shot size, material, barrel fit |
+
+Three of those have a non-obvious implementation, each because the obvious one is wrong:
+
+- **Sampling is area-weighted, not per-facet.** An STL's rim is meshed with many tiny triangles.
+  Sampling facets uniformly puts most rays on the rim, and a ray cast inward from the 1.5 mm edge
+  of a plate measures the plate's 150 mm *span*. Weighting by area also happens to be the quantity
+  you want: "how much of the surface is thin", not "how many triangles are thin".
+- **Thickness is the largest inscribed sphere**, not a ray cast inward. A single inward ray
+  over-reads at every rim, where it measures the plate's *span* rather than its wall; the
+  inscribed sphere reads 1.5 mm from the face and from the rim alike. The p95 wall sets the
+  cooling time, so that error would go straight into the cycle and the price.
+
+  ⚠️ **This replaced a bundle of tilted rays cast through a VTK OBB tree, and the reason is
+  worth keeping.** That tree was rebuilt non-deterministically: the same file measured between
+  1 and 461 usable samples run to run, aborting outright below 10, and it reported a 31 mm
+  median wall on a part 21.9 mm deep. The measurement now comes from trimesh and is identical
+  on every run of the same file. If anyone proposes going back to ray casting for speed, this
+  is what they are buying back.
+- **Complexity uses the shape factor, not surface-to-volume.** Surface-to-volume looks like a
+  complexity measure and is mostly a thinness measure: a plain 1.5 mm plate scores 15 cm⁻¹ and
+  would be priced like a ribbed housing (it was, in the first run of this example — the tool came
+  out 28 % too expensive). Shape factor is ≈1 for a flat part and climbs with real features.
+
+**Known limits.** Wall thickness under-reads at edges and corners, where a genuinely smaller
+sphere fits — read the median as the nominal wall, not the p05. The undercut count is geometric:
+it cannot know that a feature will be moulded with a hand-loaded insert instead of a slide. If
+the cadmould mesher's own thickness/w2w data becomes reachable from the SDK, prefer it over this
+geometric estimate. ⚠️ **The numbers have not been validated against a part of known wall
+thickness** — they are physically plausible and reproducible, which is not the same as correct.
+
+---
+
+## 2. The simulations (`quoting/study.py`)
+
+One cloud project per quote, one group per batch, a project note per decision. The part is meshed
+and uploaded once.
+
+**Batch Q1 — gate count.** One run per gate count at a fixed nominal process. This is the batch
+that pays for itself.
+
+**Batch Q2 — process window (optional).** A flow-rate sweep at the chosen gating. Worth it when
+fill time is a real share of the cycle; on a thick-walled part cooling dominates and the sweep
+tells you nothing you will use.
+
+**Nominal flow rate** comes from the SDK's own `estimate_fill_time`, which accounts for wall
+thickness and the material's rheology. Do not derive it from a guessed fill time — a hand-picked
+"fill it in 1 s" has been measured 3.5× wrong on a thin part, which moves the entire process
+window and everything downstream of it.
+
+**The material lookup is worth more than it looks.** `GET /material-versions/{id}` carries not just
+the recommended melt and mould temperatures but the thermal data the cooling model needs —
+`lambda_W_mK`, `cp_J_kgK`, `melt_density_kg_m3`, `no_flow_temperature_K`,
+`ejection_temperature_K`. So the cycle-time estimate is built from *this grade's* physics rather
+than a textbook constant. If the payload lacks them, `FAMILY_THERMAL` supplies family defaults and
+the material is marked `family-default`.
+
+---
+
+## 3. The cost model (`quoting/costing.py`)
+
+### 3.1 Clamp force
+
+```
+F[kN] = p_mean[bar] × A_projected[cm²] / 100          (1 bar = 0.1 N/mm²)
+p_mean = max(p_peak_simulated × sim_peak_to_mean, material rule of thumb)
+F_required = F × clamp_safety_factor
+```
+
+Both factors live in `shop/lessons.md`. The `max()` is the important part and §5.2 is why. On a
+cold-runner tool the runner's own projected area is added (15 % of the cavity area); on a hot
+runner it is not, because the melt channel is inside the manifold rather than in the parting line.
+
+### 3.2 Press selection
+
+Smallest press clearing **clamp** (≤ 80 % utilisation), **tie-bar opening**, and the **shot window**
+(20–80 % of barrel). The three are not equally hard, and treating them as if they were produces
+"nothing fits" on ordinary parts. Clamp and tie-bar are hard constraints — too little tonnage is
+flash, and a mold that does not fit does not fit. The shot window is soft: a small shot is a melt
+residence problem to be managed, not a reason to refuse the job. So the search relaxes the shot
+window last and names the constraint it bent.
+
+### 3.3 Cycle time
+
+```
+cycle = fill + max(hold, cool) + handling
+cool  = h²/(π²α) · ln[ (4/π) · (T_melt − T_mould)/(T_eject − T_mould) ] · cooling_time_factor
+```
+
+with `h` the half **governing** wall (p95 — the slowest-cooling section governs ejection) and
+`α = λ/(ρ·c_p)` from the grade's own data. Holding time is `pack_time_s_per_mm_wall × nominal`
+wall, because gate freeze follows the wall the melt flows through, not the thickest section.
+Holding and cooling run concurrently, hence the `max()`.
+
+**This is an analytic estimate, not a cooling simulation** — the filling solver has no cooling
+phase. Its virtue is that a process engineer can redo it on paper from a datasheet, and an estimate
+the customer can check beats a black box. Its known weakness is ribs and bosses, which is exactly
+what `cooling_time_factor` exists to absorb (see L-001 in `lessons.md`).
+
+### 3.4 The tool
+
+Base + cavities × complexity + side actions + feed system + cooling + ejection + finish +
+engineering + sampling, then project management, risk and margin. Every rate is in
+`shop/tooling.md`. The gate count enters as `cavities × gates_per_cavity` hot-runner nozzles.
+
+### 3.5 The piece price
+
+```
+material + machine + labour + secondary + setup → manufacturing
++ overhead (on material and labour ONLY) + margin → price
+```
+
+**Overhead is not applied to the machine line.** The machine rates in `shop/machines.md` are loaded
+rates that already recover fixed cost; applying overhead again is the classic double count.
+
+Only two things move along the volume ladder: **setup amortisation** (capped by the minimum
+economic batch — nobody sets up twelve times a year for 800-part runs) and the **material price
+break** on annual tonnage. A ladder that comes out nearly flat between two rungs is therefore a
+correct answer, not a missing discount.
+
+### 3.6 Choosing the gating
+
+`compare_options()` prices every gating option end to end and ranks by **tool + piece × volume** at
+the reference volume. That is the whole reason the study runs before the quote. If the winner is
+within a couple of percent of the runner-up, the model cannot tell them apart — say so.
+
+---
+
+## 4. The quote document
+
+`python main.py cost` writes `quote.json` — the chosen option, every option it was chosen against,
+the machine and cycle basis, and the reference volumes. That file is the deliverable.
+
+Turning it into a document is your assistant's job, and the format should be yours rather than
+ours. What the document must carry, however it looks:
+
+**The basis, stated plainly** — surrogate solver, one cavity, no runner, analytic cooling,
+geometric weld-visibility. That is not decoration: it is what makes the quote defensible when the
+first article disagrees with it.
+
+**Honest comparisons.** If the winner is within a couple of percent of the runner-up, the model
+cannot tell them apart and the document must say so. One measure per chart; never one chart with
+two y-scales.
+
+---
+
+## 5. Things to know (each cost a real mistake)
+
+### 5.1 The offline path is not a quote
+`--offline` exists so the flow can be demonstrated and tested without credentials. Everything it
+produces is marked `estimated` through to `quote.json`. Do not send it.
+
+### 5.2 Never size the clamp from the simulation alone
+The AI model is **one cavity with no runner system** and under-reads absolute pressure on
+multi-gate parts. Cavity pressure at the end of *pack* — which is what actually opens a tool — is
+not modelled at all, because the solver models filling only. The rule-of-thumb floor per material
+family in `shop/materials.md` is what keeps a tool from flashing at trial. Use the simulation to
+rank gating options; use the rule of thumb to size the press. `quote.json` records which governed.
+
+### 5.3 The endpoint sheds load
+`max_workers=2` with retry and backoff. Everything timing out means the model went cold — one lone
+request warms it. Never run a second batch concurrently with a running one.
+
+### 5.4 Determinism
+Identical configuration → identical result. Re-running for confidence buys nothing; spend every run
+on a new configuration.
+
+### 5.5 Weld lines are located, not judged
+The detector finds where flow fronts meet. Whether that position is acceptable depends on the
+part's functional and visible faces, which are on a drawing you were probably not given. It goes on
+the assumptions slide as a flag, never as a silent pass.
+
+### 5.6 Result-file details
+Handled by the reused `metrics.py`, but worth knowing: `Degree_of_filling` is a sharp 0→1 front
+(arrival = first crossing of 0.5, *not* `isfinite`); `Pressure` honours a `unit` attribute (Pa now,
+bar in older files); the `geometry3DF` group name has a trailing space; the result mesh is
+re-centred on the origin while your gate coordinates are not.
+
+---
+
+## 6. Adapting it to your shop
+
+1. **Replace `shop/` wholesale.** Keep the file names and the fenced JSON block names; change
+   everything else. The prose is read by the agent and matters as much as the numbers.
+2. **Re-derive the tooling rates** against your last ten tools. The shipped numbers are invented.
+3. **Set the calibration block to neutral** (`1.00` everywhere, `clamp_safety_factor` to whatever
+   you use today) and let it move only through `learn`. Starting from someone else's corrections
+   is how you inherit someone else's mistakes.
+4. **Quote three parts you already know the answer to**, and run `learn` on each. Three corrections
+   is roughly where the cycle-time and tool-price factors stop moving much.
+5. **Check the side-action count** on every one of those three. It is the estimate most likely to
+   be wrong and the most expensive when it is.
+
+## 7. Limitations
+
+- Filling only. No packing, cooling or warpage simulation — cooling is analytic, packing is a rate
+  per mm of wall.
+- One cavity is simulated; cavity-to-cavity imbalance on a multi-cavity tool is not represented
+  even in principle.
+- Undercut detection is geometric and cannot distinguish a slide from a hand-loaded insert.
+- The tool model covers a 2-plate mould with a hot or cold runner. Unscrewing cores, 2K tools and
+  conformal cooling are explicitly out and are flagged rather than priced.
+- Tolerances are not modelled at all. Nothing here guarantees a dimension.

simcon_toolkit/_kit/templates/quoting/README.md

@@ -0,0 +1,158 @@
+# Template · Agentic quoting (`quoting`)
+
+Give an agent **a geometry and a cavity count** — nothing else — and get back a **quotation**: a
+tool price, a piece price at a volume ladder, a press and a cycle time, written out as a
+`quote.json` your own assistant turns into the document your customer expects. The decisions that drive that price and have to be taken early — **how many gates**,
+**what cavity pressure**, **how fast it fills** — are settled by running filling simulations on the
+Simcon cloud, not by a rule of thumb.
+
+Two things make it more than a calculator:
+
+- **The agent has its own context.** `shop/` describes a specific shop: its presses, its material
+  bias, how it estimates a mould, what it declines. The agent quotes as *that* shop. It ships
+  filled in with a **fictional** shop, so the first thing to do is the 20-minute interview in
+  [`INTERVIEW.md`](INTERVIEW.md) — until then every quote is watermarked as example data, because
+  a precise price built on someone else's invented rates is worse than no price.
+- **It is meant to be corrected.** Every quote ends with a review. The estimator says what is
+  wrong and *why*; the agent writes the reason into `shop/lessons.md` and the number into that
+  file's `calibration` block, which the cost model reads on the next quote. Expect the first
+  handful of quotes to be mostly learning — that is the design.
+
+## Run it
+
+<!-- simcon-toolkit:setup -->
+**Python 3.12 or newer**, and a virtual environment created *with that interpreter* — a venv
+isolates packages, not the interpreter.
+
+**Three sign-ins, each in your browser, and each does a different job.**
+
+1. **The package index**, once, in the steps below: `cadmould-sdk-auth` lets pip install the
+   licensed `cadmould` wheel from SIMCON's private index. Your company's email domain has to be
+   enabled for it: if you can sign in but the browser tab then says `Access denied: your email
+   domain is not authorized for this API`, ask SIMCON support.
+2. **Your licence**, the first time the code opens a licence session. It first checks the
+   Thales Sentinel run-time on your machine, and prints `License init failed: HASP driver
+   version too old` or `... runtime version too old` when that needs installing or updating.
+3. **The cloud**, the first time the code calls it.
+
+⚠️ A failed licence sign-in does not stop the script. It prints `License init failed: ...` or
+`License acquisition failed.` to the terminal and carries on, so the error you meet later is `Cadmould API licence (LICENCE_API)
+required`. When you see that one, scroll up to the first.
+
+**macOS / Linux (bash):**
+
+```bash
+python3.12 -m venv .venv
+source .venv/bin/activate
+pip install --upgrade pip cadmould-sdk-auth
+cadmould-sdk-auth          # opens a browser; sign in with your Simcon account
+pip install .              # installs cadmould and everything the quoting flow needs
+```
+
+**Windows (PowerShell):**
+
+```powershell
+py -3.12 -m venv .venv
+.\.venv\Scripts\python.exe -m pip install --upgrade pip cadmould-sdk-auth
+$env:VIRTUAL_ENV = "$PWD\.venv"          # tell the login CLI which venv to configure
+.\.venv\Scripts\cadmould-sdk-auth.exe    # opens a browser; sign in with your Simcon account
+.\.venv\Scripts\python.exe -m pip install .
+```
+
+The Windows route never activates the environment. `Activate.ps1` is blocked by the default
+execution policy on many machines; naming the interpreter outright avoids it.
+<!-- /simcon-toolkit:setup -->
+
+Only the `study` stage needs the licensed wheel; `intake`, `cost` and `learn` run offline. No
+graphics stack is involved: the geometry measurements are trimesh's, and the only dependency
+beyond the shared ones is `rtree`, the ~2 MB spatial index behind them.
+
+Then, from the project folder:
+
+```powershell
+# 0. ONCE: make shop/ describe YOUR shop, not the shipped fictional one
+python main.py setup
+
+# 1. what the geometry alone decides (offline, seconds)
+python main.py intake --cavities 4              # uses the bundled sample/
+python main.py intake --part my.stl --cavities 4
+
+# 2. the simulations that settle the cost drivers (cloud; --offline to skip)
+python main.py study --gate-counts 1,2,3
+
+# 3. price every gating option, choose on total cost
+python main.py cost
+
+# 4. the review: apply the estimator's corrections to the shop context
+python main.py learn --quote <key>
+```
+
+Every stage takes the same `--part`, defaulting to the bundled sample. The last one takes
+`--quote` instead: it corrects a quote that already exists and never opens the geometry.
+
+**A quote is keyed on the part's contents, not its file name.** `intake` prints a key such as
+`clip_frame-655b895fd2b5` and every later stage derives the same key from the same file — so
+re-exporting a part starts a new quote rather than silently pricing the new shape against the
+old one's mesh, uploaded geometry and decisions.
+
+Bookkeeping lands in `cache/<key>/` (`state.json`, `decisions.md`); the quote itself lands in
+`output/<key>/quote.json`. Both are safe to delete, and only the cache costs time.
+
+**No cloud access?** Add `--offline` to step 2: gating comes from a rule of thumb instead of the
+solver and every artefact is marked `estimated`. The other three stages need neither a licence
+nor a token.
+
+## But mostly: point an agent at it
+
+The commands above are what the agent runs. The way this is meant to be used is
+[`PROMPT.md`](PROMPT.md) — one plain-English ask, in a session opened in this folder. The
+assistant reads the method from [`METHOD.md`](METHOD.md); there is no skill to load.
+
+## What's here
+
+```
+quoting/
+├── PROMPT.md                    # the prompt to give the agent
+├── INTERVIEW.md                 # the 20-min setup interview that builds YOUR shop context
+├── QUOTING_PLAYBOOK.md          # the method, the cost model, every gotcha (read before adapting)
+├── AGENTS.md                    # how an assistant drives this template
+├── METHOD.md                    # the quoting procedure, stage by stage
+├── shop/                        # THE AGENT'S OWN CONTEXT - replace with your shop
+│   ├── shop-profile.md          #   what we sell, what we do in-house, house quoting rules
+│   ├── machines.md              #   the press list + how to pick one
+│   ├── materials.md             #   house grades, prices, the material bias
+│   ├── tooling.md               #   how a mould is estimated here
+│   ├── commercial.md            #   rates, scrap, overhead, margin, the ladder
+│   └── lessons.md               #   corrections from real quotes + the calibration block
+├── quoting/                     # the code
+│   ├── geometry.py              #   projected area, wall thickness, undercuts (offline)
+│   ├── study.py                 #   the cloud filling study
+│   ├── costing.py               #   clamp, press, cycle, tool price, piece price
+│   ├── shop.py / state.py       #   context loader; quote state, decision log, the learn loop
+│   └── toolkit.py               #   reuses the kit's shared REST client + result metrics
+├── main.py                      # the five stages
+├── sample/                      # the default geometry (written when the project is generated)
+└── parts/                       # drop your own geometries here
+```
+
+## Making the method discoverable
+
+The procedure lives in [`METHOD.md`](METHOD.md) as a plain file, so every assistant can read it
+rather than only the one that loads skills. [`AGENTS.md`](AGENTS.md) points at it, and opening a
+session **in this folder** is enough for a tool that reads either file.
+
+## How it relates to the other templates
+
+This is the **gate-study one layer up**: that template answers *how should this part be gated*, this
+one answers *what should we charge for it*, and uses the gating study as one input among several.
+It reuses the kit's shared REST client and result metrics directly (`quoting/toolkit.py`) rather
+than copying them, so both stay in step.
+
+Prerequisites are the setup and the three sign-ins at the top of this file — and only for the
+`study` stage.
+
+## Read before adapting it
+
+[`QUOTING_PLAYBOOK.md`](QUOTING_PLAYBOOK.md) — what every number rests on, the three geometry
+estimators that are non-obvious for good reasons, why the clamp force is never taken from the
+simulation alone, and §6 on repointing it at your own shop.