stepscribe-cad 0.1.0__py3-none-any.whl

stepscribe/__init__.py

@@ -0,0 +1,28 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright (C) 2026 idris sadiq
+"""stepscribe: turn STEP files into an LLM Context Pack."""
+
+__version__ = "0.1.0"
+
+__all__ = ["__version__", "analyze", "build_context_pack", "export"]
+
+
+def analyze(*args, **kwargs):  # type: ignore[no-untyped-def]
+    """Analyze a STEP file or folder; see :func:`stepscribe.api.analyze`."""
+    from stepscribe.api import analyze as _analyze
+
+    return _analyze(*args, **kwargs)
+
+
+def build_context_pack(*args, **kwargs):  # type: ignore[no-untyped-def]
+    """Build a context pack; see :func:`stepscribe.api.build_context_pack`."""
+    from stepscribe.api import build_context_pack as _b
+
+    return _b(*args, **kwargs)
+
+
+def export(*args, **kwargs):  # type: ignore[no-untyped-def]
+    """Write the portable export; see :func:`stepscribe.exporter.export`."""
+    from stepscribe.exporter import export as _export
+
+    return _export(*args, **kwargs)

stepscribe/analysis.py

@@ -0,0 +1,247 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright (C) 2026 idris sadiq
+"""Per-part analysis: ties readers, geometry and feature detectors into ``Part`` models."""
+
+from __future__ import annotations
+
+import hashlib
+from collections.abc import Callable
+from dataclasses import dataclass, field
+from typing import Any, TypeVar
+
+import numpy as np
+from OCP.TopAbs import TopAbs_SOLID
+from OCP.TopoDS import TopoDS_Shape
+
+from stepscribe.features.bosses import detect_bosses
+from stepscribe.features.cutouts import detect_cutouts
+from stepscribe.features.fillets_chamfers import detect_chamfers, detect_fillets
+from stepscribe.features.holes import detect_holes
+from stepscribe.features.patterns import detect_patterns
+from stepscribe.features.shape_class import classify_shape
+from stepscribe.features.slots_pockets import detect_pockets, detect_slots
+from stepscribe.geometry.occ_utils import unique_subshapes
+from stepscribe.geometry.part_geom import PartGeom
+from stepscribe.geometry.properties import aabb, guess_density, mass_properties, obb
+from stepscribe.geometry.thickness import sample_wall_thickness
+from stepscribe.geometry.topology import topology_summary
+from stepscribe.geometry.validity import is_valid_solid
+from stepscribe.models.schema import (
+    Boss,
+    Chamfer,
+    Cutout,
+    CutoutPattern,
+    Fillet,
+    Hole,
+    HolePattern,
+    Part,
+    Pocket,
+    SemanticTag,
+    ShapeClass,
+    Slot,
+)
+
+T = TypeVar("T")
+
+
+@dataclass
+class AnalyzeOptions:
+    """User-facing options shared by the API, CLI and MCP server."""
+
+    density: float | None = None
+    material: str | None = None
+    up: str = "+Z"
+    front: str = "-Y"
+    no_timestamp: bool = False
+    check_interference: bool = False
+    skip_wall_thickness: bool = False
+    understanding: bool = True
+    check_motion: bool = False
+    motion_budget_s: int = 120
+    debug_graphs: bool = False
+    precision: int = 4
+    extra: dict[str, Any] = field(default_factory=dict)
+
+
+def split_bodies(name: str, shape: TopoDS_Shape) -> list[tuple[str, TopoDS_Shape]]:
+    """One part per solid; several solids become ``<name>_body<n>`` (stable order)."""
+    solids = unique_subshapes(shape, TopAbs_SOLID)
+    if len(solids) <= 1:
+        return [(name, solids[0] if solids else shape)]
+    keyed = []
+    for s in solids:
+        bb = aabb(s)
+        keyed.append(
+            ((round(bb.min.x, 3), round(bb.min.y, 3), round(bb.min.z, 3), round(bb.size.x, 3)), s)
+        )
+    keyed.sort(key=lambda kv: kv[0])
+    return [(f"{name}_body{i}", s) for i, (_k, s) in enumerate(keyed, 1)]
+
+
+def _guarded(label: str, default: T, warnings: list[str], fn: Callable[[], T]) -> T:
+    """Rule 11: per-entity errors become warnings, never tracebacks."""
+    try:
+        return fn()
+    except Exception as exc:  # noqa: BLE001
+        warnings.append(f"{label} failed: {type(exc).__name__}: {exc}")
+        return default
+
+
+def content_hash(part: Part) -> str:
+    """Hash of rounded volume, area, OBB sizes, face-type counts and sorted hole diameters."""
+    parts = [
+        f"{part.mass.volume_mm3:.2f}",
+        f"{part.mass.surface_area_mm2:.2f}",
+        *(f"{s:.2f}" for s in part.obb.size_sorted),
+        *(f"{k}={v}" for k, v in sorted(part.topology.face_types.items())),
+        *(f"{d:.3f}" for d in sorted(h.diameter_mm for h in part.holes)),
+    ]
+    return hashlib.sha1("|".join(parts).encode()).hexdigest()[:16]  # noqa: S324
+
+
+@dataclass
+class AnalyzedPart:
+    """A ``Part`` plus the live geometry that produced it (needed for assembly analysis)."""
+
+    part: Part
+    geom: PartGeom
+
+
+def analyze_geom(
+    geom: PartGeom,
+    source_file: str,
+    opts: AnalyzeOptions,
+    color: list[float] | None = None,
+    semantics: Callable[[PartGeom, Part], list[SemanticTag]] | None = None,
+) -> Part:
+    """Run every analysis step on one solid. Failures become warnings on the part."""
+    shape = geom.shape
+    w: list[str] = []
+    solid = is_valid_solid(shape)
+    if not solid:
+        w.append("shape is not a valid closed solid; results may be unreliable")
+    material = opts.extra.get("part_materials", {}).get(geom.name) or opts.material
+    density = opts.density
+    if density is None and material:
+        guess = guess_density(material)
+        if guess is not None:
+            density = guess[0]
+        else:
+            w.append(f"material '{material}' is not a known keyword; mass left unknown")
+    mass = mass_properties(shape, geom.name, density, material)
+    topo = topology_summary(shape, geom.table)
+    bb, ob = aabb(shape), obb(shape)
+    holes: list[Hole] = _guarded("hole detection", [], w, lambda: detect_holes(geom))
+    patterns: list[HolePattern] = _guarded(
+        "pattern detection", [], w, lambda: detect_patterns(holes)
+    )
+    no_slots: tuple[list[Slot], set[str]] = ([], set())
+    slots_used = _guarded("slot detection", no_slots, w, lambda: detect_slots(geom))
+    slots, slot_faces = slots_used
+    fillets: list[Fillet] = _guarded(
+        "fillet detection", [], w, lambda: detect_fillets(geom, slot_faces)
+    )
+    chamfers: list[Chamfer] = _guarded("chamfer detection", [], w, lambda: detect_chamfers(geom))
+    bosses: list[Boss] = _guarded("boss detection", [], w, lambda: detect_bosses(geom, holes))
+    pockets: list[Pocket] = _guarded("pocket detection", [], w, lambda: detect_pockets(geom, holes))
+    wall = None
+    if not opts.skip_wall_thickness:
+        wall = _guarded("wall thickness", None, w, lambda: sample_wall_thickness(geom))
+    shape_class: ShapeClass = _guarded(
+        "shape classification",
+        ShapeClass(confidence=0.0, evidence="classification failed", label="other"),
+        w,
+        lambda: classify_shape(geom, ob, mass.volume_mm3, mass.surface_area_mm2, holes, wall),
+    )
+    part = Part(
+        id="",
+        name=geom.name,
+        source_file=source_file,
+        content_hash="",
+        is_valid_solid=solid,
+        bbox=bb,
+        obb=ob,
+        mass=mass,
+        topology=topo,
+        shape_class=shape_class,
+        holes=holes,
+        hole_patterns=patterns,
+        fillets=fillets,
+        chamfers=chamfers,
+        bosses=bosses,
+        slots=slots,
+        pockets=pockets,
+        color_rgb=color,
+        min_wall_thickness_mm=wall[0] if wall else None,
+        warnings=[*geom.warnings, *w],
+    )
+    no_cutouts: tuple[list[Cutout], list[CutoutPattern]] = ([], [])
+    part.cutouts, part.cutout_patterns = _guarded(
+        "cutout detection", no_cutouts, part.warnings, lambda: detect_cutouts(geom, part)
+    )
+    if semantics is not None:
+        part.semantic_tags = _guarded(
+            "semantic matching", [], part.warnings, lambda: semantics(geom, part)
+        )
+    if opts.understanding:
+        from stepscribe.understanding import part_understanding
+
+        override = opts.extra.get("part_processes", {}).get(geom.name) or opts.extra.get(
+            "default_process"
+        )
+        part.understanding = _guarded(
+            "understanding", None, part.warnings, lambda: part_understanding(geom, part, override)
+        )
+    part.content_hash = content_hash(part)
+    return part
+
+
+def analyze_brep_file(
+    brep_path: str,
+    name: str,
+    source_file: str,
+    opts: AnalyzeOptions,
+    color: list[float] | None,
+) -> tuple[Part, float]:
+    """Process-pool entry point: load a solid saved as BREP and analyse it (returns Part, seconds)."""
+    import time
+
+    from OCP.BRep import BRep_Builder
+    from OCP.BRepTools import BRepTools
+
+    from stepscribe.semantics import run_semantics
+
+    started = time.time()
+    shape = TopoDS_Shape()
+    if not BRepTools.Read_s(shape, brep_path, BRep_Builder()):
+        raise RuntimeError(f"could not reload part '{name}' for parallel analysis")
+    part = analyze_geom(PartGeom(name, shape), source_file, opts, color, run_semantics)
+    return part, time.time() - started
+
+
+def worker_count(n_parts: int) -> int:
+    """Processes to use for part analysis: env STEPSCRIBE_WORKERS, else CPUs - 1 (min 1)."""
+    import os
+
+    env = os.environ.get("STEPSCRIBE_WORKERS")
+    if env and env.isdigit():
+        return max(1, min(int(env), n_parts))
+    return max(1, min((os.cpu_count() or 2) - 1, n_parts, 8))
+
+
+def assign_part_ids(parts: list[Part]) -> None:
+    """PRT001... sorted by (name, content hash): Rule 6.4."""
+    ordered = sorted(parts, key=lambda p: (p.name, p.content_hash))
+    for i, p in enumerate(ordered, 1):
+        p.id = f"PRT{i:03d}"
+
+
+__all__ = [
+    "AnalyzeOptions",
+    "AnalyzedPart",
+    "analyze_brep_file",
+    "analyze_geom",
+    "assign_part_ids",
+    "np",
+    "split_bodies",
+]

