refactor: remove legacy engine, planner, sim, trainer, viz, and server code

engine/fold_engine.py

@@ -1,249 +0,0 @@
-"""
-Fold execution engine.
-
-Applies fold operations (valley / mountain) to a Paper object using
-Rodrigues' rotation formula, face splitting, and layer tracking.
-"""
-
-from __future__ import annotations
-
-import math
-from typing import Callable
-
-import numpy as np
-
-from .paper import Paper
-
-
-# ────────────────────────────────────────────────────────────────────
-# Rodrigues' rotation
-# ────────────────────────────────────────────────────────────────────
-
-def _rodrigues_rotate(
-    points: np.ndarray,
-    axis_point: np.ndarray,
-    axis_dir: np.ndarray,
-    angle_rad: float,
-) -> np.ndarray:
-    """Rotate *points* (N, 3) around an axis defined by a point and direction
-    using Rodrigues' rotation formula.  Returns rotated points (N, 3)."""
-    k = axis_dir / (np.linalg.norm(axis_dir) + 1e-30)
-    translated = points - axis_point
-    cos_a = math.cos(angle_rad)
-    sin_a = math.sin(angle_rad)
-    dot_term = np.dot(translated, k).reshape(-1, 1) * k  # (N,1)*(3,) broadcast
-    rotated = (
-        translated * cos_a
-        + np.cross(k, translated) * sin_a
-        + dot_term * (1.0 - cos_a)
-    )
-    return rotated + axis_point
-
-
-# ────────────────────────────────────────────────────────────────────
-# Single fold
-# ────────────────────────────────────────────────────────────────────
-
-def apply_fold(
-    paper: Paper,
-    fold_dict: dict,
-) -> tuple[Paper, str | None]:
-    """Apply a single fold to *paper* and return ``(new_paper, error_or_None)``.
-
-    *fold_dict* has the form::
-
-        {
-            "type": "valley" | "mountain",
-            "line": {"start": [x, y], "end": [x, y]},
-            "angle": 0-180,
-        }
-
-    Steps:
-      1. Validate inputs.
-      2. Split faces along the fold line.
-      3. Determine vertices to rotate (one side of fold line).
-      4. Rodrigues' rotation of those vertices.
-      5. Update edge assignments for new fold-line edges.
-      6. Update fold angles.
-      7. Update layer tracking.
-    """
-
-    # ── 0. parse & validate ─────────────────────────────────────────
-    fold_type = fold_dict.get("type", "valley")
-    line = fold_dict.get("line", {})
-    angle_deg = fold_dict.get("angle", 180)
-
-    if fold_type not in ("valley", "mountain"):
-        return paper, f"Unknown fold type: {fold_type}"
-
-    try:
-        start_2d = np.array(line["start"], dtype=np.float64)[:2]
-        end_2d = np.array(line["end"], dtype=np.float64)[:2]
-    except (KeyError, TypeError, IndexError) as exc:
-        return paper, f"Invalid fold line: {exc}"
-
-    if np.linalg.norm(end_2d - start_2d) < 1e-12:
-        return paper, "Fold line has zero length"
-
-    if not (0 < angle_deg <= 180):
-        return paper, f"Angle must be in (0, 180], got {angle_deg}"
-
-    # ── 1. deep copy so the original is untouched ───────────────────
-    new_paper = paper.copy()
-
-    # ── 2. split faces along fold line ──────────────────────────────
-    try:
-        fold_edge_ids = new_paper.split_faces_along_line(start_2d, end_2d)
-    except Exception as exc:
-        return paper, f"Face split failed: {exc}"
-
-    # ── 3. determine vertices to rotate ─────────────────────────────
-    rotate_ids = new_paper.get_vertices_on_side(start_2d, end_2d, "positive")
-
-    if not rotate_ids:
-        # Try the other side — maybe the fold line is at the boundary
-        rotate_ids = new_paper.get_vertices_on_side(start_2d, end_2d, "negative")
-        if not rotate_ids:
-            return paper, "No vertices to rotate — fold line may not intersect paper"
-
-    # ── 4. Rodrigues' rotation ──────────────────────────────────────
-    sign = 1.0 if fold_type == "valley" else -1.0
-    angle_rad = sign * math.radians(angle_deg)
-
-    axis_point = np.array([start_2d[0], start_2d[1], 0.0])
-    axis_dir = np.array([end_2d[0] - start_2d[0], end_2d[1] - start_2d[1], 0.0])
-
-    pts = new_paper.vertices[rotate_ids]
-    rotated = _rodrigues_rotate(pts, axis_point, axis_dir, angle_rad)
-    new_paper.vertices[rotate_ids] = rotated
-
-    # ── 5. update edge assignments ──────────────────────────────────
-    assignment = "V" if fold_type == "valley" else "M"
-    for eidx in fold_edge_ids:
-        if eidx < len(new_paper.assignments):
-            new_paper.assignments[eidx] = assignment
-
-    # ── 6. update fold angles ───────────────────────────────────────
-    for eidx in fold_edge_ids:
-        if eidx < len(new_paper.fold_angles):
-            new_paper.fold_angles[eidx] = angle_deg * sign
-
-    # ── 7. update layer tracking ────────────────────────────────────
-    # For each pair of faces on opposite sides of the fold line, record
-    # layer ordering.  Simple heuristic: faces that were rotated are now
-    # on top (sign +1) of faces that stayed put.
-    rotated_set = set(rotate_ids)
-
-    def _face_side(face_verts: list[int]) -> str:
-        """Classify a face as 'rotated', 'fixed', or 'mixed'."""
-        r_count = sum(1 for v in face_verts if v in rotated_set)
-        if r_count == len(face_verts):
-            return "rotated"
-        if r_count == 0:
-            return "fixed"
-        return "mixed"
-
-    face_sides = [_face_side(f) for f in new_paper.faces]
-    for i in range(len(new_paper.faces)):
-        for j in range(i + 1, len(new_paper.faces)):
-            if face_sides[i] == "rotated" and face_sides[j] == "fixed":
-                new_paper.face_orders.append((i, j, 1))
-            elif face_sides[i] == "fixed" and face_sides[j] == "rotated":
-                new_paper.face_orders.append((j, i, 1))
-
-    new_paper.fold_count += 1
-
-    return new_paper, None
-
-
-# ────────────────────────────────────────────────────────────────────
-# Strategy executor (matches mock_env.execute_fold_strategy signature)
-# ────────────────────────────────────────────────────────────────────
-
-def execute_fold_strategy(
-    strategy_fn: Callable,
-    paper: Paper,
-    max_folds: int = 20,
-) -> tuple[Paper, list[dict], str | None]:
-    """Execute a ``fold_strategy`` function against the real physics engine.
-
-    Signature matches ``mock_env.execute_fold_strategy`` so the trainer
-    reward functions can swap engines transparently.
-
-    Parameters
-    ----------
-    strategy_fn : callable
-        ``strategy_fn(paper_state_dict) -> list[dict]``
-    paper : Paper
-        The initial paper state.
-    max_folds : int
-        Maximum number of folds to apply.
-
-    Returns
-    -------
-    (final_paper, applied_folds, error_or_None)
-    """
-    state_dict = paper.to_dict()
-    try:
-        folds = strategy_fn(state_dict)
-    except Exception as exc:
-        return paper, [], f"Strategy function raised: {exc}"
-
-    if not isinstance(folds, list):
-        return paper, [], "Strategy must return a list of fold dicts"
-
-    applied: list[dict] = []
-    current = paper
-
-    for i, fold in enumerate(folds):
-        if i >= max_folds:
-            break
-        if not isinstance(fold, dict):
-            return current, applied, f"Fold {i} is not a dict"
-
-        current, error = apply_fold(current, fold)
-        if error:
-            return current, applied, f"Fold {i} failed: {error}"
-        applied.append(fold)
-
-    return current, applied, None
-
-
-def apply_pleat(
-    paper: Paper,
-    line1: dict,
-    line2: dict,
-    angle: float = 180.0,
-) -> tuple[Paper, str | None]:
-    """Pleat fold: valley at line1, mountain at line2 (two parallel folds).
-
-    Both line dicts have the form: {"start": [x, y], "end": [x, y]}
-    Returns (new_paper, error_or_None).
-    """
-    paper, err = apply_fold(paper, {"type": "valley", "line": line1, "angle": angle})
-    if err:
-        return paper, f"Pleat valley fold failed: {err}"
-    paper, err = apply_fold(paper, {"type": "mountain", "line": line2, "angle": angle})
-    if err:
-        return paper, f"Pleat mountain fold failed: {err}"
-    return paper, None
-
-
-def apply_crimp(
-    paper: Paper,
-    line1: dict,
-    line2: dict,
-    angle: float = 180.0,
-) -> tuple[Paper, str | None]:
-    """Crimp fold: mountain at line1, valley at line2 (reverse of pleat).
-
-    Both line dicts have the form: {"start": [x, y], "end": [x, y]}
-    Returns (new_paper, error_or_None).
-    """
-    paper, err = apply_fold(paper, {"type": "mountain", "line": line1, "angle": angle})
-    if err:
-        return paper, f"Crimp mountain fold failed: {err}"
-    paper, err = apply_fold(paper, {"type": "valley", "line": line2, "angle": angle})
-    if err:
-        return paper, f"Crimp valley fold failed: {err}"
-    return paper, None

engine/materials.py

@@ -1,79 +0,0 @@
-"""
-Material definitions for origami simulation.
-
-Provides dataclass-based material properties and preset materials
-for paper, mylar, aluminum, and nitinol.
-"""
-
-from dataclasses import dataclass
-
-
-@dataclass
-class Material:
-    name: str
-    thickness_mm: float       # mm
-    youngs_modulus_gpa: float  # GPa
-    max_strain: float          # fraction (e.g. 0.03 = 3%)
-    poissons_ratio: float = 0.3  # dimensionless
-
-    @property
-    def thickness_m(self) -> float:
-        """Thickness in meters."""
-        return self.thickness_mm / 1000.0
-
-    @property
-    def youngs_modulus_pa(self) -> float:
-        """Young's modulus in Pascals."""
-        return self.youngs_modulus_gpa * 1e9
-
-
-# ── Preset materials ────────────────────────────────────────────────
-
-MATERIAL_PRESETS: dict[str, Material] = {
-    "paper": Material(
-        name="paper",
-        thickness_mm=0.1,
-        youngs_modulus_gpa=2.0,
-        max_strain=0.03,
-        poissons_ratio=0.3,
-    ),
-    "mylar": Material(
-        name="mylar",
-        thickness_mm=0.05,
-        youngs_modulus_gpa=4.0,
-        max_strain=0.03,
-        poissons_ratio=0.38,
-    ),
-    "aluminum": Material(
-        name="aluminum",
-        thickness_mm=0.1,
-        youngs_modulus_gpa=69.0,
-        max_strain=0.01,
-        poissons_ratio=0.33,
-    ),
-    "nitinol": Material(
-        name="nitinol",
-        thickness_mm=0.1,
-        youngs_modulus_gpa=75.0,
-        max_strain=0.08,
-        poissons_ratio=0.33,
-    ),
-}
-
-
-def get_material(name: str) -> Material:
-    """Return a copy of a preset material by name.
-
-    Raises KeyError if name is not in MATERIAL_PRESETS.
-    """
-    if name not in MATERIAL_PRESETS:
-        available = ", ".join(sorted(MATERIAL_PRESETS))
-        raise KeyError(f"Unknown material '{name}'. Available: {available}")
-    preset = MATERIAL_PRESETS[name]
-    return Material(
-        name=preset.name,
-        thickness_mm=preset.thickness_mm,
-        youngs_modulus_gpa=preset.youngs_modulus_gpa,
-        max_strain=preset.max_strain,
-        poissons_ratio=preset.poissons_ratio,
-    )

engine/metrics.py

@@ -1,231 +0,0 @@
-"""
-Quality metrics for folded origami.
-
-Computes bounding box, deployment ratio, fold count, and aggregated
-metric dictionaries for the trainer reward functions.
-"""
-
-from __future__ import annotations
-
-import numpy as np
-
-from .paper import Paper
-
-
-def compute_bounding_box(paper: Paper) -> np.ndarray:
-    """Axis-aligned bounding-box dimensions (dx, dy, dz).
-
-    Returns shape (3,) array.  Minimum z-thickness accounts for
-    material thickness times estimated layer count.
-    """
-    if len(paper.vertices) == 0:
-        return np.zeros(3)
-
-    ptp = np.ptp(paper.vertices, axis=0)
-    ptp = np.where(np.abs(ptp) < 1e-12, 0.0, ptp)
-
-    # Minimum z from material thickness * layers
-    t = paper.material.thickness_mm / 1000.0
-    ptp[2] = max(ptp[2], t * paper.num_layers)
-
-    return ptp
-
-
-def compute_deployment_ratio(paper: Paper) -> float:
-    """Ratio of folded XY footprint area to original sheet area.
-
-    A fully flat unfolded sheet has ratio 1.0; a tightly folded sheet
-    approaches 0.0.
-    """
-    if paper.original_area <= 0:
-        return 1.0
-
-    bb = compute_bounding_box(paper)
-    folded_area = bb[0] * bb[1]
-
-    ratio = folded_area / paper.original_area
-    return float(np.clip(ratio, 0.0, 1.0))
-
-
-def compute_fold_count(paper: Paper) -> int:
-    """Number of mountain (M) and valley (V) edges."""
-    return sum(1 for a in paper.assignments if a in ("M", "V"))
-
-
-def compute_compactness(paper: Paper) -> float:
-    """1 - deployment_ratio.  Higher is more compact."""
-    return 1.0 - compute_deployment_ratio(paper)
-
-
-def compute_volume(paper: Paper) -> float:
-    """Bounding-box volume in cubic meters."""
-    bb = compute_bounding_box(paper)
-    return float(bb[0] * bb[1] * bb[2])
-
-
-def compute_metrics(paper: Paper, original_paper: Paper | None = None) -> dict:
-    """Compute all quality metrics and return as a dict.
-
-    Parameters
-    ----------
-    paper : Paper
-        The current (folded) paper state.
-    original_paper : Paper or None
-        The original (unfolded) paper, used for strain comparison.
-        If None, strain is computed against the current paper's rest lengths.
-
-    Returns
-    -------
-    dict with keys:
-        bounding_box, deployment_ratio, fold_count, compactness,
-        volume, max_strain, mean_strain, num_vertices, num_faces,
-        num_layers.
-    """
-    from .physics import compute_strain  # local import to avoid circular
-
-    bb = compute_bounding_box(paper)
-    strain = compute_strain(paper)
-
-    return {
-        "bounding_box": {
-            "x": float(bb[0]),
-            "y": float(bb[1]),
-            "z": float(bb[2]),
-        },
-        "deployment_ratio": compute_deployment_ratio(paper),
-        "fold_count": compute_fold_count(paper),
-        "compactness": compute_compactness(paper),
-        "volume": compute_volume(paper),
-        "max_strain": float(np.max(strain)) if len(strain) > 0 else 0.0,
-        "mean_strain": float(np.mean(strain)) if len(strain) > 0 else 0.0,
-        "num_vertices": len(paper.vertices),
-        "num_faces": len(paper.faces),
-        "num_layers": paper.num_layers,
-    }
-
-
-def compute_all_metrics(paper, task: dict, validation: dict) -> dict:
-    """Compute every metric and return a flat dict.
-
-    Called after physics + validation. Combines validity, compactness,
-    structural, efficiency, and deployability metrics.
-
-    Parameters
-    ----------
-    paper : Paper
-        Current paper state (after simulate()).
-    task : dict
-        Task definition with keys: width, height, target_ratio, target_box, must_deploy.
-    validation : dict
-        Output of validate_state(paper).
-    """
-    import numpy as np
-
-    bb = paper.bounding_box  # (3,) array
-    original_area = paper.original_area if paper.original_area > 0 else (paper.material.thickness_mm / 1000.0)
-    t = paper.material.thickness_mm / 1000.0
-    original_bbox_vol = original_area * t
-    folded_bbox_vol = float(bb[0] * bb[1] * bb[2]) if bb[2] > 0 else float(bb[0] * bb[1] * t)
-
-    # ── Folded area (XY footprint) ────────────────────────────────
-    if len(paper.vertices) >= 3:
-        try:
-            from scipy.spatial import ConvexHull
-            hull = ConvexHull(paper.vertices[:, :2])
-            folded_area = float(hull.volume)
-        except Exception:
-            ptp = np.ptp(paper.vertices[:, :2], axis=0)
-            folded_area = float(ptp[0] * ptp[1])
-    else:
-        folded_area = original_area
-
-    deployment_ratio = folded_area / original_area if original_area > 0 else 1.0
-    compactness = 1.0 - deployment_ratio
-    volume_compaction = folded_bbox_vol / original_bbox_vol if original_bbox_vol > 0 else 1.0
-    material_volume = original_area * t
-    packing_efficiency = material_volume / folded_bbox_vol if folded_bbox_vol > 0 else 0.0
-
-    # ── Target box check ──────────────────────────��──────────────
-    target_box = task.get("target_box")
-    fits_target_box = False
-    if target_box and len(target_box) == 3:
-        fits_target_box = bool(
-            bb[0] <= target_box[0] + 1e-6 and
-            bb[1] <= target_box[1] + 1e-6 and
-            bb[2] <= target_box[2] + 1e-6
-        )
-
-    # ── Strain ───────────────────────────────────────────────────
-    strain = paper.strain_per_vertex
-    max_strain = float(np.max(strain)) if len(strain) > 0 else 0.0
-    mean_strain = float(np.mean(strain)) if len(strain) > 0 else 0.0
-
-    # ── Energy ───────────────────────────────────────────────────
-    energy = paper.energy
-
-    # ── Efficiency ───────────────────────────────────────────────
-    fold_count = paper.fold_count
-
-    # Crease complexity: entropy of M/V assignment distribution
-    mv_assignments = [a for a in paper.assignments if a in ("M", "V")]
-    if mv_assignments:
-        total = len(mv_assignments)
-        m_count = mv_assignments.count("M")
-        v_count = mv_assignments.count("V")
-        p_m = m_count / total if total > 0 else 0
-        p_v = v_count / total if total > 0 else 0
-        crease_complexity = 0.0
-        if p_m > 0:
-            crease_complexity -= p_m * np.log2(p_m)
-        if p_v > 0:
-            crease_complexity -= p_v * np.log2(p_v)
-    else:
-        crease_complexity = 0.0
-
-    folding_efficiency = compactness / max(fold_count, 1)
-
-    # ── Deployability ─────────────────────────────────────────────
-    must_deploy = task.get("must_deploy", False)
-    # Simple deployability heuristic: if valid and compactness > 0, assume deployable
-    is_deployable = bool(validation.get("is_valid", False) and compactness > 0.01) if must_deploy else None
-    # Deployment force estimate from total energy gradient (rough)
-    deployment_force_estimate = float(energy.get("fold", 0.0)) / max(paper.original_area, 1e-6)
-
-    return {
-        # Validity (from validation dict)
-        "is_valid": validation.get("is_valid", False),
-        "kawasaki_violations": validation.get("kawasaki_violations", 0),
-        "kawasaki_total_error": validation.get("kawasaki_total_error", 0.0),
-        "maekawa_violations": validation.get("maekawa_violations", 0),
-        "self_intersections": validation.get("self_intersections", 0),
-        "strain_exceeded": validation.get("strain_exceeded", False),
-
-        # Compactness
-        "deployment_ratio": float(deployment_ratio),
-        "compactness": float(compactness),
-        "volume_compaction": float(volume_compaction),
-        "packing_efficiency": float(packing_efficiency),
-        "fits_target_box": fits_target_box,
-        "bounding_box": bb.tolist(),
-
-        # Structural
-        "max_strain": max_strain,
-        "mean_strain": mean_strain,
-        "total_energy": float(energy.get("total", 0.0)),
-        "energy_bar": float(energy.get("bar", 0.0)),
-        "energy_facet": float(energy.get("facet", 0.0)),
-        "energy_fold": float(energy.get("fold", 0.0)),
-
-        # Efficiency
-        "fold_count": fold_count,
-        "folding_efficiency": float(folding_efficiency),
-        "crease_complexity": float(crease_complexity),
-
-        # Deployability
-        "is_deployable": is_deployable,
-        "deployment_force_estimate": float(deployment_force_estimate),
-
-        # Shape similarity placeholders
-        "chamfer_distance": None,
-        "hausdorff_distance": None,
-    }

engine/paper.py

@@ -1,525 +0,0 @@
-"""
-Paper — the core geometric data structure for origami simulation.
-
-Stores vertices, edges, faces, fold assignments, fold angles, layer ordering,
-and material.  Supports FOLD-format serialization and the face-splitting
-operation needed by the fold engine.
-"""
-
-from __future__ import annotations
-
-import copy
-import json
-from dataclasses import dataclass, field
-from typing import Any
-
-import numpy as np
-
-from .materials import Material, get_material
-
-
-# ────────────────────────────────────────────────────────────────────
-# Helper: 2-D line-segment intersection
-# ────────────────────────────────────────────────────────────────────
-
-def _seg_seg_intersect_2d(
-    p1: np.ndarray, p2: np.ndarray,
-    p3: np.ndarray, p4: np.ndarray,
-    eps: float = 1e-10,
-) -> np.ndarray | None:
-    """Return the intersection point of segments (p1-p2) and (p3-p4) in 2-D,
-    or None if they do not intersect.  Points that lie on the segment
-    endpoints are considered intersections (within tolerance *eps*).
-
-    All inputs are shape (2,).
-    """
-    d1 = p2 - p1
-    d2 = p4 - p3
-    denom = d1[0] * d2[1] - d1[1] * d2[0]
-
-    if abs(denom) < eps:
-        return None  # parallel / collinear
-
-    dp = p3 - p1
-    t = (dp[0] * d2[1] - dp[1] * d2[0]) / denom
-    u = (dp[0] * d1[1] - dp[1] * d1[0]) / denom
-
-    if -eps <= t <= 1.0 + eps and -eps <= u <= 1.0 + eps:
-        return p1 + np.clip(t, 0.0, 1.0) * d1
-    return None
-
-
-# ────────────────────────────────────────────────────────────────────
-# Paper dataclass
-# ────────────────────────────────────────────────────────────────────
-
-@dataclass
-class Paper:
-    """Origami sheet state.
-
-    Attributes
-    ----------
-    vertices : np.ndarray, shape (N, 3)
-        Vertex positions in 3-D.
-    edges : np.ndarray, shape (E, 2), dtype int
-        Each row is (v_start, v_end).
-    faces : list[list[int]]
-        Each face is an ordered list of vertex indices (CCW winding).
-    assignments : list[str]
-        Per-edge assignment: 'M' (mountain), 'V' (valley), 'B' (boundary),
-        'F' (flat / unfolded), 'U' (unassigned).
-    fold_angles : np.ndarray, shape (E,)
-        Current fold angle (degrees) per edge.
-    face_orders : list[tuple[int, int, int]]
-        Layer ordering triples (f_i, f_j, +1/-1) meaning f_i is above/below f_j.
-    material : Material
-        The sheet material.
-    rest_lengths : np.ndarray, shape (E,)
-        Original (unfolded) edge lengths — used for strain computation.
-    original_area : float
-        Area of the sheet before any folds.
-    """
-
-    vertices: np.ndarray
-    edges: np.ndarray
-    faces: list[list[int]]
-    assignments: list[str]
-    fold_angles: np.ndarray
-    face_orders: list[tuple[int, int, int]] = field(default_factory=list)
-    material: Material = field(default_factory=lambda: get_material("paper"))
-    rest_lengths: np.ndarray = field(default_factory=lambda: np.empty(0))
-    original_area: float = 0.0
-    rest_positions: np.ndarray = field(default_factory=lambda: np.empty((0, 3)))
-    strain_per_vertex: np.ndarray = field(default_factory=lambda: np.empty(0))
-    energy: dict = field(default_factory=lambda: {"total": 0.0, "bar": 0.0, "facet": 0.0, "fold": 0.0})
-    fold_count: int = 0
-
-    # ── constructors ────────────────────────────────────────────────
-
-    @staticmethod
-    def create_flat_sheet(
-        width: float = 1.0,
-        height: float = 1.0,
-        material: Material | None = None,
-    ) -> "Paper":
-        """Create a flat rectangular sheet with 4 vertices, 5 edges
-        (including one diagonal), and 2 triangular faces."""
-        mat = material if material is not None else get_material("paper")
-
-        verts = np.array([
-            [0.0, 0.0, 0.0],
-            [width, 0.0, 0.0],
-            [width, height, 0.0],
-            [0.0, height, 0.0],
-        ], dtype=np.float64)
-
-        edges = np.array([
-            [0, 1],  # bottom
-            [1, 2],  # right
-            [2, 3],  # top
-            [3, 0],  # left
-            [0, 2],  # diagonal
-        ], dtype=np.int64)
-
-        faces: list[list[int]] = [[0, 1, 2], [0, 2, 3]]
-        assignments = ["B", "B", "B", "B", "F"]
-        fold_angles = np.zeros(len(edges), dtype=np.float64)
-        rest_lengths = np.array(
-            [np.linalg.norm(verts[e[1]] - verts[e[0]]) for e in edges],
-            dtype=np.float64,
-        )
-
-        paper = Paper(
-            vertices=verts,
-            edges=edges,
-            faces=faces,
-            assignments=assignments,
-            fold_angles=fold_angles,
-            material=mat,
-            rest_lengths=rest_lengths,
-            original_area=width * height,
-        )
-        paper.rest_positions = verts.copy()
-        return paper
-
-    # ── dict / prompt serialization (matches mock_env.PaperState.to_dict) ──
-
-    def to_dict(self) -> dict:
-        """Return a simplified dict suitable for LLM prompts.
-
-        The format matches ``mock_env.PaperState.to_dict()`` so that the
-        trainer reward functions work with either engine.
-        """
-        bb = self.bounding_box
-        return {
-            "width": float(bb[0]),
-            "height": float(bb[1]),
-            "material": {
-                "name": self.material.name,
-                "thickness_mm": self.material.thickness_mm,
-                "youngs_modulus_gpa": self.material.youngs_modulus_gpa,
-            },
-            "vertices": self.vertices.tolist(),
-            "edges": self.edges.tolist(),
-            "assignments": list(self.assignments),
-            "fold_angles": self.fold_angles.tolist(),
-            "num_layers_at_center": self.num_layers,
-            "bounding_box": {
-                "x": float(bb[0]),
-                "y": float(bb[1]),
-                "z": float(bb[2]),
-            },
-        }
-
-    def to_observation_dict(self) -> dict:
-        bb = self.bounding_box
-        return {
-            "vertices_coords": self.vertices.tolist(),
-            "edges_vertices": self.edges.tolist(),
-            "faces_vertices": self.faces,
-            "edges_assignment": list(self.assignments),
-            "edges_foldAngle": self.fold_angles.tolist(),
-            "num_vertices": len(self.vertices),
-            "num_edges": len(self.edges),
-            "num_faces": len(self.faces),
-            "bounding_box": bb.tolist(),
-            "num_layers": self.num_layers,
-            "material": {
-                "name": self.material.name,
-                "thickness_mm": self.material.thickness_mm,
-                "youngs_modulus_gpa": self.material.youngs_modulus_gpa,
-                "max_strain": self.material.max_strain,
-                "poisson_ratio": self.material.poissons_ratio,
-            },
-            "strain_per_vertex": self.strain_per_vertex.tolist(),
-            "energy": dict(self.energy),
-            "fold_count": self.fold_count,
-            "width": float(self.original_area ** 0.5) if self.original_area > 0 else 1.0,
-            "height": float(self.original_area ** 0.5) if self.original_area > 0 else 1.0,
-        }
-
-    # ── FOLD format serialization ───────────────────────────────────
-
-    def to_fold_json(self) -> str:
-        """Serialize to FOLD JSON format (v1.1 subset)."""
-        fold = {
-            "file_spec": 1.1,
-            "file_creator": "optigami",
-            "file_classes": ["singleModel"],
-            "frame_classes": ["foldedForm"],
-            "vertices_coords": self.vertices.tolist(),
-            "edges_vertices": self.edges.tolist(),
-            "edges_assignment": self.assignments,
-            "edges_foldAngle": self.fold_angles.tolist(),
-            "faces_vertices": self.faces,
-            "faceOrders": [list(fo) for fo in self.face_orders],
-        }
-        return json.dumps(fold, indent=2)
-
-    @staticmethod
-    def from_fold_json(data: str | dict, material: Material | None = None) -> "Paper":
-        """Deserialize from FOLD JSON format."""
-        if isinstance(data, str):
-            data = json.loads(data)
-
-        verts = np.array(data["vertices_coords"], dtype=np.float64)
-        edges = np.array(data["edges_vertices"], dtype=np.int64)
-        faces = data.get("faces_vertices", [])
-        assignments = data.get("edges_assignment", ["U"] * len(edges))
-        fold_angles = np.array(
-            data.get("edges_foldAngle", [0.0] * len(edges)),
-            dtype=np.float64,
-        )
-        face_orders = [tuple(fo) for fo in data.get("faceOrders", [])]
-
-        rest_lengths = np.array(
-            [np.linalg.norm(verts[e[1]] - verts[e[0]]) for e in edges],
-            dtype=np.float64,
-        )
-
-        mat = material if material is not None else get_material("paper")
-
-        # Approximate original area from convex hull of initial XY footprint
-        try:
-            from scipy.spatial import ConvexHull
-            hull = ConvexHull(verts[:, :2])
-            area = hull.volume  # 2-D ConvexHull.volume is area
-        except Exception:
-            # Fallback: bounding-box area from XY coordinates
-            if len(verts) >= 2:
-                ptp = np.ptp(verts[:, :2], axis=0)
-                area = float(ptp[0] * ptp[1])
-            else:
-                area = 0.0
-
-        return Paper(
-            vertices=verts,
-            edges=edges,
-            faces=faces,
-            assignments=assignments,
-            fold_angles=fold_angles,
-            face_orders=face_orders,
-            material=mat,
-            rest_lengths=rest_lengths,
-            original_area=area,
-        )
-
-    # ── computed properties ─────────────────────────────────────────
-
-    @property
-    def bounding_box(self) -> np.ndarray:
-        """Axis-aligned bounding-box dimensions (dx, dy, dz)."""
-        if len(self.vertices) == 0:
-            return np.zeros(3)
-        ptp = np.ptp(self.vertices, axis=0)
-        ptp = np.where(np.abs(ptp) < 1e-12, 0.0, ptp)
-        # Ensure minimum z height from material thickness * layers
-        t = self.material.thickness_mm / 1000.0
-        ptp[2] = max(ptp[2], t * self.num_layers)
-        return ptp
-
-    @property
-    def num_layers(self) -> int:
-        """Estimate layer count from face-order triples.
-
-        Falls back to 1 + number of M/V edges as a simple heuristic when
-        face_orders is empty.
-        """
-        if self.face_orders:
-            face_ids = set()
-            for fo in self.face_orders:
-                face_ids.add(fo[0])
-                face_ids.add(fo[1])
-            return max(len(face_ids), 1)
-        # Heuristic: each fold adds one layer
-        mv_count = sum(1 for a in self.assignments if a in ("M", "V"))
-        return 1 + mv_count
-
-    # ── topology helpers ────────────────────────────────────────────
-
-    def _find_or_add_vertex(self, point_3d: np.ndarray, tol: float = 1e-8) -> int:
-        """Return index of an existing vertex close to *point_3d*, or add a
-        new vertex and return its index."""
-        for i, v in enumerate(self.vertices):
-            if np.linalg.norm(v - point_3d) < tol:
-                return i
-        idx = len(self.vertices)
-        self.vertices = np.vstack([self.vertices, point_3d.reshape(1, 3)])
-        return idx
-
-    def _find_or_add_edge(self, v1: int, v2: int) -> int:
-        """Return index of edge (v1,v2) or (v2,v1), or add a new edge and
-        return its index.  New edges get assignment 'F' and fold-angle 0."""
-        for i, e in enumerate(self.edges):
-            if (e[0] == v1 and e[1] == v2) or (e[0] == v2 and e[1] == v1):
-                return i
-        idx = len(self.edges)
-        self.edges = np.vstack([self.edges, np.array([[v1, v2]], dtype=np.int64)])
-        self.assignments.append("F")
-        self.fold_angles = np.append(self.fold_angles, 0.0)
-        # Rest length for the new edge
-        rl = np.linalg.norm(self.vertices[v1] - self.vertices[v2])
-        self.rest_lengths = np.append(self.rest_lengths, rl)
-        return idx
-
-    # ── face splitting ──────────────────────────────────────────────
-
-    def split_faces_along_line(
-        self,
-        start_2d: np.ndarray | list,
-        end_2d: np.ndarray | list,
-    ) -> list[int]:
-        """Split every face that the 2-D line (start_2d -> end_2d) crosses.
-
-        The line is infinite for intersection purposes (we test each face
-        edge-segment against the full fold-line extent clipped to the paper).
-
-        Returns a list of edge indices that lie *on* the fold line (i.e. the
-        newly created edges along the fold path).
-
-        This mutates ``self`` in-place (vertices, edges, faces, assignments,
-        fold_angles, rest_lengths are updated).
-        """
-        start_2d = np.asarray(start_2d, dtype=np.float64)
-        end_2d = np.asarray(end_2d, dtype=np.float64)
-
-        fold_edge_indices: list[int] = []
-        new_faces: list[list[int]] = []
-
-        faces_to_process = list(range(len(self.faces)))
-
-        for fi in faces_to_process:
-            face = self.faces[fi]
-            n = len(face)
-
-            # Gather intersection points along the face boundary
-            hits: list[tuple[int, np.ndarray]] = []  # (local_edge_index, point_2d)
-
-            for k in range(n):
-                v_a = face[k]
-                v_b = face[(k + 1) % n]
-                pa = self.vertices[v_a][:2]
-                pb = self.vertices[v_b][:2]
-
-                pt = _seg_seg_intersect_2d(start_2d, end_2d, pa, pb)
-                if pt is not None:
-                    hits.append((k, pt))
-
-            # Deduplicate hits that are at the same location (e.g. hitting a vertex)
-            if len(hits) >= 2:
-                unique_hits: list[tuple[int, np.ndarray]] = [hits[0]]
-                for h in hits[1:]:
-                    is_dup = False
-                    for uh in unique_hits:
-                        if np.linalg.norm(h[1] - uh[1]) < 1e-8:
-                            is_dup = True
-                            break
-                    if not is_dup:
-                        unique_hits.append(h)
-                hits = unique_hits
-
-            if len(hits) < 2:
-                # Line does not fully cross this face — keep face as-is
-                new_faces.append(face)
-                continue
-
-            # We only handle the first two intersection points (one chord across face)
-            hit_a_edge_idx, hit_a_pt = hits[0]
-            hit_b_edge_idx, hit_b_pt = hits[1]
-
-            # Create / find 3-D vertices at intersection points (z=0 for flat, interpolated otherwise)
-            def _interp_z(pt2d: np.ndarray, edge_local: int) -> np.ndarray:
-                """Interpolate z from the edge endpoints."""
-                v_a = face[edge_local]
-                v_b = face[(edge_local + 1) % n]
-                pa = self.vertices[v_a]
-                pb = self.vertices[v_b]
-                seg = pb[:2] - pa[:2]
-                seg_len = np.linalg.norm(seg)
-                if seg_len < 1e-12:
-                    return np.array([pt2d[0], pt2d[1], pa[2]])
-                t = np.linalg.norm(pt2d - pa[:2]) / seg_len
-                t = np.clip(t, 0.0, 1.0)
-                z = pa[2] + t * (pb[2] - pa[2])
-                return np.array([pt2d[0], pt2d[1], z])
-
-            pt_a_3d = _interp_z(hit_a_pt, hit_a_edge_idx)
-            pt_b_3d = _interp_z(hit_b_pt, hit_b_edge_idx)
-
-            idx_a = self._find_or_add_vertex(pt_a_3d)
-            idx_b = self._find_or_add_vertex(pt_b_3d)
-
-            if idx_a == idx_b:
-                new_faces.append(face)
-                continue
-
-            # Add the fold-line edge between the two intersection points
-            fold_eidx = self._find_or_add_edge(idx_a, idx_b)
-            fold_edge_indices.append(fold_eidx)
-
-            # ── Split the face into two sub-faces ──
-            # Walk around the face vertices, inserting idx_a and idx_b at the
-            # appropriate positions, then split into two loops.
-            ordered_verts = list(face)
-
-            # Insert intersection vertices into the vertex ring if not already present
-            def _insert_after(ring: list[int], after_local: int, vid: int) -> list[int]:
-                """Insert *vid* after position *after_local* if it is not already
-                adjacent in the ring at that position."""
-                pos = after_local + 1
-                if ring[after_local % len(ring)] == vid:
-                    return ring
-                if ring[pos % len(ring)] == vid:
-                    return ring
-                return ring[:pos] + [vid] + ring[pos:]
-
-            # Determine insertion order — always insert the one with the
-            # larger local-edge index first so that the earlier index stays valid.
-            if hit_a_edge_idx <= hit_b_edge_idx:
-                ordered_verts = _insert_after(ordered_verts, hit_b_edge_idx, idx_b)
-                # Recompute hit_a_edge_idx offset if idx_b was inserted before it
-                # (it shouldn't be, since hit_b >= hit_a, but guard anyway)
-                a_pos = hit_a_edge_idx
-                ordered_verts = _insert_after(ordered_verts, a_pos, idx_a)
-            else:
-                ordered_verts = _insert_after(ordered_verts, hit_a_edge_idx, idx_a)
-                ordered_verts = _insert_after(ordered_verts, hit_b_edge_idx, idx_b)
-
-            # Now split the ring at idx_a and idx_b
-            try:
-                pos_a = ordered_verts.index(idx_a)
-                pos_b = ordered_verts.index(idx_b)
-            except ValueError:
-                new_faces.append(face)
-                continue
-
-            if pos_a > pos_b:
-                pos_a, pos_b = pos_b, pos_a
-
-            loop1 = ordered_verts[pos_a: pos_b + 1]
-            loop2 = ordered_verts[pos_b:] + ordered_verts[: pos_a + 1]
-
-            # Only keep faces with >= 3 unique vertices
-            for loop in (loop1, loop2):
-                unique = list(dict.fromkeys(loop))  # preserve order, dedupe
-                if len(unique) >= 3:
-                    new_faces.append(unique)
-                    # Ensure all edges of this new face exist
-                    for k in range(len(unique)):
-                        self._find_or_add_edge(unique[k], unique[(k + 1) % len(unique)])
-
-        self.faces = new_faces
-        return fold_edge_indices
-
-    # ── vertex side test ────────────────────────────────────────────
-
-    def get_vertices_on_side(
-        self,
-        line_start: np.ndarray | list,
-        line_end: np.ndarray | list,
-        side: str = "positive",
-    ) -> list[int]:
-        """Return indices of vertices on one side of a 2-D line.
-
-        *side* can be ``"positive"`` or ``"negative"``.  The positive side is
-        defined by the left-hand normal of (line_end - line_start).
-        """
-        ls = np.asarray(line_start, dtype=np.float64)[:2]
-        le = np.asarray(line_end, dtype=np.float64)[:2]
-        d = le - ls
-        normal = np.array([-d[1], d[0]])
-
-        indices: list[int] = []
-        for i, v in enumerate(self.vertices):
-            dot = np.dot(v[:2] - ls, normal)
-            if side == "positive" and dot > 1e-9:
-                indices.append(i)
-            elif side == "negative" and dot < -1e-9:
-                indices.append(i)
-        return indices
-
-    # ── deep copy ───────────────────────────────────────────────────
-
-    def copy(self) -> "Paper":
-        """Return an independent deep copy."""
-        return Paper(
-            vertices=self.vertices.copy(),
-            edges=self.edges.copy(),
-            faces=copy.deepcopy(self.faces),
-            assignments=list(self.assignments),
-            fold_angles=self.fold_angles.copy(),
-            face_orders=list(self.face_orders),
-            material=Material(
-                name=self.material.name,
-                thickness_mm=self.material.thickness_mm,
-                youngs_modulus_gpa=self.material.youngs_modulus_gpa,
-                max_strain=self.material.max_strain,
-                poissons_ratio=self.material.poissons_ratio,
-            ),
-            rest_lengths=self.rest_lengths.copy(),
-            original_area=self.original_area,
-            rest_positions=self.rest_positions.copy(),
-            strain_per_vertex=self.strain_per_vertex.copy(),
-            energy=dict(self.energy),
-            fold_count=self.fold_count,
-        )

