stdraw 0.7.13__py3-none-any.whl

stdraw/delivery.py

@@ -0,0 +1,81 @@
+# -*- coding: utf-8 -*-
+"""Delivery-contract metadata for stdraw coordinate outputs.
+
+stdraw's deliverable is the interactive demo page (demo-2d.html: drag
+touch-up layer + embedded quality certificate), not bare coordinates.
+Every coordinate dict produced by the layout pipelines (ortho-v1 /
+auto-v2) therefore carries an explicit delivery contract:
+
+    "delivery"         "coordinates-only" | "stdraw-cli"
+    "interactive"      false | true
+    "engine_version"   stdraw.__version__ of the producing engine
+    "delivery_warning" one-line warning (coordinates-only mode only)
+
+The contract is additive metadata: hosts that only read known keys
+(nodes/edges/viewBox/meta) keep working unchanged. Hosts that build
+their own static renderer from the coordinates lose live drag
+re-routing, waypoint handles, the export->recompute loop and the honest
+quality certificate -- the warning says so at the point of consumption.
+
+Layering:
+  - pipeline cores (planar.PlanarLayout.run / layout_auto.layout) stamp
+    coordinates-only metadata;
+  - the CLI re-stamps to "stdraw-cli" / interactive=true when the full
+    deliverable set (demo-2d.html + certificate.json) was produced, and
+    omits the warning;
+  - the ortho CLI strips the metadata before writing layout.json: the
+    ortho-v1 layout.json artifact is a byte-frozen production pin
+    (tests/baselines/, ci_checks gate A) and must stay byte-stable; its
+    delivery contract travels on certificate.json instead (the
+    "interactive" / "drag_layer" fields).
+
+Consumers who truly need raw coordinates can silence the warning via
+stdraw.recipes.run(..., suppress_delivery_warning=True) -- an explicit,
+transparent opt-out.
+"""
+from . import __version__
+
+DELIVERY_KEYS = ("delivery", "interactive", "engine_version",
+                 "delivery_warning")
+
+DELIVERY_WARNING = (
+    "coordinates-only output: this file is layout coordinates, not the "
+    "stdraw deliverable. The stdraw deliverable is demo-2d.html (drag "
+    "touch-up layer + embedded quality certificate); produce it with "
+    "`stdraw layout <input.cld>` and embed that page (see README, "
+    "Agent Integration). Building a static renderer from these "
+    "coordinates loses live drag re-routing, waypoint handles, the "
+    "export->recompute loop and the quality certificate.")
+
+
+def stamp_coordinates_only(v4: dict, warning: bool = True) -> dict:
+    """Stamp the coordinates-only delivery contract onto a layout dict.
+
+    Additive: delivery keys are appended after the existing keys; existing
+    keys and their order are untouched (backward compatible, deterministic).
+    """
+    v4["delivery"] = "coordinates-only"
+    v4["interactive"] = False
+    v4["engine_version"] = __version__
+    if warning:
+        v4["delivery_warning"] = DELIVERY_WARNING
+    else:
+        v4.pop("delivery_warning", None)
+    return v4
+
+
+def stamp_cli_deliverable(v4: dict) -> dict:
+    """Re-stamp a layout dict produced alongside the full CLI deliverable
+    (demo-2d.html + certificate.json): interactive, no warning."""
+    v4["delivery"] = "stdraw-cli"
+    v4["interactive"] = True
+    v4["engine_version"] = __version__
+    v4.pop("delivery_warning", None)
+    return v4
+
+
+def strip_delivery_metadata(v4: dict) -> dict:
+    """Remove delivery-contract keys (ortho CLI freeze-compat path)."""
+    for k in DELIVERY_KEYS:
+        v4.pop(k, None)
+    return v4

stdraw/dsl.py

