ventforge 0.1.0__py3-none-any.whl

ventforge/mcp_server.py

@@ -0,0 +1,206 @@
+"""MCP server for VentForge. Works on one "current" design file; the GUI watches that file,
+so every change made here shows up live in an open editor window."""
+from __future__ import annotations
+
+import subprocess
+import sys
+from dataclasses import fields, is_dataclass
+from pathlib import Path
+
+from mcp.server.mcpserver import Image, MCPServer
+
+from . import model
+from .model import Design
+
+PRESETS = Path(__file__).resolve().parent / "presets"
+HOME = Path.home() / "Documents" / "VentForge"
+
+mcp = MCPServer("ventforge", instructions=(
+    "Design vent hole patterns for 3D parts. Units mm, canvas centred at origin, y up, angles in degrees. "
+    "Workflow: new_design (or open_design) -> describe_parameters -> set_params / add_control -> preview "
+    "(look at the image and stats: open_area_ratio, min_wall_violations) -> iterate -> export. "
+    "The current design is a .vent.json file; call open_in_gui to let the user watch it live."))
+
+_current: Path | None = None
+
+
+def _path() -> Path:
+    global _current
+    if _current is None:
+        HOME.mkdir(parents=True, exist_ok=True)
+        _current = HOME / "current.vent.json"
+        if not _current.exists():
+            Design().save(_current)
+    return _current
+
+
+def _load() -> Design:
+    return Design.load(_path())
+
+
+def _generate(d: Design):
+    from .pattern import generate
+    return generate(d)
+
+
+def _stats(r) -> dict:
+    return {k: (round(v, 4) if isinstance(v, float) else v) for k, v in r.stats.items()}
+
+
+@mcp.tool()
+def new_design(path: str = "", preset: str = "", name: str = "") -> dict:
+    """Start a design (default file ~/Documents/VentForge/current.vent.json), optionally from a preset name
+    (see list_presets). Returns the file path and stats."""
+    global _current
+    d = Design.load(PRESETS / f"{preset}.vent.json") if preset else Design()
+    if name:
+        d.name = name
+    _current = Path(path).expanduser().resolve() if path else _path()
+    _current.parent.mkdir(parents=True, exist_ok=True)
+    d.save(_current)
+    return {"path": str(_current), "stats": _stats(_generate(d))}
+
+
+@mcp.tool()
+def open_design(path: str) -> dict:
+    """Make an existing .vent.json file the current design."""
+    global _current
+    p = Path(path).expanduser().resolve()
+    d = Design.load(p)
+    _current = p
+    return {"path": str(p), "name": d.name, "stats": _stats(_generate(d))}
+
+
+@mcp.tool()
+def list_presets() -> list[str]:
+    """Names of the built-in presets usable with new_design(preset=...)."""
+    return sorted(p.name.removesuffix(".vent.json") for p in PRESETS.glob("*.vent.json"))
+
+
+@mcp.tool()
+def get_design() -> dict:
+    """The full current design as a dict (same shape as the .vent.json file)."""
+    return {"path": str(_path()), "design": _load().to_dict()}
+
+
+def _schema(obj) -> dict:
+    return {f.name: _schema(getattr(obj, f.name)) if is_dataclass(getattr(obj, f.name))
+            else f"{type(getattr(obj, f.name)).__name__} = {getattr(obj, f.name)!r}" for f in fields(obj)}
+
+
+@mcp.tool()
+def describe_parameters() -> dict:
+    """Every parameter with its type and default, plus the allowed enum values. Parameter meanings are
+    documented in ventforge/model.py; pattern.<mode> holds the settings of each layout mode."""
+    return {"enums": {"dot.shape": model.SHAPES, "pattern.mode": model.MODES, "boundary.type": model.BOUNDARIES,
+                      "gradients.target_shape": model.TARGET_SHAPES,
+                      "pattern.grid.arrangement": ("square", "diamond", "hexagon"),
+                      "rotate_by": ("row", "col", "both"), "flowlines.edge_style": ("flat", "round"),
+                      "control.kind": ("point", "line", "curve"), "gradient.falloff": ("linear", "smooth")},
+            "gradient_semantics": "size/spacing are multipliers (edge 1 = neutral), angle adds degrees, "
+                                  "shape morphs 0..1 towards target_shape. A control has `value` at its "
+                                  "location blending to the gradient's `edge` value at distance `radius`.",
+            "defaults": _schema(Design())}
+
+
+@mcp.tool()
+def set_params(patch: dict) -> dict:
+    """Deep-merge a partial design, e.g. {"dot": {"shape": "hexagon", "diameter": 3},
+    "pattern": {"mode": "grid", "grid": {"spacing_x": 4.5}}}. Lists (points, controls) are replaced whole.
+    Saves the file (live-updates the GUI) and returns stats."""
+    d = _load().patched(patch).resolve_images(_path().parent)
+    r = _generate(d)  # generate before saving so a bad patch never lands in the file
+    d.save(_path())
+    return {"stats": _stats(r)}
+
+
+@mcp.tool()
+def add_control(target: str, kind: str = "point", points: list[list[float]] | None = None,
+                value: float = 0.2, radius: float = 50.0, enable: bool = True) -> dict:
+    """Add a gradient control to target size|spacing|angle|shape. kind point (1 point), line (2), curve (>=3)."""
+    d = _load()
+    g = getattr(d.gradients, target)
+    g.controls.append(model.Control(kind=kind, points=points or [[0.0, 0.0]], value=value, radius=radius))
+    g.enabled = g.enabled or enable
+    r = _generate(d)
+    d.save(_path())
+    return {"controls": len(g.controls), "stats": _stats(r)}
+
+
+@mcp.tool()
+def clear_controls(target: str) -> dict:
+    """Remove all controls of gradient target size|spacing|angle|shape."""
+    d = _load()
+    getattr(d.gradients, target).controls.clear()
+    d.save(_path())
+    return {"stats": _stats(_generate(d))}
+
+
+@mcp.tool()
+def preview(px: int = 900) -> list:
+    """Render the current design as a PNG (holes on the plate outline) plus stats. Look at it before exporting."""
+    from .export import to_png
+    d = _load()
+    r = _generate(d)
+    return [Image(data=to_png(r, d, px=px, transparent=False), format="png"), {"stats": _stats(r)}]
+
+
+@mcp.tool()
+def export(path: str) -> dict:
+    """Export the current design; format from the extension: .svg .png .dxf .step/.stp .stl (3D plate of
+    canvas.thickness)."""
+    from .export import export as do_export
+    d = _load()
+    r = _generate(d)
+    out = Path(path).expanduser().resolve()
+    out.parent.mkdir(parents=True, exist_ok=True)
+    do_export(r, d, str(out))
+    return {"path": str(out), "bytes": out.stat().st_size, "stats": _stats(r)}
+
+
+@mcp.tool()
+def wrap_cylinder(path: str, radius: float | None = None, wall: float | None = None,
+                  height: float | None = None) -> dict:
+    """Wrap the pattern around a tube (canvas width = arc length) and cut it through the wall.
+    Defaults: radius = width/2π (wraps once), wall = thickness, height = canvas height. Writes .step or .stl."""
+    from .export import wrap_cylinder as wrap
+    d = _load()
+    out = Path(path).expanduser().resolve()
+    wrap(_generate(d), d, str(out), radius=radius, wall=wall, height=height)
+    return {"path": str(out), "bytes": out.stat().st_size}
+
+
+@mcp.tool()
+def cut_into_part(part_path: str, out_path: str, origin: list[float] = [0, 0, 0],
+                  normal: list[float] = [0, 0, 1], x_dir: list[float] = [1, 0, 0],
+                  depth: float | None = None) -> dict:
+    """Cut the vent pattern into an existing STEP part. The pattern plane sits at `origin` facing `normal`
+    (holes are cut along -normal), canvas x along `x_dir`. depth None = through the whole part."""
+    from .export import cut_into_part as cut
+    d = _load()
+    out = Path(out_path).expanduser().resolve()
+    cut(_generate(d), d, str(Path(part_path).expanduser().resolve()), str(out),
+        origin=tuple(origin), normal=tuple(normal), x_dir=tuple(x_dir), depth=depth)
+    return {"path": str(out), "bytes": out.stat().st_size}
+
+
+@mcp.tool()
+def open_in_gui() -> str:
+    """Open the current design in the VentForge desktop editor (it live-reloads when this server edits it)."""
+    flags = getattr(subprocess, "DETACHED_PROCESS", 0) | getattr(subprocess, "CREATE_NEW_PROCESS_GROUP", 0)
+    if getattr(sys, "frozen", False):  # bundled app: the executable itself is the editor
+        cmd = [sys.executable, str(_path())]
+    else:
+        exe = Path(sys.executable)
+        gui_exe = exe.with_name("pythonw.exe") if exe.with_name("pythonw.exe").exists() else exe
+        cmd = [str(gui_exe), "-m", "ventforge", str(_path())]
+    subprocess.Popen(cmd, creationflags=flags)
+    return f"opened {_path()}"
+
+
+def main():
+    mcp.run()
+
+
+if __name__ == "__main__":
+    main()

