napkin2factory 0.1.0__py3-none-any.whl

napkin2factory/__init__.py

@@ -0,0 +1,3 @@
+"""napkin2factory: compile a text-only product model into a manufacturable package."""
+
+__version__ = "0.1.0"

napkin2factory/bom/__init__.py

@@ -0,0 +1 @@
+"""Bill of materials: rollups, validation tiers, CSV/XLSX, curated catalog."""

napkin2factory/bom/files.py

@@ -0,0 +1,313 @@
+"""BOM files: validation (D15), flat CSV and a formatted XLSX workbook (D18, D17).
+
+The rollup numbers are written as values, never formulas, so readers that do not
+calculate (CSV importers, ``openpyxl`` with ``data_only``) see the same totals as
+``rollups.json``.
+"""
+
+from __future__ import annotations
+
+import csv
+import json
+from collections.abc import Iterator
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from napkin2factory.core.graph.rules import RunContext
+
+COLUMNS = [
+    "level",
+    "uri",
+    "id",
+    "rev",
+    "name",
+    "kind",
+    "qty",
+    "total_qty",
+    "process",
+    "material",
+    "finish",
+    "tolerance_class",
+    "unit_cost_usd",
+    "ext_cost_usd",
+    "lead_time_days",
+    "mass_kg",
+    "sourcing_status",
+    "source",
+    "manufacturer",
+]
+
+TOTALS = [
+    ("total_cost_usd", "total_cost"),
+    ("total_mass_kg", "total_mass"),
+    ("part_count", "part_count"),
+    ("custom_count", "custom_count"),
+    ("custom_ratio", "custom_ratio"),
+    ("max_lead_time_days", "max_lead_time"),
+    ("cost_complete", "cost_complete"),
+    ("mass_complete", "mass_complete"),
+]
+
+SOURCING_NOTE = (
+    "Unverified sources are marked in sourcing_status; costs are declared estimates unless "
+    "basis says quote"
+)
+
+_WIDTHS = {
+    "level": 6,
+    "uri": 24,
+    "id": 16,
+    "rev": 6,
+    "name": 32,
+    "kind": 10,
+    "qty": 6,
+    "total_qty": 9,
+    "process": 16,
+    "material": 22,
+    "finish": 18,
+    "tolerance_class": 14,
+    "unit_cost_usd": 13,
+    "ext_cost_usd": 13,
+    "lead_time_days": 14,
+    "mass_kg": 10,
+    "sourcing_status": 15,
+    "source": 28,
+    "manufacturer": 60,
+}
+
+
+def iter_lines(rollups: dict[str, Any]) -> Iterator[dict[str, Any]]:
+    """Every BOM line, depth-first through sub-assemblies, for each top assembly.
+
+    Args:
+        rollups: The ``rollups.json`` payload.
+
+    Yields:
+        Line dicts (as in ``rollups["structure"]``) in display order.
+    """
+
+    def walk(lines: list[dict[str, Any]]) -> Iterator[dict[str, Any]]:
+        for ln in lines:
+            yield ln
+            yield from walk(ln.get("children") or [])
+
+    for top in rollups.get("top_assemblies", []):
+        yield from walk(rollups.get("structure", {}).get(top, []))
+
+
+def line_row(ln: dict[str, Any]) -> dict[str, Any]:
+    """Map a rollup line dict onto the :data:`COLUMNS` (``None`` for unknown numbers).
+
+    Args:
+        ln: One line dict from ``rollups["structure"]``.
+
+    Returns:
+        A dict keyed by the BOM column names.
+    """
+    return {
+        "level": ln.get("level", 0),
+        "uri": ln.get("uri", ""),
+        "id": ln.get("id", ""),
+        "rev": ln.get("rev", ""),
+        "name": ln.get("name", ""),
+        "kind": ln.get("kind", ""),
+        "qty": ln.get("qty"),
+        "total_qty": ln.get("total_qty"),
+        "process": ln.get("process", ""),
+        "material": ln.get("material", ""),
+        "finish": ln.get("finish", ""),
+        "tolerance_class": ln.get("tolerance_class", ""),
+        "unit_cost_usd": ln.get("unit_cost"),
+        "ext_cost_usd": None if ln.get("ext_cost") is None else round(ln["ext_cost"], 6),
+        "lead_time_days": ln.get("lead_time_days"),
+        "mass_kg": ln.get("mass_kg"),
+        "sourcing_status": ln.get("sourcing_status", ""),
+        "source": ln.get("source", ""),
+        "manufacturer": ln.get("manufacturer", ""),
+    }
+
+
+def _csv_value(value: Any) -> Any:
+    if value is None:
+        return ""
+    if isinstance(value, bool):
+        return "true" if value else "false"
+    return value
+
+
+def write_csv(path: Path, rollups: dict[str, Any]) -> Path:
+    """Write the flat ``bom.csv`` (one row per line, then a blank row and the totals).
+
+    Args:
+        path: Destination file.
+        rollups: The ``rollups.json`` payload.
+
+    Returns:
+        ``path``.
+    """
+    with path.open("w", encoding="utf-8", newline="") as fh:
+        writer = csv.writer(fh, lineterminator="\n")
+        writer.writerow(COLUMNS)
+        for ln in iter_lines(rollups):
+            row = line_row(ln)
+            writer.writerow([_csv_value(row[c]) for c in COLUMNS])
+        writer.writerow([])
+        for label, key in TOTALS:
+            writer.writerow([label, _csv_value(rollups.get(key))])
+        writer.writerow(
+            [
+                "note",
+                "This design was produced with an AI system and has not been reviewed "
+                "by a licensed engineer.",
+            ]
+        )
+    return path
+
+
+def write_xlsx(path: Path, rollups: dict[str, Any]) -> Path:
+    """Write ``bom.xlsx`` with the BOM, Rollups, Parts and Manufacturer sheets.
+
+    Args:
+        path: Destination file.
+        rollups: The ``rollups.json`` payload.
+
+    Returns:
+        ``path``.
+    """
+    from openpyxl import Workbook
+    from openpyxl.styles import Alignment, Font
+    from openpyxl.utils import get_column_letter
+
+    bold = Font(bold=True)
+    wb = Workbook()
+    ws = wb.active
+    ws.title = "BOM"
+    ws.append(COLUMNS)
+    for cell in ws[1]:
+        cell.font = bold
+    money = {COLUMNS.index(c) + 1 for c in ("unit_cost_usd", "ext_cost_usd")}
+    mass_col = COLUMNS.index("mass_kg") + 1
+    name_col = COLUMNS.index("name") + 1
+    for ln in iter_lines(rollups):
+        row = line_row(ln)
+        row["name"] = "  " * int(row["level"] or 0) + str(row["name"])
+        ws.append([row[c] for c in COLUMNS])
+        r = ws.max_row
+        for col in money:
+            ws.cell(r, col).number_format = "0.00"
+        ws.cell(r, mass_col).number_format = "0.000"
+        ws.cell(r, name_col).alignment = Alignment(indent=int(row["level"] or 0))
+    ws.freeze_panes = "A2"
+    for i, col in enumerate(COLUMNS, start=1):
+        ws.column_dimensions[get_column_letter(i)].width = _WIDTHS.get(col, 12)
+
+    ws.append([])
+    ws.append(["Totals"])
+    ws.cell(ws.max_row, 1).font = bold
+    for label, key in TOTALS:
+        ws.append([label, rollups.get(key)])
+        r = ws.max_row
+        ws.cell(r, 1).font = bold
+        if key == "total_cost":
+            ws.cell(r, 2).number_format = "0.00"
+        elif key == "total_mass":
+            ws.cell(r, 2).number_format = "0.000"
+    ws.append([])
+    ws.append([SOURCING_NOTE])
+    ws.cell(ws.max_row, 1).font = Font(italic=True)
+
+    rs = wb.create_sheet("Rollups")
+    rs.append(["key", "value"])
+    for cell in rs[1]:
+        cell.font = bold
+    for key in (
+        "total_cost",
+        "total_cost_unit",
+        "cost_complete",
+        "total_mass",
+        "total_mass_unit",
+        "mass_complete",
+        "part_count",
+        "distinct_parts",
+        "custom_count",
+        "custom_ratio",
+        "max_lead_time",
+        "max_lead_time_unit",
+    ):
+        if key in rollups:
+            rs.append([key, rollups[key]])
+    rs.append(["top_assemblies", ", ".join(rollups.get("top_assemblies", []))])
+    rs.append(["orphans", ", ".join(rollups.get("orphans", []))])
+    rs.column_dimensions["A"].width = 20
+    rs.column_dimensions["B"].width = 30
+
+    ps = wb.create_sheet("Parts")
+    part_cols = [
+        "uri",
+        "name",
+        "kind",
+        "total_qty",
+        "unit_cost",
+        "lead_time_days",
+        "mass_kg",
+        "sourcing_status",
+    ]
+    ps.append(part_cols)
+    for cell in ps[1]:
+        cell.font = bold
+    for part in rollups.get("parts", {}).values():
+        ps.append([part.get(c) for c in part_cols])
+        r = ps.max_row
+        ps.cell(r, part_cols.index("unit_cost") + 1).number_format = "0.00"
+        ps.cell(r, part_cols.index("mass_kg") + 1).number_format = "0.000"
+    for i, w in enumerate((24, 32, 10, 9, 10, 14, 10, 15), start=1):
+        ps.column_dimensions[get_column_letter(i)].width = w
+    ps.freeze_panes = "A2"
+
+    ms = wb.create_sheet("Manufacturer")
+    ms.append(["uri", "name", "kind", "total_qty", "instruction"])
+    for cell in ms[1]:
+        cell.font = bold
+    seen: set[str] = set()
+    for ln in iter_lines(rollups):
+        if ln.get("kind") == "assembly" or ln.get("uri") in seen:
+            continue
+        seen.add(str(ln.get("uri")))
+        total = (
+            rollups.get("parts", {}).get(ln.get("uri"), {}).get("total_qty", ln.get("total_qty"))
+        )
+        ms.append(
+            [ln.get("uri"), ln.get("name"), ln.get("kind"), total, ln.get("manufacturer", "")]
+        )
+        ms.cell(ms.max_row, 5).alignment = Alignment(wrap_text=True, vertical="top")
+    for i, w in enumerate((24, 32, 10, 9, 80), start=1):
+        ms.column_dimensions[get_column_letter(i)].width = w
+    ms.freeze_panes = "A2"
+
+    wb.save(path)
+    return path
+
+
+def write_bom_files(ctx: RunContext, rollups: dict[str, Any]) -> list[Path]:
+    """Write ``validation.json``, ``bom.csv`` and ``bom.xlsx``; return the files written.
+
+    Args:
+        ctx: The build context.
+        rollups: The ``rollups.json`` payload from ``compute_rollups``.
+
+    Returns:
+        ``[validation.json, bom.csv, bom.xlsx]``.
+    """
+    from napkin2factory.bom.validation import validate_bom
+
+    out_dir = ctx.build_dir / "bom"
+    out_dir.mkdir(parents=True, exist_ok=True)
+    validation = validate_bom(ctx.product, ctx.build_dir)
+    path = out_dir / "validation.json"
+    path.write_text(json.dumps(validation, indent=2, sort_keys=True) + "\n", encoding="utf-8")
+    return [
+        path,
+        write_csv(out_dir / "bom.csv", rollups),
+        write_xlsx(out_dir / "bom.xlsx", rollups),
+    ]

