Initial deploy: OpenEnv RL environment for origami crease patterns

FastAPI + openenv-core environment that serves as an RL training
backend for teaching LLMs to generate valid FOLD crease patterns
from natural language prompts. Includes 11 ground-truth patterns
derived from the Optigami simulator and a multi-component reward
function using graph-based structural comparison.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Dockerfile

@@ -0,0 +1,12 @@
+FROM python:3.11-slim
+
+WORKDIR /app
+
+COPY requirements.txt .
+RUN pip install --no-cache-dir -r requirements.txt
+
+COPY . .
+
+EXPOSE 7860
+
+CMD ["uvicorn", "app:app", "--host", "0.0.0.0", "--port", "7860"]

README.md

@@ -1,11 +1,39 @@
 ---
-title: 'Optigami '
-emoji: 👁
-colorFrom: gray
-colorTo: yellow
+title: Optigami
+emoji: 🦢
+colorFrom: indigo
+colorTo: purple
 sdk: docker
+app_port: 7860
 pinned: false
-short_description: ver2.0
+license: mit
+short_description: OpenEnv RL environment for origami crease patterns
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# Optigami - OpenEnv RL Environment for Origami Crease Patterns
+
+An RL training environment built with [OpenEnv](https://github.com/meta-pytorch/OpenEnv) that teaches LLMs to generate valid `.fold` crease patterns from natural language prompts.
+
+## API Endpoints
+
+- `POST /reset` - Get a new origami prompt
+- `POST /step` - Submit a generated FOLD JSON and receive a reward
+
+## Reward Structure
+
+| Condition | Reward |
+|---|---|
+| Invalid JSON | -2.0 |
+| Missing required FOLD fields | -1.0 |
+| Valid FOLD with structural comparison | -1.0 to 1.0 |
+
+## Usage with OpenEnv Client
+
+```python
+from openenv.core import EnvClient
+
+env = EnvClient("https://openenv-community-optigami-.hf.space")
+obs = env.reset()
+result = env.step('{"vertices_coords": [...], "edges_vertices": [...], ...}')
+print(result.reward)
+```

app.py

@@ -0,0 +1,524 @@
+import json
+from collections import Counter
+from typing import Any, Dict, List, Optional
+
+import numpy as np
+import networkx as nx
+from pydantic import Field
+
+from openenv.core import (
+    Action,
+    Environment,
+    Observation,
+    State,
+    create_fastapi_app,
+)
+
+# ---------------------------------------------------------------------------
+# Custom Action / Observation models
+# ---------------------------------------------------------------------------
+
+
+class FoldAction(Action):
+    """An action that contains a generated FOLD JSON string."""
+
+    fold_json: str = Field(description="A JSON string in the FOLD format")
+
+
+class FoldObservation(Observation):
+    """Observation returned by the origami environment."""
+
+    prompt: str = Field(default="", description="The origami prompt to fulfill")
+    info: Dict[str, Any] = Field(default_factory=dict, description="Extra info")
+
+
+# ---------------------------------------------------------------------------
+# Dataset: ground-truth origami crease patterns converted from the Optigami
+# TypeScript codebase (lib/patterns.ts).  Each entry has a natural-language
+# prompt and a target FOLD-format dict.
+# ---------------------------------------------------------------------------
+
+DATASET: List[Dict[str, Any]] = [
+    {
+        "prompt": "Create a simple valley fold across the center of a square sheet",
+        "target": {
+            "vertices_coords": [[-1, 1], [1, 1], [-1, 0], [1, 0], [-1, -1], [1, -1]],
+            "faces_vertices": [[0, 2, 3], [0, 3, 1], [2, 4, 5], [2, 5, 3]],
+            "edges_vertices": [
+                [0, 2], [2, 3], [3, 0], [0, 1], [1, 3],
+                [2, 4], [4, 5], [5, 3],
+            ],
+            "edges_assignment": ["B", "V", "F", "B", "B", "B", "B", "F"],
+        },
+    },
+    {
+        "prompt": "Make an accordion fold with alternating mountain and valley creases",
+        "target": {
+            "vertices_coords": [
+                [-1, 1], [-0.5, 1], [0, 1], [0.5, 1], [1, 1],
+                [-1, -1], [-0.5, -1], [0, -1], [0.5, -1], [1, -1],
+            ],
+            "faces_vertices": [
+                [0, 1, 6], [0, 6, 5],
+                [1, 2, 7], [1, 7, 6],
+                [2, 3, 8], [2, 8, 7],
+                [3, 4, 9], [3, 9, 8],
+            ],
+            "edges_vertices": [
+                [0, 1], [1, 6], [6, 0], [0, 5], [5, 6],
+                [1, 2], [2, 7], [7, 1], [6, 7],
+                [2, 3], [3, 8], [8, 2], [7, 8],
+                [3, 4], [4, 9], [9, 3], [8, 9],
+            ],
+            "edges_assignment": [
+                "B", "V", "F", "B", "B",
+                "B", "M", "F", "F",
+                "B", "V", "F", "F",
+                "B", "B", "F", "B",
+            ],
+        },
+    },
+    {
+        "prompt": "Create a waterbomb base with valley folds on diagonals and mountain folds on midlines",
+        "target": {
+            "vertices_coords": [
+                [-1, 1], [0, 1], [1, 1],
+                [-1, 0], [0, 0], [1, 0],
+                [-1, -1], [0, -1], [1, -1],
+            ],
+            "faces_vertices": [
+                [0, 1, 4], [1, 2, 4],
+                [2, 5, 4], [5, 8, 4],
+                [8, 7, 4], [7, 6, 4],
+                [6, 3, 4], [3, 0, 4],
+            ],
+            "edges_vertices": [
+                [0, 1], [1, 4], [4, 0],
+                [1, 2], [2, 4],
+                [2, 5], [5, 4],
+                [5, 8], [8, 4],
+                [8, 7], [7, 4],
+                [7, 6], [6, 4],
+                [6, 3], [3, 4],
+                [3, 0],
+            ],
+            "edges_assignment": [
+                "B", "M", "V",
+                "B", "V",
+                "B", "M",
+                "B", "V",
+                "B", "M",
+                "B", "V",
+                "B", "M",
+                "B",
+            ],
+        },
+    },
+    {
+        "prompt": "Make a preliminary fold (square base) with mountain diagonals and valley midlines",
+        "target": {
+            "vertices_coords": [
+                [-1, 1], [0, 1], [1, 1],
+                [-1, 0], [0, 0], [1, 0],
+                [-1, -1], [0, -1], [1, -1],
+            ],
+            "faces_vertices": [
+                [0, 1, 4], [1, 2, 4],
+                [2, 5, 4], [5, 8, 4],
+                [8, 7, 4], [7, 6, 4],
+                [6, 3, 4], [3, 0, 4],
+            ],
+            "edges_vertices": [
+                [0, 1], [1, 4], [4, 0],
+                [1, 2], [2, 4],
+                [2, 5], [5, 4],
+                [5, 8], [8, 4],
+                [8, 7], [7, 4],
+                [7, 6], [6, 4],
+                [6, 3], [3, 4],
+                [3, 0],
+            ],
+            "edges_assignment": [
+                "B", "V", "M",
+                "B", "M",
+                "B", "V",
+                "B", "M",
+                "B", "V",
+                "B", "M",
+                "B", "V",
+                "B",
+            ],
+        },
+    },
+    {
+        "prompt": "Create a Miura-ori tessellation fold pattern on a 2x2 grid",
+        "target": {
+            "vertices_coords": [
+                [-1, 1], [0, 1.2], [1, 1],
+                [-1, 0], [0, 0.2], [1, 0],
+                [-1, -1], [0, -0.8], [1, -1],
+            ],
+            "faces_vertices": [
+                [0, 1, 4], [0, 4, 3],
+                [1, 2, 5], [1, 5, 4],
+                [3, 4, 7], [3, 7, 6],
+                [4, 5, 8], [4, 8, 7],
+            ],
+            "edges_vertices": [
+                [0, 1], [1, 4], [4, 0], [0, 3],
+                [1, 2], [2, 5], [5, 1], [4, 5],
+                [3, 4], [4, 7], [7, 3], [3, 6],
+                [6, 7], [7, 4], [5, 8], [8, 7],
+            ],
+            "edges_assignment": [
+                "B", "M", "F", "B",
+                "B", "B", "F", "M",
+                "V", "M", "F", "B",
+                "B", "F", "B", "B",
+            ],
+        },
+    },
+    {
+        "prompt": "Design a bird base crease pattern with alternating mountain and valley folds radiating from center",
+        "target": {
+            "vertices_coords": [
+                [-1, 1], [0, 1], [1, 1],
+                [-1, 0], [0, 0], [1, 0],
+                [-1, -1], [0, -1], [1, -1],
+                [-0.5, 0.5], [0.5, 0.5], [-0.5, -0.5], [0.5, -0.5],
+            ],
+            "faces_vertices": [
+                [0, 9, 3], [0, 1, 9], [1, 4, 9], [3, 9, 4],
+                [1, 10, 4], [1, 2, 10], [2, 5, 10], [4, 10, 5],
+                [3, 4, 11], [3, 11, 6], [6, 11, 7], [4, 7, 11],
+                [4, 5, 12], [5, 8, 12], [8, 7, 12], [4, 12, 7],
+            ],
+            "edges_vertices": [
+                [0, 9], [9, 3], [0, 1], [1, 9], [1, 4], [9, 4],
+                [1, 10], [1, 2], [2, 10], [2, 5], [5, 10], [10, 4],
+                [3, 4], [3, 11], [11, 6], [6, 7], [7, 11], [11, 4],
+                [4, 5], [4, 12], [5, 12], [5, 8], [8, 12], [12, 7], [7, 4],
+            ],
+            "edges_assignment": [
+                "V", "M", "B", "M", "M", "V",
+                "M", "B", "V", "B", "M", "V",
+                "M", "M", "V", "B", "M", "V",
+                "M", "V", "M", "B", "V", "M", "M",
+            ],
+        },
+    },
+    {
+        "prompt": "Create a hyperbolic paraboloid (hypar) fold on a 4x4 grid with alternating mountain and valley creases",
+        "target": {
+            "vertices_coords": [
+                [-1, 1], [-0.5, 1], [0, 1], [0.5, 1], [1, 1],
+                [-1, 0.5], [-0.5, 0.5], [0, 0.5], [0.5, 0.5], [1, 0.5],
+                [-1, 0], [-0.5, 0], [0, 0], [0.5, 0], [1, 0],
+                [-1, -0.5], [-0.5, -0.5], [0, -0.5], [0.5, -0.5], [1, -0.5],
+                [-1, -1], [-0.5, -1], [0, -1], [0.5, -1], [1, -1],
+            ],
+            "faces_vertices": [
+                [0, 1, 6], [0, 6, 5], [1, 2, 7], [1, 7, 6],
+                [2, 3, 8], [2, 8, 7], [3, 4, 9], [3, 9, 8],
+                [5, 6, 11], [5, 11, 10], [6, 7, 12], [6, 12, 11],
+                [7, 8, 13], [7, 13, 12], [8, 9, 14], [8, 14, 13],
+                [10, 11, 16], [10, 16, 15], [11, 12, 17], [11, 17, 16],
+                [12, 13, 18], [12, 18, 17], [13, 14, 19], [13, 19, 18],
+                [15, 16, 21], [15, 21, 20], [16, 17, 22], [16, 22, 21],
+                [17, 18, 23], [17, 23, 22], [18, 19, 24], [18, 24, 23],
+            ],
+            "edges_vertices": [
+                [0, 1], [1, 6], [6, 0], [0, 5], [5, 6],
+                [1, 2], [2, 7], [7, 1], [6, 7],
+                [2, 3], [3, 8], [8, 2], [7, 8],
+                [3, 4], [4, 9], [9, 3], [8, 9],
+                [5, 11], [10, 11], [6, 11],
+                [6, 12], [11, 12], [7, 12],
+                [7, 13], [12, 13], [8, 13],
+                [8, 14], [13, 14], [9, 14],
+                [5, 10], [10, 16], [10, 15], [15, 16], [11, 16],
+                [11, 17], [16, 17], [12, 17],
+                [12, 18], [17, 18], [13, 18],
+                [13, 19], [18, 19], [14, 19],
+                [15, 21], [15, 20], [20, 21], [16, 21],
+                [16, 22], [21, 22], [17, 22],
+                [17, 23], [22, 23], [18, 23],
+                [18, 24], [23, 24], [19, 24],
+            ],
+            "edges_assignment": [
+                "B", "M", "F", "B", "V",
+                "B", "V", "F", "V",
+                "B", "M", "F", "V",
+                "B", "B", "F", "V",
+                "F", "M", "M",
+                "V", "M", "V",
+                "M", "M", "M",
+                "F", "M", "B",
+                "B", "F", "B", "V", "V",
+                "M", "V", "V",
+                "V", "V", "V",
+                "F", "V", "B",
+                "F", "B", "B", "V",
+                "M", "V", "V",
+                "V", "V", "V",
+                "F", "B", "B",
+            ],
+        },
+    },
+    # --- Additional prompt variations for training diversity ---
+    {
+        "prompt": "Fold a piece of paper in half horizontally",
+        "target": {
+            "vertices_coords": [[-1, 1], [1, 1], [-1, 0], [1, 0], [-1, -1], [1, -1]],
+            "faces_vertices": [[0, 2, 3], [0, 3, 1], [2, 4, 5], [2, 5, 3]],
+            "edges_vertices": [
+                [0, 2], [2, 3], [3, 0], [0, 1], [1, 3],
+                [2, 4], [4, 5], [5, 3],
+            ],
+            "edges_assignment": ["B", "V", "F", "B", "B", "B", "B", "F"],
+        },
+    },
+    {
+        "prompt": "Make a zig-zag fold like a paper fan",
+        "target": {
+            "vertices_coords": [
+                [-1, 1], [-0.5, 1], [0, 1], [0.5, 1], [1, 1],
+                [-1, -1], [-0.5, -1], [0, -1], [0.5, -1], [1, -1],
+            ],
+            "faces_vertices": [
+                [0, 1, 6], [0, 6, 5],
+                [1, 2, 7], [1, 7, 6],
+                [2, 3, 8], [2, 8, 7],
+                [3, 4, 9], [3, 9, 8],
+            ],
+            "edges_vertices": [
+                [0, 1], [1, 6], [6, 0], [0, 5], [5, 6],
+                [1, 2], [2, 7], [7, 1], [6, 7],
+                [2, 3], [3, 8], [8, 2], [7, 8],
+                [3, 4], [4, 9], [9, 3], [8, 9],
+            ],
+            "edges_assignment": [
+                "B", "V", "F", "B", "B",
+                "B", "M", "F", "F",
+                "B", "V", "F", "F",
+                "B", "B", "F", "B",
+            ],
+        },
+    },
+    {
+        "prompt": "Create the base for a paper crane",
+        "target": {
+            "vertices_coords": [
+                [-1, 1], [0, 1], [1, 1],
+                [-1, 0], [0, 0], [1, 0],
+                [-1, -1], [0, -1], [1, -1],
+                [-0.5, 0.5], [0.5, 0.5], [-0.5, -0.5], [0.5, -0.5],
+            ],
+            "faces_vertices": [
+                [0, 9, 3], [0, 1, 9], [1, 4, 9], [3, 9, 4],
+                [1, 10, 4], [1, 2, 10], [2, 5, 10], [4, 10, 5],
+                [3, 4, 11], [3, 11, 6], [6, 11, 7], [4, 7, 11],
+                [4, 5, 12], [5, 8, 12], [8, 7, 12], [4, 12, 7],
+            ],
+            "edges_vertices": [
+                [0, 9], [9, 3], [0, 1], [1, 9], [1, 4], [9, 4],
+                [1, 10], [1, 2], [2, 10], [2, 5], [5, 10], [10, 4],
+                [3, 4], [3, 11], [11, 6], [6, 7], [7, 11], [11, 4],
+                [4, 5], [4, 12], [5, 12], [5, 8], [8, 12], [12, 7], [7, 4],
+            ],
+            "edges_assignment": [
+                "V", "M", "B", "M", "M", "V",
+                "M", "B", "V", "B", "M", "V",
+                "M", "M", "V", "B", "M", "V",
+                "M", "V", "M", "B", "V", "M", "M",
+            ],
+        },
+    },
+    {
+        "prompt": "Make a simple diagonal fold from corner to corner",
+        "target": {
+            "vertices_coords": [[0, 0], [1, 0], [1, 1], [0, 1]],
+            "faces_vertices": [[0, 1, 2], [0, 2, 3]],
+            "edges_vertices": [[0, 1], [1, 2], [2, 3], [3, 0], [0, 2]],
+            "edges_assignment": ["B", "B", "B", "B", "V"],
+        },
+    },
+]
+
+
+# ---------------------------------------------------------------------------
+# Reward calculation
+# ---------------------------------------------------------------------------
+
+
+def _build_graph(fold_data: dict) -> nx.Graph:
+    """Convert FOLD data to a networkx graph for structural comparison."""
+    G = nx.Graph()
+    verts = fold_data.get("vertices_coords", [])
+    edges = fold_data.get("edges_vertices", [])
+    assignments = fold_data.get("edges_assignment", [])
+
+    for i, v in enumerate(verts):
+        G.add_node(i, x=float(v[0]), y=float(v[1]))
+
+    for i, e in enumerate(edges):
+        a = assignments[i] if i < len(assignments) else "U"
+        G.add_edge(int(e[0]), int(e[1]), assignment=a)
+
+    return G
+
+
+def _edge_overlap_score(gen_graph: nx.Graph, target_graph: nx.Graph) -> float:
+    """
+    Compute a normalised edge-overlap score based on assignment histogram IoU.
+    """
+    gen_assign = sorted(
+        [d.get("assignment", "U") for _, _, d in gen_graph.edges(data=True)]
+    )
+    tgt_assign = sorted(
+        [d.get("assignment", "U") for _, _, d in target_graph.edges(data=True)]
+    )
+
+    gen_counts = Counter(gen_assign)
+    tgt_counts = Counter(tgt_assign)
+
+    all_keys = set(gen_counts.keys()) | set(tgt_counts.keys())
+    intersection = sum(min(gen_counts[k], tgt_counts[k]) for k in all_keys)
+    union = sum(max(gen_counts[k], tgt_counts[k]) for k in all_keys)
+
+    if union == 0:
+        return 0.0
+    return intersection / union
+
+
+def calculate_fold_reward(generated_json: str, target_json: dict) -> float:
+    """
+    Multi-component reward for comparing a generated FOLD JSON to a target.
+
+    Components:
+      1. JSON validity          (-2.0 penalty if invalid)
+      2. Required fields        (-1.0 penalty if missing)
+      3. Vertex count similarity (0 - 0.3)
+      4. Edge count similarity   (0 - 0.3)
+      5. Assignment overlap IoU  (0 - 0.4)
+
+    Total reward clipped to [-2.0, 1.0].
+    """
+    try:
+        gen_data = json.loads(generated_json)
+    except (json.JSONDecodeError, TypeError):
+        return -2.0
+
+    for field in ("vertices_coords", "edges_vertices"):
+        if field not in gen_data:
+            return -1.0
+
+    reward = 0.0
+
+    # Vertex count similarity (max 0.3)
+    gen_v = len(gen_data.get("vertices_coords", []))
+    tgt_v = len(target_json.get("vertices_coords", []))
+    if tgt_v > 0:
+        v_ratio = 1.0 - min(abs(gen_v - tgt_v) / tgt_v, 1.0)
+        reward += v_ratio * 0.3
+
+    # Edge count similarity (max 0.3)
+    gen_e = len(gen_data.get("edges_vertices", []))
+    tgt_e = len(target_json.get("edges_vertices", []))
+    if tgt_e > 0:
+        e_ratio = 1.0 - min(abs(gen_e - tgt_e) / tgt_e, 1.0)
+        reward += e_ratio * 0.3
+
+    # Assignment overlap (max 0.4)
+    try:
+        gen_graph = _build_graph(gen_data)
+        tgt_graph = _build_graph(target_json)
+        overlap = _edge_overlap_score(gen_graph, tgt_graph)
+        reward += overlap * 0.4
+    except Exception:
+        pass
+
+    return max(-2.0, min(1.0, reward))
+
+
+# ---------------------------------------------------------------------------
+# OpenEnv Environment
+# ---------------------------------------------------------------------------
+
+
+class OrigamiEnv(Environment[FoldAction, FoldObservation, State]):
+    """
+    Single-turn RL environment for origami crease-pattern generation.
+
+    reset() -> returns a natural-language prompt as the observation.
+    step()  -> accepts FOLD JSON, compares to ground truth, returns reward.
+    """
+
+    def __init__(self) -> None:
+        super().__init__()
+        self.dataset = DATASET
+        self.current_idx = 0
+        self._step_count = 0
+        self._episode_id: Optional[str] = None
+
+    def reset(
+        self,
+        seed: Optional[int] = None,
+        episode_id: Optional[str] = None,
+        **kwargs: Any,
+    ) -> FoldObservation:
+        if seed is not None:
+            np.random.seed(seed)
+        self.current_idx = int(np.random.randint(len(self.dataset)))
+        self._step_count = 0
+        self._episode_id = episode_id
+        return FoldObservation(
+            prompt=self.dataset[self.current_idx]["prompt"],
+            done=False,
+            reward=None,
+            info={
+                "target_vertex_count": len(
+                    self.dataset[self.current_idx]["target"]["vertices_coords"]
+                ),
+                "target_edge_count": len(
+                    self.dataset[self.current_idx]["target"]["edges_vertices"]
+                ),
+            },
+        )
+
+    def step(
+        self,
+        action: FoldAction,
+        timeout_s: Optional[float] = None,
+        **kwargs: Any,
+    ) -> FoldObservation:
+        target = self.dataset[self.current_idx]["target"]
+        reward = calculate_fold_reward(action.fold_json, target)
+        self._step_count += 1
+        return FoldObservation(
+            prompt="Episode finished.",
+            done=True,
+            reward=reward,
+            info={
+                "prompt": self.dataset[self.current_idx]["prompt"],
+                "target_vertex_count": len(target["vertices_coords"]),
+                "target_edge_count": len(target["edges_vertices"]),
+            },
+        )
+
+    def state(self) -> State:
+        return State(
+            episode_id=self._episode_id,
+            step_count=self._step_count,
+        )
+
+
+# ---------------------------------------------------------------------------
+# Create the FastAPI application
+# ---------------------------------------------------------------------------
+
+app = create_fastapi_app(
+    env=OrigamiEnv,
+    action_cls=FoldAction,
+    observation_cls=FoldObservation,
+)

requirements.txt

@@ -0,0 +1,5 @@
+openenv-core>=0.2.1
+fastapi
+uvicorn
+numpy
+networkx