ventforge/model.py

@@ -0,0 +1,301 @@
+"""Design model: every parameter of a vent design, stored as JSON (*.vent.json).
+
+Coordinates are millimetres, origin at the canvas centre, x right, y UP (CAD convention).
+The GUI flips y for display. All angles are degrees, counter-clockwise.
+"""
+from __future__ import annotations
+
+import json
+import time
+from dataclasses import asdict, dataclass, field, fields, is_dataclass
+from pathlib import Path
+from typing import get_type_hints
+
+Pt = list[float]  # [x, y]
+
+SHAPES = ("circle", "rounded_rectangle", "hexagon", "polygon", "star", "custom")
+MODES = ("grid", "random", "path", "spiral", "concentric", "fibonacci",
+         "crosslines", "voronoi", "flowlines", "custom_points")
+BOUNDARIES = ("none", "circle", "rounded_rectangle", "custom")
+TARGET_SHAPES = ("circle", "rectangle", "polygon", "star")
+
+
+@dataclass
+class Canvas:
+    width: float = 100.0
+    height: float = 100.0
+    thickness: float = 2.0  # plate thickness for 3D exports
+
+
+@dataclass
+class Boundary:
+    type: str = "none"            # BOUNDARIES; "none" = the canvas rectangle
+    corner_radius: float = 10.0   # rounded_rectangle
+    margin: float = 2.0           # min distance from holes to the boundary edge
+    points: list[Pt] = field(default_factory=list)  # custom outline polygon
+    clip: bool = False            # False: drop holes crossing the edge; True: clip them
+
+
+@dataclass
+class DotStyle:
+    shape: str = "circle"         # SHAPES
+    diameter: float = 4.0         # outer size (circumscribed width)
+    aspect: float = 1.0           # rounded_rectangle height / width
+    corner_radius: float = 0.5    # rounded_rectangle
+    sides: int = 6                # polygon
+    star_points: int = 5
+    star_inner: float = 0.5       # inner radius ratio of star
+    rotation: float = 0.0
+    custom_points: list[Pt] = field(default_factory=list)  # unit shape, scaled to diameter
+    color: str = "#F7BB3B"        # display only
+
+
+@dataclass
+class Grid:
+    arrangement: str = "diamond"  # square | diamond (staggered rows) | hexagon (honeycomb pitch)
+    spacing_x: float = 6.0
+    spacing_y: float = 6.0
+    offset_x: float = 0.0
+    offset_y: float = 0.0
+    rotation: float = 0.0          # whole grid
+    row_rotation: float = 0.0      # extra dot rotation applied to alternate rows/cols
+    rotate_by: str = "row"         # row | col | both (chessboard)
+
+
+@dataclass
+class RandomP:
+    count: int = 300
+    min_distance: float = 5.0      # Poisson-disc style rejection
+    seed: int = 1
+
+
+@dataclass
+class PathP:
+    points: list[Pt] = field(default_factory=list)  # empty = default circle
+    closed: bool = True
+    smooth: bool = True            # Catmull-Rom through points
+    count: int = 40                # dots on the base path; other layers scale by length
+    layers: int = 1                # parallel offset copies of the path
+    layer_spacing: float = 6.0
+    align: bool = True             # rotate dots to path tangent
+
+
+@dataclass
+class Spiral:
+    radius: float = 45.0
+    turns: float = 5.0
+    inner_radius: float = 3.0
+    count: int = 120
+    rotation: float = 0.0
+    even_spacing: bool = True      # equal arc length between dots
+    align: bool = True
+
+
+@dataclass
+class Concentric:
+    ring_spacing: float = 6.0
+    dot_spacing: float = 6.0       # arc distance between dots on a ring
+    inner_radius: float = 0.0      # 0 = a dot in the centre
+    outer_radius: float = 0.0      # 0 = fill the boundary
+    rotation: float = 0.0
+    stagger: bool = True           # offset alternate rings by half a step
+    align: bool = True
+
+
+@dataclass
+class Fibonacci:
+    count: int = 400
+    spread: float = 3.5            # c in r = c * sqrt(n)
+    inner_radius: float = 0.0
+    rotation: float = 0.0
+    align: bool = False
+
+
+@dataclass
+class Crosslines:
+    left_angle: float = 60.0
+    right_angle: float = 120.0
+    left_spacing: float = 6.0
+    right_spacing: float = 6.0
+    rotation: float = 0.0
+    row_rotation: float = 0.0
+    rotate_by: str = "both"        # left | right | both — dots sit at line intersections
+
+
+@dataclass
+class Voronoi:
+    cell_size: float = 8.0
+    irregularity: float = 60.0     # percent jitter
+    crack_width: float = 1.2       # wall width between cells (holes are shrunken cells)
+    corner_radius: float = 0.5
+    rotation: float = 0.0
+    seed: int = 1
+
+
+@dataclass
+class Flowlines:
+    line_spacing: float = 5.0
+    line_width: float = 2.0        # slot width
+    rotation: float = 0.0
+    edge_style: str = "round"      # flat | round slot ends
+    follow_boundary: bool = False  # lines are offsets of the boundary instead of straight
+    invert: bool = False           # swap lines and gaps
+    amplitude: float = 3.0         # waviness
+    wavelength: float = 30.0
+    seed: int = 1
+
+
+@dataclass
+class CustomPoints:
+    """Explicit dots, e.g. written by an AI through MCP. size/angle optional per dot."""
+    points: list[Pt] = field(default_factory=list)
+    sizes: list[float] = field(default_factory=list)   # multipliers of DotStyle.diameter
+    angles: list[float] = field(default_factory=list)  # added to DotStyle.rotation
+
+
+@dataclass
+class Pattern:
+    mode: str = "grid"             # MODES
+    grid: Grid = field(default_factory=Grid)
+    random: RandomP = field(default_factory=RandomP)
+    path: PathP = field(default_factory=PathP)
+    spiral: Spiral = field(default_factory=Spiral)
+    concentric: Concentric = field(default_factory=Concentric)
+    fibonacci: Fibonacci = field(default_factory=Fibonacci)
+    crosslines: Crosslines = field(default_factory=Crosslines)
+    voronoi: Voronoi = field(default_factory=Voronoi)
+    flowlines: Flowlines = field(default_factory=Flowlines)
+    custom_points: CustomPoints = field(default_factory=CustomPoints)
+
+
+@dataclass
+class Control:
+    kind: str = "point"            # point | line | curve (smooth polyline)
+    points: list[Pt] = field(default_factory=lambda: [[0.0, 0.0]])
+    value: float = 0.2             # field value AT the control
+    radius: float = 50.0           # falloff distance to the edge value
+
+
+@dataclass
+class Gradient:
+    """A scalar field over the canvas. Far from all controls it equals `edge`."""
+    enabled: bool = False
+    controls: list[Control] = field(default_factory=list)
+    edge: float = 1.0              # value far away (neutral: 1 for size/spacing, 0 for angle/shape)
+    falloff: str = "smooth"        # linear | smooth
+    noise: float = 0.0             # 0..1 amplitude, relative
+    noise_scale: float = 20.0      # mm feature size
+    noise_seed: int = 1
+    image: str = ""                # grayscale image path used as the field (fit to canvas)
+    image_min: float = 0.2         # value at black
+    image_max: float = 1.0         # value at white
+    invert_image: bool = False
+
+
+@dataclass
+class Gradients:
+    size: Gradient = field(default_factory=Gradient)           # multiplier on diameter
+    spacing: Gradient = field(default_factory=Gradient)        # local spacing multiplier
+    angle: Gradient = field(default_factory=lambda: Gradient(edge=0.0))   # degrees added
+    shape: Gradient = field(default_factory=lambda: Gradient(edge=0.0))   # 0..1 morph to target
+    target_shape: str = "star"     # TARGET_SHAPES
+    target_sides: int = 4          # for target polygon
+
+
+@dataclass
+class Background:
+    image: str = ""                # reference image shown under the pattern (GUI only)
+    opacity: float = 0.5
+
+
+@dataclass
+class Design:
+    name: str = "Untitled"
+    canvas: Canvas = field(default_factory=Canvas)
+    boundary: Boundary = field(default_factory=Boundary)
+    dot: DotStyle = field(default_factory=DotStyle)
+    pattern: Pattern = field(default_factory=Pattern)
+    gradients: Gradients = field(default_factory=Gradients)
+    background: Background = field(default_factory=Background)
+    min_wall: float = 0.8          # holes closer than this are flagged in stats
+    version: int = 1
+
+    # ---- (de)serialisation -------------------------------------------------
+    def to_dict(self) -> dict:
+        return asdict(self)
+
+    @classmethod
+    def from_dict(cls, d: dict) -> "Design":
+        return _build(cls, d)
+
+    def to_json(self) -> str:
+        return json.dumps(self.to_dict(), indent=2)
+
+    @classmethod
+    def load(cls, path: str | Path) -> "Design":
+        d = cls.from_dict(json.loads(Path(path).read_text(encoding="utf-8")))
+        return d.resolve_images(Path(path).resolve().parent)
+
+    def resolve_images(self, base: str | Path) -> "Design":
+        """Make relative image paths absolute against `base` (the design file's folder), so the GUI
+        and the MCP server, which run from different working folders, find the same files."""
+        for g in (self.gradients.size, self.gradients.spacing, self.gradients.angle, self.gradients.shape,
+                  self.background):
+            if g.image and not Path(g.image).is_absolute():
+                g.image = str((Path(base) / g.image).resolve())
+        return self
+
+    def save(self, path: str | Path) -> None:
+        p = Path(path)
+        tmp = p.with_suffix(p.suffix + ".tmp")
+        tmp.write_text(self.to_json(), encoding="utf-8")
+        for i in range(6):  # atomic replace, so a watching GUI never reads half a file
+            try:
+                return tmp.replace(p)
+            except PermissionError:  # Windows: AV/indexer/a reader briefly holds the target
+                if i == 5:
+                    raise
+                time.sleep(0.05 * (i + 1))
+
+    def patched(self, patch: dict) -> "Design":
+        """Deep-merge a partial dict, e.g. {"dot": {"diameter": 3}}. Unknown keys raise."""
+        return Design.from_dict(_merge(self.to_dict(), patch))
+
+
+def _merge(base: dict, patch: dict, path: str = "") -> dict:
+    out = dict(base)
+    for k, v in patch.items():
+        if k not in base:
+            raise KeyError(f"unknown parameter: {path}{k}")
+        out[k] = _merge(base[k], v, f"{path}{k}.") if isinstance(v, dict) and isinstance(base[k], dict) else v
+    return out
+
+
+def _build(cls, d: dict):
+    hints = get_type_hints(cls)
+    kw = {}
+    for f in fields(cls):
+        if f.name not in d:
+            continue
+        t, v = hints[f.name], d[f.name]
+        if is_dataclass(t):
+            kw[f.name] = _build(t, v or {})
+        elif getattr(t, "__origin__", None) is list and t.__args__[0] is Control:
+            kw[f.name] = [_build(Control, c) for c in v]
+        elif t is float:
+            kw[f.name] = float(v)
+        elif t is int:
+            kw[f.name] = int(v)
+        else:
+            kw[f.name] = v
+    return cls(**kw)
+
+
+@dataclass
+class Result:
+    """Output of pattern.generate(design). Shared by exporters, GUI and MCP."""
+    holes: list            # shapely Polygons, mm, y-up, already clipped/filtered to the outline
+    outline: object        # shapely Polygon: the plate outline (canvas rect or boundary shape)
+    stats: dict            # count, open_area_ratio (0..1), hole_area, plate_area, min_wall_violations
+    circles: list = field(default_factory=list)  # per hole: (cx, cy, r) if it is an exact unclipped circle, else None
+    # (lets SVG/DXF/STEP write true circles instead of polygons; same length as holes, or empty)