autoassembler 0.3.1__py3-none-any.whl

autoassembler/_custom/planning.py

@@ -0,0 +1,598 @@
+"""The `ProcessPlan` handle and the curated `client.planning` namespace.
+
+Hand-written, protected via `.fernignore`. Built on the generated client, which
+stays reachable as ``client.api.planning`` for anything not covered here (the full
+PATCH op vocabulary, replace, ...).
+
+Vocabulary: a `ProcessPlan` is a manufacturing process plan (MPP) for one assembly,
+made of `Station`s; ``plan()``, ``validate()`` and ``evaluate_dfa()`` return an
+``Operation`` whose result is one record per requested station, in the document's
+own words (``complete | partial | failed``, ``feasible | infeasible``).
+``client.planning.adapt()`` carries a plan over to a revised assembly.
+
+Everything the handle shows is **derived from the document**, never stored on the
+client: `Part`s are the source state-of-assembly nodes of the station graph,
+``unassigned_parts`` are those with no station edge in either direction (the server's
+``computeUnassigned``), a station's ``inputs`` are its incoming boundary, and its
+``status`` / ``feasibility`` read ``plan.status[s]`` / ``plan.feasibility[s]``.
+
+A run's `Operation` is the server's: it is done once the run's results are saved, and
+its result is then read from the document. A station is authored with one PATCH of two
+public ops; the server expands the move into edges and the station's output node.
+"""
+
+from __future__ import annotations
+
+import secrets
+import typing
+from collections.abc import Iterable, Iterator
+from dataclasses import dataclass
+
+from ..alpha.planning.types.apply_ops_planning_request_ops_item import (
+    ApplyOpsPlanningRequestOpsItem,
+)
+from ..core.request_options import RequestOptions
+from ..errors.conflict_error import ConflictError
+from ..operation import Operation
+from ..types.diff_report import DiffReport
+from ..types.manufacturing_process_plan import ManufacturingProcessPlan
+from ..types.operation import Operation as OperationResource
+from ..types.operation_metadata import (
+    OperationMetadata_MppEvaluateDfa,
+    OperationMetadata_MppPlan,
+    OperationMetadata_MppValidate,
+)
+from ..types.operation_response import OperationResponse_MppAdapt
+
+if typing.TYPE_CHECKING:
+    from ..client import AutoAssembler
+    from .assemblies import Assembly
+
+PlanningStatus = typing.Literal["pending", "complete", "partial", "failed"]
+"""How far a station's refinement got. ``partial`` is a usable plan, not an error."""
+
+FeasibilityStatus = typing.Literal["feasible", "infeasible"]
+"""Whether a station's planned steps can be physically carried out."""
+
+_STATION_RUN_METADATA = (
+    OperationMetadata_MppPlan,
+    OperationMetadata_MppValidate,
+    OperationMetadata_MppEvaluateDfa,
+)
+
+# ---------------------------------------------------------------------------
+# Derived records
+# ---------------------------------------------------------------------------
+
+
+@dataclass(frozen=True)
+class Part:
+    """A unit of material in the station graph: one occurrence, or a preassembled group.
+
+    ``id`` is the state-of-assembly node id, which is what every planning op names.
+    """
+
+    id: str
+    occurrences: tuple[str, ...]
+    name: str | None = None
+
+
+@dataclass(frozen=True)
+class StationPlanStatus:
+    """A station's planning outcome, as persisted at ``plan.status[station_id]``."""
+
+    station_id: str
+    status: PlanningStatus
+    messages: tuple[str, ...] = ()
+    findings: tuple[dict[str, typing.Any], ...] = ()
+    assumptions: tuple[dict[str, typing.Any], ...] = ()
+
+
+@dataclass(frozen=True)
+class StationFeasibility:
+    """A station's validation verdict, as persisted at ``plan.feasibility[station_id]``."""
+
+    station_id: str
+    status: FeasibilityStatus
+    messages: tuple[str, ...] = ()
+    issues: tuple[dict[str, typing.Any], ...] = ()
+
+
+@dataclass(frozen=True)
+class StationDfaReport:
+    """A station's DFA scores, as persisted at ``plan.dfa[station_id]`` (raw report)."""
+
+    station_id: str
+    report: dict[str, typing.Any]
+
+    @property
+    def total_score(self) -> float | None:
+        return self.report.get("total_score")
+
+    @property
+    def average_score(self) -> float | None:
+        return self.report.get("average_score")
+
+
+class StationOutcomes[R]:
+    """One record per requested station, indexable by `Station` or id.
+
+    ``skipped`` lists requested stations the server accepted but did not run (nothing
+    to do for them); they have no record here.
+    """
+
+    def __init__(self, records: dict[str, R], *, skipped: Iterable[str] = ()):
+        self._records = dict(records)
+        self.skipped: tuple[str, ...] = tuple(skipped)
+
+    def __getitem__(self, station: Station | str) -> R:
+        return self._records[station.id if isinstance(station, Station) else station]
+
+    def __contains__(self, station: object) -> bool:
+        key = station.id if isinstance(station, Station) else station
+        return key in self._records
+
+    def __iter__(self) -> Iterator[str]:
+        return iter(self._records)
+
+    def __len__(self) -> int:
+        return len(self._records)
+
+    def items(self) -> typing.ItemsView[str, R]:
+        return self._records.items()
+
+    def values(self) -> typing.ValuesView[R]:
+        return self._records.values()
+
+    def __repr__(self) -> str:
+        return f"{type(self).__name__}({self._records!r}, skipped={self.skipped!r})"
+
+
+class PlanOutcome(StationOutcomes[StationPlanStatus]):
+    """Result of `ProcessPlan.plan`. ``ok`` iff every station came out ``complete``."""
+
+    @property
+    def ok(self) -> bool:
+        return all(record.status == "complete" for record in self.values())
+
+
+class FeasibilityOutcome(StationOutcomes[StationFeasibility]):
+    """Result of `ProcessPlan.validate`. ``ok`` iff every station is ``feasible``."""
+
+    @property
+    def ok(self) -> bool:
+        return all(record.status == "feasible" for record in self.values())
+
+
+class DfaOutcome(StationOutcomes[StationDfaReport]):
+    """Result of `ProcessPlan.evaluate_dfa`: one scored report per station."""
+
+
+# ---------------------------------------------------------------------------
+# Handles
+# ---------------------------------------------------------------------------
+
+
+class Station:
+    """A station of a `ProcessPlan`: a manufacturing stage that takes some parts in.
+
+    Everything on it is read from the plan's latest fetched document.
+    """
+
+    def __init__(self, plan: ProcessPlan, id: str):
+        self.plan = plan
+        self.id = id
+
+    def __repr__(self) -> str:
+        return f"Station({self.id!r}, name={self.name!r}, status={self.status!r})"
+
+    def __eq__(self, other: object) -> bool:
+        return isinstance(other, Station) and (other.plan.id, other.id) == (self.plan.id, self.id)
+
+    def __hash__(self) -> int:
+        return hash((self.plan.id, self.id))
+
+    @property
+    def name(self) -> str:
+        return str(_stations(self.plan.document).get(self.id, {}).get("name", self.id))
+
+    @property
+    def inputs(self) -> list[Part]:
+        """The parts this station takes in (its incoming boundary)."""
+        doc = self.plan.document
+        soas = _soas(doc)
+        return [
+            _part(soas[edge["from"]])
+            for edge in _edges(doc).values()
+            if edge.get("to") == self.id and edge.get("from") in soas
+        ]
+
+    @property
+    def status(self) -> PlanningStatus:
+        """``pending`` until a planning run has written a record for this station."""
+        return _plan_status(self.plan.document, self.id).status
+
+    @property
+    def feasibility(self) -> FeasibilityStatus | None:
+        """``None`` until a validation run has written a verdict for this station."""
+        record = _feasibility(self.plan.document, self.id)
+        return record.status if record else None
+
+
+class ProcessPlan:
+    """A manufacturing process plan (MPP) for one assembly: the handle planning verbs hang off.
+
+    Holds its addressing (assembly, id), the last fetched document and nothing else:
+    every mutation goes to the server first. Obtained from ``client.planning.create_mpp``,
+    ``get_mpp`` or ``list_mpps``; never constructed directly.
+    """
+
+    def __init__(
+        self,
+        client: AutoAssembler,
+        assembly: Assembly,
+        *,
+        id: str,
+        document: ManufacturingProcessPlan | None = None,
+        name: str | None = None,
+        version: int | None = None,
+    ):
+        self._client = client
+        self.assembly = assembly
+        self.id = id
+        self._document = document
+        self._name = name
+        self._version = version
+
+    def __repr__(self) -> str:
+        return f"ProcessPlan({self.id!r}, name={self.name!r}, assembly={self.assembly.id!r})"
+
+    # -- document -----------------------------------------------------------------
+
+    @property
+    def document(self) -> ManufacturingProcessPlan:
+        """The last fetched document (fetched on first access)."""
+        if self._document is None:
+            self.refresh()
+        assert self._document is not None
+        return self._document
+
+    def refresh(self) -> ProcessPlan:
+        """Re-read the document from the server."""
+        response = self._client.api.planning.get_mpp(
+            self.assembly.namespace, self.assembly.id, self.id
+        )
+        self._document = response.doc
+        self._name = response.doc.name
+        self._version = response.doc.version
+        return self
+
+    @property
+    def name(self) -> str:
+        return self._name if self._name is not None else self.document.name
+
+    @property
+    def version(self) -> int:
+        """The document version last seen; sent with every mutation to detect concurrent edits."""
+        return self._version if self._version is not None else self.document.version
+
+    @property
+    def viewer_url(self) -> str:
+        """The plan in the UI."""
+        base = self._client.base_url
+        return f"{base}/assemblies-mpp/{self.assembly.namespace}/{self.assembly.id}?mpp={self.id}"
+
+    # -- derived views --------------------------------------------------------------
+
+    @property
+    def stations(self) -> list[Station]:
+        return [Station(self, station_id) for station_id in _stations(self.document)]
+
+    def station(self, id: str) -> Station:
+        if id not in _stations(self.document):
+            raise KeyError(f"process plan {self.id} has no station {id!r}")
+        return Station(self, id)
+
+    @property
+    def parts(self) -> list[Part]:
+        """Every source part the plan knows (one per eBOM occurrence, or a preassembled group)."""
+        return [_part(soa) for soa in _soas(self.document).values()]
+
+    @property
+    def unassigned_parts(self) -> list[Part]:
+        """Parts no station takes in or produces yet (the server's ``computeUnassigned``)."""
+        doc = self.document
+        touched = set()
+        for edge in _edges(doc).values():
+            touched.add(edge.get("from"))
+            touched.add(edge.get("to"))
+        return [_part(soa) for soa_id, soa in _soas(doc).items() if soa_id not in touched]
+
+    # -- authoring ------------------------------------------------------------------
+
+    def add_station(self, name: str, *, parts: Iterable[Part | str] | None = None) -> Station:
+        """Create a station and assign parts to it; every unassigned part by default.
+
+        One PATCH: the station node plus a move of the parts onto it. The server
+        expands the move into the station's input edges and its output node, so the
+        station is ready to plan when this returns.
+        """
+        station_id = f"st-{secrets.token_hex(4)}"
+        part_ids = (
+            [part.id for part in self.unassigned_parts]
+            if parts is None
+            else [part.id if isinstance(part, Part) else part for part in parts]
+        )
+        ops: list[dict[str, typing.Any]] = [
+            {"op": "addStationNode", "station": {"id": station_id, "name": name}},
+        ]
+        if part_ids:
+            ops.append(
+                {
+                    "op": "moveSourceSoasToStation",
+                    "sourceSoaIds": part_ids,
+                    "toStationId": station_id,
+                }
+            )
+        self._apply(ops)
+        return Station(self, station_id)
+
+    def _apply(self, ops: list[dict[str, typing.Any]]) -> None:
+        """Send one op batch at the current version; on a stale version, refresh and retry once.
+
+        The generated transport would retry a 409 by itself, with backoff; a version
+        conflict can never be fixed by resending the same version, so that is turned off.
+        """
+        items = [ApplyOpsPlanningRequestOpsItem.model_validate(op) for op in ops]
+        for attempt in (1, 2):
+            try:
+                self._client.api.alpha.planning.apply_ops(
+                    self.assembly.namespace,
+                    self.assembly.id,
+                    self.id,
+                    version=self.version,
+                    ops=items,
+                    request_options=RequestOptions(max_retries=0),
+                )
+                break
+            except ConflictError:
+                if attempt == 2:
+                    raise
+                self.refresh()
+        self.refresh()
+
+    def delete(self) -> None:
+        self._client.api.planning.delete_mpp(self.assembly.namespace, self.assembly.id, self.id)
+
+    # -- long-running verbs -----------------------------------------------------------
+
+    def plan(
+        self, station: Station | str, *more: Station | str, overwrite: bool = True
+    ) -> Operation[PlanOutcome]:
+        """Have the planner work out the assembly steps of the given stations.
+
+        Every station must be ready to plan (inputs assigned, one supported output), or
+        the whole request is refused (400 ``stations_not_ready_to_plan``, listing them).
+        Returns immediately with an ``Operation[PlanOutcome]``; ``result(timeout=...)``
+        returns one `StationPlanStatus` per requested station: ``complete``, ``partial``
+        (a usable partial plan, with messages saying what it could not place) or
+        ``failed``. A station that already has a plan is re-planned unless
+        ``overwrite=False``, which refuses the whole request (409) instead.
+        """
+        accepted = self._client.api.planning.plan(
+            self.assembly.namespace,
+            self.assembly.id,
+            self.id,
+            station_ids=self._station_ids((station, *more)),
+            overwrite=overwrite,
+        )
+
+        def outcome(doc: ManufacturingProcessPlan, queued: list[str], skipped: list[str]):
+            return PlanOutcome({s: _plan_status(doc, s) for s in queued}, skipped=skipped)
+
+        return self._outcome_operation(accepted.operation, outcome)
+
+    def validate(
+        self, *stations: Station | str, fix_directions: bool = False
+    ) -> Operation[FeasibilityOutcome]:
+        """Check that the planned steps of the given stations (all, if none given) are feasible.
+
+        Returns immediately with an ``Operation[FeasibilityOutcome]``; ``result()``
+        returns one `StationFeasibility` per station that was checked: ``feasible`` or
+        ``infeasible``, with the issues behind the verdict. Stations without planned
+        steps are reported in ``skipped``. ``fix_directions`` lets the server repair a
+        blocked step's direction when a free one exists.
+        """
+        kwargs: dict[str, typing.Any] = {}
+        if fix_directions:
+            kwargs["fix_directions"] = True
+        accepted = self._client.api.planning.validate(
+            self.assembly.namespace,
+            self.assembly.id,
+            self.id,
+            station_ids=self._station_ids(stations),
+            **kwargs,
+        )
+
+        def outcome(doc: ManufacturingProcessPlan, queued: list[str], skipped: list[str]):
+            records = {s: r for s in queued if (r := _feasibility(doc, s)) is not None}
+            return FeasibilityOutcome(records, skipped=skipped)
+
+        return self._outcome_operation(accepted.operation, outcome)
+
+    def evaluate_dfa(self, *stations: Station | str) -> Operation[DfaOutcome]:
+        """Score the given stations' planned steps for design-for-assembly.
+
+        With no stations named, every scorable station is scored.
+
+        A named station must be planned and ``feasible``, or the request is refused
+        (409). Returns immediately with an ``Operation[DfaOutcome]``; ``result()``
+        returns one `StationDfaReport` per scored station.
+        """
+        kwargs: dict[str, typing.Any] = {}
+        if stations:
+            kwargs["station_ids"] = self._station_ids(stations)
+        accepted = self._client.api.planning.evaluate_dfa(
+            self.assembly.namespace, self.assembly.id, self.id, **kwargs
+        )
+
+        def outcome(doc: ManufacturingProcessPlan, queued: list[str], skipped: list[str]):
+            records = {
+                s: StationDfaReport(s, report)
+                for s in queued
+                if (report := _dfa(doc, s)) is not None
+            }
+            return DfaOutcome(records, skipped=skipped)
+
+        return self._outcome_operation(accepted.operation, outcome)
+
+    def _station_ids(self, stations: tuple[Station | str, ...]) -> list[str]:
+        if not stations:
+            return list(_stations(self.document))
+        return [s.id if isinstance(s, Station) else s for s in stations]
+
+    def _outcome_operation[R](
+        self,
+        operation: OperationResource,
+        outcome: typing.Callable[[ManufacturingProcessPlan, list[str], list[str]], R],
+    ) -> Operation[R]:
+        """The run's operation, resolving to ``outcome`` of the document once it is done.
+
+        The stations come from the operation's metadata: those it ran and those it skipped.
+        """
+
+        def resolve(finished: OperationResource) -> R:
+            metadata = finished.metadata
+            if not isinstance(metadata, _STATION_RUN_METADATA):
+                raise TypeError(f"{finished.name} is not a station run: {metadata.type}")
+            self.refresh()
+            return outcome(self.document, list(metadata.station_ids), list(metadata.skipped))
+
+        return self._client.operations.handle(operation, resolve=resolve)
+
+
+class Planning:
+    """``client.planning``: process plans for an assembly."""
+
+    def __init__(self, client: AutoAssembler):
+        self._client = client
+
+    def create_mpp(
+        self, assembly: Assembly, *, name: str, description: str | None = None
+    ) -> ProcessPlan:
+        """Create an empty process plan for a ``ready`` assembly.
+
+        The new plan knows the assembly's parts and has no stations; ``add_station``
+        is the next step.
+        """
+        from ..types.create_mpp_request import CreateMppRequest
+
+        # Unset, not None: the request model serializes None as null, which the server refuses.
+        request = (
+            CreateMppRequest(name=name)
+            if description is None
+            else CreateMppRequest(name=name, description=description)
+        )
+        doc = self._client.api.planning.create_mpp(
+            assembly.namespace, assembly.id, request=request
+        )
+        return ProcessPlan(
+            self._client, assembly, id=doc.id, document=doc, name=doc.name, version=doc.version
+        )
+
+    def adapt(
+        self,
+        reference: ProcessPlan,
+        target: Assembly,
+        *,
+        diff: DiffReport,
+        name: str | None = None,
+    ) -> Operation[ProcessPlan]:
+        """A process plan for ``target``, adapted from ``reference``, a plan of an earlier revision.
+
+        ``diff`` compares ``reference``'s assembly with ``target``:
+        ``client.assemblies.diff(reference.assembly, target).result()``. Returns the
+        adaptation's operation; ``result()`` returns the new `ProcessPlan` once saved.
+        """
+        kwargs: dict[str, typing.Any] = {}
+        if name is not None:
+            kwargs["name"] = name
+        adapting = self._client.api.planning.adapt(
+            target.namespace, target.id, reference_mpp_id=reference.id, diff=diff, **kwargs
+        )
+
+        def resolve(finished: OperationResource) -> ProcessPlan:
+            if not isinstance(finished.response, OperationResponse_MppAdapt):
+                raise TypeError(f"{finished.name} is not an adaptation: {finished.metadata.type}")
+            return ProcessPlan(self._client, target, id=finished.response.mpp_id).refresh()
+
+        return self._client.operations.handle(adapting.operation, resolve=resolve)
+
+    def get_mpp(self, assembly: Assembly, mpp_id: str) -> ProcessPlan:
+        """A handle on an existing process plan (one request)."""
+        return ProcessPlan(self._client, assembly, id=mpp_id).refresh()
+
+    def list_mpps(self, assembly: Assembly) -> list[ProcessPlan]:
+        """Handles on every process plan of the assembly (documents fetched on first use)."""
+        summaries = self._client.api.planning.list_mpps(assembly.namespace, assembly.id)
+        return [
+            ProcessPlan(self._client, assembly, id=s.id, name=s.name, version=s.version)
+            for s in summaries
+        ]
+
+
+# ---------------------------------------------------------------------------
+# Document readers (the derivations, in one place)
+# ---------------------------------------------------------------------------
+
+
+def _stations(doc: ManufacturingProcessPlan) -> dict[str, dict[str, typing.Any]]:
+    return doc.station_graph.get("stations") or {}
+
+
+def _soas(doc: ManufacturingProcessPlan) -> dict[str, dict[str, typing.Any]]:
+    return doc.station_graph.get("statesOfAssembly") or {}
+
+
+def _edges(doc: ManufacturingProcessPlan) -> dict[str, dict[str, typing.Any]]:
+    return doc.station_graph.get("edges") or {}
+
+
+def _part(soa: dict[str, typing.Any]) -> Part:
+    return Part(
+        id=str(soa["id"]), occurrences=tuple(soa.get("subassembly") or ()), name=soa.get("name")
+    )
+
+
+def _plan_section(doc: ManufacturingProcessPlan, key: str) -> dict[str, typing.Any]:
+    return (doc.plan or {}).get(key) or {}
+
+
+def _plan_status(doc: ManufacturingProcessPlan, station_id: str) -> StationPlanStatus:
+    record = _plan_section(doc, "status").get(station_id)
+    if not record:
+        return StationPlanStatus(station_id, "pending")
+    return StationPlanStatus(
+        station_id,
+        record.get("status", "pending"),
+        messages=tuple(record.get("messages") or ()),
+        findings=tuple(record.get("findings") or ()),
+        assumptions=tuple(record.get("assumptions") or ()),
+    )
+
+
+def _feasibility(doc: ManufacturingProcessPlan, station_id: str) -> StationFeasibility | None:
+    record = _plan_section(doc, "feasibility").get(station_id)
+    if not record:
+        return None
+    return StationFeasibility(
+        station_id,
+        record["status"],
+        messages=tuple(record.get("messages") or ()),
+        issues=tuple(record.get("issues") or ()),
+    )
+
+
+def _dfa(doc: ManufacturingProcessPlan, station_id: str) -> dict[str, typing.Any] | None:
+    return _plan_section(doc, "dfa").get(station_id)
+