simcon-toolkit 0.1.0__py3-none-any.whl

simcon_toolkit/_kit/templates/quoting/quoting/state.py

@@ -0,0 +1,260 @@
+"""Quote state, the local decision log, and the write-back that closes the learning loop.
+
+A quote is identified by the *contents* of its part, never by the part's file name - see
+:func:`part_key`. Its bookkeeping lives under ``cache/<key>/``; the deliverable it produces
+lives under ``output/<key>/``.
+
+Three artefacts per quote, all under ``cache/<key>/``:
+
+* ``state.json``      - what has been decided so far, so a quote survives a lost session and the
+  part is meshed and uploaded exactly once.
+* ``decisions.md``    - the local decision log: every fork, what was chosen, and why. The cloud
+  project notes are the shared copy of this; this one is the primary record.
+* ``corrections.json``- the estimator's answers at review time, written by the agent from the
+  conversation and applied by :func:`apply_corrections`.
+
+They sit in ``cache/`` rather than beside the quote because the next stage reads them: a
+customer who clears ``output/`` must not lose the record that the following stage depends on.
+
+:func:`apply_corrections` is the whole self-improving mechanism: it appends a prose lesson to
+``shop/lessons.md`` **and** merges the numeric part into that file's ``calibration`` block, which
+``costing.py`` reads on the next quote. Prose without a number teaches nobody; a number without
+the prose is unmaintainable. Both, or neither.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import re
+from datetime import date
+from pathlib import Path
+from typing import Any
+
+from .shop import CALIBRATION_DEFAULTS, SHOP_DIR, read_block, write_block
+
+TEMPLATE_ROOT = Path(__file__).resolve().parents[1]
+# Ours: the mesh, the cloud ids, and the record each stage hands the next. Deleting it
+# costs a re-mesh and a re-upload, never a wrong answer.
+CACHE_DIR = TEMPLATE_ROOT / "cache"
+# Yours: the priced quote and the simulation results it was read from. Safe to delete.
+OUTPUT_DIR = TEMPLATE_ROOT / "output"
+
+
+class NoSuchQuote(KeyError):
+    """Raised when a quote is asked for by a key nothing has written."""
+
+
+def part_key(part: str | Path) -> str:
+    """Quote identity for a part: its name, plus enough of its content to be honest.
+
+    The name alone is not an identity. Two customers can both send ``bracket.stl``, and
+    re-exporting a part changes its bytes but not its path - the ordinary working loop
+    here. Either way a name-keyed quote would price the new shape against the previous
+    revision's mesh, uploaded geometry and recorded decisions, with nothing to show it.
+    """
+    part = Path(part)
+    with part.open("rb") as fh:
+        digest = hashlib.file_digest(fh, "sha256").hexdigest()[:12]
+    return f"{part.stem}-{digest}"
+
+
+class AmbiguousQuote(RuntimeError):
+    """Raised when a resuming stage was not told which quote it is resuming."""
+
+
+def part_for_stage(
+    explicit: str | Path | None,
+    default: str | Path,
+    *,
+    cache_root: str | Path = CACHE_DIR,
+) -> Path:
+    """The geometry a *resuming* stage acts on, refusing to guess between quotes.
+
+    A stage that continues a quote must not silently fall back to the bundled sample: a
+    customer who ran ``intake`` on their own part and then omitted the flag would have the
+    sample's quote re-studied and re-priced, and the deliverable written under the sample's
+    key - plausible output, wrong part, no warning. So the default stands only while it is
+    unambiguous, which is the demo case of the sample being the sole quote on file.
+    """
+    if explicit is not None:
+        return Path(explicit)
+    default = Path(default)
+    known = quotes_on_file(cache_root)
+    default_key = part_key(default) if default.is_file() else None
+    if [k for k in known if k != default_key]:
+        listed = "\n  ".join(known)
+        raise AmbiguousQuote(
+            "this stage resumes a quote, so it needs to know which one.\n"
+            "Pass --part pointing at the geometry you ran `intake` on.\n"
+            f"Quotes on file:\n  {listed}"
+        )
+    return default
+
+
+def quotes_on_file(cache_root: str | Path = CACHE_DIR) -> list[str]:
+    """Every quote that has actually been written, newest-looking last.
+
+    A directory alone does not count: a folder can exist before any stage has decided
+    anything, and offering that back as a resumable quote would be a lie.
+    """
+    cache_root = Path(cache_root)
+    if not cache_root.is_dir():
+        return []
+    return sorted(p.name for p in cache_root.iterdir() if (p / "state.json").is_file())
+
+
+# ==========================================================================
+# per-quote state
+# ==========================================================================
+class QuoteState:
+    """A small json file that makes a quote resumable."""
+
+    def __init__(
+        self,
+        key: str,
+        *,
+        cache_root: str | Path = CACHE_DIR,
+        output_root: str | Path = OUTPUT_DIR,
+    ):
+        self.key = key
+        self.dir = Path(cache_root) / key
+        self.output_dir = Path(output_root) / key
+        # Deliberately no mkdir here: opening a quote must leave no trace, or every
+        # mistyped key litters the cache with an empty folder that nothing cleans up.
+        self.path = self.dir / "state.json"
+        self.data: dict[str, Any] = json.loads(self.path.read_text(encoding="utf-8")) if self.path.exists() else {}
+
+    @classmethod
+    def for_part(cls, part: str | Path, **roots: str | Path) -> QuoteState:
+        """The quote for this geometry, opened or started. Keyed on the file's contents."""
+        return cls(part_key(part), **roots)
+
+    @classmethod
+    def open_existing(cls, key: str, **roots: str | Path) -> QuoteState:
+        """An existing quote, by key. Refuses to invent one, and says what it does have.
+
+        Starting a fresh quote here would be silent and wrong: the stage that needs this
+        writes the estimator's corrections, so an empty record swallows the lesson.
+        """
+        quote = cls(key, **roots)
+        if not quote.path.exists():
+            known = quotes_on_file(quote.dir.parent)
+            listed = "\n  ".join(known) if known else "(none yet - run `intake` first)"
+            raise NoSuchQuote(f"no quote on file for '{key}'. Quotes that do exist:\n  {listed}")
+        return quote
+
+    def get(self, key: str, default: Any = None) -> Any:
+        return self.data.get(key, default)
+
+    def update(self, **kw: Any) -> None:
+        self.dir.mkdir(parents=True, exist_ok=True)
+        self.data.update(kw)
+        self.path.write_text(json.dumps(self.data, indent=2, default=str), encoding="utf-8")
+
+    # -- the local decision log -------------------------------------------
+    @property
+    def decisions_path(self) -> Path:
+        return self.dir / "decisions.md"
+
+    def decide(self, title: str, choice: str, why: str, *, alternatives: str = "") -> None:
+        """Append one decision. A fork with no recorded reason is a fork you will re-argue."""
+        path = self.decisions_path
+        if not path.exists():
+            self.dir.mkdir(parents=True, exist_ok=True)
+            path.write_text(
+                f"# Decision log - {self.dir.name}\n\nEvery fork in this quote, what was chosen, "
+                "and why. Written as the quote runs, not summarised afterwards.\n",
+                encoding="utf-8",
+            )
+        block = [f"\n## {date.today().isoformat()} - {title}\n", f"**Chosen:** {choice}\n", f"**Why:** {why}\n"]
+        if alternatives:
+            block.append(f"**Alternatives considered:** {alternatives}\n")
+        with path.open("a", encoding="utf-8") as fh:
+            fh.write("".join(block))
+
+
+# ==========================================================================
+# the learning loop
+# ==========================================================================
+CORRECTIONS_TEMPLATE: dict[str, Any] = {
+    "quote": "<part name>",
+    "reviewer": "<who corrected it>",
+    "corrections": [
+        {
+            "title": "<one line, e.g. 'Cycle time too optimistic'>",
+            "agent_decided": "<what the agent put in the quote>",
+            "corrected_to": "<what it should have been>",
+            "why": "<the estimator's own words - this is the part that transfers>",
+            "rule": "<what to do differently next time>",
+            "calibration": {"<key>": 0.0},
+        }
+    ],
+}
+
+
+def next_lesson_id(lessons_md: Path) -> str:
+    ids = [int(m) for m in re.findall(r"^## L-(\d{3})", lessons_md.read_text(encoding="utf-8"), re.M)]
+    return f"L-{max(ids) + 1 if ids else 1:03d}"
+
+
+def apply_corrections(corrections: dict[str, Any], *, shop_dir: Path = SHOP_DIR, today: str | None = None) -> list[str]:
+    """Write the estimator's corrections into ``shop/lessons.md``. Returns the lesson ids added.
+
+    Numeric changes are validated against the known calibration knobs before anything is written -
+    a typo'd key would otherwise sit in the file looking effective while changing nothing.
+    """
+    lessons = Path(shop_dir) / "lessons.md"
+    stamp = today or date.today().isoformat()
+    quote_name = corrections.get("quote", "unnamed quote")
+    items = corrections.get("corrections", [])
+    if not items:
+        raise ValueError("no corrections given - nothing to learn")
+
+    calibration = read_block(lessons, "calibration")
+    text = lessons.read_text(encoding="utf-8")
+    marker = "<!-- New entries are appended here by `main.py learn`. -->"
+    if marker not in text:
+        raise ValueError("shop/lessons.md has lost its append marker - restore it before learning")
+
+    first_id = int(next_lesson_id(lessons)[2:])
+    added: list[str] = []
+    entries: list[str] = []
+    for n, item in enumerate(items):
+        for key in item.get("calibration") or {}:
+            if key not in CALIBRATION_DEFAULTS:
+                raise ValueError(
+                    f"'{key}' is not a calibration knob the cost model reads. "
+                    f"Known: {', '.join(sorted(CALIBRATION_DEFAULTS))}"
+                )
+        lesson_id = f"L-{first_id + n:03d}"
+        added.append(lesson_id)
+        changed = []
+        for key, value in (item.get("calibration") or {}).items():
+            old = calibration.get(key, CALIBRATION_DEFAULTS[key])
+            calibration[key] = value
+            changed.append(f"`calibration.{key}` {old} -> {value}")
+        entries.append(
+            "\n".join(
+                [
+                    f"## {lesson_id} - {stamp} - {quote_name} - {item.get('title', 'correction')}",
+                    "",
+                    f"**Agent decided:** {item.get('agent_decided', '-')}",
+                    "",
+                    f"**Corrected to:** {item.get('corrected_to', '-')}",
+                    "",
+                    f"**Why (estimator's words):** {item.get('why', '-')}",
+                    "",
+                    f"**Rule for next time:** {item.get('rule', '-')}",
+                    "",
+                    "**Changed:** " + ("; ".join(changed) if changed else "nothing numeric - judgement only"),
+                    "",
+                    "---",
+                    "",
+                ]
+            )
+        )
+
+    lessons.write_text(text.replace(marker, "\n".join(entries) + "\n" + marker), encoding="utf-8")
+    write_block(lessons, "calibration", calibration)
+    return added