@@ -0,0 +1,99 @@
+# -*- coding: utf-8 -*-
+"""stdraw DSL v0.1 (draft) parser — the minimal closed loop.
+
+Syntax (line-oriented, # starts a comment, blank lines ignored):
+
+    graph "graph name"
+    var <id> "<label>" [@value "<value text>"] [@group <gid>] [@w <extra px>]
+    <a> -> <+|-> <b> [@loops <id1>,<id2>]
+    loop <id> "<label>" "<R|B>" [<n1>, <n2>, ...]
+    group <gid> "<group label>"
+
+- Variables must be declared before use; polarity edge pairs are the input to
+  layout and certificates;
+- Loop declarations state semantic loops, validated by loops.lint for closure
+  + R/B polarity edge counting;
+- Groups are optional and do not participate in layout (tension handling is
+  discussed in the model.py module docstring).
+
+Parsing is deterministic: the same text always yields the same Graph.
+"""
+import re
+from .model import Graph, Node, Edge, Loop, Group
+
+_VAR_RE = re.compile(
+    r'^var\s+(\w+)\s+"([^"]*)"(?:\s+@value\s+"([^"]*)")?'
+    r'(?:\s+@group\s+(\w+))?(?:\s+@w\s+(\d+))?\s*$')
+_EDGE_RE = re.compile(
+    r'^(\w+)\s*->\s*([+\-])\s*(\w+)(?:\s+@loops\s+([\w,\s]+))?\s*$')
+_LOOP_RE = re.compile(
+    r'^loop\s+(\w+)\s+"([^"]*)"\s+"?([RB])"?\s*\[([^\]]*)\]\s*$')
+_GROUP_RE = re.compile(r'^group\s+(\w+)\s+"([^"]*)"\s*$')
+_GRAPH_RE = re.compile(r'^graph\s+"([^"]*)"\s*$')
+
+
+def parse(text: str) -> Graph:
+    g = Graph(nodes=[], edges=[], loops=[], groups=[], name="")
+    for lineno, raw in enumerate(text.splitlines(), 1):
+        line = raw.split("#", 1)[0].strip()
+        if not line:
+            continue
+        m = _GRAPH_RE.match(line)
+        if m:
+            g.name = m.group(1)
+            continue
+        m = _VAR_RE.match(line)
+        if m:
+            g.nodes.append(Node(id=m.group(1), label=m.group(2),
+                                value=m.group(3) or "",
+                                group=m.group(4) or None,
+                                extra_w=int(m.group(5) or 0)))
+            continue
+        m = _EDGE_RE.match(line)
+        if m:
+            loops = [x.strip() for x in (m.group(4) or "").split(",") if x.strip()]
+            g.edges.append(Edge(a=m.group(1), b=m.group(3),
+                                polarity=m.group(2), loops=loops))
+            continue
+        m = _LOOP_RE.match(line)
+        if m:
+            ns = [x.strip() for x in m.group(4).split(",") if x.strip()]
+            g.loops.append(Loop(id=m.group(1), label=m.group(2),
+                                nodes=ns, kind=m.group(3)))
+            continue
+        m = _GROUP_RE.match(line)
+        if m:
+            g.groups.append(Group(id=m.group(1), label=m.group(2)))
+            continue
+        raise ValueError(f"DSL line {lineno} cannot be parsed: {raw.strip()!r}")
+    problems = g.validate()
+    if problems:
+        raise ValueError("DSL structural validation failed:\n  " + "\n  ".join(problems))
+    return g
+
+
+def dumps(g: Graph) -> str:
+    """Graph -> DSL text (round-trip consistent: parse(dumps(g)) == g)."""
+    out = []
+    if g.name:
+        out.append(f'graph "{g.name}"')
+    out.append("")
+    for n in g.nodes:
+        parts = [f'var {n.id} "{n.label}"']
+        if n.value:
+            parts.append(f'@value "{n.value}"')
+        if n.group:
+            parts.append(f"@group {n.group}")
+        if n.extra_w:
+            parts.append(f"@w {n.extra_w}")
+        out.append(" ".join(parts))
+    out.append("")
+    for e in g.edges:
+        tail = f" @loops {','.join(e.loops)}" if e.loops else ""
+        out.append(f"{e.a} -> {e.polarity} {e.b}{tail}")
+    out.append("")
+    for lp in g.loops:
+        out.append(f'loop {lp.id} "{lp.label}" "{lp.kind}" [{", ".join(lp.nodes)}]')
+    for gr in g.groups:
+        out.append(f'group {gr.id} "{gr.label}"')
+    return "\n".join(out) + "\n"