napkin2factory/bom/rollups.py

@@ -0,0 +1,297 @@
+"""BOM structure and rollups (D18): quantities through sub-assemblies, cost, mass, counts.
+
+Every declared value is read through recording selectors so the ``bom`` rule's
+dependencies are exact (``part://x#cost.unit``, ``asm://y#children``, ``part://x#props.mass``).
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+from napkin2factory.core.loader import Product
+from napkin2factory.core.model import Part
+from napkin2factory.core.units import format_quantity, parse_quantity
+from napkin2factory.geometry.accessors import ReadLog
+
+
+@dataclass
+class BomLine:
+    """One indented BOM row."""
+
+    level: int
+    uri: str
+    id: str
+    name: str
+    kind: str
+    qty: int  # quantity at this position (per parent)
+    total_qty: int  # rolled-up quantity in the top assembly
+    process: str = ""
+    material: str = ""
+    finish: str = ""
+    tolerance_class: str = ""
+    unit_cost: float | None = None
+    cost_basis: str = ""
+    lead_time_days: float | None = None
+    mass_kg: float | None = None
+    mass_source: str = ""
+    source: str = ""
+    sourcing_status: str = ""
+    manufacturer: str = ""
+    rev: str = ""
+    children: list[BomLine] = field(default_factory=list)
+
+    @property
+    def ext_cost(self) -> float | None:
+        """Extended cost (unit × total quantity)."""
+        return None if self.unit_cost is None else self.unit_cost * self.total_qty
+
+
+def _props_mass(build_dir: Path | None, part: Part) -> tuple[float | None, str]:
+    if part.mass is not None:
+        return float(part.mass.to("kg").magnitude), "declared"
+    if build_dir is None:
+        return None, "not built"
+    p = build_dir / "parts" / part.id / "props.json"
+    if not p.is_file():
+        return None, "not built"
+    import json
+
+    data = json.loads(p.read_text(encoding="utf-8"))
+    return float(data["mass"]), str(data.get("mass_source", "computed"))
+
+
+def manufacturer_column(part: Part, qty: int) -> str:
+    """The "what to tell the manufacturer" text for a row."""
+    if part.kind == "reference":
+        return f"supplied by the owner / already exists: {part.name} ({qty}×); not quoted"
+    if part.kind == "cots":
+        src = part.source
+        return f"buy {qty}× {part.name}" + (f" ({src.vendor} {src.mpn})" if src else "")
+    bits = [part.process]
+    if part.material:
+        bits.append(part.material.spec or part.material.name)
+    if part.finish:
+        bits.append(part.finish)
+    if part.tolerance_class:
+        bits.append(part.tolerance_class)
+    bits.append(f"qty {qty}")
+    if part.manufacturer_notes:
+        bits.append(part.manufacturer_notes)
+    return "; ".join(b for b in bits if b)
+
+
+def sourcing_status(part: Part) -> str:
+    """Complete | unverified | missing — before the URL/catalog tiers run (M4 refines)."""
+    if part.kind == "reference":
+        return "reference"
+    if part.kind != "cots":
+        return "custom"
+    if part.source is None:
+        return "missing"
+    if not part.source.url:
+        return "no-url"
+    return "verified" if part.source.verified else "unverified"
+
+
+def build_lines(
+    product: Product,
+    asm_id: str,
+    log: ReadLog,
+    build_dir: Path | None,
+    level: int = 0,
+    multiplier: int = 1,
+) -> list[BomLine]:
+    """Indented lines for one assembly, recursing into sub-assemblies."""
+    asm = product.assemblies[asm_id]
+    log.add(f"asm://{asm_id}#children")
+    lines: list[BomLine] = []
+    for child in asm.children:
+        if child.part is not None:
+            part = product.parts[child.part.id]
+            for sel in (
+                "name",
+                "kind",
+                "process",
+                "material",
+                "finish",
+                "tolerance_class",
+                "cost",
+                "lead_time",
+                "source",
+                "rev",
+                "mass",
+                "manufacturer_notes",
+            ):
+                log.add(f"{part.uri}#{sel}")
+            mass, mass_src = _props_mass(build_dir, part)
+            log.add(f"{part.uri}#geometry")
+            if part.mass is None and part.has_geometry:
+                log.add(f"{part.uri}#props.mass")
+            lines.append(
+                BomLine(
+                    level=level,
+                    uri=part.uri,
+                    id=part.id,
+                    name=part.name,
+                    kind=part.kind,
+                    qty=child.qty,
+                    total_qty=child.qty * multiplier,
+                    process=part.process,
+                    material=(part.material.spec or part.material.name) if part.material else "",
+                    finish=part.finish or "",
+                    tolerance_class=part.tolerance_class or "",
+                    unit_cost=float(part.cost.unit.to("USD").magnitude) if part.cost else None,
+                    cost_basis=part.cost.basis if part.cost else "",
+                    lead_time_days=float(part.lead_time.to("day").magnitude)
+                    if part.lead_time
+                    else None,
+                    mass_kg=mass,
+                    mass_source=mass_src,
+                    source=f"{part.source.vendor} {part.source.mpn}" if part.source else "",
+                    sourcing_status=sourcing_status(part),
+                    manufacturer=manufacturer_column(part, child.qty * multiplier),
+                    rev=part.rev,
+                )
+            )
+        elif child.asm is not None:
+            sub = product.assemblies[child.asm.id]
+            log.add(f"{sub.uri}#name")
+            log.add(f"{sub.uri}#rev")
+            line = BomLine(
+                level=level,
+                uri=sub.uri,
+                id=sub.id,
+                name=sub.name,
+                kind="assembly",
+                qty=child.qty,
+                total_qty=child.qty * multiplier,
+                rev=sub.rev,
+            )
+            line.children = build_lines(
+                product, sub.id, log, build_dir, level + 1, multiplier * child.qty
+            )
+            lines.append(line)
+    return lines
+
+
+def flatten_lines(lines: list[BomLine]) -> list[BomLine]:
+    """Depth-first list including nested children."""
+    out: list[BomLine] = []
+    for ln in lines:
+        out.append(ln)
+        out.extend(flatten_lines(ln.children))
+    return out
+
+
+def top_assemblies(product: Product) -> list[str]:
+    """Assemblies no other assembly contains."""
+    used = {c.asm.id for a in product.assemblies.values() for c in a.children if c.asm is not None}
+    return sorted(a for a in product.assemblies if a not in used)
+
+
+def compute_rollups(
+    product: Product, build_dir: Path | None = None, log: ReadLog | None = None
+) -> dict[str, Any]:
+    """The ``rollups.json`` payload: lines per top assembly plus totals."""
+    log = log if log is not None else ReadLog()
+    log.add("set://parts")
+    log.add("set://asms")
+    tops = top_assemblies(product)
+    per_part: dict[str, dict[str, Any]] = {}
+    structure: dict[str, list[dict[str, Any]]] = {}
+    for top in tops:
+        lines = build_lines(product, top, log, build_dir)
+        structure[f"asm://{top}"] = [line_to_dict(ln) for ln in lines]
+        for ln in flatten_lines(lines):
+            if ln.kind == "assembly":
+                continue
+            agg = per_part.setdefault(
+                ln.uri,
+                {
+                    "uri": ln.uri,
+                    "name": ln.name,
+                    "kind": ln.kind,
+                    "total_qty": 0,
+                    "unit_cost": ln.unit_cost,
+                    "lead_time_days": ln.lead_time_days,
+                    "mass_kg": ln.mass_kg,
+                    "sourcing_status": ln.sourcing_status,
+                },
+            )
+            agg["total_qty"] += ln.total_qty
+    total_cost = 0.0
+    cost_known = True
+    total_mass = 0.0
+    mass_known = True
+    max_lead = 0.0
+    custom = 0
+    part_count = 0
+    for agg in per_part.values():
+        part_count += agg["total_qty"]
+        if agg["kind"] == "custom":
+            custom += agg["total_qty"]
+        if agg["kind"] == "reference":
+            pass  # not bought, not made: contributes mass but no cost
+        elif agg["unit_cost"] is None:
+            cost_known = False
+        else:
+            total_cost += agg["unit_cost"] * agg["total_qty"]
+        if agg["mass_kg"] is None:
+            mass_known = False
+        else:
+            total_mass += agg["mass_kg"] * agg["total_qty"]
+        if agg["lead_time_days"] is not None:
+            max_lead = max(max_lead, agg["lead_time_days"])
+    # Parts in no assembly still count for sourcing but not for totals.
+    orphans = sorted(p.uri for p in product.parts.values() if p.uri not in per_part)
+    return {
+        "top_assemblies": [f"asm://{t}" for t in tops],
+        "structure": structure,
+        "parts": dict(sorted(per_part.items())),
+        "orphans": orphans,
+        "total_cost": round(total_cost, 2),
+        "total_cost_unit": "USD",
+        "cost_complete": cost_known,
+        "total_mass": round(total_mass, 4),
+        "total_mass_unit": "kg",
+        "mass_complete": mass_known,
+        "part_count": part_count,
+        "distinct_parts": len(per_part),
+        "custom_count": custom,
+        "custom_ratio": round(custom / part_count, 4) if part_count else 0.0,
+        "max_lead_time": max_lead,
+        "max_lead_time_unit": "d",
+        "reads": log.keys,
+    }
+
+
+def line_to_dict(ln: BomLine) -> dict[str, Any]:
+    """JSON form of a line (recursive)."""
+    d = {k: v for k, v in ln.__dict__.items() if k != "children"}
+    d["ext_cost"] = ln.ext_cost
+    d["children"] = [line_to_dict(c) for c in ln.children]
+    return d
+
+
+def rollup_value(rollups: dict[str, Any], selector: str) -> Any:
+    """``bom://rollups#total_cost`` → a pint quantity (or plain number) for the checks."""
+    units = {"total_cost": "USD", "total_mass": "kg", "max_lead_time": "d"}
+    if selector not in rollups:
+        raise KeyError(
+            f"bom://rollups has no {selector!r}; available: total_cost, total_mass, "
+            "part_count, custom_ratio, max_lead_time"
+        )
+    val = rollups[selector]
+    return parse_quantity(val, units.get(selector)) if isinstance(val, (int, float)) else val
+
+
+__all__ = [
+    "BomLine",
+    "compute_rollups",
+    "flatten_lines",
+    "format_quantity",
+    "rollup_value",
+    "top_assemblies",
+]