engine/physics.py

@@ -1,517 +0,0 @@
-"""
-Bar-and-hinge physics model.
-
-Three energy components:
-  E_total = E_bar + E_facet + E_fold
-
-Stiffness parameters are derived from the material properties.
-"""
-
-from __future__ import annotations
-
-from dataclasses import dataclass
-
-import numpy as np
-
-from .paper import Paper
-
-
-# ────────────────────────────────────────────────────────────────────
-# Stiffness
-# ────────────────────────────────────────────────────────────────────
-
-@dataclass
-class StiffnessParams:
-    """Stiffness values derived from material properties."""
-    k_axial: np.ndarray   # per-edge axial stiffness  (E,)
-    k_facet: float         # facet (panel bending) stiffness
-    k_fold: float          # fold (crease torsion) stiffness
-
-
-def compute_stiffness(paper: Paper) -> StiffnessParams:
-    """Derive stiffness parameters from the paper's material and geometry.
-
-    k_axial = E * t * w / L0   (per edge, w ≈ average of adjacent edge lengths)
-    k_facet = E * t^3 / (12 * (1 - nu^2))
-    k_fold  = 0.1 * k_facet    (crease torsional stiffness, empirical fraction)
-    """
-    mat = paper.material
-    E = mat.youngs_modulus_pa  # Pa
-    t = mat.thickness_m        # m
-    nu = mat.poissons_ratio
-
-    rest = paper.rest_lengths
-    # Guard against zero rest lengths
-    safe_rest = np.where(rest > 1e-15, rest, 1e-15)
-
-    # Approximate edge width as the average rest length (simple heuristic)
-    w = np.mean(safe_rest) if len(safe_rest) > 0 else 1e-3
-
-    k_axial = E * t * w / safe_rest  # (E,)
-
-    k_facet = E * t ** 3 / (12.0 * (1.0 - nu ** 2))
-
-    # Crease torsional stiffness — a fraction of facet stiffness
-    k_fold = 0.1 * k_facet
-
-    return StiffnessParams(k_axial=k_axial, k_facet=k_facet, k_fold=k_fold)
-
-
-# ────────────────────────────────────────────────────────────────────
-# Energy components
-# ────────────────────────────────────────────────────────────────────
-
-def compute_bar_energy(paper: Paper) -> float:
-    """E_bar = sum (1/2) * k_axial * (L - L0)^2
-
-    Measures stretching / compression of edges relative to rest lengths.
-    """
-    if len(paper.edges) == 0:
-        return 0.0
-
-    verts = paper.vertices
-    edges = paper.edges
-    current_lengths = np.array([
-        np.linalg.norm(verts[e[1]] - verts[e[0]]) for e in edges
-    ])
-
-    stiff = compute_stiffness(paper)
-    delta = current_lengths - paper.rest_lengths
-    energy = 0.5 * np.sum(stiff.k_axial * delta ** 2)
-    return float(energy)
-
-
-def compute_facet_energy(paper: Paper) -> float:
-    """E_facet = sum (1/2) * k_facet * l * (theta - pi)^2
-
-    Measures bending of facet panels away from flat (pi).
-    *l* is the edge length (hinge length) and *theta* is the dihedral angle
-    across the edge between two adjacent faces.  For edges that are not
-    shared by two faces we skip them.
-    """
-    if len(paper.edges) == 0 or len(paper.faces) < 2:
-        return 0.0
-
-    stiff = compute_stiffness(paper)
-    verts = paper.vertices
-    edges = paper.edges
-
-    # Build edge → face adjacency
-    edge_faces: dict[int, list[int]] = {}
-    for fi, face in enumerate(paper.faces):
-        n = len(face)
-        for k in range(n):
-            va, vb = face[k], face[(k + 1) % n]
-            for ei, e in enumerate(edges):
-                if (e[0] == va and e[1] == vb) or (e[0] == vb and e[1] == va):
-                    edge_faces.setdefault(ei, []).append(fi)
-                    break
-
-    energy = 0.0
-    for ei, adj_faces in edge_faces.items():
-        if len(adj_faces) < 2:
-            continue
-        # Only consider non-fold edges (flat or boundary interior)
-        if paper.assignments[ei] in ("M", "V"):
-            continue
-
-        f1, f2 = adj_faces[0], adj_faces[1]
-        theta = _dihedral_angle(verts, paper.faces[f1], paper.faces[f2], edges[ei])
-        l = np.linalg.norm(verts[edges[ei][1]] - verts[edges[ei][0]])
-        energy += 0.5 * stiff.k_facet * l * (theta - np.pi) ** 2
-
-    return float(energy)
-
-
-def compute_fold_energy(paper: Paper) -> float:
-    """E_fold = sum (1/2) * k_fold * l * (rho - rho_target)^2
-
-    Measures deviation of fold creases from their target angles.
-    *rho* is the current dihedral angle across the fold edge and
-    *rho_target* comes from ``fold_angles``.
-    """
-    if len(paper.edges) == 0:
-        return 0.0
-
-    stiff = compute_stiffness(paper)
-    verts = paper.vertices
-    edges = paper.edges
-
-    # Build edge → face adjacency
-    edge_faces: dict[int, list[int]] = {}
-    for fi, face in enumerate(paper.faces):
-        n = len(face)
-        for k in range(n):
-            va, vb = face[k], face[(k + 1) % n]
-            for ei, e in enumerate(edges):
-                if (e[0] == va and e[1] == vb) or (e[0] == vb and e[1] == va):
-                    edge_faces.setdefault(ei, []).append(fi)
-                    break
-
-    energy = 0.0
-    for ei in range(len(edges)):
-        if paper.assignments[ei] not in ("M", "V"):
-            continue
-        if ei not in edge_faces or len(edge_faces[ei]) < 2:
-            continue
-
-        f1, f2 = edge_faces[ei][0], edge_faces[ei][1]
-        rho = _dihedral_angle(verts, paper.faces[f1], paper.faces[f2], edges[ei])
-        rho_target = np.radians(paper.fold_angles[ei])  # fold_angles stored in degrees
-        l = np.linalg.norm(verts[edges[ei][1]] - verts[edges[ei][0]])
-        energy += 0.5 * stiff.k_fold * l * (rho - rho_target) ** 2
-
-    return float(energy)
-
-
-def compute_total_energy(paper: Paper) -> float:
-    """E_total = E_bar + E_facet + E_fold."""
-    return compute_bar_energy(paper) + compute_facet_energy(paper) + compute_fold_energy(paper)
-
-
-# ────────────────────────────────────────────────────────────────────
-# Strain
-# ────────────────────────────────────────────────────────────────────
-
-def compute_strain(paper: Paper) -> np.ndarray:
-    """Per-vertex Cauchy strain: average fractional edge-length deviation.
-
-    Returns shape (N,) array of non-negative strain values.
-    """
-    n_verts = len(paper.vertices)
-    if n_verts == 0:
-        return np.empty(0)
-
-    verts = paper.vertices
-    edges = paper.edges
-    rest = paper.rest_lengths
-
-    # Build vertex → edge adjacency
-    vert_edges: dict[int, list[int]] = {}
-    for ei, e in enumerate(edges):
-        vert_edges.setdefault(int(e[0]), []).append(ei)
-        vert_edges.setdefault(int(e[1]), []).append(ei)
-
-    strain = np.zeros(n_verts, dtype=np.float64)
-    for vi in range(n_verts):
-        adj = vert_edges.get(vi, [])
-        if not adj:
-            continue
-        devs = []
-        for ei in adj:
-            v1, v2 = edges[ei]
-            L = np.linalg.norm(verts[v1] - verts[v2])
-            L0 = rest[ei]
-            if L0 > 1e-15:
-                devs.append(abs(L - L0) / L0)
-        if devs:
-            strain[vi] = float(np.mean(devs))
-
-    return strain
-
-
-# ────────────────────────────────────────────────────────────────────
-# Dihedral angle helper
-# ────────────────────────────────────────────────────────────────────
-
-def _dihedral_angle(
-    verts: np.ndarray,
-    face1: list[int],
-    face2: list[int],
-    edge: np.ndarray,
-) -> float:
-    """Compute the dihedral angle (in radians) between two faces sharing *edge*.
-
-    Returns angle in [0, 2*pi).  Returns pi if normals cannot be computed.
-    """
-    n1 = _face_normal(verts, face1)
-    n2 = _face_normal(verts, face2)
-
-    if n1 is None or n2 is None:
-        return np.pi
-
-    cos_a = np.clip(np.dot(n1, n2), -1.0, 1.0)
-    angle = np.arccos(cos_a)
-
-    # Determine sign from edge direction
-    edge_dir = verts[edge[1]] - verts[edge[0]]
-    edge_dir = edge_dir / (np.linalg.norm(edge_dir) + 1e-30)
-    cross = np.cross(n1, n2)
-    if np.dot(cross, edge_dir) < 0:
-        angle = 2.0 * np.pi - angle
-
-    return float(angle)
-
-
-def _face_normal(verts: np.ndarray, face: list[int]) -> np.ndarray | None:
-    """Compute outward unit normal of a face, or None if degenerate."""
-    if len(face) < 3:
-        return None
-    v0 = verts[face[0]]
-    v1 = verts[face[1]]
-    v2 = verts[face[2]]
-    normal = np.cross(v1 - v0, v2 - v0)
-    norm = np.linalg.norm(normal)
-    if norm < 1e-15:
-        return None
-    return normal / norm
-
-
-# ────────────────────────────────────────────────────────────────────
-# Topology precomputation
-# ────────────────────────────────────────────────────────────────────
-
-def build_beam_list(paper: Paper) -> list[tuple[int, int, float, float]]:
-    """Build list of (node_a, node_b, rest_len, k_axial) for every edge.
-
-    Uses normalized stiffness values (arch doc constants) scaled by material
-    Young's modulus ratio — keeps the Verlet integrator stable at unit scale.
-    """
-    # Normalized stiffness constants (arch doc values)
-    K_AXIAL_BASE = 70.0
-    # Scale by material: paper (3 GPa) = 1.0 baseline
-    mat = paper.material
-    E_ratio = mat.youngs_modulus_gpa / 3.0
-    k_axial = K_AXIAL_BASE * E_ratio
-
-    beams = []
-    for ei, (v1, v2) in enumerate(paper.edges):
-        L0 = paper.rest_lengths[ei]
-        beams.append((int(v1), int(v2), float(L0), float(k_axial)))
-    return beams
-
-
-def build_crease_list(paper: Paper) -> list[tuple[int, int, int, int, float, float, str]]:
-    """Build list of (n1, n2, n3, n4, target_angle_rad, k, type) for each crease hinge.
-
-    Each hinge is defined by 4 nodes: n1-n2 is the hinge edge, n3 and n4 are
-    the wing-tip nodes of the two adjacent faces.
-    type is 'fold' (M/V crease) or 'facet' (interior flat edge).
-    """
-    verts = paper.vertices
-
-    # Build edge → face adjacency
-    edge_faces: dict[int, list[int]] = {}
-    for fi, face in enumerate(paper.faces):
-        n = len(face)
-        for k in range(n):
-            va, vb = face[k], face[(k + 1) % n]
-            for ei, e in enumerate(paper.edges):
-                if (e[0] == va and e[1] == vb) or (e[0] == vb and e[1] == va):
-                    edge_faces.setdefault(ei, []).append(fi)
-                    break
-
-    creases = []
-    for ei, adj in edge_faces.items():
-        if len(adj) < 2:
-            continue
-        f1, f2 = adj[0], adj[1]
-        face1, face2 = paper.faces[f1], paper.faces[f2]
-        n1, n2 = int(paper.edges[ei][0]), int(paper.edges[ei][1])
-
-        # Find wing-tip nodes (in each face, the vertex NOT on the shared edge)
-        wing1 = [v for v in face1 if v != n1 and v != n2]
-        wing2 = [v for v in face2 if v != n1 and v != n2]
-        if not wing1 or not wing2:
-            continue
-        n3, n4 = int(wing1[0]), int(wing2[0])
-
-        # Normalized stiffness constants (arch doc values), scaled by material
-        E_ratio = paper.material.youngs_modulus_gpa / 3.0
-        K_FACET = 0.2 * E_ratio
-        K_FOLD = 0.7 * E_ratio
-
-        asgn = paper.assignments[ei]
-        if asgn in ("M", "V"):
-            target = float(np.radians(paper.fold_angles[ei]))
-            k = K_FOLD
-            ctype = "fold"
-        else:
-            target = float(np.pi)
-            k = K_FACET
-            ctype = "facet"
-
-        creases.append((n1, n2, n3, n4, target, k, ctype))
-    return creases
-
-
-def _torque_to_forces(
-    p1: np.ndarray, p2: np.ndarray,
-    p3: np.ndarray, p4: np.ndarray,
-    torque: float,
-) -> tuple[np.ndarray, np.ndarray, np.ndarray, np.ndarray]:
-    """Convert a dihedral torque into forces on the 4 hinge nodes.
-
-    p1-p2 is the hinge edge. p3 and p4 are wing tips.
-    Returns (f1, f2, f3, f4) as (3,) arrays.
-    """
-    e = p2 - p1
-    e_len = np.linalg.norm(e)
-    if e_len < 1e-12:
-        zero = np.zeros(3)
-        return zero, zero, zero, zero
-
-    e_hat = e / e_len
-
-    # Perpendicular components of wing vectors relative to hinge
-    d3 = p3 - p1
-    d4 = p4 - p1
-    d3_perp = d3 - np.dot(d3, e_hat) * e_hat
-    d4_perp = d4 - np.dot(d4, e_hat) * e_hat
-
-    len3 = np.linalg.norm(d3_perp)
-    len4 = np.linalg.norm(d4_perp)
-
-    if len3 < 1e-12 or len4 < 1e-12:
-        zero = np.zeros(3)
-        return zero, zero, zero, zero
-
-    # Force on wing tips proportional to torque / lever arm
-    f3 = torque / (len3 * e_len) * np.cross(e_hat, d3_perp / len3)
-    f4 = -torque / (len4 * e_len) * np.cross(e_hat, d4_perp / len4)
-
-    # Reaction forces distributed to hinge nodes
-    f1 = -(f3 + f4) * 0.5
-    f2 = -(f3 + f4) * 0.5
-
-    return f1, f2, f3, f4
-
-
-# ────────────────────────────────────────────────────────────────────
-# Verlet solver
-# ────────────────────────────────────────────────────────────────────
-
-def simulate(
-    paper: Paper,
-    fold_percent: float = 1.0,
-    n_steps: int = 500,
-    dt: float = 0.005,
-    damping: float = 0.15,
-) -> Paper:
-    """Run bar-and-hinge Verlet integration to relax the mesh.
-
-    Updates paper.vertices, paper.strain_per_vertex, and paper.energy in-place.
-    Returns the mutated paper for chaining.
-
-    Parameters
-    ----------
-    paper : Paper
-        Paper state after a fold has been applied (vertices already rotated).
-    fold_percent : float
-        How far along the fold to drive (0=flat, 1=full target angle).
-    n_steps : int
-        Maximum integration steps.
-    dt : float
-        Time step. Keep small (0.005) for stability with stiff materials.
-    damping : float
-        Velocity damping coefficient (0=undamped, 1=fully damped).
-    """
-    if len(paper.vertices) == 0:
-        return paper
-
-    beams = build_beam_list(paper)
-    creases = build_crease_list(paper)
-
-    pos = paper.vertices.copy()        # (N, 3) current positions
-    last_pos = pos.copy()              # (N, 3) previous positions (Verlet)
-
-    max_force_cap = 1e6  # prevent runaway forces
-
-    for _ in range(n_steps):
-        forces = np.zeros_like(pos)
-
-        # ── Beam (axial spring) forces ───────────────────────────────
-        for (a, b, L0, k) in beams:
-            delta = pos[b] - pos[a]
-            L = np.linalg.norm(delta)
-            if L < 1e-12:
-                continue
-            strain = (L - L0) / L0
-            F_mag = k * strain
-            F_vec = F_mag * (delta / L)
-            # Clamp to prevent instability
-            F_vec = np.clip(F_vec, -max_force_cap, max_force_cap)
-            forces[a] += F_vec
-            forces[b] -= F_vec
-
-        # ── Crease (dihedral spring) forces ─────────────────────────
-        for (n1, n2, n3, n4, target, k, ctype) in creases:
-            actual_target = target * fold_percent if ctype == "fold" else target
-            try:
-                theta = _compute_dihedral_rad(pos[n1], pos[n2], pos[n3], pos[n4])
-            except Exception:
-                continue
-            delta_theta = theta - actual_target
-            edge_len = np.linalg.norm(pos[n2] - pos[n1])
-            torque = k * edge_len * delta_theta
-            torque = float(np.clip(torque, -max_force_cap, max_force_cap))
-
-            f1, f2, f3, f4 = _torque_to_forces(
-                pos[n1], pos[n2], pos[n3], pos[n4], torque
-            )
-            forces[n1] += np.clip(f1, -max_force_cap, max_force_cap)
-            forces[n2] += np.clip(f2, -max_force_cap, max_force_cap)
-            forces[n3] += np.clip(f3, -max_force_cap, max_force_cap)
-            forces[n4] += np.clip(f4, -max_force_cap, max_force_cap)
-
-        # ── Verlet integration ───────────────────────────────────────
-        new_pos = pos + (1.0 - damping) * (pos - last_pos) + forces * (dt * dt)
-
-        # NaN guard
-        if np.any(np.isnan(new_pos)):
-            break
-
-        last_pos = pos
-        pos = new_pos
-
-        # ── Convergence check ────────────────────────────────────────
-        kinetic = np.sum((pos - last_pos) ** 2)
-        if kinetic < 1e-12:
-            break
-
-    # ── Write results back to paper ──────────────────────────────────
-    paper.vertices = pos
-    paper.strain_per_vertex = compute_strain(paper)
-    paper.energy = {
-        "total": compute_total_energy(paper),
-        "bar": compute_bar_energy(paper),
-        "facet": compute_facet_energy(paper),
-        "fold": compute_fold_energy(paper),
-    }
-
-    return paper
-
-
-def _compute_dihedral_rad(
-    p1: np.ndarray, p2: np.ndarray,
-    p3: np.ndarray, p4: np.ndarray,
-) -> float:
-    """Dihedral angle in radians between planes (p1,p2,p3) and (p1,p2,p4).
-
-    p1-p2 is the hinge edge. p3 and p4 are the wing tips.
-    Returns angle in [0, 2*pi).
-    """
-    e = p2 - p1
-    e_norm = np.linalg.norm(e)
-    if e_norm < 1e-12:
-        return float(np.pi)
-    e_hat = e / e_norm
-
-    n1 = np.cross(p3 - p1, e)
-    n2 = np.cross(e, p4 - p1)
-    len1 = np.linalg.norm(n1)
-    len2 = np.linalg.norm(n2)
-    if len1 < 1e-12 or len2 < 1e-12:
-        return float(np.pi)
-
-    n1 = n1 / len1
-    n2 = n2 / len2
-
-    cos_a = float(np.clip(np.dot(n1, n2), -1.0, 1.0))
-    angle = np.arccos(cos_a)
-
-    cross = np.cross(n1, n2)
-    if np.dot(cross, e_hat) < 0:
-        angle = 2.0 * np.pi - angle
-
-    return float(angle)

engine/validation.py

@@ -1,278 +0,0 @@
-"""
-Geometric validation for origami crease patterns.
-
-Implements Kawasaki's theorem, Maekawa's theorem, and triangle-triangle
-self-intersection detection.
-"""
-
-from __future__ import annotations
-
-from dataclasses import dataclass
-
-import numpy as np
-
-from .paper import Paper
-
-
-# ────────────────────────────────────────────────────────────────────
-# Result container
-# ────────────────────────────────────────────────────────────────────
-
-@dataclass
-class ValidationResult:
-    kawasaki_valid: bool
-    kawasaki_violation: float
-    maekawa_valid: bool
-    maekawa_violation: float
-    intersection_free: bool
-    self_intersection_count: int
-    is_valid: bool  # all checks pass
-
-
-# ────────────────────────────────────────────────────────────────────
-# Kawasaki's theorem
-# ────────────────────────────────────────────────────────────────────
-
-def check_kawasaki(paper: Paper) -> tuple[bool, float]:
-    """At each interior vertex, the alternating sum of sector angles equals pi.
-
-    Specifically, for a vertex with 2n incident creases, the sum of
-    odd-indexed sector angles equals the sum of even-indexed sector
-    angles equals pi.
-
-    Returns (is_valid, total_violation).  A violation of < 1e-6 is
-    considered valid.
-    """
-    verts = paper.vertices
-    edges = paper.edges
-    n_verts = len(verts)
-
-    # Build adjacency: vertex -> list of neighbor vertices (via edges)
-    adj: dict[int, list[int]] = {}
-    for e in edges:
-        adj.setdefault(int(e[0]), []).append(int(e[1]))
-        adj.setdefault(int(e[1]), []).append(int(e[0]))
-
-    # Identify boundary vertices (incident to a 'B' edge)
-    boundary_verts: set[int] = set()
-    for ei, e in enumerate(edges):
-        if paper.assignments[ei] == "B":
-            boundary_verts.add(int(e[0]))
-            boundary_verts.add(int(e[1]))
-
-    total_violation = 0.0
-
-    for vi in range(n_verts):
-        if vi in boundary_verts:
-            continue
-        neighbors = adj.get(vi, [])
-        if len(neighbors) < 2:
-            continue
-
-        # Sort neighbors by angle around vi (in the XY plane for flat-foldability)
-        center = verts[vi][:2]
-        angles = []
-        for ni in neighbors:
-            d = verts[ni][:2] - center
-            angles.append((np.arctan2(d[1], d[0]), ni))
-        angles.sort(key=lambda x: x[0])
-
-        # Sector angles
-        sector_angles = []
-        for k in range(len(angles)):
-            a1 = angles[k][0]
-            a2 = angles[(k + 1) % len(angles)][0]
-            diff = a2 - a1
-            if diff <= 0:
-                diff += 2.0 * np.pi
-            sector_angles.append(diff)
-
-        if len(sector_angles) < 2:
-            continue
-
-        # Kawasaki: alternating sums should both equal pi
-        even_sum = sum(sector_angles[i] for i in range(0, len(sector_angles), 2))
-        odd_sum = sum(sector_angles[i] for i in range(1, len(sector_angles), 2))
-
-        violation = abs(even_sum - odd_sum)
-        total_violation += violation
-
-    is_valid = bool(total_violation < 1e-4)
-    return is_valid, float(total_violation)
-
-
-# ────────────────────────────────────────────────────────────────────
-# Maekawa's theorem
-# ────────────────────────────────────────────────────────────────────
-
-def check_maekawa(paper: Paper) -> tuple[bool, float]:
-    """At each interior vertex, |M - V| = 2.
-
-    Returns (is_valid, total_violation) where violation is
-    sum of |abs(M-V) - 2| over all interior vertices.
-    """
-    edges = paper.edges
-    verts = paper.vertices
-    n_verts = len(verts)
-
-    # Boundary vertices
-    boundary_verts: set[int] = set()
-    for ei, e in enumerate(edges):
-        if paper.assignments[ei] == "B":
-            boundary_verts.add(int(e[0]))
-            boundary_verts.add(int(e[1]))
-
-    # Count M and V edges per vertex
-    m_count = [0] * n_verts
-    v_count = [0] * n_verts
-    total_mv_per_vertex = [0] * n_verts
-
-    for ei, e in enumerate(edges):
-        a = paper.assignments[ei]
-        if a == "M":
-            m_count[int(e[0])] += 1
-            m_count[int(e[1])] += 1
-        elif a == "V":
-            v_count[int(e[0])] += 1
-            v_count[int(e[1])] += 1
-        if a in ("M", "V"):
-            total_mv_per_vertex[int(e[0])] += 1
-            total_mv_per_vertex[int(e[1])] += 1
-
-    total_violation = 0.0
-    for vi in range(n_verts):
-        if vi in boundary_verts:
-            continue
-        # Only check vertices that actually have creases
-        if total_mv_per_vertex[vi] == 0:
-            continue
-        diff = abs(m_count[vi] - v_count[vi])
-        violation = abs(diff - 2)
-        total_violation += violation
-
-    is_valid = total_violation < 0.5  # integer theorem, so < 0.5 means exact
-    return is_valid, float(total_violation)
-
-
-# ────────────────────────────────────────────────────────────────────
-# Self-intersection detection (triangle-triangle)
-# ────────────────────────────────────────────────────────────────────
-
-def check_self_intersection(paper: Paper) -> tuple[bool, int]:
-    """Check for triangle-triangle intersections among the paper's faces.
-
-    Uses the separating-axis theorem (SAT) for triangle-triangle overlap
-    in 3-D.  Faces that share an edge or vertex are skipped.
-
-    Returns (is_valid, count_of_intersections).
-    """
-    verts = paper.vertices
-    faces = paper.faces
-    count = 0
-
-    for i in range(len(faces)):
-        for j in range(i + 1, len(faces)):
-            # Skip faces that share vertices (adjacent faces)
-            if set(faces[i]) & set(faces[j]):
-                continue
-            if _triangles_intersect(verts, faces[i], faces[j]):
-                count += 1
-
-    return count == 0, count
-
-
-def _triangles_intersect(
-    verts: np.ndarray,
-    face1: list[int],
-    face2: list[int],
-) -> bool:
-    """Test whether two triangular faces intersect in 3-D using
-    the separating-axis theorem (Moller's method simplified).
-
-    For non-triangular faces, only tests the first three vertices.
-    Returns True if the triangles intersect.
-    """
-    if len(face1) < 3 or len(face2) < 3:
-        return False
-
-    t1 = verts[face1[:3]]
-    t2 = verts[face2[:3]]
-
-    # 13 potential separating axes:
-    # - normals of each triangle (2)
-    # - cross products of edge pairs (3x3 = 9)
-    # - edges themselves don't need separate tests in 3D SAT
-
-    e1_edges = [t1[1] - t1[0], t1[2] - t1[1], t1[0] - t1[2]]
-    e2_edges = [t2[1] - t2[0], t2[2] - t2[1], t2[0] - t2[2]]
-
-    n1 = np.cross(e1_edges[0], e1_edges[1])
-    n2 = np.cross(e2_edges[0], e2_edges[1])
-
-    axes = [n1, n2]
-    for e1 in e1_edges:
-        for e2 in e2_edges:
-            ax = np.cross(e1, e2)
-            if np.linalg.norm(ax) > 1e-12:
-                axes.append(ax)
-
-    for axis in axes:
-        norm = np.linalg.norm(axis)
-        if norm < 1e-12:
-            continue
-        axis = axis / norm
-
-        proj1 = np.dot(t1, axis)
-        proj2 = np.dot(t2, axis)
-
-        min1, max1 = proj1.min(), proj1.max()
-        min2, max2 = proj2.min(), proj2.max()
-
-        # Check for separation (with small tolerance for shared-edge adjacency)
-        if max1 < min2 - 1e-9 or max2 < min1 - 1e-9:
-            return False  # separating axis found
-
-    return True  # no separating axis → intersection
-
-
-# ────────────────────────────────────────────────────────────────────
-# Combined validation
-# ────────────────────────────────────────────────────────────────────
-
-def validate_paper(paper: Paper) -> ValidationResult:
-    """Run all validation checks and return a combined result."""
-    k_valid, k_violation = check_kawasaki(paper)
-    m_valid, m_violation = check_maekawa(paper)
-    si_valid, si_count = check_self_intersection(paper)
-
-    return ValidationResult(
-        kawasaki_valid=k_valid,
-        kawasaki_violation=k_violation,
-        maekawa_valid=m_valid,
-        maekawa_violation=m_violation,
-        intersection_free=si_valid,
-        self_intersection_count=si_count,
-        is_valid=k_valid and m_valid and si_valid,
-    )
-
-
-def validate_state(paper: Paper) -> dict:
-    """Run all validation checks and return a flat dict.
-
-    This is the interface used by OrigamiEnvironment. It calls the
-    existing validation functions and returns a dict with all fields
-    the environment and metrics system need.
-    """
-    result = validate_paper(paper)
-    strain_exceeded = bool(
-        len(paper.strain_per_vertex) > 0
-        and float(paper.strain_per_vertex.max()) > paper.material.max_strain
-    )
-    return {
-        "is_valid": result.is_valid and not strain_exceeded,
-        "kawasaki_violations": int(not result.kawasaki_valid),
-        "kawasaki_total_error": float(result.kawasaki_violation),
-        "maekawa_violations": int(not result.maekawa_valid),
-        "self_intersections": result.self_intersection_count,
-        "strain_exceeded": strain_exceeded,
-    }