stdraw/layout3d.py

@@ -0,0 +1,167 @@
+# -*- coding: utf-8 -*-
+"""3D placement layer (the "lowest-tier" delivery form): nodes arranged in regular solids.
+
+Five-solid slot generation + deterministic assignment; arbitrary-angle rotation, depth shading, wireframe reference.
+
+Solids: sphere (Fibonacci sphere) / cube (lattice points) / tetra (tetrahedron face mesh) /
+cone (concentric rings shrinking to the apex). Assignment: greedy nearest neighbor + pairwise-swap optimization minimizing total edge length
+(deterministic: slot order, assignment order, and swap order all fixed; no RNG).
+
+Chords not intersecting in space is guaranteed by dimensional redundancy; projection crossings are resolved by the camera in the user's hands --
+the 3D layer makes no 2D crossing promise (honest tiering).
+"""
+import math
+from typing import Dict, List, Tuple
+
+
+# ── Slot generation (all deterministic, unit coordinates, uniformly scaled after generation) ──────────
+def sphere_slots(n: int) -> List[Tuple[float, float, float]]:
+    pts = []
+    golden = math.pi * (3 - math.sqrt(5))
+    for i in range(n):
+        y = 1 - (i / max(n - 1, 1)) * 2
+        r = math.sqrt(max(0.0, 1 - y * y))
+        th = golden * i
+        pts.append((math.cos(th) * r, y, math.sin(th) * r))
+    return pts
+
+
+def cube_slots(n: int) -> List[Tuple[float, float, float]]:
+    m = max(2, math.ceil(n ** (1 / 3)))
+    pts = []
+    for z in range(m):
+        for y in range(m):
+            for x in range(m):
+                pts.append(((x / (m - 1)) * 2 - 1,
+                            (y / (m - 1)) * 2 - 1,
+                            (z / (m - 1)) * 2 - 1))
+    return pts[:n]
+
+
+_TETRA_V = [(1, 1, 1), (1, -1, -1), (-1, 1, -1), (-1, -1, 1)]
+
+
+def tetra_slots(n: int) -> List[Tuple[float, float, float]]:
+    """Tetrahedron face mesh: barycentric layer sweep (each layer lies on the 4 faces, min component = 0)."""
+    pts = []
+    s = 3
+    while len(pts) < n and s < 60:
+        layer = []
+        for i in range(s + 1):
+            for j in range(s + 1 - i):
+                for k in range(s + 1 - i - j):
+                    l = s - i - j - k
+                    b = (i, j, k, l)
+                    if min(b) == 0:      # on a face
+                        x = sum(c * v[0] for c, v in zip(b, _TETRA_V)) / s
+                        y = sum(c * v[1] for c, v in zip(b, _TETRA_V)) / s
+                        z = sum(c * v[2] for c, v in zip(b, _TETRA_V)) / s
+                        layer.append((x, y, z))
+        layer.sort()                     # deterministic order
+        pts.extend(layer)
+        s += 1
+    # fallback: truncate when full; if short, top up with a Fibonacci sphere (recorded honestly)
+    if len(pts) >= n:
+        return pts[:n]
+    extra = sphere_slots(n - len(pts))
+    return pts + extra
+
+
+def cone_slots(n: int) -> List[Tuple[float, float, float]]:
+    """Cone: 1 apex point + concentric rings going down (radius scaling up linearly, uniform angles within a ring)."""
+    pts = [(0.0, 1.0, 0.0)]
+    if n == 1:
+        return pts
+    rings = max(1, round(math.sqrt(n - 1)))
+    per = max(1, (n - 1) // rings)
+    t = 0
+    placed = 1
+    while placed < n:
+        frac = (t + 1) / rings
+        r = frac
+        y = 1 - frac * 2
+        cnt = min(per, n - placed) if placed + per < n else n - placed
+        cnt = max(1, cnt)
+        for k in range(cnt):
+            ang = 2 * math.pi * k / cnt + 0.5 * t      # inter-layer offset (deterministic)
+            pts.append((math.cos(ang) * r, y, math.sin(ang) * r))
+        placed += cnt
+        t += 1
+    return pts[:n]
+
+
+SOLIDS = {"sphere": sphere_slots, "cube": cube_slots,
+          "tetra": tetra_slots, "cone": cone_slots}
+
+
+# ── Deterministic assignment: greedy nearest neighbor + pairwise-swap optimization ────────────────────
+def assign(nodes: List[str], slots: List[Tuple[float, float, float]],
+           edges: List[Tuple[str, str]]) -> Dict[str, Tuple[float, float, float]]:
+    """Nodes -> slots. Greedy (fixed node order) + all-pairs swap passes (swap only on positive gain, fixed order)."""
+    avail = list(range(len(slots)))
+    m = {v: None for v in nodes}
+    # coarse ordering across components: node order by adjacency-chain BFS order (deterministic), isolated nodes last
+    adj: Dict[str, List[str]] = {v: [] for v in nodes}
+    for a, b in edges:
+        adj.setdefault(a, []).append(b)
+        adj.setdefault(b, []).append(a)
+    order, seen = [], set()
+    for v in nodes:
+        if v in seen or not adj[v]:
+            continue
+        stack = [v]
+        while stack:
+            u = stack.pop()
+            if u in seen:
+                continue
+            seen.add(u)
+            order.append(u)
+            for w in sorted(adj[u], reverse=True):
+                if w not in seen:
+                    stack.append(w)
+    order += [v for v in nodes if v not in seen]
+
+    def edge_len_sum():
+        return sum(math.dist(m[a], m[b]) for a, b in edges
+                   if m.get(a) and m.get(b))
+
+    for v in order:
+        if not avail:
+            break
+        # greedy: pick the slot minimizing the increment in assigned edge length (ties resolved toward the smaller index, deterministic)
+        best, best_cost = None, None
+        for si in avail:
+            c = 0.0
+            for w in adj[v]:
+                if m.get(w) is not None:
+                    c += math.dist(slots[si], m[w])
+            if best_cost is None or c < best_cost - 1e-12:
+                best, best_cost = si, c
+        m[v] = slots[best]
+        avail.remove(best)
+    # pairwise-swap optimization (at most 4 passes)
+    node_list = order
+    for _ in range(4):
+        improved = False
+        for i in range(len(node_list)):
+            for j in range(i + 1, len(node_list)):
+                a, b = node_list[i], node_list[j]
+                m[a], m[b] = m[b], m[a]
+                if edge_len_sum() < edge_len_sum() - 1e-9:
+                    improved = True
+                else:
+                    m[a], m[b] = m[b], m[a]
+        if not improved:
+            break
+    return m
+
+
+def layout3d(graph_dict: dict, solid: str = "sphere", scale: float = 300.0):
+    """graph_dict: {"nodes":[{id,label}], "edges":[{a,b}]} -> {"positions": {...}}"""
+    gen = SOLIDS[solid]
+    ids = [n["id"] for n in graph_dict["nodes"]]
+    edges = [(e["a"], e["b"]) for e in graph_dict["edges"]]
+    slots = gen(len(ids))
+    m = assign(ids, slots, edges)
+    return {"solid": solid, "scale": scale,
+            "positions": {v: [round(c * scale, 1) for c in m[v]] for v in ids}}