cortex-solver 3.0.0__py3-none-any.whl

cortex/core/solver.py

@@ -0,0 +1,304 @@
+"""Constraint solver for part recipes."""
+
+from __future__ import annotations
+
+from collections import deque
+from dataclasses import dataclass
+from typing import Iterable
+
+from cortex.types import (
+    Constraint,
+    Dimensions,
+    Mirror,
+    PartRecipe,
+    PartSpec,
+    SolveResult,
+)
+
+AXIS_INDEX = {"X": 0, "Y": 1, "Z": 2}
+DIMENSION_INDEX = {0: "width", 1: "depth", 2: "height"}
+TOLERANCE = 0.0001
+
+
+@dataclass(slots=True)
+class _AxisAssignment:
+    axis: int
+    value: float
+    constraint: Constraint
+
+
+@dataclass(slots=True)
+class _AxisSetResult:
+    position: list[float]
+    conflicts: list[dict[str, object]]
+
+
+def solve(recipe: PartRecipe) -> SolveResult:
+    """Solve all part positions for a recipe."""
+
+    if recipe.anchor not in recipe.parts:
+        return SolveResult(
+            success=False,
+            error="Anchor part is missing from recipe parts.",
+        )
+
+    part_names = set(recipe.parts.keys())
+    constraints = list(recipe.constraints or [])
+    dependencies: dict[str, set[str]] = {name: set() for name in part_names}
+    dependents: dict[str, set[str]] = {name: set() for name in part_names}
+
+    for constraint in constraints:
+        if constraint.part_a in part_names and constraint.part_b in part_names:
+            dependencies[constraint.part_a].add(constraint.part_b)
+            dependents[constraint.part_b].add(constraint.part_a)
+
+    in_degree = {name: len(dependencies[name]) for name in part_names}
+    zero_degree = sorted(
+        name for name, degree in in_degree.items() if degree == 0 and name != recipe.anchor
+    )
+    queue = deque(
+        [recipe.anchor, *zero_degree] if in_degree.get(recipe.anchor, 0) == 0 else []
+    )
+    build_order: list[str] = []
+
+    while queue:
+        current = queue.popleft()
+        build_order.append(current)
+        for dependent in sorted(dependents.get(current, [])):
+            in_degree[dependent] -= 1
+            if in_degree[dependent] == 0:
+                queue.append(dependent)
+
+    if len(build_order) < len(part_names):
+        return SolveResult(
+            success=False,
+            error="Circular dependency detected in recipe constraints.",
+            build_order=build_order,
+        )
+
+    positions: dict[str, dict[str, list[float]]] = {}
+    conflicts: list[dict[str, object]] = []
+
+    anchor_position = list(recipe.anchor_position)
+    anchor_spec = recipe.parts[recipe.anchor]
+    positions[recipe.anchor] = _make_position(anchor_position, anchor_spec)
+
+    if len(part_names) == 1:
+        return SolveResult(
+            success=True,
+            positions=positions,
+            build_order=build_order,
+            conflicts=conflicts,
+        )
+
+    constraints_by_target: dict[str, list[Constraint]] = {
+        name: [] for name in part_names
+    }
+    for constraint in constraints:
+        if constraint.part_a in part_names:
+            constraints_by_target[constraint.part_a].append(constraint)
+
+    for part_name in build_order:
+        if part_name == recipe.anchor:
+            continue
+        part_spec = recipe.parts[part_name]
+        axis_set = _solve_part_axes(
+            part_name,
+            part_spec,
+            constraints_by_target.get(part_name, []),
+            recipe.parts,
+            positions,
+            anchor_position,
+        )
+        positions[part_name] = _make_position(axis_set.position, part_spec)
+        conflicts.extend(axis_set.conflicts)
+
+    for mirror in recipe.mirrors:
+        if mirror.source not in positions:
+            continue
+        mirrored = _apply_mirror(
+            mirror, positions[mirror.source]["location"], anchor_position
+        )
+        positions[mirror.target] = {
+            "location": list(mirrored),
+            "dimensions": list(positions[mirror.source]["dimensions"]),
+        }
+
+    return SolveResult(
+        success=True,
+        positions=positions,
+        build_order=build_order,
+        conflicts=conflicts,
+    )
+
+
+def _solve_part_axes(
+    part_name: str,
+    part_spec: PartSpec,
+    constraints: Iterable[Constraint],
+    parts: dict[str, PartSpec],
+    positions: dict[str, dict[str, list[float]]],
+    anchor_position: list[float],
+) -> _AxisSetResult:
+    axis_values = list(anchor_position)
+    axis_locked = [False, False, False]
+    conflicts: list[dict[str, object]] = []
+
+    for constraint in constraints:
+        if constraint.part_b not in positions:
+            continue
+        target_assignments = _resolve_constraint(
+            constraint,
+            part_spec,
+            parts[constraint.part_b],
+            positions[constraint.part_b]["location"],
+            anchor_position,
+        )
+        for assignment in target_assignments:
+            conflicts = _apply_axis_assignment(
+                part_name,
+                axis_values,
+                axis_locked,
+                assignment,
+                conflicts,
+            )
+
+    return _AxisSetResult(position=axis_values, conflicts=conflicts)
+
+
+def _resolve_constraint(
+    constraint: Constraint,
+    part_a: PartSpec,
+    part_b: PartSpec,
+    b_position: list[float],
+    anchor_position: list[float],
+) -> list[_AxisAssignment]:
+    constraint_type = constraint.type
+    axis_index = AXIS_INDEX.get(constraint.axis)
+    if axis_index is None:
+        return []
+
+    a_dim = _dimension_for_axis(part_a.dimensions, axis_index)
+    b_dim = _dimension_for_axis(part_b.dimensions, axis_index)
+    a_half = a_dim / 2.0
+    b_half = b_dim / 2.0
+
+    if constraint_type == "STACKED":
+        if constraint.reference == "top":
+            value = b_position[axis_index] + b_half + a_half
+        else:
+            value = b_position[axis_index] - b_half - a_half
+        return [_AxisAssignment(axis=axis_index, value=value, constraint=constraint)]
+
+    if constraint_type == "CENTERED":
+        return [
+            _AxisAssignment(
+                axis=axis_index, value=b_position[axis_index], constraint=constraint
+            )
+        ]
+
+    if constraint_type == "FLUSH":
+        b_face = _face_position(b_position[axis_index], b_half, constraint.face_b)
+        a_center = _face_center(b_face, a_half, constraint.face_a)
+        return [_AxisAssignment(axis=axis_index, value=a_center, constraint=constraint)]
+
+    if constraint_type == "OFFSET":
+        b_face = _face_position(b_position[axis_index], b_half, constraint.face_b)
+        a_center = _face_center(b_face, a_half, constraint.face_a) + constraint.offset
+        return [_AxisAssignment(axis=axis_index, value=a_center, constraint=constraint)]
+
+    if constraint_type == "COAXIAL":
+        assignments = []
+        for other_axis in range(3):
+            if other_axis == axis_index:
+                continue
+            assignments.append(
+                _AxisAssignment(
+                    axis=other_axis,
+                    value=b_position[other_axis],
+                    constraint=constraint,
+                )
+            )
+        return assignments
+
+    if constraint_type == "INSIDE":
+        return [
+            _AxisAssignment(
+                axis=axis_index, value=b_position[axis_index], constraint=constraint
+            )
+        ]
+
+    if constraint_type == "ALIGNED":
+        return [
+            _AxisAssignment(
+                axis=axis_index, value=b_position[axis_index], constraint=constraint
+            )
+        ]
+
+    if constraint_type == "SYMMETRIC":
+        mirrored = [b_position[0], b_position[1], b_position[2]]
+        mirrored[axis_index] = 2 * anchor_position[axis_index] - b_position[axis_index]
+        return [
+            _AxisAssignment(axis=0, value=mirrored[0], constraint=constraint),
+            _AxisAssignment(axis=1, value=mirrored[1], constraint=constraint),
+            _AxisAssignment(axis=2, value=mirrored[2], constraint=constraint),
+        ]
+
+    return []
+
+
+def _apply_axis_assignment(
+    part_name: str,
+    axis_values: list[float],
+    axis_locked: list[bool],
+    assignment: _AxisAssignment,
+    conflicts: list[dict[str, object]],
+) -> list[dict[str, object]]:
+    axis = assignment.axis
+    if axis_locked[axis]:
+        if abs(axis_values[axis] - assignment.value) > TOLERANCE:
+            conflicts.append(
+                {
+                    "part": part_name,
+                    "axis": axis,
+                    "value": axis_values[axis],
+                    "conflict": assignment.value,
+                    "constraint": assignment.constraint,
+                }
+            )
+        return conflicts
+
+    axis_values[axis] = assignment.value
+    axis_locked[axis] = True
+    return conflicts
+
+
+def _dimension_for_axis(dimensions: Dimensions, axis_index: int) -> float:
+    return getattr(dimensions, DIMENSION_INDEX[axis_index])
+
+
+def _face_position(center_value: float, half: float, face: str) -> float:
+    if face == "+":
+        return center_value + half
+    return center_value - half
+
+
+def _face_center(face_value: float, half: float, face: str) -> float:
+    if face == "+":
+        return face_value - half
+    return face_value + half
+
+
+def _apply_mirror(
+    mirror: Mirror, source_position: list[float], anchor_position: list[float]
+) -> list[float]:
+    axis_index = AXIS_INDEX.get(mirror.axis)
+    if axis_index is None:
+        return list(source_position)
+    mirrored = list(source_position)
+    mirrored[axis_index] = 2 * anchor_position[axis_index] - source_position[axis_index]
+    return mirrored
+
+
+def _make_position(position: list[float], spec: PartSpec) -> dict[str, list[float]]:
+    return {"location": list(position), "dimensions": spec.dimensions.as_list()}

