Files
make-cad/viewer/server/operation_tips.py
T
NiJingzhe ec4bb31ae8 feat(viewer): submission context gains per-entity neighborhood cards; op registry 7 categories
- runtime.entity_neighborhood: one-level adjacency cards (face→edges with
  adjacent faces + vertices; edge→vertices/faces/adjacent edges; vertex→
  edges/faces), truncated lists name their totals
- compose_submission passes BRepModel.adjacency_details into the context
- scene_build tags edges with seam/degenerate flags and meshes edges at a
  finer tolerance (lin 0.1 / ang 0.1)
- operation registry: boolean.md split into union/cut/intersect; new
  box/cylinder/cone/sphere/shell/mirror/twisted_sweep/helical_sweep docs
  (5 → 7 categories, 23 operations)
- tests: seam flags, neighborhood cards per entity kind, registry shape
2026-09-06 02:32:49 +08:00

155 lines
6.3 KiB
Python

"""Operation tip loader for the re-studio composer.
An operation tip is a packaged prompt fragment (CLI-command style) bound to a
composer chip. Tips are content, not code: each ``operations/<op_id>.md``
file carries YAML-ish frontmatter (label, category, api, reads, doc_refs)
plus the hint text as its body. Editing or adding a tip is a markdown edit;
this module only loads and validates the folder.
Semantics of the frontmatter fields:
- ``category`` — one of ``OPERATION_CATEGORIES`` (the human's five-way
classification: sketch / solid build / modifier / surface / pattern);
- ``api`` — the SDK entry points the tip is about;
- ``reads`` — which geometric features of the tagged entities the operation
consumes, so context assembly knows what to extract and pass;
- ``doc_refs`` — repo-relative skill references the agent should read before
using the operation;
- body — the imperative hint itself.
The browser renders its palette from ``GET /api/operations`` and
``compose_submission`` embeds the tips for every referenced operation, so the
agent receives the doc pointers without scraping. Malformed files are never
silently skipped: they are named in the payload ``errors`` list and logged.
"""
from __future__ import annotations
import re
import sys
from pathlib import Path
from typing import Any
_TIPS_DIR = Path(__file__).resolve().parent / "operations"
_KNOWN_FIELDS = ("label", "category", "api", "reads", "doc_refs")
_LIST_FIELDS = ("api", "reads", "doc_refs")
OPERATION_CATEGORIES: tuple[dict[str, str], ...] = (
{"id": "sketch", "label": "SKETCH", "description": "constrained 2D profiles (sketch API)"},
{"id": "boolean", "label": "BOOLEAN", "description": "union / cut / intersect"},
{"id": "solid", "label": "SOLID", "description": "extrude / revolve / sweep / loft body builds"},
{"id": "primitive", "label": "PRIMITIVE", "description": "box / cylinder / cone / sphere stock bodies"},
{"id": "modify", "label": "MODIFY", "description": "fillet / chamfer / shell edge & face treatments"},
{"id": "surface", "label": "SURFACE", "description": "patch / fill / freeform surface construction"},
{"id": "pattern", "label": "PATTERN", "description": "linear / radial (circular) arrays and mirrors"},
)
_CATEGORY_ORDER = {category["id"]: index for index, category in enumerate(OPERATION_CATEGORIES)}
_REGISTRY_CACHE: dict[str, Any] | None = None
_REGISTRY_STAMP: tuple[tuple[str, float], ...] | None = None
def _parse_frontmatter(text: str) -> tuple[dict[str, Any], str]:
"""Parse the tiny frontmatter subset these files use (stdlib only)."""
lines = text.splitlines()
if not lines or lines[0].strip() != "---":
raise ValueError("frontmatter must open with '---'")
fields: dict[str, Any] = {}
index = 1
while index < len(lines) and lines[index].strip() != "---":
stripped = lines[index].strip()
if not stripped or stripped.startswith("#"):
index += 1
continue
match = re.match(r"^([A-Za-z_][A-Za-z0-9_]*):\s*(.*)$", stripped)
if not match:
raise ValueError(f"unparseable frontmatter line {index + 1}: {stripped!r}")
key, value = match.group(1), match.group(2).strip()
if key not in _KNOWN_FIELDS:
raise ValueError(f"unknown frontmatter field {key!r}")
if value:
fields[key] = value
index += 1
continue
items: list[str] = []
index += 1
while index < len(lines) and lines[index].strip().startswith("- ") and lines[index].strip() != "---":
items.append(lines[index].strip()[2:].strip())
index += 1
fields[key] = items
if index >= len(lines):
raise ValueError("frontmatter is never terminated with '---'")
body = "\n".join(lines[index + 1 :]).strip()
return fields, body
def _validate_tip(op_id: str, fields: dict[str, Any], body: str) -> None:
if not isinstance(fields.get("label"), str) or not fields["label"]:
raise ValueError("label must be a non-empty string")
category = fields.get("category")
if category not in _CATEGORY_ORDER:
raise ValueError(f"category {category!r} is not one of {sorted(_CATEGORY_ORDER)}")
for field in _LIST_FIELDS:
value = fields.get(field)
if not isinstance(value, list) or not value or not all(isinstance(item, str) and item for item in value):
raise ValueError(f"{field} must be a non-empty dash list")
if not body:
raise ValueError("hint body is empty")
def _load_registry() -> dict[str, Any]:
"""Load (and mtime-cache) the operations folder."""
global _REGISTRY_CACHE, _REGISTRY_STAMP
files = sorted(_TIPS_DIR.glob("*.md")) if _TIPS_DIR.is_dir() else []
stamp = tuple((path.name, path.stat().st_mtime) for path in files)
if _REGISTRY_CACHE is not None and stamp == _REGISTRY_STAMP:
return _REGISTRY_CACHE
tips: dict[str, dict[str, Any]] = {}
errors: list[str] = []
for path in files:
op_id = path.stem
try:
fields, body = _parse_frontmatter(path.read_text(encoding="utf-8"))
_validate_tip(op_id, fields, body)
except (OSError, ValueError) as exc:
message = f"{path.name}: {exc}"
errors.append(message)
print(f"[re-studio] operation tip rejected — {message}", file=sys.stderr)
continue
tips[op_id] = {"op_id": op_id, **fields, "hint": body}
registry = {"tips": tips, "errors": errors}
_REGISTRY_CACHE = registry
_REGISTRY_STAMP = stamp
return registry
def operation_payload() -> dict[str, Any]:
"""Registry payload for ``GET /api/operations`` (browser palette)."""
registry = _load_registry()
operations = sorted(
registry["tips"].values(),
key=lambda tip: (_CATEGORY_ORDER[tip["category"]], tip["op_id"]),
)
return {
"categories": [dict(category) for category in OPERATION_CATEGORIES],
"operations": operations,
"errors": list(registry["errors"]),
}
def operation_context_for(op_ids: list[str]) -> dict[str, dict[str, Any]]:
"""Tips for every referenced operation, keyed by op id (stable order)."""
registry = _load_registry()
return {op_id: dict(registry["tips"][op_id]) for op_id in op_ids if op_id in registry["tips"]}
__all__ = [
"OPERATION_CATEGORIES",
"operation_context_for",
"operation_payload",
]