planner/decomposer.py

@@ -1,284 +0,0 @@
-"""
-Task decomposer: breaks a parsed instruction into sequential sub-goals
-with concrete fold operations on a unit square.
-"""
-
-from __future__ import annotations
-
-import copy
-from planner.knowledge import (
-    ORIGAMI_MODELS,
-    ORIGAMI_BASES,
-    FOLD_OPERATIONS,
-    get_model_steps,
-    get_base_steps,
-)
-
-
-# ---------------------------------------------------------------------------
-# Internal helpers
-# ---------------------------------------------------------------------------
-
-def _step_to_fold_operation(step: dict) -> dict:
-    """
-    Convert a knowledge-base step dict into the engine's fold operation format:
-      {"type": ..., "line": {"start": [...], "end": [...]}, "angle": ...}
-    """
-    op = {
-        "type": step["type"],
-        "line": copy.deepcopy(step["line"]),
-        "angle": step.get("angle", 180),
-    }
-    if "layer_select" in step:
-        op["layer_select"] = step["layer_select"]
-    return op
-
-
-def _expected_state_after_fold(fold_type: str, prev_state: dict | None) -> dict:
-    """
-    Produce a lightweight expected-state dict describing what the paper
-    should look like after a fold.  This is intentionally approximate --
-    the real simulation engine computes exact geometry.
-    """
-    state = dict(prev_state or {"layers": 1, "shape": "square", "phase": "flat"})
-    if fold_type in ("valley", "mountain"):
-        state["layers"] = state.get("layers", 1) * 2
-    elif fold_type == "petal":
-        state["shape"] = "narrow_diamond"
-    elif fold_type == "squash":
-        state["shape"] = "diamond"
-    elif fold_type == "reverse_inside":
-        state["shape"] = "pointed_flap_reversed"
-    elif fold_type == "inflate":
-        state["phase"] = "3d"
-    elif fold_type == "turn_over":
-        state["flipped"] = not state.get("flipped", False)
-    elif fold_type == "unfold":
-        # Layers don't literally halve on every unfold, but this is a hint
-        state["layers"] = max(1, state.get("layers", 1) // 2)
-    return state
-
-
-def _validation_for_fold(fold_type: str) -> dict:
-    """Return a simple validation dict for a step."""
-    checks: dict = {"flat_foldable": True}
-    if fold_type in ("valley", "mountain"):
-        checks["kawasaki_check"] = True
-        checks["maekawa_check"] = True
-    if fold_type == "inflate":
-        checks["is_3d"] = True
-        checks["flat_foldable"] = False
-    return checks
-
-
-# ---------------------------------------------------------------------------
-# Known-model decomposition
-# ---------------------------------------------------------------------------
-
-def _decompose_known_model(parsed: dict) -> list[dict]:
-    """Decompose a known model into sub-goal steps."""
-    model_name: str = parsed["model_name"]
-    model_info = ORIGAMI_MODELS.get(model_name)
-    if model_info is None:
-        return _decompose_free_fold(parsed)
-
-    base_name = model_info.get("base")
-    steps = get_model_steps(model_name)
-    sub_goals: list[dict] = []
-    running_state: dict = {"layers": 1, "shape": "square", "phase": "flat"}
-
-    for i, step in enumerate(steps):
-        fold_op = _step_to_fold_operation(step)
-        running_state = _expected_state_after_fold(step["type"], running_state)
-
-        sub_goals.append({
-            "step_number": i + 1,
-            "description": step.get("description", f"Step {i + 1}"),
-            "base_required": base_name if i == 0 else None,
-            "fold_operations": [fold_op],
-            "expected_state": dict(running_state),
-            "validation": _validation_for_fold(step["type"]),
-        })
-
-    return sub_goals
-
-
-# ---------------------------------------------------------------------------
-# Packing / optimization decomposition
-# ---------------------------------------------------------------------------
-
-def _decompose_packing(parsed: dict) -> list[dict]:
-    """
-    Decompose an optimize_packing task into sub-goals.
-    Returns a Miura-ori-style fold plan on a unit square.
-    """
-    w = parsed["dimensions"]["width"]
-    h = parsed["dimensions"]["height"]
-    material = parsed["material"]
-    constraints = parsed.get("constraints", {})
-    max_folds = constraints.get("max_folds", 20)
-
-    sub_goals: list[dict] = []
-    step_num = 0
-
-    # Horizontal valley/mountain pleats (zigzag in Y)
-    n_horizontal = min(4, max_folds // 4)
-    spacing_y = 1.0 / (n_horizontal + 1)
-    for i in range(n_horizontal):
-        step_num += 1
-        y = spacing_y * (i + 1)
-        fold_type = "valley" if i % 2 == 0 else "mountain"
-        sub_goals.append({
-            "step_number": step_num,
-            "description": f"Horizontal {fold_type} fold at y={y:.3f} (pleat {i + 1}/{n_horizontal})",
-            "base_required": None,
-            "fold_operations": [{
-                "type": fold_type,
-                "line": {"start": [0.0, y], "end": [1.0, y]},
-                "angle": 180,
-                "layer_select": "all",
-            }],
-            "expected_state": {"layers": i + 2, "phase": "flat", "pattern": "miura_horizontal"},
-            "validation": {"flat_foldable": True, "kawasaki_check": True},
-        })
-
-    # Vertical zigzag valley/mountain pleats (Miura-ori angle offsets)
-    n_vertical = min(4, (max_folds - n_horizontal) // 2)
-    spacing_x = 1.0 / (n_vertical + 1)
-    for i in range(n_vertical):
-        step_num += 1
-        x = spacing_x * (i + 1)
-        fold_type = "valley" if i % 2 == 0 else "mountain"
-        # Miura-ori: alternate slight angle offset to create parallelogram cells
-        angle_offset = 0.02 * (1 if i % 2 == 0 else -1)
-        sub_goals.append({
-            "step_number": step_num,
-            "description": f"Vertical {fold_type} fold at x={x:.3f} (Miura-ori column {i + 1}/{n_vertical})",
-            "base_required": None,
-            "fold_operations": [{
-                "type": fold_type,
-                "line": {"start": [x, 0.0 + angle_offset], "end": [x, 1.0 - angle_offset]},
-                "angle": 180,
-                "layer_select": "all",
-            }],
-            "expected_state": {
-                "layers": (n_horizontal + 1) * (i + 2),
-                "phase": "flat",
-                "pattern": "miura_complete" if i == n_vertical - 1 else "miura_partial",
-            },
-            "validation": {"flat_foldable": True, "kawasaki_check": True, "maekawa_check": True},
-        })
-
-    # Final collapse
-    step_num += 1
-    sub_goals.append({
-        "step_number": step_num,
-        "description": "Collapse all creases simultaneously into compact Miura-ori stack",
-        "base_required": None,
-        "fold_operations": [{
-            "type": "valley",
-            "line": {"start": [0.0, 0.5], "end": [1.0, 0.5]},
-            "angle": 180,
-            "layer_select": "all",
-        }],
-        "expected_state": {
-            "layers": (n_horizontal + 1) * (n_vertical + 1),
-            "phase": "compact",
-            "pattern": "miura_ori",
-        },
-        "validation": {
-            "flat_foldable": True,
-            "check_bounding_box": constraints.get("target_box"),
-            "check_deployable": constraints.get("must_deploy", False),
-        },
-    })
-
-    return sub_goals
-
-
-# ---------------------------------------------------------------------------
-# Free-fold / unknown model decomposition
-# ---------------------------------------------------------------------------
-
-def _decompose_free_fold(parsed: dict) -> list[dict]:
-    """
-    Generic decomposition for an unknown model or free-form folding task.
-    Returns a minimal plan that an LLM can expand upon.
-    """
-    return [
-        {
-            "step_number": 1,
-            "description": "Create reference creases (diagonals and midlines)",
-            "base_required": None,
-            "fold_operations": [
-                {"type": "valley", "line": {"start": [0.0, 0.0], "end": [1.0, 1.0]}, "angle": 180},
-                {"type": "unfold", "line": {"start": [0.0, 0.0], "end": [1.0, 1.0]}, "angle": 0},
-                {"type": "valley", "line": {"start": [1.0, 0.0], "end": [0.0, 1.0]}, "angle": 180},
-                {"type": "unfold", "line": {"start": [1.0, 0.0], "end": [0.0, 1.0]}, "angle": 0},
-                {"type": "valley", "line": {"start": [0.0, 0.5], "end": [1.0, 0.5]}, "angle": 180},
-                {"type": "unfold", "line": {"start": [0.0, 0.5], "end": [1.0, 0.5]}, "angle": 0},
-            ],
-            "expected_state": {"layers": 1, "shape": "square", "phase": "creased"},
-            "validation": {"flat_foldable": True},
-        },
-        {
-            "step_number": 2,
-            "description": "Collapse into a base form using reference creases",
-            "base_required": "preliminary_base",
-            "fold_operations": [
-                {"type": "valley", "line": {"start": [0.0, 0.0], "end": [1.0, 1.0]}, "angle": 180, "layer_select": "all"},
-            ],
-            "expected_state": {"layers": 4, "shape": "diamond", "phase": "base"},
-            "validation": {"flat_foldable": True},
-        },
-        {
-            "step_number": 3,
-            "description": "Shape the model with additional folds (LLM determines specifics)",
-            "base_required": None,
-            "fold_operations": [],  # Left empty for LLM to fill
-            "expected_state": {"phase": "shaped"},
-            "validation": {"flat_foldable": True},
-        },
-    ]
-
-
-# ---------------------------------------------------------------------------
-# Fold-pattern decomposition
-# ---------------------------------------------------------------------------
-
-def _decompose_pattern(parsed: dict) -> list[dict]:
-    """Decompose a tessellation/pattern task."""
-    # For now, delegate to packing which generates a Miura-ori pattern
-    return _decompose_packing(parsed)
-
-
-# ---------------------------------------------------------------------------
-# Public API
-# ---------------------------------------------------------------------------
-
-def decompose_task(parsed: dict) -> list[dict]:
-    """
-    Decompose a parsed instruction into sequential sub-goals.
-
-    Args:
-        parsed: Output of parse_instruction()
-
-    Returns:
-        List of sub-goal dicts, each with:
-          - step_number: int
-          - description: str
-          - base_required: str or None
-          - fold_operations: list[dict]  (engine-format fold dicts)
-          - expected_state: dict
-          - validation: dict
-    """
-    intent = parsed.get("intent", "free_fold")
-
-    if intent == "fold_model" and parsed.get("model_name"):
-        return _decompose_known_model(parsed)
-    elif intent == "optimize_packing":
-        return _decompose_packing(parsed)
-    elif intent == "fold_pattern":
-        return _decompose_pattern(parsed)
-    else:
-        return _decompose_free_fold(parsed)

planner/knowledge.py

@@ -1,753 +0,0 @@
-"""
-Origami knowledge base: bases, models, and fold operation primitives.
-
-All fold coordinates are defined on a unit square (0,0) to (1,1).
-Fold lines use {"start": [x, y], "end": [x, y]} format matching the
-engine's FoldAction specification from architecture.md.
-"""
-
-# ---------------------------------------------------------------------------
-# Primitive fold operations — mapping from named folds to engine-level dicts
-# ---------------------------------------------------------------------------
-
-FOLD_OPERATIONS = {
-    "valley_fold": {
-        "type": "valley",
-        "angle": 180,
-        "description": "Fold paper toward you along a crease line.",
-    },
-    "mountain_fold": {
-        "type": "mountain",
-        "angle": 180,
-        "description": "Fold paper away from you along a crease line.",
-    },
-    "squash_fold": {
-        "type": "squash",
-        "angle": 180,
-        "description": "Open a flap and flatten it symmetrically.",
-        "primitives": [
-            {"type": "valley", "angle": 90, "sub_op": "open_flap"},
-            {"type": "valley", "angle": 180, "sub_op": "flatten"},
-        ],
-    },
-    "petal_fold": {
-        "type": "petal",
-        "angle": 180,
-        "description": "Lift a point while collapsing sides inward to create a narrow flap.",
-        "primitives": [
-            {"type": "valley", "angle": 180, "sub_op": "fold_left_edge_to_center"},
-            {"type": "valley", "angle": 180, "sub_op": "fold_right_edge_to_center"},
-            {"type": "valley", "angle": 180, "sub_op": "lift_bottom_point"},
-            {"type": "mountain", "angle": 180, "sub_op": "collapse_left"},
-            {"type": "mountain", "angle": 180, "sub_op": "collapse_right"},
-        ],
-    },
-    "reverse_inside_fold": {
-        "type": "reverse_inside",
-        "angle": 180,
-        "description": "Push a flap tip inward, reversing the spine crease.",
-        "primitives": [
-            {"type": "valley", "angle": 180, "sub_op": "new_crease_left"},
-            {"type": "valley", "angle": 180, "sub_op": "new_crease_right"},
-            {"type": "mountain", "angle": 180, "sub_op": "reverse_spine"},
-        ],
-    },
-    "reverse_outside_fold": {
-        "type": "reverse_outside",
-        "angle": 180,
-        "description": "Wrap a flap tip around the outside, reversing the spine crease.",
-        "primitives": [
-            {"type": "mountain", "angle": 180, "sub_op": "new_crease_left"},
-            {"type": "mountain", "angle": 180, "sub_op": "new_crease_right"},
-            {"type": "valley", "angle": 180, "sub_op": "reverse_spine"},
-        ],
-    },
-    "crimp": {
-        "type": "crimp",
-        "angle": 180,
-        "description": "Pair of reverse folds creating a zigzag step.",
-        "primitives": [
-            {"type": "valley", "angle": 180, "sub_op": "first_crease"},
-            {"type": "mountain", "angle": 180, "sub_op": "second_crease"},
-        ],
-    },
-    "pleat": {
-        "type": "pleat",
-        "angle": 180,
-        "description": "Alternating valley and mountain folds creating an accordion.",
-        "primitives": [
-            {"type": "valley", "angle": 180, "sub_op": "valley_crease"},
-            {"type": "mountain", "angle": 180, "sub_op": "mountain_crease"},
-        ],
-    },
-    "rabbit_ear": {
-        "type": "rabbit_ear",
-        "angle": 180,
-        "description": "Three creases meeting at a point, creating a triangular raised flap.",
-        "primitives": [
-            {"type": "valley", "angle": 180, "sub_op": "bisector_1"},
-            {"type": "valley", "angle": 180, "sub_op": "bisector_2"},
-            {"type": "mountain", "angle": 180, "sub_op": "ridge"},
-        ],
-    },
-    "sink_fold": {
-        "type": "sink",
-        "angle": 180,
-        "description": "Push a point into the interior of the model.",
-        "primitives": [
-            {"type": "mountain", "angle": 180, "sub_op": "reverse_creases"},
-            {"type": "valley", "angle": 180, "sub_op": "reflatten"},
-        ],
-    },
-    "turn_over": {
-        "type": "turn_over",
-        "angle": 0,
-        "description": "Flip the paper over.",
-    },
-    "unfold": {
-        "type": "unfold",
-        "angle": 0,
-        "description": "Reverse a previous fold (crease remains).",
-    },
-    "inflate": {
-        "type": "inflate",
-        "angle": 0,
-        "description": "Gently open and puff out the model to create 3D form.",
-    },
-}
-
-
-# ---------------------------------------------------------------------------
-# Origami bases — fundamental starting configurations
-# ---------------------------------------------------------------------------
-
-ORIGAMI_BASES = {
-    "preliminary_base": {
-        "name": "Preliminary Base (Square Base)",
-        "description": "Multi-layered diamond standing on a corner. Gateway to bird and frog bases.",
-        "total_steps": 9,
-        "steps": [
-            {
-                "description": "Fold in half diagonally (bottom-left to top-right)",
-                "type": "valley",
-                "line": {"start": [0.0, 0.0], "end": [1.0, 1.0]},
-                "angle": 180,
-                "layer_select": "all",
-            },
-            {
-                "description": "Unfold",
-                "type": "unfold",
-                "line": {"start": [0.0, 0.0], "end": [1.0, 1.0]},
-                "angle": 0,
-                "layer_select": "all",
-            },
-            {
-                "description": "Fold in half on other diagonal (bottom-right to top-left)",
-                "type": "valley",
-                "line": {"start": [1.0, 0.0], "end": [0.0, 1.0]},
-                "angle": 180,
-                "layer_select": "all",
-            },
-            {
-                "description": "Unfold",
-                "type": "unfold",
-                "line": {"start": [1.0, 0.0], "end": [0.0, 1.0]},
-                "angle": 0,
-                "layer_select": "all",
-            },
-            {
-                "description": "Fold in half horizontally",
-                "type": "valley",
-                "line": {"start": [0.0, 0.5], "end": [1.0, 0.5]},
-                "angle": 180,
-                "layer_select": "all",
-            },
-            {
-                "description": "Unfold",
-                "type": "unfold",
-                "line": {"start": [0.0, 0.5], "end": [1.0, 0.5]},
-                "angle": 0,
-                "layer_select": "all",
-            },
-            {
-                "description": "Fold in half vertically",
-                "type": "valley",
-                "line": {"start": [0.5, 0.0], "end": [0.5, 1.0]},
-                "angle": 180,
-                "layer_select": "all",
-            },
-            {
-                "description": "Unfold",
-                "type": "unfold",
-                "line": {"start": [0.5, 0.0], "end": [0.5, 1.0]},
-                "angle": 0,
-                "layer_select": "all",
-            },
-            {
-                "description": "Collapse into preliminary base: push sides in using existing creases",
-                "type": "valley",
-                "line": {"start": [0.0, 0.0], "end": [1.0, 1.0]},
-                "angle": 180,
-                "layer_select": "all",
-                "simultaneous": [
-                    {"type": "valley", "line": {"start": [1.0, 0.0], "end": [0.0, 1.0]}, "angle": 180},
-                    {"type": "mountain", "line": {"start": [0.0, 0.5], "end": [1.0, 0.5]}, "angle": 180},
-                    {"type": "mountain", "line": {"start": [0.5, 0.0], "end": [0.5, 1.0]}, "angle": 180},
-                ],
-            },
-        ],
-    },
-
-    "waterbomb_base": {
-        "name": "Waterbomb Base",
-        "description": "Flat triangle with multiple layers. Inverse of preliminary base.",
-        "total_steps": 9,
-        "steps": [
-            {
-                "description": "Fold both diagonals — first diagonal",
-                "type": "valley",
-                "line": {"start": [0.0, 0.0], "end": [1.0, 1.0]},
-                "angle": 180,
-                "layer_select": "all",
-            },
-            {
-                "description": "Unfold first diagonal",
-                "type": "unfold",
-                "line": {"start": [0.0, 0.0], "end": [1.0, 1.0]},
-                "angle": 0,
-                "layer_select": "all",
-            },
-            {
-                "description": "Fold second diagonal",
-                "type": "valley",
-                "line": {"start": [1.0, 0.0], "end": [0.0, 1.0]},
-                "angle": 180,
-                "layer_select": "all",
-            },
-            {
-                "description": "Unfold second diagonal",
-                "type": "unfold",
-                "line": {"start": [1.0, 0.0], "end": [0.0, 1.0]},
-                "angle": 0,
-                "layer_select": "all",
-            },
-            {
-                "description": "Mountain fold horizontally",
-                "type": "mountain",
-                "line": {"start": [0.0, 0.5], "end": [1.0, 0.5]},
-                "angle": 180,
-                "layer_select": "all",
-            },
-            {
-                "description": "Unfold horizontal",
-                "type": "unfold",
-                "line": {"start": [0.0, 0.5], "end": [1.0, 0.5]},
-                "angle": 0,
-                "layer_select": "all",
-            },
-            {
-                "description": "Mountain fold vertically",
-                "type": "mountain",
-                "line": {"start": [0.5, 0.0], "end": [0.5, 1.0]},
-                "angle": 180,
-                "layer_select": "all",
-            },
-            {
-                "description": "Unfold vertical",
-                "type": "unfold",
-                "line": {"start": [0.5, 0.0], "end": [0.5, 1.0]},
-                "angle": 0,
-                "layer_select": "all",
-            },
-            {
-                "description": "Collapse into waterbomb base: fold top edge down, push sides in",
-                "type": "mountain",
-                "line": {"start": [0.0, 0.5], "end": [1.0, 0.5]},
-                "angle": 180,
-                "layer_select": "all",
-                "simultaneous": [
-                    {"type": "valley", "line": {"start": [0.0, 0.0], "end": [1.0, 1.0]}, "angle": 180},
-                    {"type": "valley", "line": {"start": [1.0, 0.0], "end": [0.0, 1.0]}, "angle": 180},
-                ],
-            },
-        ],
-    },
-
-    "bird_base": {
-        "name": "Bird Base (Crane Base)",
-        "description": "Long diamond with 4 narrow flaps. Built from preliminary base + 2 petal folds.",
-        "requires_base": "preliminary_base",
-        "total_steps": 13,
-        "steps": [
-            # Steps 1-9 are the preliminary base (included by reference)
-            # Steps 10-22 from the crane sequence build the bird base
-            {
-                "description": "Fold left edge of top layer to center line",
-                "type": "valley",
-                "line": {"start": [0.25, 0.5], "end": [0.5, 1.0]},
-                "angle": 180,
-                "layer_select": "top",
-            },
-            {
-                "description": "Fold right edge of top layer to center line",
-                "type": "valley",
-                "line": {"start": [0.75, 0.5], "end": [0.5, 1.0]},
-                "angle": 180,
-                "layer_select": "top",
-            },
-            {
-                "description": "Fold top triangle down over kite flaps (crease only)",
-                "type": "valley",
-                "line": {"start": [0.25, 0.75], "end": [0.75, 0.75]},
-                "angle": 180,
-                "layer_select": "top",
-            },
-            {
-                "description": "Unfold top triangle",
-                "type": "unfold",
-                "line": {"start": [0.25, 0.75], "end": [0.75, 0.75]},
-                "angle": 0,
-                "layer_select": "top",
-            },
-            {
-                "description": "Unfold kite folds",
-                "type": "unfold",
-                "line": {"start": [0.25, 0.5], "end": [0.5, 1.0]},
-                "angle": 0,
-                "layer_select": "top",
-            },
-            {
-                "description": "Petal fold front: lift bottom point up, sides collapse inward",
-                "type": "petal",
-                "line": {"start": [0.5, 0.5], "end": [0.5, 1.0]},
-                "angle": 180,
-                "layer_select": "top",
-            },
-            {
-                "description": "Turn model over",
-                "type": "turn_over",
-                "line": {"start": [0.5, 0.0], "end": [0.5, 1.0]},
-                "angle": 0,
-                "layer_select": "all",
-            },
-            {
-                "description": "Fold left edge to center line (back)",
-                "type": "valley",
-                "line": {"start": [0.25, 0.5], "end": [0.5, 1.0]},
-                "angle": 180,
-                "layer_select": "top",
-            },
-            {
-                "description": "Fold right edge to center line (back)",
-                "type": "valley",
-                "line": {"start": [0.75, 0.5], "end": [0.5, 1.0]},
-                "angle": 180,
-                "layer_select": "top",
-            },
-            {
-                "description": "Fold top triangle down (crease only, back)",
-                "type": "valley",
-                "line": {"start": [0.25, 0.75], "end": [0.75, 0.75]},
-                "angle": 180,
-                "layer_select": "top",
-            },
-            {
-                "description": "Unfold top triangle (back)",
-                "type": "unfold",
-                "line": {"start": [0.25, 0.75], "end": [0.75, 0.75]},
-                "angle": 0,
-                "layer_select": "top",
-            },
-            {
-                "description": "Unfold kite folds (back)",
-                "type": "unfold",
-                "line": {"start": [0.25, 0.5], "end": [0.5, 1.0]},
-                "angle": 0,
-                "layer_select": "top",
-            },
-            {
-                "description": "Petal fold back: lift bottom point up, sides collapse inward",
-                "type": "petal",
-                "line": {"start": [0.5, 0.5], "end": [0.5, 1.0]},
-                "angle": 180,
-                "layer_select": "top",
-            },
-        ],
-    },
-
-    "frog_base": {
-        "name": "Frog Base",
-        "description": "4 long narrow flaps radiating from center. Built from preliminary base + 4 squash + 4 petal folds.",
-        "requires_base": "preliminary_base",
-        "total_steps": 8,
-        "steps": [
-            {
-                "description": "Squash fold front-left flap",
-                "type": "squash",
-                "line": {"start": [0.25, 0.5], "end": [0.5, 0.75]},
-                "angle": 180,
-                "layer_select": "top",
-            },
-            {
-                "description": "Squash fold front-right flap",
-                "type": "squash",
-                "line": {"start": [0.75, 0.5], "end": [0.5, 0.75]},
-                "angle": 180,
-                "layer_select": "top",
-            },
-            {
-                "description": "Squash fold back-left flap",
-                "type": "squash",
-                "line": {"start": [0.25, 0.5], "end": [0.5, 0.75]},
-                "angle": 180,
-                "layer_select": "top",
-            },
-            {
-                "description": "Squash fold back-right flap",
-                "type": "squash",
-                "line": {"start": [0.75, 0.5], "end": [0.5, 0.75]},
-                "angle": 180,
-                "layer_select": "top",
-            },
-            {
-                "description": "Petal fold first diamond",
-                "type": "petal",
-                "line": {"start": [0.5, 0.5], "end": [0.5, 1.0]},
-                "angle": 180,
-                "layer_select": "top",
-            },
-            {
-                "description": "Petal fold second diamond",
-                "type": "petal",
-                "line": {"start": [0.5, 0.5], "end": [0.5, 1.0]},
-                "angle": 180,
-                "layer_select": "top",
-            },
-            {
-                "description": "Petal fold third diamond",
-                "type": "petal",
-                "line": {"start": [0.5, 0.5], "end": [0.5, 1.0]},
-                "angle": 180,
-                "layer_select": "top",
-            },
-            {
-                "description": "Petal fold fourth diamond",
-                "type": "petal",
-                "line": {"start": [0.5, 0.5], "end": [0.5, 1.0]},
-                "angle": 180,
-                "layer_select": "top",
-            },
-        ],
-    },
-
-    "fish_base": {
-        "name": "Fish Base",
-        "description": "Diamond shape with 4 points. Built from kite folds + rabbit ears.",
-        "total_steps": 7,
-        "steps": [
-            {
-                "description": "Fold diagonal crease (reference line)",
-                "type": "valley",
-                "line": {"start": [0.0, 0.0], "end": [1.0, 1.0]},
-                "angle": 180,
-                "layer_select": "all",
-            },
-            {
-                "description": "Unfold diagonal",
-                "type": "unfold",
-                "line": {"start": [0.0, 0.0], "end": [1.0, 1.0]},
-                "angle": 0,
-                "layer_select": "all",
-            },
-            {
-                "description": "Kite fold: fold bottom-left edge to diagonal",
-                "type": "valley",
-                "line": {"start": [0.0, 0.0], "end": [0.5, 0.5]},
-                "angle": 180,
-                "layer_select": "all",
-            },
-            {
-                "description": "Kite fold: fold top-left edge to diagonal",
-                "type": "valley",
-                "line": {"start": [0.0, 1.0], "end": [0.5, 0.5]},
-                "angle": 180,
-                "layer_select": "all",
-            },
-            {
-                "description": "Rabbit ear fold on bottom-right corner",
-                "type": "rabbit_ear",
-                "line": {"start": [0.5, 0.0], "end": [1.0, 0.5]},
-                "angle": 180,
-                "layer_select": "all",
-            },
-            {
-                "description": "Rabbit ear fold on top-right corner",
-                "type": "rabbit_ear",
-                "line": {"start": [0.5, 1.0], "end": [1.0, 0.5]},
-                "angle": 180,
-                "layer_select": "all",
-            },
-            {
-                "description": "Fold resulting flaps down flat",
-                "type": "valley",
-                "line": {"start": [0.5, 0.5], "end": [1.0, 0.5]},
-                "angle": 180,
-                "layer_select": "top",
-            },
-        ],
-    },
-
-    "kite_base": {
-        "name": "Kite Base",
-        "description": "Simplest base: a kite shape from two folds to a diagonal.",
-        "total_steps": 3,
-        "steps": [
-            {
-                "description": "Fold diagonal (reference crease)",
-                "type": "valley",
-                "line": {"start": [0.0, 0.0], "end": [1.0, 1.0]},
-                "angle": 180,
-                "layer_select": "all",
-            },
-            {
-                "description": "Unfold diagonal",
-                "type": "unfold",
-                "line": {"start": [0.0, 0.0], "end": [1.0, 1.0]},
-                "angle": 0,
-                "layer_select": "all",
-            },
-            {
-                "description": "Fold bottom-left and top-left edges to lie on diagonal",
-                "type": "valley",
-                "line": {"start": [0.0, 0.0], "end": [0.5, 0.5]},
-                "angle": 180,
-                "layer_select": "all",
-            },
-        ],
-    },
-}
-
-
-# ---------------------------------------------------------------------------
-# Complete origami models — full fold sequences from flat square to finished
-# ---------------------------------------------------------------------------
-
-ORIGAMI_MODELS = {
-    "crane": {
-        "name": "Paper Crane (Tsuru)",
-        "difficulty": "intermediate",
-        "base": "bird_base",
-        "total_steps": 31,
-        "description": "The traditional Japanese crane. 31 steps from flat square.",
-        "steps": [
-            # Phase 1: Pre-crease (steps 1-8)
-            {"step": 1, "description": "Fold square in half diagonally (bottom-left to top-right)", "type": "valley", "line": {"start": [0.0, 0.0], "end": [1.0, 1.0]}, "angle": 180, "layer_select": "all"},
-            {"step": 2, "description": "Unfold", "type": "unfold", "line": {"start": [0.0, 0.0], "end": [1.0, 1.0]}, "angle": 0, "layer_select": "all"},
-            {"step": 3, "description": "Fold in half on other diagonal", "type": "valley", "line": {"start": [1.0, 0.0], "end": [0.0, 1.0]}, "angle": 180, "layer_select": "all"},
-            {"step": 4, "description": "Unfold", "type": "unfold", "line": {"start": [1.0, 0.0], "end": [0.0, 1.0]}, "angle": 0, "layer_select": "all"},
-            {"step": 5, "description": "Fold in half horizontally", "type": "valley", "line": {"start": [0.0, 0.5], "end": [1.0, 0.5]}, "angle": 180, "layer_select": "all"},
-            {"step": 6, "description": "Unfold", "type": "unfold", "line": {"start": [0.0, 0.5], "end": [1.0, 0.5]}, "angle": 0, "layer_select": "all"},
-            {"step": 7, "description": "Fold in half vertically", "type": "valley", "line": {"start": [0.5, 0.0], "end": [0.5, 1.0]}, "angle": 180, "layer_select": "all"},
-            {"step": 8, "description": "Unfold", "type": "unfold", "line": {"start": [0.5, 0.0], "end": [0.5, 1.0]}, "angle": 0, "layer_select": "all"},
-
-            # Phase 2: Collapse into preliminary base (step 9)
-            {"step": 9, "description": "Collapse into preliminary base: push left and right edges inward, fold top down", "type": "valley", "line": {"start": [0.0, 0.0], "end": [1.0, 1.0]}, "angle": 180, "layer_select": "all"},
-
-            # Phase 3: Front kite folds (steps 10-14)
-            {"step": 10, "description": "Fold left edge of top layer to center line", "type": "valley", "line": {"start": [0.25, 0.5], "end": [0.5, 1.0]}, "angle": 180, "layer_select": "top"},
-            {"step": 11, "description": "Fold right edge of top layer to center line", "type": "valley", "line": {"start": [0.75, 0.5], "end": [0.5, 1.0]}, "angle": 180, "layer_select": "top"},
-            {"step": 12, "description": "Fold top triangle down over kite flaps", "type": "valley", "line": {"start": [0.25, 0.75], "end": [0.75, 0.75]}, "angle": 180, "layer_select": "top"},
-            {"step": 13, "description": "Unfold step 12", "type": "unfold", "line": {"start": [0.25, 0.75], "end": [0.75, 0.75]}, "angle": 0, "layer_select": "top"},
-            {"step": 14, "description": "Unfold steps 10-11", "type": "unfold", "line": {"start": [0.25, 0.5], "end": [0.5, 1.0]}, "angle": 0, "layer_select": "top"},
-
-            # Phase 4: Front petal fold (step 15)
-            {"step": 15, "description": "Petal fold: lift bottom point of top layer upward, sides collapse inward", "type": "petal", "line": {"start": [0.5, 0.5], "end": [0.5, 1.0]}, "angle": 180, "layer_select": "top"},
-
-            # Phase 5: Repeat on back (steps 16-22)
-            {"step": 16, "description": "Turn model over", "type": "turn_over", "line": {"start": [0.5, 0.0], "end": [0.5, 1.0]}, "angle": 0, "layer_select": "all"},
-            {"step": 17, "description": "Fold left edge to center line", "type": "valley", "line": {"start": [0.25, 0.5], "end": [0.5, 1.0]}, "angle": 180, "layer_select": "top"},
-            {"step": 18, "description": "Fold right edge to center line", "type": "valley", "line": {"start": [0.75, 0.5], "end": [0.5, 1.0]}, "angle": 180, "layer_select": "top"},
-            {"step": 19, "description": "Fold top triangle down", "type": "valley", "line": {"start": [0.25, 0.75], "end": [0.75, 0.75]}, "angle": 180, "layer_select": "top"},
-            {"step": 20, "description": "Unfold step 19", "type": "unfold", "line": {"start": [0.25, 0.75], "end": [0.75, 0.75]}, "angle": 0, "layer_select": "top"},
-            {"step": 21, "description": "Unfold steps 17-18", "type": "unfold", "line": {"start": [0.25, 0.5], "end": [0.5, 1.0]}, "angle": 0, "layer_select": "top"},
-            {"step": 22, "description": "Petal fold back: lift bottom point up, collapse sides in. Bird base complete.", "type": "petal", "line": {"start": [0.5, 0.5], "end": [0.5, 1.0]}, "angle": 180, "layer_select": "top"},
-
-            # Phase 6: Narrow the legs (steps 23-27)
-            {"step": 23, "description": "Fold left flap (front) edge to center", "type": "valley", "line": {"start": [0.375, 0.5], "end": [0.5, 1.0]}, "angle": 180, "layer_select": "top"},
-            {"step": 24, "description": "Fold right flap (front) edge to center", "type": "valley", "line": {"start": [0.625, 0.5], "end": [0.5, 1.0]}, "angle": 180, "layer_select": "top"},
-            {"step": 25, "description": "Turn over", "type": "turn_over", "line": {"start": [0.5, 0.0], "end": [0.5, 1.0]}, "angle": 0, "layer_select": "all"},
-            {"step": 26, "description": "Fold left flap (back) edge to center", "type": "valley", "line": {"start": [0.375, 0.5], "end": [0.5, 1.0]}, "angle": 180, "layer_select": "top"},
-            {"step": 27, "description": "Fold right flap (back) edge to center", "type": "valley", "line": {"start": [0.625, 0.5], "end": [0.5, 1.0]}, "angle": 180, "layer_select": "top"},
-
-            # Phase 7: Form neck and tail (steps 28-29)
-            {"step": 28, "description": "Inside reverse fold left flap upward to form neck", "type": "reverse_inside", "line": {"start": [0.35, 0.6], "end": [0.45, 0.85]}, "angle": 150, "layer_select": "all"},
-            {"step": 29, "description": "Inside reverse fold right flap upward to form tail", "type": "reverse_inside", "line": {"start": [0.55, 0.6], "end": [0.65, 0.85]}, "angle": 150, "layer_select": "all"},
-
-            # Phase 8: Head and finish (steps 30-31)
-            {"step": 30, "description": "Inside reverse fold tip of neck downward to form head/beak", "type": "reverse_inside", "line": {"start": [0.38, 0.82], "end": [0.42, 0.9]}, "angle": 150, "layer_select": "all"},
-            {"step": 31, "description": "Pull wings apart gently and press bottom to inflate body", "type": "inflate", "line": {"start": [0.5, 0.5], "end": [0.5, 0.7]}, "angle": 0, "layer_select": "all"},
-        ],
-    },
-
-    "boat": {
-        "name": "Simple Boat",
-        "difficulty": "simple",
-        "base": None,
-        "total_steps": 9,
-        "description": "A flat boat/hat from simple valley and mountain folds.",
-        "steps": [
-            {"step": 1, "description": "Fold in half horizontally (top to bottom)", "type": "valley", "line": {"start": [0.0, 0.5], "end": [1.0, 0.5]}, "angle": 180, "layer_select": "all"},
-            {"step": 2, "description": "Fold in half vertically (crease only)", "type": "valley", "line": {"start": [0.5, 0.0], "end": [0.5, 0.5]}, "angle": 180, "layer_select": "all"},
-            {"step": 3, "description": "Unfold vertical", "type": "unfold", "line": {"start": [0.5, 0.0], "end": [0.5, 0.5]}, "angle": 0, "layer_select": "all"},
-            {"step": 4, "description": "Fold top-left corner down to center mark", "type": "valley", "line": {"start": [0.15, 0.5], "end": [0.5, 0.35]}, "angle": 180, "layer_select": "top"},
-            {"step": 5, "description": "Fold top-right corner down to center mark", "type": "valley", "line": {"start": [0.85, 0.5], "end": [0.5, 0.35]}, "angle": 180, "layer_select": "top"},
-            {"step": 6, "description": "Fold bottom strip up (front layer)", "type": "valley", "line": {"start": [0.0, 0.15], "end": [1.0, 0.15]}, "angle": 180, "layer_select": "top"},
-            {"step": 7, "description": "Turn over", "type": "turn_over", "line": {"start": [0.5, 0.0], "end": [0.5, 0.5]}, "angle": 0, "layer_select": "all"},
-            {"step": 8, "description": "Fold bottom strip up (back layer)", "type": "valley", "line": {"start": [0.0, 0.15], "end": [1.0, 0.15]}, "angle": 180, "layer_select": "top"},
-            {"step": 9, "description": "Open from bottom and flatten into boat shape", "type": "inflate", "line": {"start": [0.5, 0.0], "end": [0.5, 0.5]}, "angle": 0, "layer_select": "all"},
-        ],
-    },
-
-    "airplane": {
-        "name": "Paper Airplane (Dart)",
-        "difficulty": "simple",
-        "base": None,
-        "total_steps": 6,
-        "description": "Classic dart-style paper airplane using only valley folds.",
-        "steps": [
-            {"step": 1, "description": "Fold in half vertically (left to right)", "type": "valley", "line": {"start": [0.5, 0.0], "end": [0.5, 1.0]}, "angle": 180, "layer_select": "all"},
-            {"step": 2, "description": "Unfold", "type": "unfold", "line": {"start": [0.5, 0.0], "end": [0.5, 1.0]}, "angle": 0, "layer_select": "all"},
-            {"step": 3, "description": "Fold top-left corner to center line", "type": "valley", "line": {"start": [0.0, 1.0], "end": [0.5, 0.7]}, "angle": 180, "layer_select": "all"},
-            {"step": 4, "description": "Fold top-right corner to center line", "type": "valley", "line": {"start": [1.0, 1.0], "end": [0.5, 0.7]}, "angle": 180, "layer_select": "all"},
-            {"step": 5, "description": "Fold left angled edge to center line", "type": "valley", "line": {"start": [0.0, 0.7], "end": [0.5, 0.4]}, "angle": 180, "layer_select": "all"},
-            {"step": 6, "description": "Fold right angled edge to center line", "type": "valley", "line": {"start": [1.0, 0.7], "end": [0.5, 0.4]}, "angle": 180, "layer_select": "all"},
-        ],
-    },
-
-    "box": {
-        "name": "Masu Box (Open-Top Box)",
-        "difficulty": "low_intermediate",
-        "base": None,
-        "total_steps": 13,
-        "description": "An open-top box. Uses preliminary base concept with tuck folds.",
-        "steps": [
-            {"step": 1, "description": "Fold in half horizontally", "type": "valley", "line": {"start": [0.0, 0.5], "end": [1.0, 0.5]}, "angle": 180, "layer_select": "all"},
-            {"step": 2, "description": "Unfold", "type": "unfold", "line": {"start": [0.0, 0.5], "end": [1.0, 0.5]}, "angle": 0, "layer_select": "all"},
-            {"step": 3, "description": "Fold in half vertically", "type": "valley", "line": {"start": [0.5, 0.0], "end": [0.5, 1.0]}, "angle": 180, "layer_select": "all"},
-            {"step": 4, "description": "Unfold", "type": "unfold", "line": {"start": [0.5, 0.0], "end": [0.5, 1.0]}, "angle": 0, "layer_select": "all"},
-            {"step": 5, "description": "Fold all four corners to center", "type": "valley", "line": {"start": [0.0, 0.0], "end": [0.5, 0.5]}, "angle": 180, "layer_select": "all"},
-            {"step": 6, "description": "Fold bottom-right corner to center", "type": "valley", "line": {"start": [1.0, 0.0], "end": [0.5, 0.5]}, "angle": 180, "layer_select": "all"},
-            {"step": 7, "description": "Fold top-left corner to center", "type": "valley", "line": {"start": [0.0, 1.0], "end": [0.5, 0.5]}, "angle": 180, "layer_select": "all"},
-            {"step": 8, "description": "Fold top-right corner to center", "type": "valley", "line": {"start": [1.0, 1.0], "end": [0.5, 0.5]}, "angle": 180, "layer_select": "all"},
-            {"step": 9, "description": "Fold top third down to center", "type": "valley", "line": {"start": [0.0, 0.667], "end": [1.0, 0.667]}, "angle": 180, "layer_select": "all"},
-            {"step": 10, "description": "Fold bottom third up to center", "type": "valley", "line": {"start": [0.0, 0.333], "end": [1.0, 0.333]}, "angle": 180, "layer_select": "all"},
-            {"step": 11, "description": "Unfold top and bottom, and unfold left/right corners", "type": "unfold", "line": {"start": [0.0, 0.333], "end": [1.0, 0.333]}, "angle": 0, "layer_select": "all"},
-            {"step": 12, "description": "Raise left and right walls using existing creases, tuck corners in", "type": "valley", "line": {"start": [0.25, 0.0], "end": [0.25, 1.0]}, "angle": 90, "layer_select": "all"},
-            {"step": 13, "description": "Fold flaps over into box and lock walls in place", "type": "valley", "line": {"start": [0.0, 0.5], "end": [1.0, 0.5]}, "angle": 90, "layer_select": "top"},
-        ],
-    },
-
-    "fortune_teller": {
-        "name": "Fortune Teller (Cootie Catcher)",
-        "difficulty": "simple",
-        "base": None,
-        "total_steps": 8,
-        "description": "Classic fortune teller: fold corners to center, flip, repeat.",
-        "steps": [
-            {"step": 1, "description": "Fold in half diagonally (crease only)", "type": "valley", "line": {"start": [0.0, 0.0], "end": [1.0, 1.0]}, "angle": 180, "layer_select": "all"},
-            {"step": 2, "description": "Unfold", "type": "unfold", "line": {"start": [0.0, 0.0], "end": [1.0, 1.0]}, "angle": 0, "layer_select": "all"},
-            {"step": 3, "description": "Fold bottom-left corner to center", "type": "valley", "line": {"start": [0.0, 0.0], "end": [0.5, 0.5]}, "angle": 180, "layer_select": "all"},
-            {"step": 4, "description": "Fold bottom-right corner to center", "type": "valley", "line": {"start": [1.0, 0.0], "end": [0.5, 0.5]}, "angle": 180, "layer_select": "all"},
-            {"step": 5, "description": "Fold top-left corner to center", "type": "valley", "line": {"start": [0.0, 1.0], "end": [0.5, 0.5]}, "angle": 180, "layer_select": "all"},
-            {"step": 6, "description": "Fold top-right corner to center", "type": "valley", "line": {"start": [1.0, 1.0], "end": [0.5, 0.5]}, "angle": 180, "layer_select": "all"},
-            {"step": 7, "description": "Turn over", "type": "turn_over", "line": {"start": [0.5, 0.0], "end": [0.5, 1.0]}, "angle": 0, "layer_select": "all"},
-            {"step": 8, "description": "Fold all four new corners to center again", "type": "valley", "line": {"start": [0.25, 0.25], "end": [0.5, 0.5]}, "angle": 180, "layer_select": "all"},
-        ],
-    },
-
-    "waterbomb": {
-        "name": "Waterbomb (Paper Balloon)",
-        "difficulty": "simple",
-        "base": "waterbomb_base",
-        "total_steps": 12,
-        "description": "Inflatable paper balloon built on the waterbomb base.",
-        "steps": [
-            # Phase 1: Waterbomb base (steps 1-9 same as waterbomb_base)
-            {"step": 1, "description": "Fold first diagonal", "type": "valley", "line": {"start": [0.0, 0.0], "end": [1.0, 1.0]}, "angle": 180, "layer_select": "all"},
-            {"step": 2, "description": "Unfold", "type": "unfold", "line": {"start": [0.0, 0.0], "end": [1.0, 1.0]}, "angle": 0, "layer_select": "all"},
-            {"step": 3, "description": "Fold second diagonal", "type": "valley", "line": {"start": [1.0, 0.0], "end": [0.0, 1.0]}, "angle": 180, "layer_select": "all"},
-            {"step": 4, "description": "Unfold", "type": "unfold", "line": {"start": [1.0, 0.0], "end": [0.0, 1.0]}, "angle": 0, "layer_select": "all"},
-            {"step": 5, "description": "Fold in half horizontally", "type": "valley", "line": {"start": [0.0, 0.5], "end": [1.0, 0.5]}, "angle": 180, "layer_select": "all"},
-            {"step": 6, "description": "Collapse into waterbomb base (triangle)", "type": "valley", "line": {"start": [0.0, 0.0], "end": [1.0, 1.0]}, "angle": 180, "layer_select": "all"},
-            # Phase 2: Fold flaps to top
-            {"step": 7, "description": "Fold bottom-left corner of front layer up to top", "type": "valley", "line": {"start": [0.0, 0.0], "end": [0.5, 0.5]}, "angle": 180, "layer_select": "top"},
-            {"step": 8, "description": "Fold bottom-right corner of front layer up to top", "type": "valley", "line": {"start": [1.0, 0.0], "end": [0.5, 0.5]}, "angle": 180, "layer_select": "top"},
-            # Phase 3: Tuck flaps
-            {"step": 9, "description": "Fold left and right points to center", "type": "valley", "line": {"start": [0.25, 0.25], "end": [0.5, 0.5]}, "angle": 180, "layer_select": "top"},
-            {"step": 10, "description": "Tuck small triangles into pockets", "type": "valley", "line": {"start": [0.35, 0.4], "end": [0.5, 0.5]}, "angle": 180, "layer_select": "top"},
-            {"step": 11, "description": "Repeat steps 7-10 on back", "type": "valley", "line": {"start": [0.0, 0.0], "end": [0.5, 0.5]}, "angle": 180, "layer_select": "top"},
-            # Phase 4: Inflate
-            {"step": 12, "description": "Blow into hole at bottom to inflate into cube/sphere", "type": "inflate", "line": {"start": [0.5, 0.0], "end": [0.5, 0.5]}, "angle": 0, "layer_select": "all"},
-        ],
-    },
-
-    "jumping_frog": {
-        "name": "Jumping Frog",
-        "difficulty": "low_intermediate",
-        "base": None,
-        "total_steps": 15,
-        "description": "A frog that jumps when you press its back. Uses pleats for the spring.",
-        "steps": [
-            {"step": 1, "description": "Fold in half horizontally", "type": "valley", "line": {"start": [0.0, 0.5], "end": [1.0, 0.5]}, "angle": 180, "layer_select": "all"},
-            {"step": 2, "description": "Fold top-left corner to right edge", "type": "valley", "line": {"start": [0.0, 1.0], "end": [1.0, 0.75]}, "angle": 180, "layer_select": "all"},
-            {"step": 3, "description": "Unfold", "type": "unfold", "line": {"start": [0.0, 1.0], "end": [1.0, 0.75]}, "angle": 0, "layer_select": "all"},
-            {"step": 4, "description": "Fold top-right corner to left edge", "type": "valley", "line": {"start": [1.0, 1.0], "end": [0.0, 0.75]}, "angle": 180, "layer_select": "all"},
-            {"step": 5, "description": "Unfold", "type": "unfold", "line": {"start": [1.0, 1.0], "end": [0.0, 0.75]}, "angle": 0, "layer_select": "all"},
-            {"step": 6, "description": "Collapse top into waterbomb-like triangle", "type": "valley", "line": {"start": [0.0, 0.75], "end": [1.0, 0.75]}, "angle": 180, "layer_select": "all"},
-            {"step": 7, "description": "Fold left point of triangle up and outward for front leg", "type": "valley", "line": {"start": [0.25, 0.75], "end": [0.5, 1.0]}, "angle": 180, "layer_select": "top"},
-            {"step": 8, "description": "Fold right point of triangle up and outward for front leg", "type": "valley", "line": {"start": [0.75, 0.75], "end": [0.5, 1.0]}, "angle": 180, "layer_select": "top"},
-            {"step": 9, "description": "Fold bottom half up to meet triangle base", "type": "valley", "line": {"start": [0.0, 0.375], "end": [1.0, 0.375]}, "angle": 180, "layer_select": "all"},
-            {"step": 10, "description": "Fold left side to center", "type": "valley", "line": {"start": [0.25, 0.0], "end": [0.25, 0.75]}, "angle": 180, "layer_select": "all"},
-            {"step": 11, "description": "Fold right side to center", "type": "valley", "line": {"start": [0.75, 0.0], "end": [0.75, 0.75]}, "angle": 180, "layer_select": "all"},
-            {"step": 12, "description": "Fold bottom up", "type": "valley", "line": {"start": [0.25, 0.25], "end": [0.75, 0.25]}, "angle": 180, "layer_select": "all"},
-            {"step": 13, "description": "Pull back legs out to sides", "type": "valley", "line": {"start": [0.375, 0.0], "end": [0.375, 0.375]}, "angle": 180, "layer_select": "top"},
-            {"step": 14, "description": "Pleat fold for spring: fold bottom half down", "type": "mountain", "line": {"start": [0.25, 0.15], "end": [0.75, 0.15]}, "angle": 180, "layer_select": "all"},
-            {"step": 15, "description": "Valley fold bottom portion back up for spring action", "type": "valley", "line": {"start": [0.25, 0.08], "end": [0.75, 0.08]}, "angle": 180, "layer_select": "all"},
-        ],
-    },
-}
-
-
-# ---------------------------------------------------------------------------
-# Helpers
-# ---------------------------------------------------------------------------
-
-def get_base_steps(base_name: str) -> list[dict]:
-    """Return the fold steps for a given base, or empty list if not found."""
-    base = ORIGAMI_BASES.get(base_name)
-    if base is None:
-        return []
-    return list(base["steps"])
-
-
-def get_model_steps(model_name: str) -> list[dict]:
-    """Return the full fold steps for a known model, or empty list."""
-    model = ORIGAMI_MODELS.get(model_name)
-    if model is None:
-        return []
-    return list(model["steps"])
-
-
-def list_known_models() -> list[str]:
-    """Return names of all known origami models."""
-    return list(ORIGAMI_MODELS.keys())
-
-
-def list_known_bases() -> list[str]:
-    """Return names of all known origami bases."""
-    return list(ORIGAMI_BASES.keys())
-
-
-def get_fold_operation(name: str) -> dict | None:
-    """Look up a fold operation by name."""
-    return FOLD_OPERATIONS.get(name)

planner/parser.py

@@ -1,291 +0,0 @@
-"""
-Instruction parser: converts human text into a structured origami task.
-
-Handles variations like:
-  - "make a paper crane"
-  - "fold me a crane"
-  - "i want to make a paper crane"
-  - "crane please"
-  - "can you fold a crane?"
-  - "pack a 1m x 1m mylar sheet as compact as possible"
-"""
-
-from __future__ import annotations
-
-import re
-from planner.knowledge import ORIGAMI_MODELS, list_known_models
-
-
-# ---------------------------------------------------------------------------
-# Vocabulary for matching
-# ---------------------------------------------------------------------------
-
-# Model aliases → canonical name
-_MODEL_ALIASES: dict[str, str] = {
-    # Crane
-    "crane": "crane",
-    "tsuru": "crane",
-    "bird": "crane",
-    "orizuru": "crane",
-    # Boat
-    "boat": "boat",
-    "hat": "boat",
-    "paper boat": "boat",
-    "paper hat": "boat",
-    # Airplane
-    "airplane": "airplane",
-    "aeroplane": "airplane",
-    "plane": "airplane",
-    "paper airplane": "airplane",
-    "paper plane": "airplane",
-    "dart": "airplane",
-    "paper dart": "airplane",
-    # Box
-    "box": "box",
-    "masu": "box",
-    "masu box": "box",
-    "open box": "box",
-    # Fortune teller
-    "fortune teller": "fortune_teller",
-    "fortune-teller": "fortune_teller",
-    "cootie catcher": "fortune_teller",
-    "cootie-catcher": "fortune_teller",
-    "chatterbox": "fortune_teller",
-    # Waterbomb / balloon
-    "waterbomb": "waterbomb",
-    "water bomb": "waterbomb",
-    "balloon": "waterbomb",
-    "paper balloon": "waterbomb",
-    # Jumping frog
-    "jumping frog": "jumping_frog",
-    "frog": "jumping_frog",
-    "leap frog": "jumping_frog",
-}
-
-# Sorted longest-first so multi-word aliases match before single-word ones
-_ALIAS_KEYS_SORTED = sorted(_MODEL_ALIASES.keys(), key=len, reverse=True)
-
-_MATERIALS = {
-    "paper": "paper",
-    "mylar": "mylar",
-    "aluminum": "aluminum",
-    "aluminium": "aluminum",
-    "metal": "metal",
-    "nitinol": "nitinol",
-    "foil": "aluminum",
-    "cardboard": "cardboard",
-    "cardstock": "cardstock",
-    "fabric": "fabric",
-    "cloth": "fabric",
-}
-
-# Intent keywords
-_FOLD_VERBS = {
-    "make", "fold", "create", "build", "construct", "origami",
-    "craft", "form", "shape", "assemble",
-}
-_PACK_VERBS = {
-    "pack", "compress", "compact", "minimize", "reduce", "stow",
-    "shrink", "deploy", "collapse",
-}
-_OPTIMIZE_PHRASES = [
-    "as compact as possible",
-    "minimize volume",
-    "minimize packed volume",
-    "minimize area",
-    "solar panel",
-    "stent",
-    "deployable",
-    "maximize compactness",
-    "flatten",
-]
-
-# Dimension patterns
-_DIM_PATTERNS = [
-    # "10cm x 10cm", "10 cm x 10 cm"
-    re.compile(
-        r"(\d+(?:\.\d+)?)\s*(cm|mm|m|in|inch|inches|ft|feet)\s*[xX\u00d7]\s*(\d+(?:\.\d+)?)\s*(cm|mm|m|in|inch|inches|ft|feet)",
-        re.IGNORECASE,
-    ),
-    # "10cm square", "1 meter square"
-    re.compile(
-        r"(\d+(?:\.\d+)?)\s*(cm|mm|m|in|inch|inches|ft|feet|meter|meters|metre|metres)\s+square",
-        re.IGNORECASE,
-    ),
-]
-
-_UNIT_TO_M = {
-    "m": 1.0,
-    "meter": 1.0,
-    "meters": 1.0,
-    "metre": 1.0,
-    "metres": 1.0,
-    "cm": 0.01,
-    "mm": 0.001,
-    "in": 0.0254,
-    "inch": 0.0254,
-    "inches": 0.0254,
-    "ft": 0.3048,
-    "feet": 0.3048,
-}
-
-
-# ---------------------------------------------------------------------------
-# Parsing helpers
-# ---------------------------------------------------------------------------
-
-def _normalise(text: str) -> str:
-    """Lower-case and strip extra whitespace."""
-    return " ".join(text.lower().split())
-
-
-def _detect_model(text: str) -> str | None:
-    """Return canonical model name if one is mentioned, else None."""
-    norm = _normalise(text)
-
-    # Strip out constraint phrases that might contain model-name false positives
-    # e.g. "into a 15cm x 15cm x 5cm box" should not match "box" as a model
-    cleaned = re.sub(
-        r"(?:fit\s+)?(?:in(?:to)?|inside)\s+(?:a\s+)?\d.*?box",
-        "",
-        norm,
-    )
-
-    for alias in _ALIAS_KEYS_SORTED:
-        # Use word-boundary-aware search to avoid partial matches
-        pattern = r"(?:^|\b)" + re.escape(alias) + r"(?:\b|$)"
-        if re.search(pattern, cleaned):
-            return _MODEL_ALIASES[alias]
-    return None
-
-
-def _detect_material(text: str) -> str:
-    """Return detected material or default 'paper'."""
-    norm = _normalise(text)
-    # Check multi-word materials first (none currently, but future-proof)
-    for keyword, canonical in sorted(_MATERIALS.items(), key=lambda kv: -len(kv[0])):
-        if keyword in norm:
-            return canonical
-    return "paper"
-
-
-def _detect_dimensions(text: str) -> dict[str, float]:
-    """Parse explicit dimensions. Returns {"width": m, "height": m} or defaults."""
-    for pat in _DIM_PATTERNS:
-        m = pat.search(text)
-        if m:
-            groups = m.groups()
-            if len(groups) == 4:
-                # WxH pattern
-                w = float(groups[0]) * _UNIT_TO_M.get(groups[1].lower(), 1.0)
-                h = float(groups[2]) * _UNIT_TO_M.get(groups[3].lower(), 1.0)
-                return {"width": round(w, 6), "height": round(h, 6)}
-            elif len(groups) == 2:
-                # "N unit square"
-                side = float(groups[0]) * _UNIT_TO_M.get(groups[1].lower(), 1.0)
-                return {"width": round(side, 6), "height": round(side, 6)}
-    # Default: unit square
-    return {"width": 1.0, "height": 1.0}
-
-
-def _detect_constraints(text: str) -> dict:
-    """Detect any explicit constraints mentioned in the instruction."""
-    norm = _normalise(text)
-    constraints: dict = {}
-
-    # Target bounding box: "fit in a 15cm x 15cm x 5cm box"
-    box_pat = re.compile(
-        r"fit\s+(?:in(?:to)?|inside)\s+(?:a\s+)?(\d+(?:\.\d+)?)\s*(cm|mm|m)\s*[xX\u00d7]\s*"
-        r"(\d+(?:\.\d+)?)\s*(cm|mm|m)\s*[xX\u00d7]\s*(\d+(?:\.\d+)?)\s*(cm|mm|m)",
-        re.IGNORECASE,
-    )
-    bm = box_pat.search(norm)
-    if bm:
-        g = bm.groups()
-        constraints["target_box"] = [
-            float(g[0]) * _UNIT_TO_M.get(g[1], 1.0),
-            float(g[2]) * _UNIT_TO_M.get(g[3], 1.0),
-            float(g[4]) * _UNIT_TO_M.get(g[5], 1.0),
-        ]
-
-    # Max folds
-    folds_pat = re.compile(r"(?:max(?:imum)?|at most|no more than)\s+(\d+)\s+fold", re.IGNORECASE)
-    fm = folds_pat.search(norm)
-    if fm:
-        constraints["max_folds"] = int(fm.group(1))
-
-    # Compactness emphasis
-    for phrase in _OPTIMIZE_PHRASES:
-        if phrase in norm:
-            constraints["optimize_compactness"] = True
-            break
-
-    # Must deploy
-    if "deploy" in norm or "unfold" in norm and "clean" in norm:
-        constraints["must_deploy"] = True
-
-    return constraints
-
-
-def _detect_intent(text: str, model_name: str | None, constraints: dict) -> str:
-    """Determine the high-level intent of the instruction."""
-    norm = _normalise(text)
-    words = set(norm.split())
-
-    # If packing / optimization phrases are present, it's an optimization task
-    if constraints.get("optimize_compactness"):
-        return "optimize_packing"
-    if words & _PACK_VERBS:
-        return "optimize_packing"
-
-    # If a known model is detected, it's a fold_model task
-    if model_name is not None:
-        return "fold_model"
-
-    # If fold verbs are present but no model, it's a free fold
-    if words & _FOLD_VERBS:
-        return "free_fold"
-
-    # Fallback: if there's a pattern keyword
-    pattern_words = {"miura", "tessellation", "pattern", "waterbomb tessellation", "pleat"}
-    if words & pattern_words:
-        return "fold_pattern"
-
-    return "free_fold"
-
-
-# ---------------------------------------------------------------------------
-# Public API
-# ---------------------------------------------------------------------------
-
-def parse_instruction(text: str) -> dict:
-    """
-    Parse a human origami instruction into a structured task.
-
-    Args:
-        text: Natural-language instruction, e.g. "make a paper crane"
-
-    Returns:
-        {
-            "intent": "fold_model" | "fold_pattern" | "optimize_packing" | "free_fold",
-            "model_name": str or None,
-            "material": str,
-            "dimensions": {"width": float, "height": float},
-            "constraints": {...},
-            "raw_instruction": str,
-        }
-    """
-    model_name = _detect_model(text)
-    material = _detect_material(text)
-    dimensions = _detect_dimensions(text)
-    constraints = _detect_constraints(text)
-    intent = _detect_intent(text, model_name, constraints)
-
-    return {
-        "intent": intent,
-        "model_name": model_name,
-        "material": material,
-        "dimensions": dimensions,
-        "constraints": constraints,
-        "raw_instruction": text,
-    }

planner/planner.py

@@ -1,305 +0,0 @@
-"""
-OrigamiPlanner: the main orchestrator that converts human instructions
-into structured fold plans with LLM-ready prompts.
-
-Usage:
-    from planner.planner import OrigamiPlanner
-
-    planner = OrigamiPlanner()
-    plan = planner.plan("make a paper crane")
-    print(plan.summary())
-    prompt = plan.get_prompt_for_step(0)
-"""
-
-from __future__ import annotations
-
-import json
-from dataclasses import dataclass, field
-
-from planner.parser import parse_instruction
-from planner.decomposer import decompose_task
-from planner.knowledge import ORIGAMI_MODELS, FOLD_OPERATIONS
-
-
-# ---------------------------------------------------------------------------
-# Material defaults (mirrors trainer/prompts.py TASK_CONFIGS)
-# ---------------------------------------------------------------------------
-
-_MATERIAL_DEFAULTS = {
-    "paper":     {"thickness_mm": 0.1,  "youngs_modulus_gpa": 2.0,  "max_strain_pct": 3},
-    "mylar":     {"thickness_mm": 0.05, "youngs_modulus_gpa": 4.0,  "max_strain_pct": 3},
-    "aluminum":  {"thickness_mm": 0.02, "youngs_modulus_gpa": 69.0, "max_strain_pct": 1},
-    "metal":     {"thickness_mm": 0.05, "youngs_modulus_gpa": 200.0,"max_strain_pct": 0.5},
-    "nitinol":   {"thickness_mm": 0.1,  "youngs_modulus_gpa": 75.0, "max_strain_pct": 8},
-    "cardboard": {"thickness_mm": 1.0,  "youngs_modulus_gpa": 1.0,  "max_strain_pct": 2},
-    "cardstock": {"thickness_mm": 0.3,  "youngs_modulus_gpa": 1.5,  "max_strain_pct": 2},
-    "fabric":    {"thickness_mm": 0.2,  "youngs_modulus_gpa": 0.1,  "max_strain_pct": 15},
-}
-
-
-# ---------------------------------------------------------------------------
-# FoldPlan dataclass
-# ---------------------------------------------------------------------------
-
-@dataclass
-class FoldPlan:
-    """
-    A complete, executable fold plan produced by OrigamiPlanner.
-
-    Attributes:
-        instruction: The original human instruction.
-        parsed: Structured parse result (intent, model, material, etc.).
-        steps: Ordered list of sub-goal dicts from the decomposer.
-        prompts: Pre-built LLM prompts, one per step.
-    """
-
-    instruction: str
-    parsed: dict
-    steps: list[dict]
-    prompts: list[str]
-
-    # ------------------------------------------------------------------
-    # Summaries
-    # ------------------------------------------------------------------
-
-    def summary(self) -> str:
-        """Human-readable summary of the plan."""
-        lines: list[str] = []
-        lines.append(f"Origami Plan: {self.instruction}")
-        lines.append(f"  Intent : {self.parsed['intent']}")
-        if self.parsed.get("model_name"):
-            model = ORIGAMI_MODELS.get(self.parsed["model_name"], {})
-            lines.append(f"  Model  : {model.get('name', self.parsed['model_name'])}")
-            lines.append(f"  Difficulty: {model.get('difficulty', 'unknown')}")
-        lines.append(f"  Material: {self.parsed['material']}")
-        dims = self.parsed["dimensions"]
-        lines.append(f"  Sheet  : {dims['width']}m x {dims['height']}m")
-        lines.append(f"  Steps  : {len(self.steps)}")
-        lines.append("")
-        lines.append("Step-by-step:")
-        for s in self.steps:
-            n = s["step_number"]
-            desc = s["description"]
-            n_ops = len(s.get("fold_operations", []))
-            lines.append(f"  {n:>3}. {desc}  ({n_ops} fold op{'s' if n_ops != 1 else ''})")
-        return "\n".join(lines)
-
-    # ------------------------------------------------------------------
-    # Prompt access
-    # ------------------------------------------------------------------
-
-    def get_prompt_for_step(self, step_index: int, current_state: dict | None = None) -> str:
-        """
-        Get the LLM prompt for a specific step, optionally enriched with
-        the current paper state from the simulation engine.
-
-        Args:
-            step_index: Zero-based index into self.steps.
-            current_state: Optional live paper_state dict from the engine.
-
-        Returns:
-            A fully-formatted prompt string ready for the LLM.
-        """
-        if step_index < 0 or step_index >= len(self.steps):
-            raise IndexError(f"step_index {step_index} out of range (0..{len(self.steps) - 1})")
-
-        base_prompt = self.prompts[step_index]
-
-        if current_state is None:
-            return base_prompt
-
-        # Inject live state into the prompt
-        state_block = _format_state_block(current_state)
-        return base_prompt.replace("{{CURRENT_STATE}}", state_block)
-
-    # ------------------------------------------------------------------
-    # Convenience: all fold operations flattened
-    # ------------------------------------------------------------------
-
-    def all_fold_operations(self) -> list[dict]:
-        """Return every fold operation across all steps, in order."""
-        ops: list[dict] = []
-        for step in self.steps:
-            ops.extend(step.get("fold_operations", []))
-        return ops
-
-    def total_fold_count(self) -> int:
-        """Total number of fold operations in the plan."""
-        return sum(len(s.get("fold_operations", [])) for s in self.steps)
-
-
-# ---------------------------------------------------------------------------
-# Prompt builder helpers
-# ---------------------------------------------------------------------------
-
-def _format_state_block(state: dict) -> str:
-    """Format a paper_state dict as a human-readable block for the prompt."""
-    lines = ["CURRENT STATE:"]
-    if "bounding_box" in state:
-        bb = state["bounding_box"]
-        if isinstance(bb, dict):
-            lines.append(f"  Bounding box: {bb.get('x', '?')}m x {bb.get('y', '?')}m x {bb.get('z', '?')}m")
-        elif isinstance(bb, (list, tuple)) and len(bb) >= 3:
-            lines.append(f"  Bounding box: {bb[0]}m x {bb[1]}m x {bb[2]}m")
-    if "num_layers_at_center" in state:
-        lines.append(f"  Layers at center: {state['num_layers_at_center']}")
-    if "deployment_ratio" in state:
-        lines.append(f"  Deployment ratio: {state['deployment_ratio']:.3f}")
-    if "fold_angles" in state:
-        n_folds = sum(1 for a in state["fold_angles"] if a != 0)
-        lines.append(f"  Active folds: {n_folds}")
-    return "\n".join(lines)
-
-
-def _format_fold_ops_as_code(ops: list[dict]) -> str:
-    """Format fold operations as Python list literal for inclusion in a prompt."""
-    if not ops:
-        return "    # (LLM: determine fold operations for this step)\n    return []"
-
-    lines = ["    return ["]
-    for op in ops:
-        clean = {
-            "type": op["type"],
-            "line": op.get("line", {"start": [0, 0], "end": [1, 1]}),
-            "angle": op.get("angle", 180),
-        }
-        lines.append(f"        {json.dumps(clean)},")
-    lines.append("    ]")
-    return "\n".join(lines)
-
-
-# ---------------------------------------------------------------------------
-# OrigamiPlanner
-# ---------------------------------------------------------------------------
-
-class OrigamiPlanner:
-    """
-    Full pipeline: human instruction -> structured plan -> executable fold operations.
-
-    The planner:
-      1. Parses the instruction (parser.py)
-      2. Decomposes into sub-goals (decomposer.py)
-      3. Builds LLM-ready prompts matching trainer/prompts.py format
-    """
-
-    def plan(self, instruction: str) -> FoldPlan:
-        """
-        Plan an origami task from a human instruction.
-
-        Args:
-            instruction: e.g. "make a paper crane", "pack a 1m mylar sheet"
-
-        Returns:
-            A FoldPlan with steps and LLM prompts.
-        """
-        parsed = parse_instruction(instruction)
-        steps = decompose_task(parsed)
-        prompts = [self._build_prompt(step, i, parsed) for i, step in enumerate(steps)]
-        return FoldPlan(
-            instruction=instruction,
-            parsed=parsed,
-            steps=steps,
-            prompts=prompts,
-        )
-
-    # ------------------------------------------------------------------
-    # Prompt construction
-    # ------------------------------------------------------------------
-
-    def _build_prompt(self, step: dict, step_index: int, parsed: dict) -> str:
-        """
-        Build an LLM-ready prompt for a single sub-goal step.
-
-        The format matches trainer/prompts.py: task description at top,
-        material/constraints in the middle, and a fold_strategy() code
-        block wrapped in triple backticks at the bottom.
-        """
-        material = parsed["material"]
-        mat_info = _MATERIAL_DEFAULTS.get(material, _MATERIAL_DEFAULTS["paper"])
-        dims = parsed["dimensions"]
-        constraints = parsed.get("constraints", {})
-        total_steps = len(parsed.get("_all_steps", [])) or step.get("step_number", 1)
-
-        # ---- Header ----
-        intent = parsed["intent"]
-        if intent == "fold_model" and parsed.get("model_name"):
-            model_info = ORIGAMI_MODELS.get(parsed["model_name"], {})
-            task_line = (
-                f"TASK: Step {step['step_number']} of {total_steps} — "
-                f"{step['description']}\n"
-                f"MODEL: {model_info.get('name', parsed['model_name'])} "
-                f"(difficulty: {model_info.get('difficulty', 'unknown')})"
-            )
-        elif intent == "optimize_packing":
-            task_line = (
-                f"TASK: Step {step['step_number']} — {step['description']}\n"
-                f"GOAL: Minimize packed volume while maintaining deployability."
-            )
-        else:
-            task_line = f"TASK: Step {step['step_number']} — {step['description']}"
-
-        # ---- Material ----
-        material_block = (
-            f"MATERIAL:\n"
-            f"  - Name: {material}\n"
-            f"  - Thickness: {mat_info['thickness_mm']}mm\n"
-            f"  - Max strain: {mat_info['max_strain_pct']}%"
-        )
-
-        # ---- Constraints ----
-        constraint_lines = ["CONSTRAINTS:"]
-        if "max_folds" in constraints:
-            constraint_lines.append(f"  - Maximum {constraints['max_folds']} fold operations")
-        if "target_box" in constraints:
-            tb = constraints["target_box"]
-            constraint_lines.append(
-                f"  - Must pack into bounding box <= "
-                f"{tb[0]*100:.0f}cm x {tb[1]*100:.0f}cm x {tb[2]*100:.0f}cm"
-            )
-        if constraints.get("must_deploy"):
-            constraint_lines.append("  - Must deploy to >= 80% of original area")
-        constraint_lines.append("  - No self-intersections allowed")
-        constraints_block = "\n".join(constraint_lines)
-
-        # ---- State placeholder ----
-        state_block = (
-            f"CURRENT STATE:\n"
-            f"  Sheet: {dims['width']}m x {dims['height']}m\n"
-            f"  {{{{CURRENT_STATE}}}}"
-        )
-
-        # ---- Fold operations hint ----
-        ops = step.get("fold_operations", [])
-        ops_code = _format_fold_ops_as_code(ops)
-
-        # ---- Expected result ----
-        expected = step.get("expected_state", {})
-        expected_block = ""
-        if expected:
-            expected_block = f"\nEXPECTED RESULT: {json.dumps(expected)}"
-
-        # ---- Code block (matches trainer/prompts.py format) ----
-        code_block = (
-            f'Write a fold_strategy(paper_state) function that returns a list of fold operations.\n'
-            f'Each fold: {{"type": "valley"|"mountain", "line": {{"start": [x,y], "end": [x,y]}}, "angle": 0-180}}\n'
-            f'\n'
-            f'```python\n'
-            f'def fold_strategy(paper_state):\n'
-            f'{ops_code}\n'
-            f'```'
-        )
-
-        # ---- Assemble ----
-        sections = [
-            task_line,
-            "",
-            material_block,
-            "",
-            constraints_block,
-            "",
-            state_block,
-            expected_block,
-            "",
-            code_block,
-        ]
-        return "\n".join(sections)

server/app.py

@@ -1,181 +0,0 @@
-"""
-server/app.py — Training WebSocket server for Colab environment.
-
-Provides /ws/training for live streaming of RL training episodes to browsers.
-Mount at a publicly accessible URL in Colab (e.g., via ngrok or Colab's proxy).
-
-Usage in training:
-    from server.app import broadcast
-    broadcast.publish(episode_id, {"type": "episode_update", ...})
-"""
-from __future__ import annotations
-
-import json
-from pathlib import Path
-
-import numpy as np
-import uvicorn
-from fastapi import FastAPI, HTTPException, WebSocket
-from fastapi.middleware.cors import CORSMiddleware
-from fastapi.responses import HTMLResponse, JSONResponse
-from fastapi.staticfiles import StaticFiles
-
-
-def _np_default(obj):
-    if isinstance(obj, np.bool_):
-        return bool(obj)
-    if isinstance(obj, np.integer):
-        return int(obj)
-    if isinstance(obj, np.floating):
-        return float(obj)
-    if isinstance(obj, np.ndarray):
-        return obj.tolist()
-    raise TypeError(f"Not serializable: {type(obj)}")
-
-
-class NumpyJSONResponse(JSONResponse):
-    def render(self, content) -> bytes:
-        return json.dumps(content, default=_np_default).encode("utf-8")
-
-from server.training_broadcast import TrainingBroadcastServer
-
-app = FastAPI(title="Optigami Training Server", version="1.0")
-
-# Allow cross-origin connections (Colab public URL → browser)
-app.add_middleware(
-    CORSMiddleware,
-    allow_origins=["*"],
-    allow_credentials=True,
-    allow_methods=["*"],
-    allow_headers=["*"],
-)
-
-# Global broadcast server — import and use from training code
-broadcast = TrainingBroadcastServer()
-
-
-@app.on_event("startup")
-async def _store_loop() -> None:
-    """Capture the asyncio event loop so training threads can schedule coroutines."""
-    import asyncio
-    broadcast._loop = asyncio.get_running_loop()
-
-
-@app.websocket("/ws/training")
-async def training_ws(websocket: WebSocket) -> None:
-    """Spectator WebSocket endpoint. Viewers connect here to watch training."""
-    await broadcast.connect_spectator(websocket)
-
-
-@app.get("/health")
-def health() -> dict:
-    return {
-        "status": "ok",
-        "spectators": broadcast.spectator_count,
-        "active_episodes": broadcast.active_episodes,
-    }
-
-
-# ── Demo endpoints (same as openenv_server/app.py so the React UI works) ──
-
-@app.get("/targets", response_class=NumpyJSONResponse)
-def get_targets():
-    from server.tasks import available_task_names, get_task_by_name
-    return NumpyJSONResponse({
-        name: {
-            "name": name,
-            "level": t["difficulty"],
-            "description": t.get("description", ""),
-            "n_creases": t.get("max_folds", 3),
-            "difficulty": t["difficulty"],
-            "material": t.get("material", "paper"),
-        }
-        for name in available_task_names()
-        if (t := get_task_by_name(name))
-    })
-
-
-_DEMO_SEQUENCES: dict[str, list[dict]] = {
-    "half_fold":    [{"type": "valley",   "line": {"start": [0.0, 0.5],   "end": [1.0, 0.5]},   "angle": 180.0}],
-    "quarter_fold": [{"type": "valley",   "line": {"start": [0.0, 0.5],   "end": [1.0, 0.5]},   "angle": 180.0},
-                     {"type": "valley",   "line": {"start": [0.5, 0.0],   "end": [0.5, 1.0]},   "angle": 180.0}],
-    "letter_fold":  [{"type": "valley",   "line": {"start": [0.0, 0.333], "end": [1.0, 0.333]}, "angle": 180.0},
-                     {"type": "mountain", "line": {"start": [0.0, 0.667], "end": [1.0, 0.667]}, "angle": 180.0}],
-    "map_fold":     [{"type": "valley",   "line": {"start": [0.0, 0.5],   "end": [1.0, 0.5]},   "angle": 180.0},
-                     {"type": "mountain", "line": {"start": [0.5, 0.0],   "end": [0.5, 1.0]},   "angle": 180.0}],
-    "solar_panel":  [{"type": "valley",   "line": {"start": [0.0, 0.25],  "end": [1.0, 0.25]},  "angle": 180.0},
-                     {"type": "mountain", "line": {"start": [0.0, 0.5],   "end": [1.0, 0.5]},   "angle": 180.0},
-                     {"type": "valley",   "line": {"start": [0.0, 0.75],  "end": [1.0, 0.75]},  "angle": 180.0}],
-}
-
-
-@app.get("/episode/demo", response_class=NumpyJSONResponse)
-def demo_episode(target: str = "half_fold"):
-    from server.origami_environment import OrigamiEnvironment
-    from server.models import OrigamiAction as NewAction
-    from server.tasks import get_task_by_name
-
-    folds = _DEMO_SEQUENCES.get(target, _DEMO_SEQUENCES["half_fold"])
-    env = OrigamiEnvironment()
-    obs = env.reset(task_name=target)
-    steps: list[dict] = []
-
-    for i, fold_dict in enumerate(folds):
-        action = NewAction(
-            fold_type=fold_dict["type"],
-            fold_line=fold_dict["line"],
-            fold_angle=float(fold_dict.get("angle", 180.0)),
-        )
-        obs = env.step(action)
-        steps.append({"step": i + 1, "fold": fold_dict,
-                       "paper_state": obs.paper_state, "metrics": obs.metrics,
-                       "done": obs.done})
-        if obs.done:
-            break
-
-    return NumpyJSONResponse({"task_name": target, "task": get_task_by_name(target) or {},
-                               "steps": steps, "final_metrics": obs.metrics if steps else {}})
-
-
-@app.get("/episode/replay/{ep_id}", response_class=NumpyJSONResponse)
-def replay_episode(ep_id: str):
-    """Return a stored training episode in the same format as /episode/demo."""
-    from server.tasks import get_task_by_name
-    ep = broadcast._registry.get(ep_id)
-    if not ep:
-        raise HTTPException(status_code=404, detail=f"Episode '{ep_id}' not found in registry")
-    return NumpyJSONResponse({
-        "task_name": ep.task_name,
-        "task": get_task_by_name(ep.task_name) or {},
-        "steps": ep.steps,
-        "final_metrics": ep.final_metrics or (ep.steps[-1]["metrics"] if ep.steps else {}),
-    })
-
-
-# ── Static files — viewer first, then React app (LAST, catch-all) ──
-
-_VIEWER_DIR = Path(__file__).resolve().parent.parent / "viewer"
-_BUILD_DIR  = Path(__file__).resolve().parent.parent / "build"
-
-if _VIEWER_DIR.exists():
-    app.mount("/viewer", StaticFiles(directory=str(_VIEWER_DIR), html=True), name="viewer")
-
-
-if _BUILD_DIR.exists():
-    app.mount("/", StaticFiles(directory=str(_BUILD_DIR), html=True), name="react")
-else:
-    @app.get("/", include_in_schema=False)
-    def _no_build() -> HTMLResponse:
-        return HTMLResponse(
-            "<p>React build not found. Run <code>npm run build</code> in the frontend directory.</p>"
-            "<p>Training viewer: <a href='/viewer/training.html'>/viewer/training.html</a></p>"
-        )
-
-
-def run(host: str = "0.0.0.0", port: int = 9001) -> None:
-    """Start the training server. Call from Colab notebook."""
-    uvicorn.run(app, host=host, port=port)
-
-
-if __name__ == "__main__":
-    run()

server/models.py

@@ -1,59 +0,0 @@
-"""
-OpenEnv Pydantic models for the origami RL environment.
-
-OrigamiAction  — one fold per step
-OrigamiObservation — everything the LLM and Three.js viewer need
-OrigamiState   — server-side episode tracking
-"""
-from __future__ import annotations
-
-from typing import Any, Optional
-
-from pydantic import Field
-
-from openenv.core.env_server.types import Action, Observation, State
-
-
-class OrigamiAction(Action):
-    """One fold operation sent by the client each step."""
-
-    fold_type: str = Field(
-        default="valley",
-        description="'valley' | 'mountain' | 'pleat' | 'crimp' | 'stop'",
-    )
-    fold_line: dict[str, list[float]] = Field(
-        default_factory=lambda: {"start": [0.0, 0.5], "end": [1.0, 0.5]},
-        description="{'start': [x, y], 'end': [x, y]} normalized 0-1",
-    )
-    fold_angle: float = Field(
-        default=180.0,
-        description="Fold angle in degrees, 0-180",
-    )
-    layer_select: str = Field(
-        default="all",
-        description="'all' | 'top' | 'bottom'",
-    )
-
-
-class OrigamiObservation(Observation):
-    """Everything the LLM and Three.js viewer need.
-
-    paper_state contains FOLD-compatible geometry + physics data.
-    metrics contains all computed quality metrics.
-    No render_urls — the browser renders from paper_state directly.
-    """
-
-    task: dict[str, Any] = Field(default_factory=dict)
-    paper_state: dict[str, Any] = Field(default_factory=dict)
-    metrics: dict[str, Any] = Field(default_factory=dict)
-    fold_history: list[dict[str, Any]] = Field(default_factory=list)
-    error: Optional[str] = Field(default=None)
-
-
-class OrigamiState(State):
-    """Server-side episode tracking."""
-
-    task_name: str = Field(default="")
-    num_folds_applied: int = Field(default=0)
-    is_valid: bool = Field(default=True)
-    total_reward: float = Field(default=0.0)

server/origami_environment.py

@@ -1,211 +0,0 @@
-"""
-OrigamiEnvironment — OpenEnv environment wrapping the origami physics engine.
-
-Implements reset() / step() / state following the OpenEnv interface.
-Engine (physics, fold, validation, metrics) lives in engine/.
-No server-side image rendering — paper_state contains all geometry data.
-"""
-from __future__ import annotations
-
-import json
-import os
-import uuid
-from typing import Any, Optional
-
-from openenv.core.env_server.interfaces import Environment
-
-from engine.paper import Paper
-from engine.fold_engine import apply_fold
-from engine.physics import simulate
-from engine.validation import validate_state
-from engine.metrics import compute_all_metrics
-from server.models import OrigamiAction, OrigamiObservation, OrigamiState
-from server.tasks import get_task_by_name, sample_task
-
-
-def _get_material(name: str):
-    """Get material by name, falling back to paper."""
-    try:
-        from engine.materials import get_material
-        return get_material(name)
-    except Exception:
-        from engine.materials import get_material
-        return get_material("paper")
-
-
-class OrigamiEnvironment(Environment[OrigamiAction, OrigamiObservation, OrigamiState]):
-    """Origami folding RL environment.
-
-    Each episode: agent receives paper_state + task, applies folds one at a
-    time via step(), receives metrics + reward, ends with 'stop' action or
-    when max_folds is reached.
-    """
-
-    SUPPORTS_CONCURRENT_SESSIONS = False
-
-    def __init__(self, **kwargs):
-        super().__init__(**kwargs)
-        self._paper: Optional[Paper] = None
-        self._task: Optional[dict] = None
-        self._fold_history: list[dict] = []
-        self._metrics: dict = {}
-        self._validation: dict = {}
-        self._error: Optional[str] = None
-        self._episode_id: Optional[str] = None
-        self._step_count: int = 0
-        self._total_reward: float = 0.0
-
-    # ── reset ─────────────────────────────────────────────────────────
-
-    def reset(
-        self,
-        seed: Optional[int] = None,
-        episode_id: Optional[str] = None,
-        **kwargs: Any,
-    ) -> OrigamiObservation:
-        self._episode_id = episode_id or str(uuid.uuid4())
-        self._step_count = 0
-        self._fold_history = []
-        self._error = None
-        self._total_reward = 0.0
-
-        # Select task
-        task_name = kwargs.get("task_name")
-        if task_name:
-            self._task = get_task_by_name(task_name)
-        if not self._task:
-            self._task = sample_task(seed=seed)
-
-        # Create flat sheet
-        mat = _get_material(self._task["material"])
-        self._paper = Paper.create_flat_sheet(
-            width=self._task["width"],
-            height=self._task["height"],
-            material=mat,
-        )
-
-        # Initial validation + metrics (no physics needed for flat sheet)
-        self._validation = validate_state(self._paper)
-        self._metrics = compute_all_metrics(self._paper, self._task, self._validation)
-
-        return self._make_observation(done=False, reward=None)
-
-    # ── step ──────────────────────────────────────────────────────────
-
-    def step(
-        self,
-        action: OrigamiAction,
-        timeout_s: Optional[float] = None,
-        **kwargs: Any,
-    ) -> OrigamiObservation:
-        if self._paper is None or self._task is None:
-            return self._make_observation(done=True, reward=-5.0)
-
-        self._step_count += 1
-        self._error = None
-
-        # ── Stop action ───────────────────────────────────────────────
-        if action.fold_type == "stop":
-            return self._finalize_episode()
-
-        # ── Build fold dict ───────────────────────────────────────────
-        fold_dict = {
-            "type": action.fold_type,
-            "line": action.fold_line,
-            "angle": action.fold_angle,
-        }
-
-        # ── Apply fold ────────────────────────────────────────────────
-        new_paper, err = apply_fold(self._paper, fold_dict)
-        if err:
-            self._error = err
-            return self._make_observation(done=True, reward=-5.0)
-
-        self._paper = new_paper
-        self._fold_history.append({**fold_dict, "step": self._step_count})
-
-        # ── Physics relaxation ────────────────────────────────────────
-        try:
-            self._paper = simulate(self._paper, fold_percent=1.0)
-        except Exception as exc:
-            self._error = f"Physics failed: {exc}"
-            # Continue — don't abort episode on physics failure
-
-        # ── Validate ──────────────────────────────────────────────────
-        self._validation = validate_state(self._paper)
-
-        # ── Metrics ───────────────────────────────────────────────────
-        self._metrics = compute_all_metrics(self._paper, self._task, self._validation)
-
-        # ── Check termination ─────────────────────────────────────────
-        max_folds = self._task.get("max_folds", 50)
-        if self._step_count >= max_folds:
-            return self._finalize_episode()
-
-        if self._validation.get("self_intersections", 0) > 0:
-            self._error = "Self-intersection detected"
-            return self._finalize_episode()
-
-        return self._make_observation(done=False, reward=None)
-
-    # ── state ─────────────────────────────────────────────────────────
-
-    @property
-    def state(self) -> OrigamiState:
-        return OrigamiState(
-            episode_id=self._episode_id,
-            step_count=self._step_count,
-            task_name=self._task.get("name", "") if self._task else "",
-            num_folds_applied=len(self._fold_history),
-            is_valid=self._metrics.get("is_valid", True),
-            total_reward=self._total_reward,
-        )
-
-    # ── internals ─────────────────────────────────────────────────────
-
-    def _finalize_episode(self) -> OrigamiObservation:
-        reward = self._compute_reward()
-        self._total_reward = reward
-        return self._make_observation(done=True, reward=reward)
-
-    def _make_observation(self, done: bool, reward: Optional[float]) -> OrigamiObservation:
-        return OrigamiObservation(
-            done=done,
-            reward=reward,
-            task=self._task or {},
-            paper_state=self._paper.to_observation_dict() if self._paper else {},
-            metrics=self._metrics,
-            fold_history=self._fold_history,
-            error=self._error,
-        )
-
-    def _compute_reward(self) -> float:
-        m = self._metrics
-        reward = 0.0
-
-        # Compactness is the main signal
-        reward += m.get("compactness", 0.0) * 20.0
-
-        # Bonus for fitting in target box
-        if m.get("fits_target_box", False):
-            reward += 10.0
-
-        # Bonus for deployability (if task requires it)
-        if m.get("is_deployable", False):
-            reward += 5.0
-
-        # Penalties for violations
-        reward -= m.get("kawasaki_violations", 0) * 2.0
-        reward -= m.get("maekawa_violations", 0) * 2.0
-        reward -= m.get("self_intersections", 0) * 5.0
-
-        # Penalty for too many folds (encourage efficiency)
-        reward -= m.get("fold_count", 0) * 0.5
-
-        # Penalty for exceeding material strain limit
-        max_strain = m.get("max_strain", 0.0)
-        strain_limit = self._paper.material.max_strain if self._paper else 0.05
-        if max_strain > strain_limit:
-            reward -= 3.0 * (max_strain / strain_limit)
-
-        return float(reward)

server/tasks.py

@@ -1,123 +0,0 @@
-"""
-Task pool and curriculum for the origami RL environment.
-
-7 tasks across 4 difficulty levels.
-"""
-from __future__ import annotations
-
-import random
-from typing import Optional
-
-
-TASKS: dict[str, dict] = {
-    "half_fold": {
-        "name": "half_fold",
-        "description": "Fold a 1x1 paper sheet in half along the horizontal midline.",
-        "width": 1.0,
-        "height": 1.0,
-        "material": "paper",
-        "target_ratio": 0.50,
-        "max_folds": 3,
-        "target_box": [1.0, 0.5, 0.02],
-        "must_deploy": False,
-        "difficulty": 1,
-    },
-    "quarter_fold": {
-        "name": "quarter_fold",
-        "description": "Fold a 1x1 paper sheet into quarters using two perpendicular folds.",
-        "width": 1.0,
-        "height": 1.0,
-        "material": "paper",
-        "target_ratio": 0.25,
-        "max_folds": 5,
-        "target_box": [0.5, 0.5, 0.04],
-        "must_deploy": False,
-        "difficulty": 1,
-    },
-    "letter_fold": {
-        "name": "letter_fold",
-        "description": "Fold a 1x1 paper into thirds (letter fold) using two parallel folds.",
-        "width": 1.0,
-        "height": 1.0,
-        "material": "paper",
-        "target_ratio": 0.33,
-        "max_folds": 5,
-        "target_box": [1.0, 0.34, 0.03],
-        "must_deploy": False,
-        "difficulty": 2,
-    },
-    "map_fold": {
-        "name": "map_fold",
-        "description": "Fold a 1x1 paper into eighths using a grid fold pattern. Must be re-deployable.",
-        "width": 1.0,
-        "height": 1.0,
-        "material": "paper",
-        "target_ratio": 0.125,
-        "max_folds": 8,
-        "target_box": [0.5, 0.25, 0.08],
-        "must_deploy": True,
-        "difficulty": 2,
-    },
-    "solar_panel": {
-        "name": "solar_panel",
-        "description": "Pack a 1x1 Mylar solar panel into a compact configuration using a Miura-ori style fold. Must deploy.",
-        "width": 1.0,
-        "height": 1.0,
-        "material": "mylar",
-        "target_ratio": 0.05,
-        "max_folds": 20,
-        "target_box": [0.25, 0.25, 0.05],
-        "must_deploy": True,
-        "difficulty": 3,
-    },
-    "shelter_wall": {
-        "name": "shelter_wall",
-        "description": "Fold a 1x1 aluminum sheet into a compact structural panel within strain limits.",
-        "width": 1.0,
-        "height": 1.0,
-        "material": "aluminum",
-        "target_ratio": 0.10,
-        "max_folds": 15,
-        "target_box": [0.5, 0.25, 0.1],
-        "must_deploy": False,
-        "difficulty": 3,
-    },
-    "stent": {
-        "name": "stent",
-        "description": "Fold a 0.5x1.5 nitinol sheet into a compact tube configuration for a medical stent. Superelastic material.",
-        "width": 0.5,
-        "height": 1.5,
-        "material": "nitinol",
-        "target_ratio": 0.09,
-        "max_folds": 25,
-        "target_box": [0.1, 0.1, 0.15],
-        "must_deploy": True,
-        "difficulty": 4,
-    },
-}
-
-
-def get_task_by_name(name: str) -> Optional[dict]:
-    """Return task dict by name, or None if not found."""
-    return TASKS.get(name)
-
-
-def sample_task(seed: Optional[int] = None, difficulty: Optional[int] = None) -> dict:
-    """Sample a random task, optionally filtered by difficulty level."""
-    rng = random.Random(seed)
-    pool = list(TASKS.values())
-    if difficulty is not None:
-        pool = [t for t in pool if t["difficulty"] == difficulty]
-    if not pool:
-        pool = list(TASKS.values())
-    return dict(rng.choice(pool))
-
-
-def get_tasks_by_difficulty(level: int) -> list[dict]:
-    """Return all tasks at a given difficulty level."""
-    return [dict(t) for t in TASKS.values() if t["difficulty"] == level]
-
-
-def available_task_names() -> list[str]:
-    """Return sorted list of all task names."""
-    return sorted(TASKS.keys())

server_legacy.py

@@ -1,172 +0,0 @@
-"""
-FastAPI server for the origami RL environment.
-Serves episode data to the React frontend.
-
-Usage: uvicorn server:app --reload --port 8000
-"""
-
-try:
-    from fastapi import FastAPI
-    from fastapi.middleware.cors import CORSMiddleware
-    from pydantic import BaseModel
-except ImportError:
-    print("Run: pip install fastapi uvicorn pydantic")
-    raise
-
-from typing import Optional
-
-
-app = FastAPI(title="OrigamiRL API")
-
-app.add_middleware(
-    CORSMiddleware,
-    allow_origins=["*"],  # localhost:3000 for React dev
-    allow_methods=["*"],
-    allow_headers=["*"],
-)
-
-
-class FoldAction(BaseModel):
-    from_point: list[float]  # [x, y]
-    to_point: list[float]    # [x, y]
-    assignment: str          # 'M' or 'V'
-    instruction: str = ""
-
-
-class EpisodeStep(BaseModel):
-    step: int
-    fold: Optional[FoldAction]
-    paper_state: dict        # FOLD JSON of current crease graph
-    anchor_points: list[list[float]]
-    reward: dict
-    done: bool
-    info: dict
-    prompt: str              # LLM prompt at this step
-
-
-class EpisodeResult(BaseModel):
-    target_name: str
-    target: dict             # FOLD JSON of target
-    steps: list[EpisodeStep]
-    final_reward: dict
-
-
-@app.get("/")
-def health_check():
-    """Health check — returns status and available target names."""
-    from env.environment import OrigamiEnvironment
-    env = OrigamiEnvironment()
-    return {"status": "ok", "targets": env.available_targets()}
-
-
-@app.get("/targets")
-def get_targets():
-    """Return list of available target names and their metadata."""
-    from env.environment import OrigamiEnvironment
-    env = OrigamiEnvironment()
-    targets = {}
-    for name in env.available_targets():
-        t = env._targets[name]
-        targets[name] = {
-            "name": name,
-            "level": t.get("level", 1),
-            "description": t.get("description", ""),
-            "n_creases": sum(1 for a in t["edges_assignment"] if a in ("M", "V")),
-        }
-    return targets
-
-
-@app.get("/episode/run")
-def run_episode(target: str = "half_horizontal", completion: str = ""):
-    """
-    Run a code-as-policy episode with a provided completion string.
-
-    If completion is empty, returns the prompt so the caller knows what to send.
-    Returns full episode result with all steps.
-    """
-    from env.environment import OrigamiEnvironment
-    from env.prompts import parse_fold_list, code_as_policy_prompt
-    from env.rewards import compute_reward, target_crease_edges
-
-    env = OrigamiEnvironment(mode="step")
-    obs = env.reset(target_name=target)
-
-    if not completion:
-        return {"prompt": obs["prompt"], "steps": [], "target": env.target}
-
-    try:
-        folds = parse_fold_list(completion)
-    except ValueError as e:
-        return {"error": str(e), "steps": []}
-
-    steps = []
-    for i, fold in enumerate(folds):
-        result = env.paper.add_crease(fold["from"], fold["to"], fold["assignment"])
-        reward = compute_reward(env.paper, result, env.target)
-
-        paper_state = {
-            "vertices": {str(k): list(v) for k, v in env.paper.graph.vertices.items()},
-            "edges": [
-                {
-                    "id": k,
-                    "v1": list(env.paper.graph.vertices[v[0]]),
-                    "v2": list(env.paper.graph.vertices[v[1]]),
-                    "assignment": v[2],
-                }
-                for k, v in env.paper.graph.edges.items()
-            ],
-            "anchor_points": [list(p) for p in env.paper.anchor_points()],
-        }
-
-        # Build per-step prompt reflecting current state
-        from env.prompts import step_level_prompt
-        step_prompt = step_level_prompt(
-            target=env.target,
-            paper_state=env.paper,
-            step=i + 1,
-            max_steps=env.max_steps,
-            last_reward=reward,
-        )
-
-        steps.append({
-            "step": i + 1,
-            "fold": {
-                "from_point": fold["from"],
-                "to_point": fold["to"],
-                "assignment": fold["assignment"],
-                "instruction": fold.get("instruction", ""),
-            },
-            "paper_state": paper_state,
-            "anchor_points": [list(p) for p in env.paper.anchor_points()],
-            "reward": reward,
-            "done": reward.get("completion", 0) > 0,
-            "info": env._info(),
-            "prompt": step_prompt,
-        })
-
-        if reward.get("completion", 0) > 0:
-            break
-
-    return {
-        "target_name": target,
-        "target": env.target,
-        "steps": steps,
-        "final_reward": steps[-1]["reward"] if steps else {},
-    }
-
-
-@app.get("/episode/demo")
-def demo_episode(target: str = "half_horizontal"):
-    """Return a pre-solved demo episode for each target."""
-    DEMO_COMPLETIONS = {
-        "half_horizontal": '<folds>[{"instruction": "Valley fold along horizontal center line", "from": [0, 0.5], "to": [1, 0.5], "assignment": "V"}]</folds>',
-        "half_vertical": '<folds>[{"instruction": "Mountain fold along vertical center line", "from": [0.5, 0], "to": [0.5, 1], "assignment": "M"}]</folds>',
-        "diagonal_main": '<folds>[{"instruction": "Valley fold along main diagonal", "from": [0, 0], "to": [1, 1], "assignment": "V"}]</folds>',
-        "diagonal_anti": '<folds>[{"instruction": "Mountain fold along anti-diagonal", "from": [1, 0], "to": [0, 1], "assignment": "M"}]</folds>',
-        "thirds_h": '<folds>[{"instruction": "Valley fold at one-third height", "from": [0, 0.333], "to": [1, 0.333], "assignment": "V"}, {"instruction": "Valley fold at two-thirds height", "from": [0, 0.667], "to": [1, 0.667], "assignment": "V"}]</folds>',
-        "thirds_v": '<folds>[{"instruction": "Mountain fold at one-third width", "from": [0.333, 0], "to": [0.333, 1], "assignment": "M"}, {"instruction": "Mountain fold at two-thirds width", "from": [0.667, 0], "to": [0.667, 1], "assignment": "M"}]</folds>',
-        "accordion_3h": '<folds>[{"instruction": "Valley fold at quarter height", "from": [0, 0.25], "to": [1, 0.25], "assignment": "V"}, {"instruction": "Mountain fold at half height", "from": [0, 0.5], "to": [1, 0.5], "assignment": "M"}, {"instruction": "Valley fold at three-quarter height", "from": [0, 0.75], "to": [1, 0.75], "assignment": "V"}]</folds>',
-        "accordion_4h": '<folds>[{"instruction": "Valley fold at 0.2", "from": [0, 0.2], "to": [1, 0.2], "assignment": "V"}, {"instruction": "Mountain fold at 0.4", "from": [0, 0.4], "to": [1, 0.4], "assignment": "M"}, {"instruction": "Valley fold at 0.6", "from": [0, 0.6], "to": [1, 0.6], "assignment": "V"}, {"instruction": "Mountain fold at 0.8", "from": [0, 0.8], "to": [1, 0.8], "assignment": "M"}]</folds>',
-    }
-    completion = DEMO_COMPLETIONS.get(target, DEMO_COMPLETIONS["half_horizontal"])
-    return run_episode(target=target, completion=completion)

sim/animate.py

@@ -1,149 +0,0 @@
-"""
-Matplotlib 3D animation of origami folding using OrigamiSimulator.
-
-Usage:
-    python -m sim.animate [target_name]
-
-    target_name defaults to 'half_horizontal', resolved against
-    env/targets/<target_name>.fold relative to this file's parent directory.
-"""
-
-from __future__ import annotations
-
-import json
-import sys
-from pathlib import Path
-
-import matplotlib.pyplot as plt
-import matplotlib.animation as animation
-import numpy as np
-from mpl_toolkits.mplot3d.art3d import Poly3DCollection
-
-from .simulator import OrigamiSimulator
-
-# ── Design system colours ─────────────────────────────────────────────────────
-BG_COLOR     = '#0d0d14'
-AX_COLOR     = '#13131d'
-PAPER_FACE   = '#fafaf5'
-PAPER_EDGE   = '#2a2a3a'
-MOUNTAIN_CLR = '#f59e0b'   # amber
-VALLEY_CLR   = '#38bdf8'   # sky
-
-
-# ── Public API ────────────────────────────────────────────────────────────────
-
-def animate_fold(fold_file: str,
-                 n_frames: int = 80,
-                 steps_per_frame: int = 40,
-                 target_name: str = 'origami') -> None:
-    """
-    Animate folding from 0% → 100% → 0% in a triangle-wave loop.
-
-    Parameters
-    ----------
-    fold_file : str
-        Path to the .fold JSON file.
-    n_frames : int
-        Total animation frames (default 80 → ~40 in, 40 out).
-    steps_per_frame : int
-        Physics steps executed per frame.
-    target_name : str
-        Display name shown in the title.
-    """
-    fold_data = json.loads(Path(fold_file).read_text())
-    sim = OrigamiSimulator(fold_data, subdivisions=2)
-
-    # Triangle-wave fold percents: 0 → 1 → 0
-    half = n_frames // 2
-    fold_percents = np.concatenate([
-        np.linspace(0.0, 1.0, half),
-        np.linspace(1.0, 0.0, n_frames - half),
-    ])
-
-    # ── Figure setup ──────────────────────────────────────────────────────────
-    fig = plt.figure(figsize=(9, 7), facecolor=BG_COLOR)
-    ax  = fig.add_subplot(111, projection='3d')
-    ax.set_facecolor(AX_COLOR)
-    ax.xaxis.pane.fill = False
-    ax.yaxis.pane.fill = False
-    ax.zaxis.pane.fill = False
-    ax.grid(False)
-    ax.set_axis_off()
-
-    def update(frame: int) -> list:
-        pct = fold_percents[frame]
-        sim.set_fold_percent(pct)
-        sim.step(steps_per_frame)
-
-        ax.clear()
-        ax.set_facecolor(AX_COLOR)
-        ax.xaxis.pane.fill = False
-        ax.yaxis.pane.fill = False
-        ax.zaxis.pane.fill = False
-        ax.grid(False)
-        ax.set_axis_off()
-
-        # ── Paper surface ─────────────────────────────────────────────────────
-        verts = [sim.pos[tri] for tri in sim.triangles]
-        poly = Poly3DCollection(
-            verts,
-            alpha=0.85,
-            facecolor=PAPER_FACE,
-            edgecolor=PAPER_EDGE,
-            linewidth=0.2,
-            zorder=1,
-        )
-        ax.add_collection3d(poly)
-
-        # ── Crease / fold edges ───────────────────────────────────────────────
-        for i in range(len(sim._crease_a)):
-            if sim._crease_assign[i] not in ('M', 'V'):
-                continue
-            a, b = sim._crease_a[i], sim._crease_b[i]
-            color = MOUNTAIN_CLR if sim._crease_assign[i] == 'M' else VALLEY_CLR
-            ax.plot(
-                [sim.pos[a, 0], sim.pos[b, 0]],
-                [sim.pos[a, 1], sim.pos[b, 1]],
-                [sim.pos[a, 2], sim.pos[b, 2]],
-                color=color,
-                linewidth=2.5,
-                zorder=2,
-            )
-
-        # ── Axis limits & style ───────────────────────────────────────────────
-        ax.set_xlim(-0.2, 1.2)
-        ax.set_ylim(-0.2, 1.2)
-        ax.set_zlim(-0.6, 0.6)
-        ax.set_box_aspect([1.4, 1.4, 1.0])
-        ax.set_title(
-            f'OPTIGAMI — {target_name}  fold: {pct * 100:.0f}%',
-            color='#e0e0f0',
-            fontsize=13,
-            pad=10,
-        )
-
-        return []
-
-    ani = animation.FuncAnimation(
-        fig,
-        update,
-        frames=n_frames,
-        interval=40,   # ms between frames (~25 fps)
-        blit=False,
-    )
-
-    plt.tight_layout()
-    plt.show()
-
-
-def main() -> None:
-    target = sys.argv[1] if len(sys.argv) > 1 else 'half_horizontal'
-    fold_file = Path(__file__).parent.parent / 'env' / 'targets' / f'{target}.fold'
-    if not fold_file.exists():
-        print(f'Error: fold file not found: {fold_file}', file=sys.stderr)
-        sys.exit(1)
-    animate_fold(str(fold_file), target_name=target)
-
-
-if __name__ == '__main__':
-    main()

sim/simulator.py

@@ -1,406 +0,0 @@
-"""
-Origami mass-spring dynamic relaxation simulator.
-
-Based on: Ghassaei et al., "Fast, Interactive Origami Simulation using GPU
-Computation", 7OSME 2018.
-"""
-
-from __future__ import annotations
-
-import numpy as np
-from scipy.spatial import Delaunay
-
-# ── Physics constants ────────────────────────────────────────────────────────
-
-AXIAL_STIFFNESS  = 20.0   # K = AXIAL_STIFFNESS / rest_length
-CREASE_STIFFNESS = 0.7    # K = CREASE_STIFFNESS * edge_length  (M/V creases)
-PANEL_STIFFNESS  = 0.7    # K = PANEL_STIFFNESS  * edge_length  (F / panel edges)
-PERCENT_DAMPING  = 0.45   # global viscous damping fraction
-DT               = 0.002  # timestep (seconds)
-
-
-# ── Geometry helpers ─────────────────────────────────────────────────────────
-
-def _normalize(v: np.ndarray) -> np.ndarray:
-    n = np.linalg.norm(v)
-    return v / n if n > 1e-12 else v
-
-
-def _triangulate_faces(faces_vertices: list[list[int]]) -> np.ndarray:
-    """Fan-triangulate polygonal faces (triangles and quads supported)."""
-    tris = []
-    for face in faces_vertices:
-        if len(face) == 3:
-            tris.append(face)
-        elif len(face) == 4:
-            a, b, c, d = face
-            tris.append([a, b, c])
-            tris.append([a, c, d])
-        else:
-            # General fan triangulation for n-gons
-            for k in range(1, len(face) - 1):
-                tris.append([face[0], face[k], face[k + 1]])
-    return np.array(tris, dtype=np.int32)
-
-
-def _point_on_segment(p: np.ndarray, p0: np.ndarray, p1: np.ndarray,
-                      tol: float = 1e-6) -> bool:
-    seg = p1 - p0
-    seg_len = np.linalg.norm(seg)
-    if seg_len < 1e-10:
-        return False
-    seg_dir = seg / seg_len
-    t = np.dot(p - p0, seg_dir)
-    perp = (p - p0) - t * seg_dir
-    return -tol <= t <= seg_len + tol and np.linalg.norm(perp) < tol
-
-
-# ── Mesh subdivision ──────────────────────────────────────────────────────────
-
-def _subdivide(pos2d: np.ndarray, triangles: np.ndarray
-               ) -> tuple[np.ndarray, np.ndarray]:
-    """Split each triangle into 4 by inserting edge midpoints."""
-    midpoint_cache: dict[tuple[int, int], int] = {}
-    new_pos = list(pos2d)
-    new_tris = []
-
-    def get_mid(i: int, j: int) -> int:
-        key = (min(i, j), max(i, j))
-        if key not in midpoint_cache:
-            mid = (np.array(new_pos[i]) + np.array(new_pos[j])) / 2.0
-            midpoint_cache[key] = len(new_pos)
-            new_pos.append(mid)
-        return midpoint_cache[key]
-
-    for tri in triangles:
-        a, b, c = tri
-        ab = get_mid(a, b)
-        bc = get_mid(b, c)
-        ca = get_mid(c, a)
-        new_tris.extend([
-            [a,  ab, ca],
-            [ab, b,  bc],
-            [ca, bc, c ],
-            [ab, bc, ca],
-        ])
-
-    return np.array(new_pos, dtype=np.float64), np.array(new_tris, dtype=np.int32)
-
-
-# ── Main simulator ────────────────────────────────────────────────────────────
-
-class OrigamiSimulator:
-    """
-    Mass-spring dynamic relaxation simulator for origami.
-
-    Parameters
-    ----------
-    fold_data : dict
-        Parsed FOLD JSON with keys: vertices_coords, edges_vertices,
-        edges_assignment.
-    subdivisions : int
-        Number of midpoint subdivision passes (default 2 → 4× mesh density).
-    """
-
-    def __init__(self, fold_data: dict, subdivisions: int = 2) -> None:
-        self._fold_percent = 0.0
-        self._build(fold_data, subdivisions)
-
-    # ── Public API ────────────────────────────────────────────────────────────
-
-    def set_fold_percent(self, percent: float) -> None:
-        """Update all crease spring target angles (0.0 = flat, 1.0 = fully folded)."""
-        self._fold_percent = float(percent)
-        self._crease_target = self._fold_percent * self._crease_full_theta
-
-    def step(self, n_steps: int = 50) -> None:
-        """Advance the simulation by n_steps Euler integration steps."""
-        for _ in range(n_steps):
-            self._euler_step()
-
-    def reset(self) -> None:
-        """Reset to flat state (z=0, vel=0), preserving current fold percent."""
-        self.pos = self._flat_pos.copy()
-        self.vel[:] = 0.0
-
-    @property
-    def crease_indices(self) -> list[tuple[int, int, str]]:
-        """Return list of (a, b, assignment) for all crease springs."""
-        return list(zip(
-            self._crease_a.tolist(),
-            self._crease_b.tolist(),
-            self._crease_assign,
-        ))
-
-    # ── Build ─────────────────────────────────────────────────────────────────
-
-    def _build(self, fold_data: dict, subdivisions: int) -> None:
-        coords = fold_data['vertices_coords']
-        orig_edges = fold_data['edges_vertices']
-        orig_assign = fold_data['edges_assignment']
-
-        # Original 2-D positions
-        pts2d = np.array([[x, y] for x, y in coords], dtype=np.float64)
-
-        # Build triangles from faces_vertices when available (preferred: ensures
-        # crease edges appear as actual mesh edges after subdivision).
-        # Quads [a,b,c,d] are split into [a,b,c] + [a,c,d].
-        # Fall back to Delaunay only if faces_vertices is absent.
-        if 'faces_vertices' in fold_data:
-            triangles = _triangulate_faces(fold_data['faces_vertices'])
-        else:
-            tri = Delaunay(pts2d)
-            triangles = tri.simplices.astype(np.int32)
-
-        # Build original crease segments for later classification
-        # Only M and V assignments are actual fold creases; B is boundary.
-        orig_creases: list[tuple[np.ndarray, np.ndarray, str]] = []
-        for (u, v), asgn in zip(orig_edges, orig_assign):
-            if asgn in ('M', 'V'):
-                orig_creases.append((pts2d[u], pts2d[v], asgn))
-
-        # Midpoint subdivision passes
-        pos2d = pts2d.copy()
-        for _ in range(subdivisions):
-            pos2d, triangles = _subdivide(pos2d, triangles)
-
-        n = len(pos2d)
-
-        # 3-D positions (flat, z=0)
-        pos3d = np.zeros((n, 3), dtype=np.float64)
-        pos3d[:, :2] = pos2d
-
-        self.pos        = pos3d
-        self._flat_pos  = pos3d.copy()
-        self.vel        = np.zeros((n, 3), dtype=np.float64)
-        self.triangles  = triangles
-
-        self._build_beams(triangles)
-        self._build_masses(triangles)
-        self._build_creases(triangles, pos2d, orig_creases)
-
-    def _build_beams(self, triangles: np.ndarray) -> None:
-        """Collect all unique triangle edges as structural (axial) springs."""
-        edge_set: set[tuple[int, int]] = set()
-        for tri in triangles:
-            a, b, c = tri
-            for i, j in [(a, b), (b, c), (c, a)]:
-                edge_set.add((min(i, j), max(i, j)))
-
-        edges = np.array(sorted(edge_set), dtype=np.int32)
-        i_arr = edges[:, 0]
-        j_arr = edges[:, 1]
-
-        rest = np.linalg.norm(self.pos[i_arr] - self.pos[j_arr], axis=1)
-        K    = AXIAL_STIFFNESS / np.maximum(rest, 1e-12)
-
-        self._beam_i    = i_arr
-        self._beam_j    = j_arr
-        self._beam_rest = rest
-        self._beam_K    = K
-
-    def _build_masses(self, triangles: np.ndarray) -> None:
-        """Mass per node = sum of (adjacent triangle area / 3)."""
-        n = len(self.pos)
-        mass = np.zeros(n, dtype=np.float64)
-        for tri in triangles:
-            a, b, c = tri
-            pa, pb, pc = self.pos[a], self.pos[b], self.pos[c]
-            area = 0.5 * np.linalg.norm(np.cross(pb - pa, pc - pa))
-            mass[a] += area / 3.0
-            mass[b] += area / 3.0
-            mass[c] += area / 3.0
-        # Guard against zero-mass nodes (degenerate triangles)
-        mass = np.maximum(mass, 1e-12)
-        self.mass = mass
-
-    def _build_creases(self, triangles: np.ndarray, pos2d: np.ndarray,
-                       orig_creases: list[tuple[np.ndarray, np.ndarray, str]]
-                       ) -> None:
-        """
-        Identify interior edges (shared by exactly 2 triangles) and classify
-        them as M/V fold creases or F panel springs.
-        """
-        # Map each canonical edge → list of triangle indices containing it
-        edge_to_tris: dict[tuple[int, int], list[int]] = {}
-        tri_edge_map: dict[tuple[int, int], list[tuple[int, int, int]]] = {}
-
-        for t_idx, tri in enumerate(triangles):
-            a, b, c = tri
-            for (ei, ej), opposite in [
-                ((min(a, b), max(a, b)), c),
-                ((min(b, c), max(b, c)), a),
-                ((min(c, a), max(c, a)), b),
-            ]:
-                edge_to_tris.setdefault((ei, ej), []).append(t_idx)
-                tri_edge_map.setdefault((ei, ej), []).append((ei, ej, opposite))
-
-        crease_a: list[int] = []
-        crease_b: list[int] = []
-        crease_c: list[int] = []
-        crease_d: list[int] = []
-        crease_assign: list[str] = []
-        crease_full_theta: list[float] = []
-        crease_K: list[float] = []
-
-        for edge_key, t_indices in edge_to_tris.items():
-            if len(t_indices) != 2:
-                continue  # boundary edge
-
-            ei, ej = edge_key
-            # Collect opposite nodes for each of the two triangles
-            # Find the opposite node for tri 0 and tri 1
-            opp_nodes = [None, None]
-            for t_pos, t_idx in enumerate(t_indices):
-                tri = triangles[t_idx]
-                for node in tri:
-                    if node != ei and node != ej:
-                        opp_nodes[t_pos] = node
-                        break
-
-            c_node = opp_nodes[0]
-            d_node = opp_nodes[1]
-            if c_node is None or d_node is None:
-                continue
-
-            # Classify: check if both endpoints lie on the same original crease segment
-            pi = pos2d[ei]
-            pj = pos2d[ej]
-            asgn = 'F'
-            for p0, p1, crease_type in orig_creases:
-                if _point_on_segment(pi, p0, p1) and _point_on_segment(pj, p0, p1):
-                    asgn = crease_type
-                    break
-
-            if asgn == 'M':
-                full_theta = +np.pi
-                K = CREASE_STIFFNESS * np.linalg.norm(pos2d[ej] - pos2d[ei])
-            elif asgn == 'V':
-                full_theta = -np.pi
-                K = CREASE_STIFFNESS * np.linalg.norm(pos2d[ej] - pos2d[ei])
-            else:  # 'F' panel
-                full_theta = 0.0
-                K = PANEL_STIFFNESS * np.linalg.norm(pos2d[ej] - pos2d[ei])
-
-            crease_a.append(ei)
-            crease_b.append(ej)
-            crease_c.append(c_node)
-            crease_d.append(d_node)
-            crease_assign.append(asgn)
-            crease_full_theta.append(full_theta)
-            crease_K.append(K)
-
-        self._crease_a          = np.array(crease_a, dtype=np.int32)
-        self._crease_b          = np.array(crease_b, dtype=np.int32)
-        self._crease_c          = np.array(crease_c, dtype=np.int32)
-        self._crease_d          = np.array(crease_d, dtype=np.int32)
-        self._crease_assign     = crease_assign
-        self._crease_full_theta = np.array(crease_full_theta, dtype=np.float64)
-        self._crease_K          = np.array(crease_K, dtype=np.float64)
-        self._crease_target     = np.zeros(len(crease_a), dtype=np.float64)
-
-    # ── Physics ───────────────────────────────────────────────────────────────
-
-    def _beam_forces(self) -> np.ndarray:
-        """Vectorized axial spring forces for all beams."""
-        n = len(self.pos)
-        forces = np.zeros((n, 3), dtype=np.float64)
-
-        pi = self.pos[self._beam_i]
-        pj = self.pos[self._beam_j]
-        diff = pj - pi
-        lengths = np.linalg.norm(diff, axis=1, keepdims=True)
-        lengths = np.maximum(lengths, 1e-12)
-        unit = diff / lengths
-
-        stretch = lengths[:, 0] - self._beam_rest
-        F_mag = self._beam_K * stretch          # scalar force magnitude
-
-        # Damping along the edge
-        vi = self.vel[self._beam_i]
-        vj = self.vel[self._beam_j]
-        rel_vel = np.sum((vj - vi) * unit, axis=1)
-        damp_mag = PERCENT_DAMPING * rel_vel
-        F_total = (F_mag + damp_mag)[:, None] * unit
-
-        np.add.at(forces, self._beam_i,  F_total)
-        np.add.at(forces, self._beam_j, -F_total)
-        return forces
-
-    def _crease_forces(self) -> np.ndarray:
-        """Torsional spring forces for all crease/panel edges (Python loop)."""
-        n = len(self.pos)
-        forces = np.zeros((n, 3), dtype=np.float64)
-
-        pos = self.pos
-        for idx in range(len(self._crease_a)):
-            a = self._crease_a[idx]
-            b = self._crease_b[idx]
-            c = self._crease_c[idx]
-            d = self._crease_d[idx]
-            K = self._crease_K[idx]
-            target = self._crease_target[idx]
-
-            pa, pb, pc, pd = pos[a], pos[b], pos[c], pos[d]
-
-            edge_vec = pb - pa
-            edge_len = np.linalg.norm(edge_vec)
-            if edge_len < 1e-12:
-                continue
-            edge_dir = edge_vec / edge_len
-
-            # Face normals
-            n1_raw = np.cross(pb - pa, pc - pa)
-            n2_raw = np.cross(pa - pb, pd - pb)
-            n1_len = np.linalg.norm(n1_raw)
-            n2_len = np.linalg.norm(n2_raw)
-            if n1_len < 1e-12 or n2_len < 1e-12:
-                continue
-            n1 = n1_raw / n1_len
-            n2 = n2_raw / n2_len
-
-            # Dihedral angle via atan2
-            cross_n = np.cross(n1, n2)
-            sin_theta = np.dot(cross_n, edge_dir)
-            cos_theta = np.dot(n1, n2)
-            theta = np.arctan2(sin_theta, cos_theta)
-
-            delta  = theta - target
-            torque = -K * delta
-
-            # Moment arms (perpendicular distance from c, d to crease line)
-            vc = pc - pa
-            vd = pd - pa
-            vc_perp = vc - np.dot(vc, edge_dir) * edge_dir
-            vd_perp = vd - np.dot(vd, edge_dir) * edge_dir
-            h_c = np.linalg.norm(vc_perp)
-            h_d = np.linalg.norm(vd_perp)
-            if h_c < 1e-12 or h_d < 1e-12:
-                continue
-
-            # Forces on opposite nodes
-            F_c =  (torque / h_c) * n1
-            F_d = -(torque / h_d) * n2
-
-            # Reaction on crease nodes (moment balance)
-            proj_c = np.dot(pc - pa, edge_dir)
-            proj_d = np.dot(pd - pa, edge_dir)
-            coef_c_a = 1.0 - proj_c / edge_len
-            coef_c_b =       proj_c / edge_len
-            coef_d_a = 1.0 - proj_d / edge_len
-            coef_d_b =       proj_d / edge_len
-
-            forces[c] += F_c
-            forces[d] += F_d
-            forces[a] -= coef_c_a * F_c + coef_d_a * F_d
-            forces[b] -= coef_c_b * F_c + coef_d_b * F_d
-
-        return forces
-
-    def _euler_step(self) -> None:
-        forces = self._beam_forces() + self._crease_forces()
-        accel  = forces / self.mass[:, None]
-        vel_new = self.vel + accel * DT
-        vel_new *= (1.0 - PERCENT_DAMPING * DT)
-        self.pos += vel_new * DT
-        self.vel  = vel_new

trainer/mock_env.py

@@ -1,249 +0,0 @@
-"""
-Mock origami environment for trainer development.
-
-Returns fake PaperState responses so we can iterate on the GRPO loop
-without waiting for the real physics engine. The mock applies geometric
-transforms (vertex rotations around fold lines) but skips energy/strain
-computation — those return plausible dummy values.
-"""
-
-import math
-import numpy as np
-from dataclasses import dataclass, field
-
-
-@dataclass
-class Material:
-    name: str = "paper"
-    thickness_mm: float = 0.1
-    youngs_modulus_gpa: float = 2.0
-    max_strain: float = 0.03  # 3%
-
-
-@dataclass
-class PaperState:
-    vertices: np.ndarray           # (N, 3)
-    edges: np.ndarray              # (E, 2)
-    faces: list[list[int]]
-    assignments: list[str]         # M/V/B per edge
-    fold_angles: np.ndarray        # (E,) degrees
-
-    rest_lengths: np.ndarray       # (E,)
-    strain: np.ndarray             # (N,)
-    energy: float = 0.0
-
-    face_orders: list[tuple] = field(default_factory=list)
-    num_layers: int = 1
-
-    material: Material = field(default_factory=Material)
-
-    bounding_box: np.ndarray = field(default_factory=lambda: np.array([1.0, 1.0, 0.0]))
-    deployment_ratio: float = 1.0
-    is_valid: bool = True
-    kawasaki_violation: float = 0.0
-    maekawa_violation: float = 0.0
-    self_intersections: int = 0
-
-    def to_dict(self) -> dict:
-        return {
-            "width": float(self.bounding_box[0]),
-            "height": float(self.bounding_box[1]),
-            "material": {
-                "name": self.material.name,
-                "thickness_mm": self.material.thickness_mm,
-                "youngs_modulus_gpa": self.material.youngs_modulus_gpa,
-            },
-            "vertices": self.vertices.tolist(),
-            "edges": self.edges.tolist(),
-            "assignments": self.assignments,
-            "fold_angles": self.fold_angles.tolist(),
-            "num_layers_at_center": self.num_layers,
-            "bounding_box": {
-                "x": float(self.bounding_box[0]),
-                "y": float(self.bounding_box[1]),
-                "z": float(self.bounding_box[2]),
-            },
-        }
-
-
-def create_flat_sheet(width: float = 1.0, height: float = 1.0,
-                      material: Material | None = None) -> PaperState:
-    """Create a flat rectangular sheet with 4 vertices, 5 edges (incl diagonal), 2 faces."""
-    verts = np.array([
-        [0, 0, 0],
-        [width, 0, 0],
-        [width, height, 0],
-        [0, height, 0],
-    ], dtype=float)
-
-    edges = np.array([
-        [0, 1], [1, 2], [2, 3], [3, 0],  # boundary
-        [0, 2],  # diagonal
-    ], dtype=int)
-
-    faces = [[0, 1, 2], [0, 2, 3]]
-    assignments = ["B", "B", "B", "B", "F"]  # boundary + flat diagonal
-    fold_angles = np.zeros(len(edges))
-    rest_lengths = np.array([np.linalg.norm(verts[e[1]] - verts[e[0]]) for e in edges])
-    strain = np.zeros(len(verts))
-
-    mat = material or Material()
-    return PaperState(
-        vertices=verts, edges=edges, faces=faces,
-        assignments=assignments, fold_angles=fold_angles,
-        rest_lengths=rest_lengths, strain=strain,
-        material=mat,
-        bounding_box=np.array([width, height, 0.0]),
-    )
-
-
-def _rotate_points(points: np.ndarray, axis_point: np.ndarray,
-                   axis_dir: np.ndarray, angle_rad: float) -> np.ndarray:
-    """Rotate points around an arbitrary axis using Rodrigues' formula."""
-    k = axis_dir / np.linalg.norm(axis_dir)
-    translated = points - axis_point
-    cos_a = math.cos(angle_rad)
-    sin_a = math.sin(angle_rad)
-    rotated = (translated * cos_a +
-               np.cross(k, translated) * sin_a +
-               k * (np.dot(translated, k).reshape(-1, 1)) * (1 - cos_a))
-    return rotated + axis_point
-
-
-def apply_fold_mock(state: PaperState, fold: dict) -> tuple[PaperState, str | None]:
-    """
-    Apply a single fold operation to the paper state (mock version).
-
-    fold = {
-        "type": "valley" | "mountain",
-        "line": {"start": [x, y], "end": [x, y]},
-        "angle": 0-180
-    }
-
-    Returns (new_state, error_string_or_None).
-    """
-    fold_type = fold.get("type", "valley")
-    line = fold.get("line", {})
-    angle_deg = fold.get("angle", 180)
-
-    start = np.array(line.get("start", [0, 0]), dtype=float)
-    end = np.array(line.get("end", [0, 0]), dtype=float)
-
-    if np.allclose(start, end):
-        return state, "Fold line has zero length"
-
-    if fold_type not in ("valley", "mountain"):
-        return state, f"Unknown fold type: {fold_type}"
-
-    # angle=0 means "no fold" — return unchanged copy
-    if angle_deg == 0:
-        return PaperState(
-            vertices=state.vertices.copy(), edges=state.edges.copy(),
-            faces=[f[:] for f in state.faces],
-            assignments=state.assignments[:], fold_angles=state.fold_angles.copy(),
-            rest_lengths=state.rest_lengths.copy(), strain=state.strain.copy(),
-            energy=state.energy, face_orders=state.face_orders[:],
-            num_layers=state.num_layers, material=state.material,
-            bounding_box=state.bounding_box.copy(),
-            deployment_ratio=state.deployment_ratio, is_valid=state.is_valid,
-            kawasaki_violation=state.kawasaki_violation,
-            maekawa_violation=state.maekawa_violation,
-            self_intersections=state.self_intersections,
-        ), None
-
-    if not (0 < angle_deg <= 180):
-        return state, f"Angle must be in (0, 180], got {angle_deg}"
-
-    # Fold direction: valley folds up (+z), mountain folds down (-z)
-    sign = 1.0 if fold_type == "valley" else -1.0
-    angle_rad = sign * math.radians(angle_deg)
-
-    # Determine which vertices are on the "folding" side of the line
-    line_dir_2d = end - start
-    normal_2d = np.array([-line_dir_2d[1], line_dir_2d[0]])  # perpendicular
-
-    new_verts = state.vertices.copy()
-    for i, v in enumerate(new_verts):
-        point_2d = v[:2] - start
-        side = np.dot(point_2d, normal_2d)
-        if side > 1e-9:  # on the positive side → rotate
-            axis_point = np.array([start[0], start[1], 0.0])
-            axis_dir = np.array([line_dir_2d[0], line_dir_2d[1], 0.0])
-            new_verts[i] = _rotate_points(
-                v.reshape(1, -1), axis_point, axis_dir, angle_rad
-            ).flatten()
-
-    # Update bounding box (clamp near-zero values from floating point)
-    bb = np.ptp(new_verts, axis=0)  # max - min per axis
-    bb = np.where(np.abs(bb) < 1e-10, 0.0, bb)
-    # Add minimum thickness per layer (material thickness)
-    thickness = state.material.thickness_mm / 1000.0  # convert mm to m
-    num_layers = state.num_layers + 1
-    bb[2] = max(bb[2], thickness * num_layers)
-
-    # Mock strain: small random value per vertex
-    new_strain = np.random.uniform(0, 0.01, len(new_verts))
-
-    # Mock energy
-    new_energy = state.energy + 0.1 * angle_deg / 180.0
-
-    # Update assignments — add new edge as M or V
-    new_assignments = state.assignments.copy()
-
-    # Deployment ratio estimate: each full fold (180°) halves the area in one direction.
-    # Partial folds reduce proportionally. This is a mock approximation —
-    # the real engine will compute from actual face overlaps.
-    fold_factor = angle_deg / 180.0  # 1.0 for full fold, 0.5 for 90°, etc.
-    deploy_ratio = state.deployment_ratio * (1.0 - 0.5 * fold_factor)
-
-    new_state = PaperState(
-        vertices=new_verts,
-        edges=state.edges.copy(),
-        faces=state.faces.copy(),
-        assignments=new_assignments,
-        fold_angles=state.fold_angles.copy(),
-        rest_lengths=state.rest_lengths.copy(),
-        strain=new_strain,
-        energy=new_energy,
-        material=state.material,
-        bounding_box=bb,
-        deployment_ratio=deploy_ratio,
-        num_layers=state.num_layers + 1,
-        is_valid=True,
-        kawasaki_violation=0.0,
-        maekawa_violation=0.0,
-        self_intersections=0,
-    )
-    return new_state, None
-
-
-def execute_fold_strategy(strategy_fn, paper_state: PaperState,
-                          max_folds: int = 20) -> tuple[PaperState, list[dict], str | None]:
-    """
-    Execute a fold_strategy function against the mock environment.
-
-    Returns (final_state, applied_folds, error_or_None).
-    """
-    state_dict = paper_state.to_dict()
-    try:
-        folds = strategy_fn(state_dict)
-    except Exception as e:
-        return paper_state, [], f"Strategy function raised: {e}"
-
-    if not isinstance(folds, list):
-        return paper_state, [], "Strategy must return a list of fold dicts"
-
-    applied = []
-    current = paper_state
-    for i, fold in enumerate(folds):
-        if i >= max_folds:
-            break
-        if not isinstance(fold, dict):
-            return current, applied, f"Fold {i} is not a dict"
-
-        current, error = apply_fold_mock(current, fold)
-        if error:
-            return current, applied, f"Fold {i} failed: {error}"
-        applied.append(fold)
-
-    return current, applied, None

trainer/prompts.py

@@ -1,211 +0,0 @@
-"""
-Prompt templates for origami fold strategy generation.
-
-Inspired by SpatialThinker (arXiv 2511.07403): the model must produce
-a structured spatial representation BEFORE generating code.
-
-Output format (4 stages):
-  <observe>  — Describe the paper geometry and constraints
-  <plan>     — Structured fold plan with coordinates and reasoning
-  <code>     — The fold_strategy() function
-  <verify>   — Predict expected outcome (deployment ratio, fold count)
-
-Dense rewards check each stage independently, not just code execution.
-"""
-
-# ---------------------------------------------------------------------------
-# System prompt — defines the structured output format
-# ---------------------------------------------------------------------------
-
-SYSTEM_PROMPT = """\
-You are an origami engineer specializing in computational fold design.
-You solve folding tasks by reasoning spatially about paper geometry.
-
-You MUST respond in exactly this 4-stage format:
-
-<observe>
-Describe the paper: dimensions, material, coordinate system.
-Identify key geometric features (center, edges, diagonals, symmetry axes).
-Note constraints (max strain, max folds, target ratio).
-</observe>
-
-<plan>
-{
-  "strategy": "description of overall approach",
-  "folds": [
-    {
-      "description": "what this fold does",
-      "type": "valley or mountain",
-      "line_start": [x, y],
-      "line_end": [x, y],
-      "angle": 180,
-      "reasoning": "why these coordinates"
-    }
-  ],
-  "expected_ratio": 0.5,
-  "expected_folds": 1
-}
-</plan>
-
-<code>
-```python
-def fold_strategy(paper_state):
-    # Implementation matching the plan above
-    return [...]
-```
-</code>
-
-<verify>
-Expected deployment ratio: X.XX
-Expected fold count: N
-Expected max strain: X.XXXX
-Potential issues: ...
-</verify>
-
-Rules:
-- Only use native Python (no imports except math, itertools, functools)
-- Each fold: {"type": "valley"|"mountain", "line": {"start": [x,y], "end": [x,y]}, "angle": 0-180}
-- Fold lines must cross the paper boundary (intersect at least 2 edges)
-- Valley = fold toward you (+Z), Mountain = fold away (-Z)
-- angle=180 = fully folded, smaller = partial fold
-- Each fold changes the geometry — later folds operate on already-folded paper
-- Fewer folds is better (efficiency matters)
-- Respect material strain limits\
-"""
-
-
-# ---------------------------------------------------------------------------
-# Task templates — each includes spatial context
-# ---------------------------------------------------------------------------
-
-TASK_TEMPLATES = {
-    "half_fold": {
-        "name": "half_fold",
-        "prompt": """\
-TASK: Fold a {width}m x {height}m {material} sheet in half to minimize one dimension.
-
-PAPER GEOMETRY:
-  Corners: (0,0), ({width},0), ({width},{height}), (0,{height})
-  Center: ({cx},{cy})
-  Horizontal midline: y={cy} from (0,{cy}) to ({width},{cy})
-  Vertical midline: x={cx} from ({cx},0) to ({cx},{height})
-  Diagonals: (0,0)→({width},{height}) and ({width},0)→(0,{height})
-
-MATERIAL: {material} (thickness: {thickness_mm}mm, max strain: {max_strain_pct}%)
-CONSTRAINTS: Maximum {max_folds} fold operations.
-TARGET: Deployment ratio <= 0.5""",
-        "target_ratio": 0.5,
-        "max_folds": 3,
-    },
-
-    "letter_fold": {
-        "name": "letter_fold",
-        "prompt": """\
-TASK: Fold a {width}m x {height}m {material} sheet into thirds (like a letter).
-
-PAPER GEOMETRY:
-  Corners: (0,0), ({width},0), ({width},{height}), (0,{height})
-  Third lines: y={t1:.4f} and y={t2:.4f}
-  Center: ({cx},{cy})
-
-MATERIAL: {material} (thickness: {thickness_mm}mm, max strain: {max_strain_pct}%)
-CONSTRAINTS: Maximum {max_folds} fold operations.
-TARGET: Deployment ratio <= 0.33""",
-        "target_ratio": 0.33,
-        "max_folds": 5,
-    },
-
-    "solar_panel": {
-        "name": "solar_panel",
-        "prompt": """\
-TASK: Fold a {width}m x {height}m Mylar sheet to minimize packed volume for a solar panel.
-The folded panel must be deployable (unfold cleanly to near-original area).
-
-PAPER GEOMETRY:
-  Corners: (0,0), ({width},0), ({width},{height}), (0,{height})
-  Center: ({cx},{cy})
-  Area: {area}m²
-
-MATERIAL: Mylar (thickness: 0.05mm, Young's modulus: 4 GPa, max strain: 3%)
-CONSTRAINTS:
-  - Maximum {max_folds} fold operations
-  - Must pack into bounding box <= 15cm x 15cm x 5cm
-  - No self-intersections
-
-TARGET: Deployment ratio <= 0.05 (95% area reduction)
-
-HINT: Tessellated patterns (alternating M/V folds in a grid) achieve high
-compaction with single-DOF deployment. Consider dividing the sheet into
-a regular grid of panels.""",
-        "target_ratio": 0.05,
-        "max_folds": 20,
-    },
-
-    "stent_fold": {
-        "name": "stent_fold",
-        "prompt": """\
-TASK: Fold a {width}m x {height}m Nitinol sheet into a compact cylinder for a medical stent.
-
-PAPER GEOMETRY:
-  Corners: (0,0), ({width},0), ({width},{height}), (0,{height})
-  Center: ({cx},{cy})
-
-MATERIAL: Nitinol (thickness: 0.1mm, Young's modulus: 75 GPa, max strain: 8%)
-CONSTRAINTS:
-  - Maximum {max_folds} fold operations
-  - Compressed diameter: 3mm, Deployed diameter: 10mm
-
-TARGET: Deployment ratio <= 0.1""",
-        "target_ratio": 0.1,
-        "max_folds": 15,
-    },
-}
-
-
-# ---------------------------------------------------------------------------
-# Config and builders
-# ---------------------------------------------------------------------------
-
-TASK_CONFIGS = {
-    "half_fold": {
-        "width": 1.0, "height": 1.0, "material": "paper",
-        "thickness_mm": 0.1, "max_strain_pct": 3, "max_folds": 3,
-    },
-    "letter_fold": {
-        "width": 1.0, "height": 1.0, "material": "paper",
-        "thickness_mm": 0.1, "max_strain_pct": 3, "max_folds": 5,
-    },
-    "solar_panel": {
-        "width": 1.0, "height": 1.0, "material": "mylar",
-        "thickness_mm": 0.05, "max_strain_pct": 3, "max_folds": 20,
-    },
-    "stent_fold": {
-        "width": 0.1, "height": 0.03, "material": "nitinol",
-        "thickness_mm": 0.1, "max_strain_pct": 8, "max_folds": 15,
-    },
-}
-
-
-def build_prompt(task_name: str = "half_fold", **overrides) -> str:
-    """Build a complete user prompt for a given task."""
-    task = TASK_TEMPLATES[task_name]
-    config = {**TASK_CONFIGS[task_name], **overrides}
-
-    # Add computed geometry values
-    w = config["width"]
-    h = config["height"]
-    config["cx"] = w / 2
-    config["cy"] = h / 2
-    config["area"] = w * h
-    config["t1"] = h / 3
-    config["t2"] = 2 * h / 3
-
-    return task["prompt"].format(**config)
-
-
-def get_task_target_ratio(task_name: str) -> float:
-    return TASK_TEMPLATES[task_name]["target_ratio"]
-
-
-def get_task_max_folds(task_name: str) -> int:
-    return TASK_TEMPLATES[task_name]["max_folds"]

trainer/rewards.py

@@ -1,713 +0,0 @@
-"""
-Reward functions for origami GRPO training.
-
-SpatialThinker-style dense rewards (arXiv 2511.07403):
-  1. format_reward     (0.10) — All 4 tags present, valid JSON plan, valid function
-  2. spatial_reward    (0.20) — Fold coordinates in plan are within bounds, lines valid
-  3. execution_reward  (0.50) — Physical validity + fold quality (code execution)
-  4. consistency_reward(0.20) — Plan matches code, verify matches actual results
-
-Plus legacy rewards for backwards compatibility:
-  - code_valid, physically_valid, fold_quality
-
-Lexicographic gating: if code doesn't parse, downstream rewards are 0.
-"""
-
-import ast
-import re
-import sys
-import json
-import math
-import traceback
-from typing import Callable
-
-# Use real engine if available, fall back to mock
-try:
-    from engine.paper import Paper
-    from engine.fold_engine import execute_fold_strategy
-    from engine.materials import Material, get_material
-    from engine.validation import validate_paper
-    from engine.metrics import compute_metrics
-
-    def _create_sheet(width, height, material):
-        return Paper.create_flat_sheet(width, height, material)
-
-    USE_REAL_ENGINE = True
-except ImportError:
-    from trainer.mock_env import (
-        PaperState as Paper, create_flat_sheet, execute_fold_strategy, Material
-    )
-
-    def _create_sheet(width, height, material):
-        return create_flat_sheet(width, height, material)
-
-    def validate_paper(p):
-        from types import SimpleNamespace
-        return SimpleNamespace(
-            is_valid=p.is_valid, kawasaki_valid=True, maekawa_valid=True,
-            kawasaki_violation=p.kawasaki_violation,
-            maekawa_violation=p.maekawa_violation,
-            self_intersection_count=p.self_intersections,
-        )
-
-    def compute_metrics(p, orig):
-        return {
-            "deployment_ratio": p.deployment_ratio,
-            "fold_count": sum(1 for a in p.assignments if a in ("M", "V")),
-            "max_strain": float(p.strain.max()) if len(p.strain) > 0 else 0.0,
-        }
-
-    USE_REAL_ENGINE = False
-
-
-# ---------------------------------------------------------------------------
-# Helpers
-# ---------------------------------------------------------------------------
-
-def extract_function(text: str) -> str | None:
-    """Extract fold_strategy() from <code> blocks or triple-backtick code blocks."""
-    # Try <code> block first (SpatialThinker format)
-    code_match = re.search(r'<code>(.*?)</code>', text, re.DOTALL)
-    if code_match:
-        code_block = code_match.group(1).strip()
-    elif text.count("```") >= 2:
-        first = text.find("```") + 3
-        second = text.find("```", first)
-        code_block = text[first:second].strip()
-    else:
-        return None
-
-    code_block = code_block.removeprefix("```python\n").removeprefix("```python\r\n")
-    code_block = code_block.removeprefix("python\n").removeprefix("python\r\n")
-    code_block = code_block.rstrip("`").strip()
-
-    # Find the def statement
-    def_idx = code_block.find("def ")
-    if def_idx == -1:
-        return None
-    fx = code_block[def_idx:]
-    if fx.startswith("def fold_strategy("):
-        return fx
-    return None
-
-
-def extract_section(text: str, tag: str) -> str | None:
-    """Extract content between <tag>...</tag>."""
-    match = re.search(rf'<{tag}>(.*?)</{tag}>', text, re.DOTALL)
-    return match.group(1).strip() if match else None
-
-
-def extract_plan_json(text: str) -> dict | None:
-    """Extract and parse the JSON fold plan from <plan> block."""
-    plan_text = extract_section(text, "plan")
-    if not plan_text:
-        return None
-    try:
-        return json.loads(plan_text)
-    except json.JSONDecodeError:
-        # Try to find JSON object within the plan text
-        brace_start = plan_text.find("{")
-        brace_end = plan_text.rfind("}")
-        if brace_start >= 0 and brace_end > brace_start:
-            try:
-                return json.loads(plan_text[brace_start:brace_end + 1])
-            except json.JSONDecodeError:
-                pass
-    return None
-
-
-def check_imports_stdlib_only(code: str) -> tuple[bool, str]:
-    """Check that code only imports from Python stdlib."""
-    try:
-        tree = ast.parse(code)
-    except SyntaxError as e:
-        return False, f"syntax error: {e}"
-
-    ALLOWED_MODULES = {
-        "math", "itertools", "functools", "collections", "copy",
-        "operator", "typing", "random", "heapq", "bisect",
-    }
-
-    for node in ast.walk(tree):
-        if isinstance(node, ast.Import):
-            for alias in node.names:
-                root = alias.name.split(".")[0]
-                if root not in ALLOWED_MODULES:
-                    return False, f"non-stdlib import: {alias.name}"
-        elif isinstance(node, ast.ImportFrom):
-            if node.module:
-                root = node.module.split(".")[0]
-                if root not in ALLOWED_MODULES:
-                    return False, f"non-stdlib import: {node.module}"
-
-    return True, "ok"
-
-
-def create_sandboxed_function(code: str) -> Callable:
-    """
-    Execute the function code in a restricted namespace.
-    Returns the fold_strategy function object.
-    """
-    allowed_builtins = {
-        "range", "len", "int", "float", "str", "list", "dict", "tuple",
-        "set", "bool", "abs", "min", "max", "sum", "sorted", "reversed",
-        "enumerate", "zip", "map", "filter", "round", "isinstance",
-        "True", "False", "None", "print",
-    }
-    safe_builtins = {k: __builtins__[k] if isinstance(__builtins__, dict)
-                     else getattr(__builtins__, k)
-                     for k in allowed_builtins
-                     if (k in __builtins__ if isinstance(__builtins__, dict)
-                         else hasattr(__builtins__, k))}
-    safe_builtins["__import__"] = __import__  # needed for stdlib imports
-
-    namespace = {"__builtins__": safe_builtins}
-    exec(code, namespace)
-
-    if "fold_strategy" not in namespace:
-        raise ValueError("No fold_strategy function defined")
-
-    return namespace["fold_strategy"]
-
-
-# ---------------------------------------------------------------------------
-# State for strategy execution
-# ---------------------------------------------------------------------------
-
-# Current task config (set by train.py before training starts)
-if USE_REAL_ENGINE:
-    _default_material = get_material("paper")
-else:
-    _default_material = Material()
-
-_current_task = {
-    "width": 1.0,
-    "height": 1.0,
-    "material": _default_material,
-    "target_ratio": 0.5,
-    "max_folds": 3,
-}
-
-PRINT_EVERY = 5
-_print_counter = 0
-
-
-def set_task_config(width=1.0, height=1.0, material=None,
-                    target_ratio=0.5, max_folds=3):
-    global _current_task
-    _current_task = {
-        "width": width,
-        "height": height,
-        "material": material or Material(),
-        "target_ratio": target_ratio,
-        "max_folds": max_folds,
-    }
-
-
-# ---------------------------------------------------------------------------
-# Reward 1: code_valid
-# ---------------------------------------------------------------------------
-
-def code_valid(completions, **kwargs) -> list[float]:
-    """
-    Does the generated code parse as valid Python and produce a callable?
-
-    +1.0  — valid function that can be created
-    -0.5  — correct structure but exec/sandbox fails
-    -2.0  — no function found or syntax error
-    -20.0 — non-stdlib imports (heavy penalty)
-    """
-    scores = []
-    for completion in completions:
-        response = completion[0]["content"]
-        function_code = extract_function(response)
-
-        if function_code is None:
-            scores.append(-2.0)
-            continue
-
-        ok, info = check_imports_stdlib_only(function_code)
-        if not ok:
-            if "syntax error" in info:
-                scores.append(-2.0)
-            else:
-                scores.append(-20.0)  # non-stdlib imports
-            continue
-
-        try:
-            create_sandboxed_function(function_code)
-            scores.append(1.0)
-        except Exception:
-            scores.append(-0.5)
-
-    return scores
-
-
-# ---------------------------------------------------------------------------
-# Reward 2: physically_valid
-# ---------------------------------------------------------------------------
-
-def physically_valid(completions, **kwargs) -> list[float]:
-    """
-    Are the folds physically possible?
-
-    +1.0  — all folds valid, no violations
-    -2.0  — per Kawasaki/Maekawa violation
-    -5.0  — any self-intersection
-    -1.0  — strain exceeds material limit
-     0.0  — function broken / can't run
-    """
-    scores = []
-    for completion in completions:
-        response = completion[0]["content"]
-        function_code = extract_function(response)
-
-        if function_code is None:
-            scores.append(0.0)
-            continue
-
-        ok, info = check_imports_stdlib_only(function_code)
-        if not ok:
-            scores.append(0.0)
-            continue
-
-        try:
-            strategy_fn = create_sandboxed_function(function_code)
-        except Exception:
-            scores.append(0.0)
-            continue
-
-        try:
-            paper = _create_sheet(
-                _current_task["width"],
-                _current_task["height"],
-                _current_task["material"],
-            )
-            original = paper
-            final_state, applied, error = execute_fold_strategy(
-                strategy_fn, paper, _current_task["max_folds"]
-            )
-
-            if error:
-                scores.append(0.0)
-                continue
-
-            if len(applied) == 0:
-                scores.append(0.0)
-                continue
-
-            # Score based on validity using engine validation
-            val = validate_paper(final_state)
-            metrics = compute_metrics(final_state, original)
-
-            score = 1.0
-            score -= 2.0 * val.kawasaki_violation
-            score -= 2.0 * val.maekawa_violation
-            if val.self_intersection_count > 0:
-                score -= 5.0
-            max_strain = metrics.get("max_strain", 0.0)
-            if max_strain > _current_task["material"].max_strain:
-                score -= 1.0
-
-            scores.append(score)
-
-        except TimeoutError:
-            scores.append(-1.0)
-        except Exception:
-            scores.append(0.0)
-
-    return scores
-
-
-# ---------------------------------------------------------------------------
-# Reward 3: fold_quality
-# ---------------------------------------------------------------------------
-
-def fold_quality(completions, **kwargs) -> list[float]:
-    """
-    How good is the folding solution?
-
-    +20.0 * compactness — main reward (1 - deployment_ratio)
-    +10.0 bonus         — if meets target ratio
-    -0.5 per fold       — efficiency penalty
-    -3.0 * overstrain   — material stress penalty
-    -1.0                — timeout
-    -3.0                — exception
-     0.0                — function broken
-    """
-    global _print_counter
-    scores = []
-
-    for completion in completions:
-        response = completion[0]["content"]
-        function_code = extract_function(response)
-
-        should_print = (_print_counter % PRINT_EVERY == 0)
-        _print_counter += 1
-
-        if should_print:
-            print(f"\n--- Strategy (sample {_print_counter}) ---")
-            print(function_code if function_code else "[no function extracted]")
-
-        if function_code is None:
-            scores.append(0.0)
-            continue
-
-        ok, info = check_imports_stdlib_only(function_code)
-        if not ok:
-            scores.append(0.0)
-            continue
-
-        try:
-            strategy_fn = create_sandboxed_function(function_code)
-        except Exception:
-            scores.append(0.0)
-            continue
-
-        try:
-            paper = _create_sheet(
-                _current_task["width"],
-                _current_task["height"],
-                _current_task["material"],
-            )
-            original = paper
-            final_state, applied, error = execute_fold_strategy(
-                strategy_fn, paper, _current_task["max_folds"]
-            )
-
-            if error:
-                if should_print:
-                    print(f"Error: {error}")
-                scores.append(0.0)
-                continue
-
-            num_folds = len(applied)
-            if num_folds == 0:
-                scores.append(0.0)
-                continue
-
-            # Use engine metrics
-            metrics = compute_metrics(final_state, original)
-            deploy_ratio = metrics.get("deployment_ratio", 1.0)
-            max_strain = metrics.get("max_strain", 0.0)
-
-            # Compactness: main reward signal
-            compactness = 1.0 - deploy_ratio
-            score = 20.0 * compactness
-
-            # Bonus for meeting target
-            if deploy_ratio <= _current_task["target_ratio"]:
-                score += 10.0
-
-            # Fold efficiency penalty
-            score -= 0.5 * num_folds
-
-            # Strain penalty
-            mat_limit = _current_task["material"].max_strain
-            if max_strain > mat_limit:
-                score -= 3.0 * (max_strain / mat_limit)
-
-            if should_print:
-                print(f"Folds: {num_folds}, Ratio: {deploy_ratio:.3f}, "
-                      f"Compactness: {compactness:.3f}, Score: {score:.2f}")
-                bb = metrics.get("bounding_box", {})
-                print(f"BBox: {bb.get('x',0):.3f} x {bb.get('y',0):.3f} x {bb.get('z',0):.3f}")
-
-            scores.append(score)
-
-        except TimeoutError:
-            if should_print:
-                print("Timeout!")
-            scores.append(-1.0)
-        except Exception as e:
-            if should_print:
-                print(f"Exception: {e}")
-            scores.append(-3.0)
-
-    return scores
-
-
-# ---------------------------------------------------------------------------
-# SpatialThinker Dense Rewards (weight 0.10 + 0.20 + 0.50 + 0.20 = 1.0)
-# ---------------------------------------------------------------------------
-
-REQUIRED_TAGS = ["observe", "plan", "code", "verify"]
-
-
-def format_reward(completions, **kwargs) -> list[float]:
-    """
-    SpatialThinker format reward (weight: 0.10).
-
-    Checks that the response has all 4 structured tags, valid JSON in <plan>,
-    and a parseable function in <code>.
-
-    Score range: [0.0, 1.0]
-    """
-    scores = []
-    for completion in completions:
-        response = completion[0]["content"]
-        score = 0.0
-
-        # Check each required tag (0.15 each = 0.60 for all 4)
-        tags_present = 0
-        for tag in REQUIRED_TAGS:
-            if extract_section(response, tag) is not None:
-                tags_present += 1
-        score += 0.15 * tags_present
-
-        # Valid JSON in <plan> (0.20)
-        plan = extract_plan_json(response)
-        if plan is not None:
-            score += 0.20
-            # Plan has required fields (0.05 bonus)
-            if "folds" in plan and isinstance(plan["folds"], list):
-                score += 0.05
-
-        # Valid function in <code> (0.15)
-        fn = extract_function(response)
-        if fn is not None:
-            score += 0.15
-
-        scores.append(score)
-    return scores
-
-
-def spatial_reward(completions, **kwargs) -> list[float]:
-    """
-    SpatialThinker spatial plan quality reward (weight: 0.20).
-
-    Checks that fold coordinates in <plan> are geometrically valid:
-    - Within paper bounds
-    - Line endpoints form valid fold lines (cross the paper)
-    - Fold types are valid
-    - Expected ratio/count are reasonable
-
-    Score range: [0.0, 1.0]
-    """
-    w = _current_task["width"]
-    h = _current_task["height"]
-
-    scores = []
-    for completion in completions:
-        response = completion[0]["content"]
-        plan = extract_plan_json(response)
-
-        if plan is None:
-            scores.append(0.0)
-            continue
-
-        score = 0.0
-        folds = plan.get("folds", [])
-
-        if not folds:
-            scores.append(0.0)
-            continue
-
-        # Score each fold in the plan
-        valid_folds = 0
-        for fold in folds:
-            fold_score = 0.0
-
-            # Has required fields
-            has_type = fold.get("type") in ("valley", "mountain")
-            has_start = isinstance(fold.get("line_start"), list) and len(fold.get("line_start", [])) == 2
-            has_end = isinstance(fold.get("line_end"), list) and len(fold.get("line_end", [])) == 2
-
-            if has_type:
-                fold_score += 0.25
-            if has_start and has_end:
-                fold_score += 0.25
-                # Coordinates within paper bounds (with small tolerance)
-                sx, sy = fold["line_start"]
-                ex, ey = fold["line_end"]
-                tol = 0.01
-                in_bounds = (
-                    -tol <= sx <= w + tol and -tol <= sy <= h + tol and
-                    -tol <= ex <= w + tol and -tol <= ey <= h + tol
-                )
-                if in_bounds:
-                    fold_score += 0.25
-
-                # Start != end (not a degenerate line)
-                dist = math.sqrt((ex - sx)**2 + (ey - sy)**2)
-                if dist > 0.01:
-                    fold_score += 0.25
-
-            if fold_score > 0.5:
-                valid_folds += 1
-
-        # Proportion of valid folds
-        score = valid_folds / len(folds) if folds else 0.0
-
-        # Bonus: expected_ratio is reasonable (0.0 to 1.0)
-        expected = plan.get("expected_ratio")
-        if isinstance(expected, (int, float)) and 0.0 < expected <= 1.0:
-            score = min(1.0, score + 0.1)
-
-        scores.append(min(1.0, score))
-    return scores
-
-
-def execution_reward(completions, **kwargs) -> list[float]:
-    """
-    SpatialThinker execution/accuracy reward (weight: 0.50).
-
-    Combines code validity, physical validity, and fold quality into
-    one normalized score. This is the main reward signal.
-
-    Score range: [0.0, 1.0]
-    """
-    scores = []
-    for completion in completions:
-        response = completion[0]["content"]
-        function_code = extract_function(response)
-
-        # Gate: no function → 0
-        if function_code is None:
-            scores.append(0.0)
-            continue
-
-        ok, info = check_imports_stdlib_only(function_code)
-        if not ok:
-            scores.append(0.0)
-            continue
-
-        try:
-            strategy_fn = create_sandboxed_function(function_code)
-        except Exception:
-            scores.append(0.0)
-            continue
-
-        try:
-            paper = _create_sheet(
-                _current_task["width"],
-                _current_task["height"],
-                _current_task["material"],
-            )
-            original = paper
-            final_state, applied, error = execute_fold_strategy(
-                strategy_fn, paper, _current_task["max_folds"]
-            )
-
-            if error or len(applied) == 0:
-                scores.append(0.0)
-                continue
-
-            val = validate_paper(final_state)
-            metrics = compute_metrics(final_state, original)
-            deploy_ratio = metrics.get("deployment_ratio", 1.0)
-            max_strain = metrics.get("max_strain", 0.0)
-
-            # Physical validity component (0-0.3)
-            phys = 0.3
-            if not val.is_valid:
-                phys -= 0.1 * val.kawasaki_violation
-                phys -= 0.1 * val.maekawa_violation
-                if val.self_intersection_count > 0:
-                    phys -= 0.15
-            mat_limit = _current_task["material"].max_strain
-            if max_strain > mat_limit:
-                phys -= 0.05
-            phys = max(0.0, phys)
-
-            # Quality component (0-0.5)
-            compactness = 1.0 - deploy_ratio
-            quality = 0.5 * compactness
-
-            # Target bonus (0-0.2)
-            target = 0.0
-            if deploy_ratio <= _current_task["target_ratio"]:
-                target = 0.2
-
-            score = phys + quality + target
-            scores.append(min(1.0, score))
-
-        except Exception:
-            scores.append(0.0)
-
-    return scores
-
-
-def consistency_reward(completions, **kwargs) -> list[float]:
-    """
-    SpatialThinker consistency reward (weight: 0.20).
-
-    Checks that <plan> matches <code> and <verify> matches actual results.
-    - Plan fold count matches code fold count
-    - Verify predictions close to actual metrics
-
-    Score range: [0.0, 1.0]
-    """
-    scores = []
-    for completion in completions:
-        response = completion[0]["content"]
-        plan = extract_plan_json(response)
-        verify = extract_section(response, "verify")
-        function_code = extract_function(response)
-
-        # Need at least plan + code to check consistency
-        if plan is None or function_code is None:
-            scores.append(0.0)
-            continue
-
-        score = 0.0
-
-        # 1. Plan fold count vs code fold count (0.4)
-        plan_folds = plan.get("folds", [])
-        plan_count = len(plan_folds)
-
-        try:
-            strategy_fn = create_sandboxed_function(function_code)
-            paper = _create_sheet(
-                _current_task["width"],
-                _current_task["height"],
-                _current_task["material"],
-            )
-            original = paper
-            final_state, applied, error = execute_fold_strategy(
-                strategy_fn, paper, _current_task["max_folds"]
-            )
-            if error or len(applied) == 0:
-                scores.append(0.0)
-                continue
-
-            actual_count = len(applied)
-            if plan_count == actual_count:
-                score += 0.4
-            elif abs(plan_count - actual_count) <= 1:
-                score += 0.2
-
-            # 2. Verify predictions vs actual (0.6)
-            if verify:
-                metrics = compute_metrics(final_state, original)
-                actual_ratio = metrics.get("deployment_ratio", 1.0)
-
-                # Extract predicted ratio from verify text
-                ratio_match = re.search(
-                    r'deployment\s*ratio[:\s]*([\d.]+)', verify, re.IGNORECASE)
-                if ratio_match:
-                    predicted_ratio = float(ratio_match.group(1))
-                    error_pct = abs(predicted_ratio - actual_ratio)
-                    if error_pct < 0.05:
-                        score += 0.4
-                    elif error_pct < 0.15:
-                        score += 0.2
-                    elif error_pct < 0.3:
-                        score += 0.1
-
-                # Extract predicted fold count
-                count_match = re.search(
-                    r'fold\s*count[:\s]*(\d+)', verify, re.IGNORECASE)
-                if count_match:
-                    predicted_count = int(count_match.group(1))
-                    if predicted_count == actual_count:
-                        score += 0.2
-                    elif abs(predicted_count - actual_count) <= 1:
-                        score += 0.1
-
-        except Exception:
-            scores.append(0.0)
-            continue
-
-        scores.append(min(1.0, score))
-    return scores

trainer/train.py

@@ -1,215 +0,0 @@
-"""
-Origami GRPO Training Script
-
-Usage (Colab with T4/A100):
-    python trainer/train.py
-
-Or in a notebook:
-    %run trainer/train.py
-
-Requires: unsloth, trl>=0.22.2, transformers>=4.56.2, trackio, datasets
-"""
-
-import os
-import sys
-
-# Ensure project root is on path
-PROJECT_ROOT = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
-if PROJECT_ROOT not in sys.path:
-    sys.path.insert(0, PROJECT_ROOT)
-
-from trainer.prompts import build_prompt, SYSTEM_PROMPT, get_task_target_ratio, get_task_max_folds
-from trainer.rewards import (
-    code_valid, physically_valid, fold_quality, set_task_config,
-    format_reward, spatial_reward, execution_reward, consistency_reward,
-)
-
-try:
-    from engine.materials import get_material
-    Material = type(get_material("paper"))  # get the Material class
-except ImportError:
-    from trainer.mock_env import Material
-    def get_material(name):
-        return Material()
-
-# ============================================================================
-# Config
-# ============================================================================
-
-MODEL_NAME = "unsloth/Qwen2.5-7B-Instruct"
-MAX_SEQ_LENGTH = 2048
-LORA_RANK = 4
-
-# Start with the simplest task
-TASK_NAME = "half_fold"
-
-# GRPO hyperparameters (from 2048 reference, adapted for origami)
-LEARNING_RATE = 2e-4
-MAX_STEPS = 600
-NUM_GENERATIONS = 2
-TEMPERATURE = 1.0
-BATCH_SIZE = 1
-GRAD_ACCUM = 1
-DATASET_SIZE = 1000  # replicated prompt dataset
-
-
-def main():
-    # ========================================================================
-    # 1. Load model with Unsloth
-    # ========================================================================
-    from unsloth import FastLanguageModel
-
-    print(f"Loading model: {MODEL_NAME}")
-    model, tokenizer = FastLanguageModel.from_pretrained(
-        model_name=MODEL_NAME,
-        load_in_4bit=True,
-        max_seq_length=MAX_SEQ_LENGTH,
-    )
-
-    # ========================================================================
-    # 2. Apply LoRA adapters
-    # ========================================================================
-    model = FastLanguageModel.get_peft_model(
-        model,
-        r=LORA_RANK,
-        target_modules=[
-            "q_proj", "k_proj", "v_proj", "o_proj",
-            "gate_proj", "up_proj", "down_proj",
-        ],
-        lora_alpha=LORA_RANK * 2,
-        use_gradient_checkpointing="unsloth",
-        random_state=3407,
-    )
-
-    # ========================================================================
-    # 3. Build prompt and dataset
-    # ========================================================================
-    user_prompt = build_prompt(TASK_NAME)
-    target_ratio = get_task_target_ratio(TASK_NAME)
-    max_folds = get_task_max_folds(TASK_NAME)
-
-    # Configure reward functions with task parameters
-    set_task_config(
-        width=1.0,
-        height=1.0,
-        material=get_material("paper"),
-        target_ratio=target_ratio,
-        max_folds=max_folds,
-    )
-
-    # Create replicated prompt dataset (same pattern as 2048)
-    from datasets import Dataset
-
-    dataset = Dataset.from_list([
-        {
-            "prompt": [
-                {"role": "system", "content": SYSTEM_PROMPT},
-                {"role": "user", "content": user_prompt},
-            ],
-        }
-    ] * DATASET_SIZE)
-
-    # Calculate prompt token length for max_completion_length
-    prompt_tokens = tokenizer.apply_chat_template(
-        [
-            {"role": "system", "content": SYSTEM_PROMPT},
-            {"role": "user", "content": user_prompt},
-        ],
-        add_generation_prompt=True,
-        tokenize=True,
-    )
-    max_prompt_length = len(prompt_tokens) + 1
-    max_completion_length = MAX_SEQ_LENGTH - max_prompt_length
-    print(f"Prompt tokens: {max_prompt_length}, Max completion: {max_completion_length}")
-
-    # ========================================================================
-    # 4. Test inference before training
-    # ========================================================================
-    print("\n=== Pre-training inference test ===")
-    text = tokenizer.apply_chat_template(
-        [
-            {"role": "system", "content": SYSTEM_PROMPT},
-            {"role": "user", "content": user_prompt},
-        ],
-        tokenize=False,
-        add_generation_prompt=True,
-    )
-
-    from transformers import TextStreamer
-    _ = model.generate(
-        **tokenizer(text, return_tensors="pt").to("cuda"),
-        temperature=TEMPERATURE,
-        max_new_tokens=min(512, max_completion_length),
-        streamer=TextStreamer(tokenizer, skip_prompt=True),
-    )
-
-    # ========================================================================
-    # 5. Configure GRPO training
-    # ========================================================================
-    from trl import GRPOConfig, GRPOTrainer
-
-    training_args = GRPOConfig(
-        temperature=TEMPERATURE,
-        learning_rate=LEARNING_RATE,
-        weight_decay=0.001,
-        warmup_ratio=0.1,
-        lr_scheduler_type="linear",
-        optim="adamw_8bit",
-        logging_steps=1,
-        per_device_train_batch_size=BATCH_SIZE,
-        gradient_accumulation_steps=GRAD_ACCUM,
-        num_generations=NUM_GENERATIONS,
-        max_prompt_length=max_prompt_length,
-        max_completion_length=max_completion_length,
-        max_steps=MAX_STEPS,
-        save_steps=100,
-        report_to="trackio",
-        output_dir="outputs",
-    )
-
-    # ========================================================================
-    # 6. Create trainer and start training
-    # ========================================================================
-    # SpatialThinker dense rewards (weighted: 0.10 + 0.20 + 0.50 + 0.20)
-    # These replace the legacy 3-reward setup with structured spatial reasoning
-    trainer = GRPOTrainer(
-        model=model,
-        processing_class=tokenizer,
-        reward_funcs=[
-            format_reward,       # 0.10 — 4-stage format compliance
-            spatial_reward,      # 0.20 — fold plan geometric validity
-            execution_reward,    # 0.50 — code execution + physical quality
-            consistency_reward,  # 0.20 — plan↔code↔verify agreement
-        ],
-        reward_weights=[0.10, 0.20, 0.50, 0.20],
-        args=training_args,
-        train_dataset=dataset,
-    )
-
-    print(f"\n=== Starting GRPO training: {TASK_NAME} ===")
-    print(f"Steps: {MAX_STEPS}, Generations: {NUM_GENERATIONS}, LR: {LEARNING_RATE}")
-    trainer.train()
-
-    # ========================================================================
-    # 7. Post-training inference
-    # ========================================================================
-    print("\n=== Post-training inference ===")
-    _ = model.generate(
-        **tokenizer(text, return_tensors="pt").to("cuda"),
-        temperature=TEMPERATURE,
-        max_new_tokens=min(1024, max_completion_length),
-        streamer=TextStreamer(tokenizer, skip_prompt=True),
-    )
-
-    # ========================================================================
-    # 8. Save model (optional)
-    # ========================================================================
-    save_path = "outputs/origami-fold-lora"
-    print(f"\nSaving LoRA adapter to {save_path}")
-    model.save_pretrained(save_path)
-    tokenizer.save_pretrained(save_path)
-    print("Done!")
-
-
-if __name__ == "__main__":
-    main()

training/demo.py

@@ -1,251 +0,0 @@
-"""
-training/demo.py — Run 8 zero-shot rollouts and stream them to the grid viewer.
-
-Usage:
-    cd /path/to/optigami
-    python -m training.demo
-
-Then open: http://localhost:9001/viewer/training.html
-
-Each of the 8 "strategies" is a heuristic that mimics what a pretrained LLM might
-produce for different tasks — varying from near-optimal to poor.  This exercises
-the full broadcast → grid viewer pipeline without requiring an LLM API key.
-"""
-from __future__ import annotations
-
-import asyncio
-import time
-import uuid
-from typing import Callable
-
-import uvicorn
-
-from server.app import app, broadcast
-from training.runner import run_batch
-
-
-# ── 8 zero-shot heuristic strategies ──────────────────────────────────────────
-# Each is a callable: paper_state (dict) → fold_dict
-# These represent the range of strategies a pretrained LLM might generate.
-
-def strategy_perfect_half(paper_state: dict) -> dict:
-    """Valley fold exactly at horizontal midline — optimal for half_fold."""
-    return {"type": "valley", "line": {"start": [0.0, 0.5], "end": [1.0, 0.5]}, "angle": 180.0}
-
-
-def strategy_slight_offset(paper_state: dict) -> dict:
-    """Valley fold slightly off-center — almost optimal."""
-    return {"type": "valley", "line": {"start": [0.0, 0.48], "end": [1.0, 0.48]}, "angle": 180.0}
-
-
-def strategy_thirds(paper_state: dict) -> dict:
-    """Letter fold at one-third — wrong for half_fold, generates interesting geometry."""
-    fold_count = paper_state.get("fold_count", 0)
-    positions = [0.333, 0.667]
-    if fold_count >= len(positions):
-        return {"type": "stop", "line": {"start": [0.0, 0.5], "end": [1.0, 0.5]}, "angle": 0.0}
-    return {
-        "type": "valley" if fold_count == 0 else "mountain",
-        "line": {"start": [0.0, positions[fold_count]], "end": [1.0, positions[fold_count]]},
-        "angle": 180.0,
-    }
-
-
-def strategy_vertical(paper_state: dict) -> dict:
-    """Vertical fold — gets compactness but in wrong dimension for target_box."""
-    return {"type": "valley", "line": {"start": [0.5, 0.0], "end": [0.5, 1.0]}, "angle": 180.0}
-
-
-def strategy_mountain(paper_state: dict) -> dict:
-    """Mountain fold at midline — same geometry, different assignment."""
-    return {"type": "mountain", "line": {"start": [0.0, 0.5], "end": [1.0, 0.5]}, "angle": 180.0}
-
-
-def strategy_accordion(paper_state: dict) -> dict:
-    """Accordion 3-fold — overfolds, achieves high compactness but more folds."""
-    fold_count = paper_state.get("fold_count", 0)
-    positions = [0.25, 0.5, 0.75]
-    assignments = ["valley", "mountain", "valley"]
-    if fold_count >= len(positions):
-        return {"type": "stop", "line": {"start": [0.0, 0.5], "end": [1.0, 0.5]}, "angle": 0.0}
-    return {
-        "type": assignments[fold_count],
-        "line": {"start": [0.0, positions[fold_count]], "end": [1.0, positions[fold_count]]},
-        "angle": 180.0,
-    }
-
-
-def strategy_diagonal(paper_state: dict) -> dict:
-    """Diagonal fold — achieves compactness but irregular bounding box."""
-    return {"type": "valley", "line": {"start": [0.0, 0.0], "end": [1.0, 1.0]}, "angle": 180.0}
-
-
-def strategy_quarter(paper_state: dict) -> dict:
-    """Two perpendicular folds — 4x compactness for quarter_fold task."""
-    fold_count = paper_state.get("fold_count", 0)
-    if fold_count == 0:
-        return {"type": "valley", "line": {"start": [0.0, 0.5], "end": [1.0, 0.5]}, "angle": 180.0}
-    if fold_count == 1:
-        return {"type": "valley", "line": {"start": [0.5, 0.0], "end": [0.5, 1.0]}, "angle": 180.0}
-    return {"type": "stop", "line": {"start": [0.0, 0.5], "end": [1.0, 0.5]}, "angle": 0.0}
-
-
-STRATEGIES: list[tuple[str, Callable]] = [
-    ("perfect_half",  strategy_perfect_half),
-    ("slight_offset", strategy_slight_offset),
-    ("thirds_fold",   strategy_thirds),
-    ("vertical_fold", strategy_vertical),
-    ("mountain_fold", strategy_mountain),
-    ("accordion_3",   strategy_accordion),
-    ("diagonal",      strategy_diagonal),
-    ("quarter_fold",  strategy_quarter),
-]
-
-
-# ── Demo runner ────────────────────────────────────────────────────────────────
-
-async def run_demo(task_name: str = "half_fold", delay_s: float = 0.5) -> None:
-    """Wait for server to be ready, then fire 8 episodes."""
-    # Give uvicorn time to bind and call startup hook (sets broadcast._loop)
-    await asyncio.sleep(1.5)
-
-    batch_id = 1
-    names, fns = zip(*STRATEGIES)
-    ep_ids = [f"ep_{name}" for name in names]
-
-    print(f"\n[demo] Starting batch {batch_id} — task: {task_name}")
-    print(f"[demo] Open http://localhost:9001/viewer/training.html\n")
-
-    # Signal grid to clear and show G=8
-    await broadcast.start_batch(batch_id, len(fns))
-
-    await asyncio.sleep(delay_s)
-
-    # Run all 8 episodes in the thread pool; broadcast_fn fires into this loop
-    results = await asyncio.gather(*[
-        asyncio.to_thread(
-            _run_one,
-            fn,
-            task_name,
-            ep_id,
-            broadcast.publish,
-        )
-        for fn, ep_id in zip(fns, ep_ids)
-    ])
-
-    scores = [r["score"] for r in results]
-    best_idx = max(range(len(scores)), key=lambda i: scores[i])
-
-    await broadcast.finish_batch(batch_id, scores, best_episode_id=ep_ids[best_idx])
-
-    print("\n[demo] Results:")
-    for name, result in zip(names, results):
-        print(f"  {name:20s}  score={result['score']:+.2f}  status={result['status']}")
-    print(f"\n[demo] Best: {names[best_idx]} (score={scores[best_idx]:+.2f})")
-    print("\n[demo] Grid viewer running. Press Ctrl+C to stop.\n")
-
-
-def _run_one(
-    strategy_fn: Callable,
-    task_name: str,
-    ep_id: str,
-    broadcast_fn: Callable,
-) -> dict:
-    """Thin wrapper: adds a small sleep between steps so the viewer can animate."""
-    from server.models import OrigamiAction
-    from server.origami_environment import OrigamiEnvironment
-
-    env = OrigamiEnvironment()
-    obs = env.reset(task_name=task_name)
-
-    broadcast_fn(ep_id, {
-        "type": "episode_update",
-        "episode_id": ep_id,
-        "task_name": task_name,
-        "step": 0,
-        "observation": _obs_dict(obs),
-    })
-
-    max_steps = env._task.get("max_folds", 10) if env._task else 10
-    status = "done"
-
-    for step_idx in range(max_steps):
-        if obs.done:
-            break
-
-        time.sleep(0.3)  # pace so the viewer can animate each step
-
-        fold_dict = strategy_fn(obs.paper_state)
-
-        if fold_dict.get("type") == "stop":
-            break
-
-        action = OrigamiAction(
-            fold_type=fold_dict["type"],
-            fold_line=fold_dict["line"],
-            fold_angle=float(fold_dict.get("angle", 180.0)),
-        )
-        obs = env.step(action)
-
-        broadcast_fn(ep_id, {
-            "type": "episode_update",
-            "episode_id": ep_id,
-            "task_name": task_name,
-            "step": step_idx + 1,
-            "observation": _obs_dict(obs),
-        })
-
-        if obs.done:
-            break
-    else:
-        status = "timeout"
-
-    score = obs.reward if obs.reward is not None else env._total_reward or 0.0
-
-    broadcast_fn(ep_id, {
-        "type": "episode_done",
-        "episode_id": ep_id,
-        "status": status,
-        "score": float(score),
-        "final_metrics": obs.metrics,
-    })
-
-    return {
-        "episode_id": ep_id,
-        "score": float(score),
-        "final_metrics": obs.metrics,
-        "status": status,
-    }
-
-
-def _obs_dict(obs) -> dict:
-    try:
-        return obs.model_dump()
-    except AttributeError:
-        return {
-            "paper_state": getattr(obs, "paper_state", {}),
-            "metrics": getattr(obs, "metrics", {}),
-            "fold_history": getattr(obs, "fold_history", []),
-            "done": getattr(obs, "done", False),
-            "reward": getattr(obs, "reward", None),
-        }
-
-
-# ── Entry point ────────────────────────────────────────────────────────────────
-
-async def _main() -> None:
-    config = uvicorn.Config(app, host="0.0.0.0", port=9001, log_level="warning")
-    server = uvicorn.Server(config)
-
-    # Run demo concurrently with the uvicorn server
-    await asyncio.gather(
-        server.serve(),
-        run_demo(task_name="half_fold"),
-    )
-
-
-if __name__ == "__main__":
-    try:
-        asyncio.run(_main())
-    except KeyboardInterrupt:
-        print("\n[demo] Stopped.")

training/demo_llm.py

@@ -1,318 +0,0 @@
-"""
-training/demo_llm.py — 8 rollouts using Claude as the zero-shot fold strategist.
-
-Usage:
-    cd /path/to/optigami
-    ANTHROPIC_API_KEY=sk-... python -m training.demo_llm
-
-Each of the 8 episodes calls Claude (claude-haiku-4-5) once per fold step.
-Claude receives the current paper state (metrics + fold history) and decides
-the next fold action.  Episodes run concurrently; all stream to the grid viewer.
-"""
-from __future__ import annotations
-
-import asyncio
-import json
-import os
-import re
-import time
-from typing import Any
-
-import anthropic
-import uvicorn
-
-from server.app import app, broadcast
-from server.models import OrigamiAction
-from server.origami_environment import OrigamiEnvironment
-from server.tasks import get_task_by_name
-
-
-TASK_NAME = "half_fold"
-NUM_EPISODES = 8
-MODEL = "claude-haiku-4-5-20251001"
-
-
-# ── System prompt ──────────────────────────────────────────────────────────────
-
-SYSTEM_PROMPT = """\
-You are an origami folding agent controlling a robotic paper-folding system.
-
-COORDINATE SYSTEM
-- Paper starts as a flat sheet; coordinates are normalized to the sheet's original size.
-- x=0 is the left edge, x=1 is the right edge.
-- y=0 is the bottom edge, y=1 is the top edge.
-- Fold line endpoints must be on or outside the paper boundary (0.0–1.0 range).
-- A fold line that runs off the edge is fine — it just doesn't affect paper outside the sheet.
-
-FOLD TYPES
-- "valley": folds the paper toward you (creates a V crease when viewed from above).
-- "mountain": folds the paper away from you (creates a ^ crease).
-- "stop": you are satisfied — no more folds needed.
-
-PHYSICS
-- angle=180 means a fully flat fold (paper halved).
-- Smaller angles (e.g. 90) create partial folds.
-- Each fold updates compactness, bounding_box, and strain readings.
-- Kawasaki/Maekawa violations indicate geometrically invalid crease patterns.
-
-RESPONSE FORMAT — output ONLY valid JSON, no markdown, no explanation:
-{"type": "valley", "line": {"start": [x, y], "end": [x, y]}, "angle": 180}
-"""
-
-# Eight distinct approach hints — gives diversity across the parallel episodes.
-APPROACH_HINTS = [
-    "Try a single clean horizontal fold at the exact midline.",
-    "Try a single clean vertical fold at the exact midline.",
-    "Use two folds: first horizontal then vertical, to create quarters.",
-    "Use a diagonal fold from one corner to the opposite.",
-    "Try folding at y=0.333 and y=0.667 to create thirds.",
-    "Try a single fold but vary the position slightly off-center to explore.",
-    "Use a mountain fold instead of valley for the primary crease.",
-    "Try to reach the target box in as few folds as possible — stop early if done.",
-]
-
-
-# ── LLM strategy factory ───────────────────────────────────────────────────────
-
-def make_llm_strategy(client: anthropic.Anthropic, task: dict, episode_num: int):
-    """Return a strategy_fn for one episode.
-
-    Each episode has its own conversation history (multi-turn) and a unique
-    approach hint so the 8 concurrent episodes explore different strategies.
-    """
-    history: list[dict[str, Any]] = []
-    hint = APPROACH_HINTS[episode_num % len(APPROACH_HINTS)]
-    prev_compactness: list[float] = [0.0]  # mutable cell for delta tracking
-
-    def strategy(paper_state: dict, fold_history: list[dict]) -> dict:
-        fold_count = paper_state.get("fold_count", 0)
-        compactness = float(paper_state.get("compactness", 0))
-        bb = paper_state.get("bounding_box", [1, 1, 0])
-        fits = paper_state.get("fits_target_box", False)
-        strain = paper_state.get("max_strain", 0.0)
-        kaw = paper_state.get("kawasaki_violations", 0)
-        target_box = task.get("target_box", [1, 0.5, 0.02])
-        max_folds = task.get("max_folds", 3)
-
-        delta = compactness - prev_compactness[0]
-        prev_compactness[0] = compactness
-
-        # Summarise what has been done so far
-        history_lines = ""
-        if fold_history:
-            history_lines = "Folds applied so far:\n"
-            for i, f in enumerate(fold_history, 1):
-                t = f.get("type", "?")
-                ln = f.get("line", {})
-                s = ln.get("start", [0, 0])
-                e = ln.get("end", [1, 1])
-                ang = f.get("angle", 180)
-                history_lines += (
-                    f"  {i}. {t} fold  "
-                    f"from ({s[0]:.3f},{s[1]:.3f}) to ({e[0]:.3f},{e[1]:.3f})  "
-                    f"angle={ang}\n"
-                )
-        else:
-            history_lines = "No folds applied yet — paper is flat.\n"
-
-        sign = "+" if delta >= 0 else ""
-        user_msg = (
-            f"Task: {task['description']}\n"
-            f"Sheet: {task['width']}×{task['height']} {task['material']}\n"
-            f"Target bounding box: {target_box}  (must fit inside to succeed)\n"
-            f"Max folds remaining: {max_folds - fold_count}\n"
-            f"\n"
-            f"{history_lines}"
-            f"\n"
-            f"Current state after fold {fold_count}/{max_folds}:\n"
-            f"  compactness : {compactness:.4f}  (Δ {sign}{delta:.4f})\n"
-            f"  bounding_box: [{bb[0]:.4f}, {bb[1]:.4f}, {bb[2]:.5f}]\n"
-            f"  fits_target : {'YES ✓' if fits else 'no'}\n"
-            f"  max_strain  : {strain:.5f}\n"
-            f"  kaw_violations: {kaw}\n"
-            f"\n"
-            f"Approach hint: {hint}\n"
-            f"\n"
-            f"What is your next fold action?  "
-            f"Return \"stop\" if the target is already achieved or no useful fold remains."
-        )
-
-        history.append({"role": "user", "content": user_msg})
-
-        response = client.messages.create(
-            model=MODEL,
-            max_tokens=150,
-            system=SYSTEM_PROMPT,
-            messages=history,
-        )
-        reply = response.content[0].text.strip()
-        history.append({"role": "assistant", "content": reply})
-
-        # Handle explicit "stop" text before JSON parse
-        if reply.lower().startswith("stop") or '"type": "stop"' in reply:
-            return {"type": "stop", "line": {"start": [0, 0.5], "end": [1, 0.5]}, "angle": 0.0}
-
-        # Extract JSON — handles markdown code fences
-        match = re.search(r'\{[^{}]+\}', reply, re.DOTALL)
-        if not match:
-            # Malformed response — default safe fold then stop next turn
-            return {"type": "valley", "line": {"start": [0.0, 0.5], "end": [1.0, 0.5]}, "angle": 180.0}
-
-        try:
-            fold_dict = json.loads(match.group())
-        except json.JSONDecodeError:
-            return {"type": "valley", "line": {"start": [0.0, 0.5], "end": [1.0, 0.5]}, "angle": 180.0}
-
-        fold_dict.setdefault("type", "valley")
-        fold_dict.setdefault("line", {"start": [0.0, 0.5], "end": [1.0, 0.5]})
-        fold_dict.setdefault("angle", 180.0)
-        return fold_dict
-
-    return strategy
-
-
-# ── Episode runner ─────────────────────────────────────────────────────────────
-
-def run_episode_llm(
-    strategy_fn,
-    task_name: str,
-    ep_id: str,
-    broadcast_fn,
-) -> dict:
-    env = OrigamiEnvironment()
-    obs = env.reset(task_name=task_name)
-    task = env._task or {}
-
-    broadcast_fn(ep_id, {
-        "type": "episode_update",
-        "episode_id": ep_id,
-        "task_name": task_name,
-        "step": 0,
-        "observation": _obs_dict(obs),
-    })
-
-    max_steps = task.get("max_folds", 5)
-    status = "done"
-
-    for step_idx in range(max_steps):
-        if obs.done:
-            break
-
-        # Merge paper_state + metrics for the strategy
-        ps = dict(obs.paper_state)
-        ps.update(obs.metrics)
-        ps["fold_count"] = step_idx
-
-        try:
-            fold_dict = strategy_fn(ps, list(obs.fold_history))
-        except Exception as exc:
-            broadcast_fn(ep_id, {
-                "type": "episode_done", "episode_id": ep_id,
-                "status": "error", "score": 0.0,
-                "final_metrics": obs.metrics, "error": str(exc),
-            })
-            return {"episode_id": ep_id, "score": 0.0, "status": "error"}
-
-        if fold_dict.get("type") == "stop":
-            break
-
-        time.sleep(0.5)  # pace for viewer animation
-
-        action = OrigamiAction(
-            fold_type=fold_dict["type"],
-            fold_line=fold_dict["line"],
-            fold_angle=float(fold_dict.get("angle", 180.0)),
-        )
-        obs = env.step(action)
-
-        broadcast_fn(ep_id, {
-            "type": "episode_update",
-            "episode_id": ep_id,
-            "task_name": task_name,
-            "step": step_idx + 1,
-            "observation": _obs_dict(obs),
-        })
-
-        if obs.done:
-            break
-    else:
-        status = "timeout"
-
-    score = obs.reward if obs.reward is not None else (env._total_reward or 0.0)
-    broadcast_fn(ep_id, {
-        "type": "episode_done",
-        "episode_id": ep_id,
-        "status": status,
-        "score": float(score),
-        "final_metrics": obs.metrics,
-    })
-
-    return {"episode_id": ep_id, "score": float(score), "status": status}
-
-
-def _obs_dict(obs) -> dict:
-    try:
-        return obs.model_dump()
-    except AttributeError:
-        return {
-            "paper_state": getattr(obs, "paper_state", {}),
-            "metrics": getattr(obs, "metrics", {}),
-            "fold_history": getattr(obs, "fold_history", []),
-            "done": getattr(obs, "done", False),
-            "reward": getattr(obs, "reward", None),
-        }
-
-
-# ── Main ───────────────────────────────────────────────────────��──────────────
-
-async def run_demo() -> None:
-    api_key = os.environ.get("ANTHROPIC_API_KEY")
-    if not api_key:
-        raise RuntimeError("Set ANTHROPIC_API_KEY environment variable")
-
-    client = anthropic.Anthropic(api_key=api_key)
-    task = get_task_by_name(TASK_NAME)
-
-    await asyncio.sleep(1.5)  # wait for server startup
-
-    print(f"\n[llm-demo] Model  : {MODEL}")
-    print(f"[llm-demo] Task   : {TASK_NAME} — {task['description']}")
-    print(f"[llm-demo] Open   : http://localhost:9001/viewer/training.html\n")
-    print(f"[llm-demo] Episodes:")
-    for i, hint in enumerate(APPROACH_HINTS):
-        print(f"  ep_{i:02d}  hint: {hint}")
-    print()
-
-    await broadcast.start_batch(1, NUM_EPISODES)
-
-    ep_ids = [f"ep_{i:02d}" for i in range(NUM_EPISODES)]
-    strategies = [make_llm_strategy(client, task, i) for i in range(NUM_EPISODES)]
-
-    results = await asyncio.gather(*[
-        asyncio.to_thread(run_episode_llm, fn, TASK_NAME, ep_id, broadcast.publish)
-        for fn, ep_id in zip(strategies, ep_ids)
-    ])
-
-    scores = [r["score"] for r in results]
-    best_idx = max(range(len(scores)), key=lambda i: scores[i])
-
-    await broadcast.finish_batch(1, scores, best_episode_id=ep_ids[best_idx])
-
-    print("\n[llm-demo] Results:")
-    for i, (result, hint) in enumerate(zip(results, APPROACH_HINTS)):
-        marker = " ← best" if i == best_idx else ""
-        print(f"  ep_{i:02d}  score={result['score']:+.2f}  status={result['status']}  hint: {hint}{marker}")
-    print(f"\n[llm-demo] Press Ctrl+C to stop.\n")
-
-
-async def _main() -> None:
-    config = uvicorn.Config(app, host="0.0.0.0", port=9001, log_level="warning")
-    server = uvicorn.Server(config)
-    await asyncio.gather(server.serve(), run_demo())
-
-
-if __name__ == "__main__":
-    try:
-        asyncio.run(_main())
-    except KeyboardInterrupt:
-        print("\n[llm-demo] Stopped.")

training/runner.py

@@ -1,191 +0,0 @@
-"""
-TrainingRunner — parallel episode executor for GRPO training.
-
-Each episode runs in a ThreadPoolExecutor thread.
-After every env.step(), observations are pushed to the broadcast server (fire-and-forget).
-"""
-from __future__ import annotations
-
-import uuid
-from concurrent.futures import ThreadPoolExecutor, as_completed
-from typing import Any, Callable, Optional
-
-from server.models import OrigamiAction
-from server.origami_environment import OrigamiEnvironment
-
-
-BroadcastFn = Callable[[str, dict], None]
-
-
-def run_episode(
-    strategy_fn: Callable[[dict], dict],
-    task_name: str,
-    ep_id: Optional[str] = None,
-    broadcast_fn: Optional[BroadcastFn] = None,
-    max_steps: Optional[int] = None,
-) -> dict:
-    """Run a single origami episode with a given strategy function.
-
-    Args:
-        strategy_fn: Callable that receives paper_state dict and returns a fold dict:
-                     {"type": "valley"|"mountain"|"pleat"|"crimp"|"stop",
-                      "line": {"start": [x, y], "end": [x, y]},
-                      "angle": 180.0}
-        task_name: Name of the task (from server/tasks.py)
-        ep_id: Episode identifier for broadcast; auto-generated if None
-        broadcast_fn: Optional callback(ep_id, data) for live streaming
-        max_steps: Override task's max_folds if provided
-
-    Returns:
-        dict with keys: episode_id, score, final_metrics, fold_history, status
-    """
-    ep_id = ep_id or str(uuid.uuid4())[:8]
-    env = OrigamiEnvironment()
-
-    obs = env.reset(task_name=task_name)
-
-    if broadcast_fn:
-        broadcast_fn(ep_id, {
-            "type": "episode_update",
-            "episode_id": ep_id,
-            "task_name": task_name,
-            "step": 0,
-            "observation": _obs_to_dict(obs),
-        })
-
-    step_limit = max_steps or env._task.get("max_folds", 20) if env._task else 20
-    status = "done"
-
-    for step_idx in range(step_limit):
-        if obs.done:
-            break
-
-        # Strategy generates a fold dict
-        try:
-            fold_dict = strategy_fn(obs.paper_state)
-        except Exception as exc:
-            status = "error"
-            if broadcast_fn:
-                broadcast_fn(ep_id, {
-                    "type": "episode_done",
-                    "episode_id": ep_id,
-                    "status": "error",
-                    "score": obs.reward or 0.0,
-                    "final_metrics": obs.metrics,
-                    "error": str(exc),
-                })
-            break
-
-        fold_type = fold_dict.get("type", "valley")
-        fold_line = fold_dict.get("line", {"start": [0, 0.5], "end": [1, 0.5]})
-        fold_angle = float(fold_dict.get("angle", 180.0))
-
-        action = OrigamiAction(
-            fold_type=fold_type,
-            fold_line=fold_line,
-            fold_angle=fold_angle,
-        )
-        obs = env.step(action)
-
-        if broadcast_fn:
-            broadcast_fn(ep_id, {
-                "type": "episode_update",
-                "episode_id": ep_id,
-                "task_name": task_name,
-                "step": step_idx + 1,
-                "observation": _obs_to_dict(obs),
-            })
-
-        if obs.done:
-            break
-    else:
-        status = "timeout"
-
-    score = obs.reward if obs.reward is not None else (env._total_reward or 0.0)
-
-    if broadcast_fn:
-        broadcast_fn(ep_id, {
-            "type": "episode_done",
-            "episode_id": ep_id,
-            "status": status,
-            "score": float(score),
-            "final_metrics": obs.metrics,
-        })
-
-    return {
-        "episode_id": ep_id,
-        "score": float(score),
-        "final_metrics": obs.metrics,
-        "fold_history": obs.fold_history,
-        "status": status,
-    }
-
-
-def run_batch(
-    strategy_fns: list[Callable[[dict], dict]],
-    task_name: str,
-    broadcast_fn: Optional[BroadcastFn] = None,
-    batch_id: Optional[int] = None,
-    max_workers: int = 8,
-) -> list[dict]:
-    """Run G episodes in parallel with a ThreadPoolExecutor.
-
-    Args:
-        strategy_fns: List of G strategy callables (one per completion)
-        task_name: Task to use for all episodes
-        broadcast_fn: Optional broadcast callback, called after each step
-        batch_id: Batch identifier for broadcast
-        max_workers: Max parallel threads (bounded by G)
-
-    Returns:
-        List of episode result dicts, in same order as strategy_fns
-    """
-    n = len(strategy_fns)
-    ep_ids = [f"ep_{(batch_id or 0):04d}_{i:02d}" for i in range(n)]
-    workers = min(max_workers, n)
-
-    results: list[dict] = [{}] * n
-
-    with ThreadPoolExecutor(max_workers=workers) as pool:
-        futures = {
-            pool.submit(
-                run_episode,
-                fn,
-                task_name,
-                ep_ids[i],
-                broadcast_fn,
-            ): i
-            for i, fn in enumerate(strategy_fns)
-        }
-
-        for future in as_completed(futures):
-            idx = futures[future]
-            try:
-                results[idx] = future.result()
-            except Exception as exc:
-                results[idx] = {
-                    "episode_id": ep_ids[idx],
-                    "score": 0.0,
-                    "final_metrics": {},
-                    "fold_history": [],
-                    "status": "error",
-                    "error": str(exc),
-                }
-
-    return results
-
-
-def _obs_to_dict(obs) -> dict:
-    """Convert OrigamiObservation to a JSON-serializable dict."""
-    try:
-        return obs.model_dump()
-    except AttributeError:
-        return {
-            "task": obs.task if hasattr(obs, "task") else {},
-            "paper_state": obs.paper_state if hasattr(obs, "paper_state") else {},
-            "metrics": obs.metrics if hasattr(obs, "metrics") else {},
-            "fold_history": obs.fold_history if hasattr(obs, "fold_history") else [],
-            "done": obs.done if hasattr(obs, "done") else False,
-            "reward": obs.reward if hasattr(obs, "reward") else None,
-            "error": obs.error if hasattr(obs, "error") else None,
-        }

viz/renderer.py

@@ -1,315 +0,0 @@
-"""
-Matplotlib-based crease pattern renderer.
-Used for quick observability during training and debugging.
-"""
-import json
-import numpy as np
-import matplotlib.pyplot as plt
-import matplotlib.patches as patches
-from matplotlib.animation import FuncAnimation
-from typing import Optional
-
-
-# Design system colors
-_COLOR_MOUNTAIN = "#f59e0b"
-_COLOR_VALLEY = "#38bdf8"
-_COLOR_PAPER = "#fafaf5"
-_COLOR_PAPER_EDGE = "#e2e8f0"
-_COLOR_AX_BG = "#1a1a2e"
-_COLOR_ANCHOR = "#4a4a6a"
-_COLOR_REWARD_BG = "#13131d"
-_COLOR_GRID = "#2a2a3a"
-_COLOR_VALIDITY = "#22d3ee"
-_COLOR_PROGRESS = "#22c55e"
-_COLOR_ECONOMY = "#a78bfa"
-
-
-def draw_paper_state(ax, paper_state, target=None, step=None, reward=None):
-    """
-    Draw the current crease pattern on a matplotlib axes object.
-
-    Args:
-        ax: matplotlib axes
-        paper_state: PaperState instance
-        target: optional FOLD dict for target crease ghost overlay
-        step: step number for title (None = "Initial")
-        reward: unused, kept for signature compatibility
-    """
-    ax.set_facecolor(_COLOR_AX_BG)
-
-    # Unit square paper
-    square = patches.Rectangle(
-        (0, 0), 1, 1,
-        facecolor=_COLOR_PAPER,
-        edgecolor=_COLOR_PAPER_EDGE,
-        linewidth=1.5,
-        zorder=1,
-    )
-    ax.add_patch(square)
-
-    # Target ghost overlay
-    if target is not None:
-        verts = target["vertices_coords"]
-        edges_v = target["edges_vertices"]
-        edges_a = target["edges_assignment"]
-        for (v1, v2), assignment in zip(edges_v, edges_a):
-            if assignment not in ("M", "V"):
-                continue
-            x1, y1 = verts[v1]
-            x2, y2 = verts[v2]
-            color = _COLOR_MOUNTAIN if assignment == "M" else _COLOR_VALLEY
-            ax.plot(
-                [x1, x2], [y1, y2],
-                color=color,
-                alpha=0.2,
-                linewidth=1,
-                linestyle="--",
-                zorder=2,
-            )
-
-    # Current crease edges
-    for edge in paper_state.crease_edges():
-        x1, y1 = edge["v1"]
-        x2, y2 = edge["v2"]
-        assignment = edge["assignment"]
-        color = _COLOR_MOUNTAIN if assignment == "M" else _COLOR_VALLEY
-        ax.plot(
-            [x1, x2], [y1, y2],
-            color=color,
-            linewidth=2.5,
-            linestyle="-",
-            solid_capstyle="round",
-            zorder=3,
-        )
-        # Endpoint dots
-        ax.plot(
-            [x1, x2], [y1, y2],
-            color=color,
-            marker="o",
-            markersize=5,
-            linestyle="none",
-            zorder=4,
-        )
-
-    # Anchor points as gray crosses
-    for x, y in paper_state.anchor_points():
-        ax.plot(
-            x, y,
-            color=_COLOR_ANCHOR,
-            marker="+",
-            markersize=3,
-            linestyle="none",
-            zorder=5,
-        )
-
-    # Title
-    title = f"Step {step}" if step is not None else "Initial"
-    ax.set_title(title, color="white", fontfamily="monospace", fontsize=10, pad=6)
-
-    # Remove ticks and spines
-    ax.set_xticks([])
-    ax.set_yticks([])
-    for spine in ax.spines.values():
-        spine.set_visible(False)
-
-    ax.set_xlim(-0.05, 1.05)
-    ax.set_ylim(-0.05, 1.05)
-    ax.set_aspect("equal")
-
-
-def draw_reward_bars(ax, reward: dict):
-    """
-    Draw a horizontal bar chart of reward components.
-
-    Args:
-        ax: matplotlib axes
-        reward: dict with keys kawasaki, maekawa, blb, progress, economy (all 0-1)
-    """
-    components = ["kawasaki", "maekawa", "blb", "progress", "economy"]
-    colors = {
-        "kawasaki": _COLOR_VALIDITY,
-        "maekawa": _COLOR_VALIDITY,
-        "blb": _COLOR_VALIDITY,
-        "progress": _COLOR_PROGRESS,
-        "economy": _COLOR_ECONOMY,
-    }
-
-    values = [float(reward.get(c, 0.0)) for c in components]
-
-    ax.set_facecolor(_COLOR_REWARD_BG)
-
-    bar_colors = [colors[c] for c in components]
-    bars = ax.barh(
-        components,
-        values,
-        height=0.6,
-        color=bar_colors,
-        zorder=2,
-    )
-
-    # Value labels at end of each bar
-    for bar, val in zip(bars, values):
-        ax.text(
-            min(val + 0.02, 0.98),
-            bar.get_y() + bar.get_height() / 2,
-            f"{val:.2f}",
-            va="center",
-            ha="left",
-            color="white",
-            fontfamily="monospace",
-            fontsize=8,
-            zorder=3,
-        )
-
-    # Y-axis label style
-    ax.tick_params(axis="y", colors="white", labelsize=8)
-    for label in ax.get_yticklabels():
-        label.set_fontfamily("monospace")
-
-    # Subtle x gridlines
-    for x_pos in [0.25, 0.5, 0.75, 1.0]:
-        ax.axvline(x_pos, color=_COLOR_GRID, linewidth=0.8, zorder=1)
-
-    ax.set_xlim(0, 1.0)
-    ax.set_xticks([])
-    ax.tick_params(axis="x", colors="white")
-    for spine in ax.spines.values():
-        spine.set_visible(False)
-
-    ax.set_title("Reward Breakdown", color="white", fontfamily="monospace", fontsize=10, pad=6)
-
-
-def render_episode(fold_history, target, rewards_history, save_path=None):
-    """
-    Create a multi-panel figure showing an entire episode.
-
-    Args:
-        fold_history: list of PaperState snapshots (one per step)
-        target: FOLD dict of target crease pattern
-        rewards_history: list of reward dicts (one per step)
-        save_path: if provided, save PNG here; otherwise plt.show()
-
-    Returns:
-        matplotlib Figure
-    """
-    n_states = len(fold_history)
-    show_states = min(n_states, 4)
-
-    fig = plt.figure(figsize=(4 * show_states + 4, 5), facecolor="#0d0d14")
-    gs = fig.add_gridspec(
-        1, show_states + 1,
-        width_ratios=[1] * show_states + [1.2],
-        wspace=0.3,
-    )
-
-    # Paper state panels (up to 4)
-    for i in range(show_states):
-        # Evenly sample from fold_history if more than 4 steps
-        idx = int(i * (n_states - 1) / max(show_states - 1, 1)) if show_states > 1 else 0
-        ax = fig.add_subplot(gs[0, i])
-        draw_paper_state(
-            ax,
-            fold_history[idx],
-            target=target,
-            step=idx + 1,
-            reward=rewards_history[idx] if idx < len(rewards_history) else None,
-        )
-
-    # Reward curves panel
-    ax_reward = fig.add_subplot(gs[0, show_states])
-    ax_reward.set_facecolor(_COLOR_REWARD_BG)
-
-    steps = list(range(1, len(rewards_history) + 1))
-    curve_specs = [
-        ("progress", _COLOR_PROGRESS, "progress"),
-        ("kawasaki", _COLOR_VALIDITY, "kawasaki"),
-        ("total", "#f8fafc", "total"),
-    ]
-
-    for key, color, label in curve_specs:
-        vals = [r.get(key, 0.0) for r in rewards_history]
-        ax_reward.plot(steps, vals, color=color, linewidth=1.5, label=label)
-
-    ax_reward.set_xlim(1, max(len(rewards_history), 1))
-    ax_reward.set_title("Reward Curves", color="white", fontfamily="monospace", fontsize=10, pad=6)
-    ax_reward.tick_params(colors="white", labelsize=8)
-    ax_reward.legend(
-        fontsize=7,
-        facecolor=_COLOR_REWARD_BG,
-        edgecolor=_COLOR_GRID,
-        labelcolor="white",
-    )
-    for spine in ax_reward.spines.values():
-        spine.set_color(_COLOR_GRID)
-
-    if save_path:
-        fig.savefig(save_path, dpi=150, facecolor="#0d0d14", bbox_inches="tight")
-    else:
-        plt.show()
-
-    return fig
-
-
-def render_training_curves(log_path: str):
-    """
-    Read a JSONL log file and plot training curves.
-
-    Each line must be a JSON object with reward component keys.
-
-    Args:
-        log_path: path to JSONL training log
-
-    Returns:
-        matplotlib Figure
-    """
-    records = []
-    with open(log_path) as f:
-        for line in f:
-            line = line.strip()
-            if not line:
-                continue
-            records.append(json.loads(line))
-
-    episodes = list(range(1, len(records) + 1))
-
-    keys_to_plot = [
-        ("total", "#f8fafc", "total reward"),
-        ("progress", _COLOR_PROGRESS, "progress"),
-        ("kawasaki", _COLOR_VALIDITY, "kawasaki"),
-        ("maekawa", _COLOR_VALIDITY, "maekawa"),
-        ("blb", _COLOR_VALIDITY, "blb"),
-    ]
-
-    fig, axes = plt.subplots(
-        2, 1,
-        figsize=(10, 6),
-        facecolor="#0d0d14",
-        gridspec_kw={"hspace": 0.4},
-    )
-
-    # Top: total + progress
-    ax_top = axes[0]
-    ax_top.set_facecolor(_COLOR_REWARD_BG)
-    for key, color, label in keys_to_plot[:2]:
-        vals = [r.get(key, 0.0) for r in records]
-        ax_top.plot(episodes, vals, color=color, linewidth=1.5, label=label)
-    ax_top.set_title("Training: Total & Progress", color="white", fontfamily="monospace", fontsize=10)
-    ax_top.tick_params(colors="white", labelsize=8)
-    ax_top.legend(fontsize=8, facecolor=_COLOR_REWARD_BG, edgecolor=_COLOR_GRID, labelcolor="white")
-    for spine in ax_top.spines.values():
-        spine.set_color(_COLOR_GRID)
-
-    # Bottom: kawasaki, maekawa, blb
-    ax_bot = axes[1]
-    ax_bot.set_facecolor(_COLOR_REWARD_BG)
-    for key, color, label in keys_to_plot[2:]:
-        vals = [r.get(key, 0.0) for r in records]
-        ax_bot.plot(episodes, vals, color=color, linewidth=1.5, label=label, alpha=0.85)
-    ax_bot.set_title("Training: Validity Checks", color="white", fontfamily="monospace", fontsize=10)
-    ax_bot.set_xlabel("Episode", color="white", fontsize=9)
-    ax_bot.tick_params(colors="white", labelsize=8)
-    ax_bot.legend(fontsize=8, facecolor=_COLOR_REWARD_BG, edgecolor=_COLOR_GRID, labelcolor="white")
-    for spine in ax_bot.spines.values():
-        spine.set_color(_COLOR_GRID)
-
-    return fig