cortex/core/validator.py

@@ -0,0 +1,360 @@
+"""Recipe validator for part constraints before solving."""
+
+from __future__ import annotations
+
+from cortex.types import (
+    ConstraintType,
+    PartRecipe,
+    ValidationError,
+    ValidationResult,
+    ValidationWarning,
+)
+
+_ALLOWED_AXES = {"X", "Y", "Z"}
+_ALLOWED_CONSTRAINTS = {
+    ConstraintType.STACKED.value,
+    ConstraintType.CENTERED.value,
+    ConstraintType.FLUSH.value,
+    ConstraintType.OFFSET.value,
+    ConstraintType.COAXIAL.value,
+    ConstraintType.INSIDE.value,
+    ConstraintType.ALIGNED.value,
+    ConstraintType.SYMMETRIC.value,
+}
+_STACKED_REFERENCES = {"top", "bottom"}
+_FACE_VALUES = {"+", "-"}
+
+
+def validate(recipe: PartRecipe) -> ValidationResult:
+    errors: list[ValidationError] = []
+    warnings: list[ValidationWarning] = []
+    _check_schema_completeness(recipe, errors)
+    _check_part_existence(recipe, errors)
+    _check_anchor_exists(recipe, errors)
+    _check_constraint_validity(recipe, errors)
+    _check_no_orphans(recipe, errors)
+    _check_circular_dependencies(recipe, errors)
+    _check_dimensions(recipe, errors)
+    _check_mirror_validity(recipe, errors)
+    _check_constraint_conflicts(recipe, warnings)
+    _check_type_validation(recipe, errors)
+    return ValidationResult(valid=not errors, errors=errors, warnings=warnings)
+
+
+def _check_schema_completeness(
+    recipe: PartRecipe, errors: list[ValidationError]
+) -> None:
+    if not getattr(recipe, "name", ""):
+        errors.append(
+            ValidationError("missing_field", "Recipe name is required.", "name")
+        )
+    if not getattr(recipe, "anchor", ""):
+        errors.append(
+            ValidationError("missing_field", "Recipe anchor is required.", "anchor")
+        )
+    anchor_position = getattr(recipe, "anchor_position", None)
+    if not isinstance(anchor_position, list) or len(anchor_position) != 3:
+        errors.append(
+            ValidationError(
+                "missing_field",
+                "Anchor position must be a list of three values.",
+                "anchor_position",
+            )
+        )
+    parts = getattr(recipe, "parts", None)
+    if not isinstance(parts, dict) or not parts:
+        errors.append(
+            ValidationError(
+                "missing_field",
+                "Recipe parts must be a non-empty dictionary.",
+                "parts",
+            )
+        )
+    constraints = getattr(recipe, "constraints", None)
+    if not isinstance(constraints, list):
+        errors.append(
+            ValidationError(
+                "missing_field", "Recipe constraints must be a list.", "constraints"
+            )
+        )
+
+
+def _check_part_existence(recipe: PartRecipe, errors: list[ValidationError]) -> None:
+    parts = recipe.parts if isinstance(recipe.parts, dict) else {}
+    constraints = recipe.constraints if isinstance(recipe.constraints, list) else []
+    for index, constraint in enumerate(constraints):
+        if constraint.part_a not in parts:
+            errors.append(
+                ValidationError(
+                    "missing_part",
+                    f"Constraint part_a '{constraint.part_a}' is missing.",
+                    f"constraints[{index}].part_a",
+                )
+            )
+        if constraint.part_b not in parts:
+            errors.append(
+                ValidationError(
+                    "missing_part",
+                    f"Constraint part_b '{constraint.part_b}' is missing.",
+                    f"constraints[{index}].part_b",
+                )
+            )
+
+
+def _check_anchor_exists(recipe: PartRecipe, errors: list[ValidationError]) -> None:
+    parts = recipe.parts if isinstance(recipe.parts, dict) else {}
+    if recipe.anchor and recipe.anchor not in parts:
+        errors.append(
+            ValidationError(
+                "missing_part",
+                f"Anchor part '{recipe.anchor}' is missing from parts.",
+                "anchor",
+            )
+        )
+
+
+def _check_constraint_validity(
+    recipe: PartRecipe, errors: list[ValidationError]
+) -> None:
+    constraints = recipe.constraints if isinstance(recipe.constraints, list) else []
+    for index, constraint in enumerate(constraints):
+        if constraint.type not in _ALLOWED_CONSTRAINTS:
+            errors.append(
+                ValidationError(
+                    "invalid_constraint",
+                    f"Constraint type '{constraint.type}' is not supported.",
+                    f"constraints[{index}].type",
+                )
+            )
+        if constraint.axis not in _ALLOWED_AXES:
+            errors.append(
+                ValidationError(
+                    "invalid_constraint",
+                    f"Constraint axis '{constraint.axis}' is invalid.",
+                    f"constraints[{index}].axis",
+                )
+            )
+        if constraint.type == ConstraintType.STACKED.value:
+            reference = constraint.reference.lower()
+            if reference not in _STACKED_REFERENCES:
+                errors.append(
+                    ValidationError(
+                        "invalid_constraint",
+                        "STACKED constraints require reference 'top' or 'bottom'.",
+                        f"constraints[{index}].reference",
+                    )
+                )
+        if constraint.type in {ConstraintType.FLUSH.value, ConstraintType.OFFSET.value}:
+            if (
+                constraint.face_a not in _FACE_VALUES
+                or constraint.face_b not in _FACE_VALUES
+            ):
+                errors.append(
+                    ValidationError(
+                        "invalid_constraint",
+                        "FLUSH/OFFSET constraints require face_a and face_b of '+' or '-'.",
+                        f"constraints[{index}]",
+                    )
+                )
+
+
+def _check_no_orphans(recipe: PartRecipe, errors: list[ValidationError]) -> None:
+    parts = recipe.parts if isinstance(recipe.parts, dict) else {}
+    if not parts:
+        return
+    anchor = recipe.anchor
+    constraints = recipe.constraints if isinstance(recipe.constraints, list) else []
+    mirrors = recipe.mirrors if isinstance(recipe.mirrors, list) else []
+    referenced_parts: set[str] = set()
+    for constraint in constraints:
+        referenced_parts.add(constraint.part_a)
+        referenced_parts.add(constraint.part_b)
+    for mirror in mirrors:
+        referenced_parts.add(mirror.source)
+        referenced_parts.add(mirror.target)
+    for part_name in parts:
+        if part_name == anchor:
+            continue
+        if part_name not in referenced_parts:
+            errors.append(
+                ValidationError(
+                    "orphan_part",
+                    f"Part '{part_name}' is not referenced by constraints or mirrors.",
+                    f"parts.{part_name}",
+                )
+            )
+
+
+def _check_circular_dependencies(
+    recipe: PartRecipe, errors: list[ValidationError]
+) -> None:
+    parts = recipe.parts if isinstance(recipe.parts, dict) else {}
+    constraints = recipe.constraints if isinstance(recipe.constraints, list) else []
+    if not parts:
+        return
+    adjacency: dict[str, set[str]] = {name: set() for name in parts}
+    for constraint in constraints:
+        if constraint.part_a in parts and constraint.part_b in parts:
+            adjacency[constraint.part_a].add(constraint.part_b)
+    visited: set[str] = set()
+    visiting: set[str] = set()
+    path: list[str] = []
+    reported: set[tuple[str, ...]] = set()
+
+    def dfs(node: str) -> None:
+        visiting.add(node)
+        path.append(node)
+        for neighbor in adjacency.get(node, ()):  # pragma: no branch
+            if neighbor in visiting:
+                cycle = _extract_cycle(path, neighbor)
+                cycle_key = tuple(cycle)
+                if cycle_key not in reported:
+                    reported.add(cycle_key)
+                    errors.append(
+                        ValidationError(
+                            "circular_dependency",
+                            f"Circular dependency detected: {' -> '.join(cycle)}.",
+                            "constraints",
+                        )
+                    )
+                continue
+            if neighbor in visited:
+                continue
+            dfs(neighbor)
+        visiting.remove(node)
+        visited.add(node)
+        path.pop()
+
+    for part in parts:
+        if part not in visited:
+            dfs(part)
+
+
+def _check_dimensions(recipe: PartRecipe, errors: list[ValidationError]) -> None:
+    parts = recipe.parts if isinstance(recipe.parts, dict) else {}
+    for part_name, part in parts.items():
+        dims = getattr(part, "dimensions", None)
+        if dims is None:
+            errors.append(
+                ValidationError(
+                    "missing_field",
+                    f"Part '{part_name}' is missing dimensions.",
+                    f"parts.{part_name}.dimensions",
+                )
+            )
+            continue
+        if not _dimensions_positive(dims):
+            errors.append(
+                ValidationError(
+                    "missing_field",
+                    f"Part '{part_name}' dimensions must be positive.",
+                    f"parts.{part_name}.dimensions",
+                )
+            )
+
+
+def _check_mirror_validity(recipe: PartRecipe, errors: list[ValidationError]) -> None:
+    parts = recipe.parts if isinstance(recipe.parts, dict) else {}
+    mirrors = recipe.mirrors if isinstance(recipe.mirrors, list) else []
+    for index, mirror in enumerate(mirrors):
+        if mirror.source not in parts:
+            errors.append(
+                ValidationError(
+                    "missing_part",
+                    f"Mirror source '{mirror.source}' is missing.",
+                    f"mirrors[{index}].source",
+                )
+            )
+        # Mirror targets need not exist in parts — the solver auto-generates
+        # them from the source part.
+        if mirror.axis not in _ALLOWED_AXES:
+            errors.append(
+                ValidationError(
+                    "invalid_constraint",
+                    f"Mirror axis '{mirror.axis}' is invalid.",
+                    f"mirrors[{index}].axis",
+                )
+            )
+        if mirror.source == mirror.target and mirror.source:
+            errors.append(
+                ValidationError(
+                    "invalid_constraint",
+                    "Mirror source and target must be different.",
+                    f"mirrors[{index}]",
+                )
+            )
+
+
+def _check_constraint_conflicts(
+    recipe: PartRecipe, warnings: list[ValidationWarning]
+) -> None:
+    constraints = recipe.constraints if isinstance(recipe.constraints, list) else []
+    axis_map: dict[tuple[str, str], int] = {}
+    for constraint in constraints:
+        for part in (constraint.part_a, constraint.part_b):
+            key = (part, constraint.axis)
+            axis_map[key] = axis_map.get(key, 0) + 1
+    for (part, axis), count in axis_map.items():
+        if count > 1:
+            warnings.append(
+                ValidationWarning(
+                    "constraint_conflict",
+                    f"Part '{part}' has multiple constraints on axis '{axis}'.",
+                )
+            )
+
+
+def _check_type_validation(recipe: PartRecipe, errors: list[ValidationError]) -> None:
+    anchor_position = recipe.anchor_position
+    if (
+        not isinstance(anchor_position, list)
+        or len(anchor_position) != 3
+        or not all(_is_number(value) for value in anchor_position)
+    ):
+        errors.append(
+            ValidationError(
+                "type_error",
+                "Anchor position must be a list of three numbers.",
+                "anchor_position",
+            )
+        )
+    constraints = recipe.constraints if isinstance(recipe.constraints, list) else []
+    for index, constraint in enumerate(constraints):
+        if not _is_number(constraint.offset):
+            errors.append(
+                ValidationError(
+                    "type_error",
+                    "Constraint offset must be numeric.",
+                    f"constraints[{index}].offset",
+                )
+            )
+
+
+def _is_number(value: object) -> bool:
+    return isinstance(value, (int, float)) and not isinstance(value, bool)
+
+
+def _dimensions_positive(dimensions: object) -> bool:
+    try:
+        return (
+            _is_number(dimensions.width)
+            and _is_number(dimensions.depth)
+            and _is_number(dimensions.height)
+            and dimensions.width > 0
+            and dimensions.depth > 0
+            and dimensions.height > 0
+        )
+    except AttributeError:
+        return False
+
+
+def _extract_cycle(path: list[str], start: str) -> list[str]:
+    cycle: list[str] = []
+    in_cycle = False
+    for node in path:
+        if node == start:
+            in_cycle = True
+        if in_cycle:
+            cycle.append(node)
+    cycle.append(start)
+    return cycle