stepscribe/api.py

@@ -0,0 +1,252 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright (C) 2026 idris sadiq
+"""Public Python API: analyse STEP files and build context packs."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import UTC, datetime
+from pathlib import Path
+from typing import Any
+
+from OCP.TopAbs import TopAbs_FACE
+from OCP.TopoDS import TopoDS_Shape
+
+from stepscribe import __version__, config
+from stepscribe.analysis import (
+    AnalyzedPart,
+    AnalyzeOptions,
+    analyze_brep_file,
+    assign_part_ids,
+    split_bodies,
+    worker_count,
+)
+from stepscribe.geometry.occ_utils import unique_subshapes
+from stepscribe.geometry.part_geom import PartGeom
+from stepscribe.io.step_reader import StepModel, StepReadError, read_step
+from stepscribe.models.schema import SCHEMA_VERSION, Meta, Part, Report
+from stepscribe.progress import Tracker
+
+PARALLEL_MIN_PARTS = 3
+PARALLEL_MIN_FACES = 300  # below this, starting processes costs more than it saves
+
+
+@dataclass
+class Analysis:
+    """A report together with the live geometry behind it."""
+
+    report: Report
+    model: StepModel | None
+    parts: list[AnalyzedPart] = field(default_factory=list)
+    proto_to_parts: dict[str, list[str]] = field(default_factory=dict)  # proto key -> part ids
+    understanding_pipeline: Any = None  # cached stages, reused when answers change
+
+
+def _tolerances() -> dict[str, float]:
+    return {
+        k: float(v)
+        for k, v in sorted(vars(config).items())
+        if k.isupper() and isinstance(v, (int, float)) and not isinstance(v, bool)
+    }
+
+
+def _meta(files: list[str], unit: str, opts: AnalyzeOptions) -> Meta:
+    return Meta(
+        schema_version=SCHEMA_VERSION,
+        tool_version=__version__,
+        generated_at=None if opts.no_timestamp else datetime.now(UTC).isoformat(timespec="seconds"),
+        source_files=files,
+        original_length_unit=unit,
+        tolerances=_tolerances(),
+        options={
+            "density": opts.density,
+            "material": opts.material,
+            "up": opts.up,
+            "front": opts.front,
+            "check_interference": opts.check_interference,
+            "understanding": opts.understanding,
+            "check_motion": opts.check_motion,
+            "debug_graphs": opts.debug_graphs,
+        },
+    )
+
+
+def _analyse_bodies(
+    bodies: list[tuple[str, str, TopoDS_Shape, list[float] | None]],
+    faces: dict[int, int],
+    source_file: str,
+    opts: AnalyzeOptions,
+    tracker: Tracker,
+    errors: list[dict[str, object]],
+) -> list[tuple[str, PartGeom, Part]]:
+    """Analyse every body, on a process pool for large assemblies.
+
+    Serial and parallel runs both analyse each part from a BREP copy, so the report is the same
+    whatever the worker count (a reload shifts floats by ~1e-13, which can flip ties such as the
+    axes of a square box, so mixing live and reloaded shapes would not be reproducible).
+    """
+    import multiprocessing as mp
+    import tempfile
+    from concurrent.futures import ProcessPoolExecutor, as_completed
+    from concurrent.futures.process import BrokenProcessPool
+
+    from OCP.BRepTools import BRepTools
+
+    workers = worker_count(len(bodies))
+    if len(bodies) < PARALLEL_MIN_PARTS or sum(faces.values()) < PARALLEL_MIN_FACES:
+        workers = 1
+    results: dict[int, Part] = {}
+
+    def failed(i: int, exc: Exception) -> None:
+        name = bodies[i][1]
+        errors.append({"file": source_file, "part": name, "error": f"{type(exc).__name__}: {exc}"})
+        tracker.part_done(name, faces[id(bodies[i][2])], 0.0)
+
+    with tempfile.TemporaryDirectory(prefix="stepscribe_") as tmp:
+        paths: list[str] = []
+        for i, (_k, name, shape, _c) in enumerate(bodies):
+            f = str(Path(tmp) / f"b{i}.brep")
+            if not BRepTools.Write_s(shape, f):
+                raise RuntimeError(f"could not serialise part '{name}'")
+            paths.append(f)
+
+        def args(i: int) -> tuple[str, str, str, AnalyzeOptions, list[float] | None]:
+            return paths[i], bodies[i][1], source_file, opts, bodies[i][3]
+
+        if workers == 1:
+            for i in range(len(bodies)):
+                try:
+                    results[i], secs = analyze_brep_file(*args(i))
+                except Exception as exc:  # noqa: BLE001
+                    failed(i, exc)
+                    continue
+                tracker.part_done(bodies[i][1], faces[id(bodies[i][2])], secs)
+        else:
+            order = sorted(range(len(bodies)), key=lambda i: -faces[id(bodies[i][2])])  # big first
+            tracker.stage("parts", f"analysing {len(bodies)} parts on {workers} processes")
+            retry: list[int] = []
+            try:
+                with ProcessPoolExecutor(workers, mp_context=mp.get_context("spawn")) as pool:
+                    futures = {pool.submit(analyze_brep_file, *args(i)): i for i in order}
+                    for fut in as_completed(futures):
+                        i = futures[fut]
+                        try:
+                            part, secs = fut.result()
+                        except BrokenProcessPool:
+                            retry.append(i)  # e.g. the caller is a script without a main guard
+                            continue
+                        except Exception as exc:  # noqa: BLE001
+                            failed(i, exc)
+                            continue
+                        results[i] = part
+                        # wall-clock share, so the ETA (faces per second) reflects the parallel speed
+                        tracker.part_done(bodies[i][1], faces[id(bodies[i][2])], secs / workers)
+            except (BrokenProcessPool, RuntimeError, OSError):
+                retry = [i for i in order if i not in results]
+            if retry:
+                tracker.stage(
+                    "parts",
+                    f"process pool unavailable: analysing {len(retry)} part(s) in this process",
+                )
+            for i in sorted(retry):
+                if i in results:
+                    continue
+                try:
+                    results[i], secs = analyze_brep_file(*args(i))
+                except Exception as exc:  # noqa: BLE001
+                    failed(i, exc)
+                    continue
+                tracker.part_done(bodies[i][1], faces[id(bodies[i][2])], secs)
+    return [
+        (bodies[i][0], PartGeom(bodies[i][1], bodies[i][2]), results[i]) for i in sorted(results)
+    ]
+
+
+def analyze_full(
+    path: str | Path, options: AnalyzeOptions | None = None, tracker: Tracker | None = None
+) -> Analysis:
+    """Analyse one STEP file; unreadable files yield a report with an ``errors`` entry."""
+    opts = options or AnalyzeOptions()
+    p = Path(path)
+    try:
+        model = read_step(p)
+    except StepReadError as exc:
+        report = Report(
+            meta=_meta([p.name], "mm", opts), parts=[], errors=[{"file": p.name, "error": str(exc)}]
+        )
+        return Analysis(report, None)
+
+    tracker = tracker or Tracker()
+    bodies = [
+        (key, name, shape, model.protos[key].color_rgb)
+        for key in sorted(model.protos)
+        for name, shape in split_bodies(model.protos[key].name, model.protos[key].shape)
+    ]
+    faces = {id(shape): len(unique_subshapes(shape, TopAbs_FACE)) for _k, _n, shape, _c in bodies}
+    tracker.plan_parts(
+        len(bodies),
+        sum(faces.values()),
+        model.is_assembly or len(model.instances) > 1 or len(bodies) > 1,
+    )
+    parts: list[AnalyzedPart] = []
+    proto_parts: dict[str, list[AnalyzedPart]] = {}
+    warnings = list(model.warnings)
+    errors: list[dict[str, object]] = []
+    done_parts = _analyse_bodies(bodies, faces, p.name, opts, tracker, errors)
+    for key, geom, part in done_parts:
+        ap = AnalyzedPart(part, geom)
+        parts.append(ap)
+        proto_parts.setdefault(key, []).append(ap)
+    assign_part_ids([ap.part for ap in parts])
+    parts.sort(key=lambda ap: ap.part.id)
+    report = Report(
+        meta=_meta([p.name], model.original_unit, opts),
+        parts=[ap.part for ap in parts],
+        warnings=warnings,
+        errors=errors,
+    )
+    analysis = Analysis(
+        report, model, parts, {k: [ap.part.id for ap in v] for k, v in proto_parts.items()}
+    )
+    from stepscribe.assembly import build_assembly
+
+    tracker.stage("assembly", "building assembly relationships")
+    report.assembly = build_assembly(analysis, opts, tracker)
+    if opts.understanding:
+        from stepscribe.understanding import build_understanding
+
+        try:
+            report.understanding = build_understanding(analysis, opts, tracker)
+        except Exception as exc:  # noqa: BLE001 - the measured report must survive
+            report.warnings.append(f"understanding layer failed: {type(exc).__name__}: {exc}")
+    return analysis
+
+
+def analyze(path: str | Path, options: AnalyzeOptions | None = None) -> Report:
+    """Analyse a STEP file and return its :class:`Report`."""
+    return analyze_full(path, options).report
+
+
+def build_context_pack(
+    path: str | Path,
+    out_dir: str | Path,
+    options: AnalyzeOptions | None = None,
+    budget_tokens: int = config.DEFAULT_BUDGET_TOKENS,
+    context_file: str | Path | None = None,
+    images: bool = False,
+    tracker: Tracker | None = None,
+) -> Path:
+    """Analyse *path* and write ``<name>_context_pack/`` under *out_dir*; returns its folder."""
+    from stepscribe.pack.design_context import apply_context, load_context
+    from stepscribe.pack.writer import write_pack
+
+    opts = options or AnalyzeOptions()
+    if context_file:
+        ctx = load_context(context_file)
+        apply_context(opts, ctx)
+    tracker = tracker or Tracker()
+    tracker.images_wanted = images
+    analysis = analyze_full(path, opts, tracker)
+    folder = write_pack(analysis, Path(out_dir), budget_tokens, context_file, images, tracker)
+    tracker.finish("pack written")
+    return folder

stepscribe/assembly/__init__.py

@@ -0,0 +1,99 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright (C) 2026 idris sadiq
+"""Assembly analysis: tree, BOM, contacts, joints, relations, spatial facts."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+import numpy as np
+
+from stepscribe.assembly.bom import build_bom
+from stepscribe.assembly.contacts import detect_contacts
+from stepscribe.assembly.interference import find_interferences
+from stepscribe.assembly.joints import detect_joints, shopping_list
+from stepscribe.assembly.relations import build_relations
+from stepscribe.assembly.spatial import spatial_facts
+from stepscribe.assembly.tree import (
+    InstanceData,
+    build_subassemblies,
+    to_schema_instance,
+    union_bounds,
+)
+from stepscribe.geometry.properties import vec3
+from stepscribe.models.schema import AssemblyInfo
+
+if TYPE_CHECKING:
+    from stepscribe.analysis import AnalyzeOptions
+    from stepscribe.api import Analysis
+    from stepscribe.progress import Tracker
+
+
+def build_instances(analysis: Analysis) -> list[InstanceData]:
+    """One :class:`InstanceData` per placed body, with stable IDs INS001..."""
+    assert analysis.model is not None
+    by_part = {ap.part.id: ap for ap in analysis.parts}
+    rows: list[tuple[str, str, InstanceData]] = []
+    for rec in analysis.model.instances:
+        part_ids = analysis.proto_to_parts.get(rec.proto_key, [])
+        for pid in part_ids:
+            ap = by_part[pid]
+            path = rec.path if len(part_ids) == 1 else f"{rec.path}/{ap.part.name}"
+            rows.append(
+                (
+                    path,
+                    pid,
+                    InstanceData("", ap, rec.matrix, path, rec.parent_path, rec.subassembly),
+                )
+            )
+    rows.sort(key=lambda r: (r[0], r[1]))
+    out = []
+    for n, (_p, _pid, inst) in enumerate(rows, 1):
+        inst.id = f"INS{n:03d}"
+        out.append(inst)
+    return out
+
+
+def build_assembly(
+    analysis: Analysis, opts: AnalyzeOptions, tracker: Tracker | None = None
+) -> AssemblyInfo | None:
+    """Assembly info for files with more than one placed body; None for a single part."""
+    if analysis.model is None or not analysis.parts:
+        return None
+    instances = build_instances(analysis)
+    if len(instances) < 2:
+        return None
+    gbox = union_bounds(instances)
+    contacts = detect_contacts(instances, tracker)
+    joints = detect_joints(instances)
+    relations = build_relations(instances, contacts, joints, opts.up)
+    masses = [i.ap.part.mass.mass_g for i in instances]
+    known = all(m is not None for m in masses)
+    total = float(sum(m for m in masses if m is not None)) if known else None
+    com = None
+    if known and total:
+        weights = np.array([m or 0.0 for m in masses])
+        cents = np.array([i.to_global_point(_centroid(i)) for i in instances])
+        com = vec3((weights[:, None] * cents).sum(axis=0) / total)
+    return AssemblyInfo(
+        root_name=analysis.model.root_name,
+        up_axis=opts.up,
+        front_axis=opts.front,
+        instances=[to_schema_instance(i, None) for i in instances],
+        subassemblies=build_subassemblies(instances),
+        bom=build_bom(instances),
+        global_bbox=gbox,
+        total_mass_g=total,
+        center_of_mass=com,
+        contacts=contacts,
+        fastener_joints=joints,
+        relations=relations,
+        spatial_facts=spatial_facts(instances, contacts, gbox, opts.up, opts.front),
+        interferences=find_interferences(instances) if opts.check_interference else [],
+        fastener_shopping_list=shopping_list(joints),
+    )
+
+
+def _centroid(inst: InstanceData) -> np.ndarray:
+    c = inst.ap.part.mass.centroid
+    return np.array([c.x, c.y, c.z])

stepscribe/assembly/bom.py

@@ -0,0 +1,28 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright (C) 2026 idris sadiq
+"""Bill of materials: instances grouped by part ID and content hash."""
+
+from __future__ import annotations
+
+from stepscribe.assembly.tree import InstanceData
+from stepscribe.models.schema import BOMLine
+
+
+def build_bom(instances: list[InstanceData]) -> list[BOMLine]:
+    """One line per unique part (grouped by ``part_id`` + ``content_hash``), sorted by part ID."""
+    groups: dict[tuple[str, str], list[InstanceData]] = {}
+    for inst in instances:
+        groups.setdefault((inst.part_id, inst.ap.part.content_hash), []).append(inst)
+    lines: list[BOMLine] = []
+    for (pid, _hash), members in sorted(groups.items()):
+        part = members[0].ap.part
+        lines.append(
+            BOMLine(
+                part_id=pid,
+                name=part.name,
+                quantity=len(members),
+                mass_each_g=part.mass.mass_g,
+                category="purchased_hardware" if part.likely_purchased_hardware else "fabricated",
+            )
+        )
+    return lines