Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
39 commits
Select commit Hold shift + click to select a range
e284972
feat(engines): Lumina adapter with a bounded CLI runner
DVOpenLabs Oct 31, 2026
887be71
fix(engines): refuse a link, junction or reparse point as the output …
DVOpenLabs Oct 31, 2026
f06a9e7
fix(engines): linear template validation; record known runner limits
DVOpenLabs Oct 31, 2026
9b2fb88
test(recovery): cross-track journey (test 11) and a validated monitor…
DVOpenLabs Nov 1, 2026
dbaa670
feat(creative): DitherForge, Kromacut and SindriCAD readers, explicit…
DVOpenLabs Nov 1, 2026
b5c7bb9
test(recovery): request sentinel that records every verb; honest test…
DVOpenLabs Nov 1, 2026
27c6e4c
feat(engines): runner process-tree stop and cleanup, slicer-name poli…
DVOpenLabs Nov 1, 2026
387d9d9
fix(creative): no filesystem path in the Prepare response; totals, wo…
DVOpenLabs Nov 1, 2026
2275485
test(recovery): the host mock records verbs that have no handler (TRA…
DVOpenLabs Nov 1, 2026
6b50b5b
fix(engines): admit CliRunner executables by pinned SHA-256 or sys.ex…
DVOpenLabs Nov 1, 2026
e5648e3
docs(engines): document identity-based executable admission and its l…
DVOpenLabs Nov 1, 2026
943c9a8
fix(engines): close Opus O1/O2/O3/O10 and O6 wording on the Lumina pa…
DVOpenLabs Nov 1, 2026
1e6fdfe
fix(creative): resolve review notes N1 (format coverage wording) and …
DVOpenLabs Nov 1, 2026
6366234
fix(recovery): capture.mjs scans visible input values and more path f…
DVOpenLabs Nov 1, 2026
38ce6bb
test(lifeline): stop mutating the shared os module in the lifeline tests
DVOpenLabs Oct 28, 2026
117adb5
test(lifeline): fix duplicate shim keyword and tighten the non-POSIX …
DVOpenLabs Oct 28, 2026
d48d568
fix(creative): Prepare accepts Kromacut's root-model layout; say why …
DVOpenLabs Nov 1, 2026
6ccab7f
docs(engines): state executable admission as the code implements it
DVOpenLabs Nov 1, 2026
a3b52e8
fix(creative): validator keeps root and file object types apart and r…
DVOpenLabs Nov 1, 2026
8273e14
fix(creative): refuse an assembly that references one id from both th…
DVOpenLabs Nov 1, 2026
2cfcf94
fix(creative): scan p:path files like the root model and resolve comp…
DVOpenLabs Nov 2, 2026
8e44d7b
fix(creative): strip comments before every structural reader; compare…
DVOpenLabs Nov 2, 2026
6be3dfe
integ: merge #141 creative journey (local demo build)
DVOpenLabs Nov 2, 2026
1e72c9c
integ: merge #142 cross-track recovery (local demo build)
DVOpenLabs Nov 2, 2026
ffa1584
integ: merge Lumina chain #139+#143 (local demo build)
DVOpenLabs Nov 2, 2026
9fef876
test(ext-routes): make the broken-module test attempt the import once…
DVOpenLabs Nov 2, 2026
0145b6b
test(ext-routes): pin the failing module, fix the sibling skip test, …
DVOpenLabs Nov 2, 2026
112601f
fix(engines): admit a Windows Store python.exe alias; pin tests copy …
DVOpenLabs Nov 2, 2026
15f097e
feat(recovery,passport): checkpoint the real workspace; keep the pass…
DVOpenLabs Nov 2, 2026
22e384c
fix(recovery): a checkpoint saved with an unverifiable file says so
DVOpenLabs Nov 2, 2026
1ce1162
fix(recovery,passport,creative): close review findings on the workspa…
DVOpenLabs Nov 2, 2026
7d5755b
fix(creative,passport): job ownership epoch for Prepare linking; Pass…
DVOpenLabs Nov 2, 2026
d43a71a
fix(passport): cancel in-flight build/check on every project change; …
DVOpenLabs Nov 2, 2026
22de807
test(passport): reset the session between tests so the in-flight buil…
DVOpenLabs Nov 2, 2026
0a6db17
Merge feat/portfolio-integration into integ/demo-20261102
DVOpenLabs Nov 14, 2026
343d90c
Merge feat/portfolio-integration (with main and #138) into integ/demo…
DVOpenLabs Nov 14, 2026
e474814
Merge main (with #140) into integ/demo-20261102
DVOpenLabs Nov 14, 2026
813e58f
fix(creative): route every archive part through the decode-first XML …
DVOpenLabs Nov 14, 2026
f5823d5
fix(creative): unreadable object part makes geometry totals unknown (…
DVOpenLabs Nov 14, 2026
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
307 changes: 281 additions & 26 deletions backend/snapstudio_api/routes_creative.py

Large diffs are not rendered by default.

254 changes: 254 additions & 0 deletions backend/snapstudio_api/routes_engines.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,254 @@
"""Routes of the Engines track: an optional, user-configured local Lumina-compatible service.

POST /engines/lumina/formats {} -> {formats, ...}
POST /engines/lumina/status {service_url} -> {status, ...}
POST /engines/lumina/generate {service_url, image_path, lut_name, format, out_dir?} -> {generated, ...}

Studio does not slice and does not control anything here. The service is whatever local address the user
typed; it is reached only through `foundation.netguard` (loopback / LAN, no redirects, bounded). The
generated artifact is written as a NEW file in a Studio-owned folder (or a local folder the user chose),
never over or next to the input image. No response carries a filesystem path or a service response body.
Progress and cancel are `unknown`: the saved Lumina research publishes neither, so none is invented.

Evidence: mock-service-tested. No real Lumina installation has been exercised.
"""
from __future__ import annotations

import os
import re

from snapstudio_core import paths
from snapstudio_core.engines import local_input
from snapstudio_core.engines.lumina import MAX_INPUT_BYTES, LuminaClient, LuminaError
from snapstudio_core.foundation.netguard import NetguardRefused

from . import ext_routes
from . import request_validation as rv

EVIDENCE = "mock-service-tested"
GENERATED_BY = "a user-configured local Lumina-compatible service (not verified)"
ADVISORY = ("Studio did not watch this file being made. It came from a service you configured, which "
"Studio has not verified. Inspect it before you use it; Studio does not slice or print it.")
DEFAULT_OUT_FOLDER = "lumina-output"
MAX_PATH_CHARS = 4096
MAX_URL_CHARS = 512

#: The explicit list. A format is never inferred; anything else is refused.
SUPPORTED_FORMATS: tuple[dict, ...] = (
{"kind": "3mf", "meaning": "A 3MF model file returned by the service.", "evidence": EVIDENCE},
{"kind": "png", "meaning": "A PNG preview image returned by the service.", "evidence": EVIDENCE},
{"kind": "glb", "meaning": "A binary glTF (GLB) preview model returned by the service.", "evidence": EVIDENCE},
)
FORMAT_KINDS = tuple(f["kind"] for f in SUPPORTED_FORMATS)

_FILE_URL = re.compile(r"\A/api/files/([A-Za-z0-9_-]{1,128})\Z")
_EXT = re.compile(r"\A\.[A-Za-z0-9]{1,8}\Z")

#: Plain explanations per adapter error code. Never a service body, URL or path.
LUMINA_MESSAGES = {
"invalid_service_url": "Enter only the service address, for example http://192.168.1.20:8000, with no path.",
"discovery_failed": "The service did not answer its description request. Check the address and that it is running.",
"malformed_discovery": "The service described itself in a shape Studio does not recognise.",
"malformed_json": "The service answered with something Studio could not read.",
"unknown_version": "The service did not say which API version it speaks, so Studio will not use it.",
"unsupported_version": "The service speaks an API version Studio has not been tested with.",
"health_failed": "The service did not pass its identity check, so Studio did not send anything to it.",
"malformed_health": "The service identity check answered in a shape Studio does not recognise.",
"route_unavailable": "The service does not offer a route Studio needs.",
"identity_not_confirmed": "The service identity was not confirmed, so Studio did not send anything to it.",
"preview_failed": "The service refused or failed the request.",
"malformed_preview": "The service answered in a shape Studio does not recognise.",
"unknown_preview_locator": "The service pointed at a file location Studio does not recognise.",
"artifact_unavailable": "The service did not provide the file it announced.",
"invalid_file_id": "The service named a file in a form Studio will not fetch.",
"invalid_input": "The image is empty or larger than Studio will send.",
"invalid_lut": "Enter a LUT name of up to 256 characters.",
"progress_unknown": "Progress is unknown: the service does not publish a progress route Studio can rely on.",
"cancel_unknown": "Cancel is unknown: the service does not publish a cancel route Studio can rely on.",
}
_GENERIC_ENGINE = "The service could not be used."


def _refusal(code: str, message: str) -> tuple[int, dict]:
return 422, {"error": "refusal", "code": code, "message": message}


def _lumina_refusal(exc: LuminaError) -> tuple[int, dict]:
return _refusal(exc.code, LUMINA_MESSAGES.get(exc.code, _GENERIC_ENGINE))


def _netguard_refusal(exc: NetguardRefused) -> tuple[int, dict]:
return _refusal(f"network_{exc.code}", str(exc))


def _service_url(data: dict) -> str:
return rv.require_bounded_str(data, "service_url", MAX_URL_CHARS).strip()


def _format_list_text() -> str:
return ", ".join(FORMAT_KINDS)


@ext_routes.route("/engines/lumina/formats")
def formats(data: dict) -> tuple[int, dict]:
return 200, {
"formats": [dict(f) for f in SUPPORTED_FORMATS],
"evidence": EVIDENCE,
"progress": "unknown",
"cancel": "unknown",
"note": ("Formats are listed explicitly and chosen by you; Studio never infers one. "
"Evidence is a synthetic loopback mock: no real Lumina installation was exercised."),
}


@ext_routes.route("/engines/lumina/status")
def status(data: dict) -> tuple[int, dict]:
url = _service_url(data)
client = None
try:
client = LuminaClient(url)
discovery = client.discover()
client.health_check()
return 200, {
"status": "ok",
"api_version": discovery.api_version,
"can_generate": {"/api/convert/preview", "/api/files/{file_id}"} <= set(discovery.paths),
"progress": "unknown",
"cancel": "unknown",
"evidence": EVIDENCE,
"note": ("That answer is not proof of what the service is or "
"that it will produce a good result."),
}
except NetguardRefused as exc:
if exc.code in ("syntax", "off_network", "public_address", "unresolvable"):
return _netguard_refusal(exc)
return 200, {"status": "unknown", "code": f"network_{exc.code}", "message": str(exc),
"progress": "unknown", "cancel": "unknown", "evidence": EVIDENCE}
except LuminaError as exc:
if exc.code == "invalid_service_url":
return _lumina_refusal(exc)
return 200, {"status": "unknown", "code": exc.code,
"message": LUMINA_MESSAGES.get(exc.code, _GENERIC_ENGINE),
"progress": "unknown", "cancel": "unknown", "evidence": EVIDENCE}
finally:
if client is not None:
client.close()


def _image_path(data: dict) -> str:
raw = rv.require_bounded_str(data, "image_path", MAX_PATH_CHARS)
if "\x00" in raw:
raise rv.ValidationError("Invalid 'image_path'")
if local_input.is_network_or_device_path(raw) or local_input.reaches_network(raw):
raise rv.ValidationError("That image path is a network or device location. Choose a file on this computer.")
if not os.path.exists(raw):
raise rv.ValidationError("That image file was not found.")
if not local_input.is_local_regular_file(raw, max_bytes=MAX_INPUT_BYTES):
raise rv.ValidationError("That is not a regular image file Studio can send "
f"(it must be a file of at most {MAX_INPUT_BYTES // (1024 * 1024)} MB).")
return raw


def _out_dir(data: dict, image_path: str) -> tuple[str, str]:
"""(directory, location label). The folder must be Studio's own or an existing local one."""
raw = data.get("out_dir")
if raw is None or raw == "":
target = os.path.join(paths.data_dir(), DEFAULT_OUT_FOLDER)
os.makedirs(target, exist_ok=True)
label = "Studio's lumina-output folder"
else:
if not isinstance(raw, str) or len(raw) > MAX_PATH_CHARS or "\x00" in raw:
raise rv.ValidationError("Invalid 'out_dir'")
if not local_input.is_local_directory(raw):
raise rv.ValidationError("That output folder is not an existing local folder Studio can write to.")
target = raw
label = "the folder you chose"
try:
if os.path.samefile(target, os.path.dirname(os.path.abspath(image_path))):
raise rv.ValidationError("Choose an output folder other than the image's own folder, so the "
"original is never written next to.")
except OSError:
raise rv.ValidationError("That output folder is not an existing local folder Studio can write to.") from None
return target, label


def _write_new(directory: str, kind: str, sha256: str, data: bytes) -> str:
"""Create a new file, never replacing one. Returns the file name only."""
for n in range(1, 1000):
name = f"lumina-{sha256[:12]}.{kind}" if n == 1 else f"lumina-{sha256[:12]}-{n}.{kind}"
try:
fd = os.open(os.path.join(directory, name), os.O_WRONLY | os.O_CREAT | os.O_EXCL | getattr(os, "O_BINARY", 0), 0o600)
except FileExistsError:
continue
with os.fdopen(fd, "wb") as handle:
handle.write(data)
return name
raise rv.ValidationError("The output folder already holds too many files with this name.")


def _read_input(path: str) -> bytes:
with open(path, "rb") as handle:
blob = handle.read(MAX_INPUT_BYTES + 1)
if not blob or len(blob) > MAX_INPUT_BYTES:
raise rv.ValidationError("The image is empty or larger than Studio will send.")
return blob


@ext_routes.route("/engines/lumina/generate")
def generate(data: dict) -> tuple[int, dict]:
url = _service_url(data)
fmt = data.get("format")
if not isinstance(fmt, str) or fmt not in FORMAT_KINDS:
raise rv.ValidationError(f"Choose one of the supported formats: {_format_list_text()}. "
"Studio does not guess a format.")
lut = rv.require_bounded_str(data, "lut_name", 256)
image_path = _image_path(data)
out_dir, location = _out_dir(data, image_path)
image = _read_input(image_path)
suffix = os.path.splitext(image_path)[1]
upload_name = "input" + (suffix if _EXT.match(suffix) else "")

client = None
try:
client = LuminaClient(url)
client.discover()
client.health_check()
preview = client.preview(image, upload_name, lut_name=lut)
locators = [preview.get("preview_url"), preview.get("preview_glb_url")]
seen: list[str] = []
artifact = None
for locator in locators:
match = _FILE_URL.match(locator) if isinstance(locator, str) else None
if match is None:
continue
candidate = client.fetch_artifact(match.group(1))
seen.append(candidate.kind)
if candidate.kind == fmt:
artifact = candidate
break
if artifact is None:
produced = ", ".join(sorted(set(seen))) if seen else "no file"
return _refusal("format_not_produced",
f"You asked for {fmt}, but the service returned {produced}. Nothing was saved. "
f"Choose a format the service produced, from: {_format_list_text()}.")
name = _write_new(out_dir, artifact.kind, artifact.sha256, artifact.data)
return 200, {
"generated": True,
"file_name": name,
"sha256": artifact.sha256,
"size_bytes": artifact.size_bytes,
"kind": artifact.kind,
"generated_by": GENERATED_BY,
"location_label": location,
"advisory": ADVISORY,
"progress": "unknown",
"cancel": "unknown",
"evidence": EVIDENCE,
}
except NetguardRefused as exc:
return _netguard_refusal(exc)
except LuminaError as exc:
return _lumina_refusal(exc)
finally:
if client is not None:
client.close()
16 changes: 12 additions & 4 deletions backend/snapstudio_core/creative/container.py
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@
import posixpath
import zipfile
import zlib
from dataclasses import dataclass
from dataclasses import dataclass, field
from xml.etree import ElementTree

CORE_NS = "http://schemas.microsoft.com/3dmanufacturing/core/2015/02"
Expand Down Expand Up @@ -38,6 +38,9 @@ class ThreeMFManifest:
passed_through: tuple[MemberDigest, ...]
model_xml: bytes
project_settings: dict | None
#: Member bytes already read under the container limits; lets format readers look inside
#: named parts without opening the archive a second time. Never serialized.
parts: dict = field(default_factory=dict, repr=False, compare=False)

def to_dict(self) -> dict:
"""Serialize member identity only; original archive payloads stay untouched."""
Expand All @@ -58,8 +61,8 @@ def _safe_name(name: str) -> str:
return normalized


def _check_model(xml: bytes) -> None:
# UTF-8 only. A byte-substring DOCTYPE check is bypassed by UTF-16/UTF-32 (NUL-interleaved), which expat
def parse_xml(xml: bytes) -> ElementTree.Element:
# The one guarded XML parse for every part of an archive (model, object parts, settings). UTF-8 only. A byte-substring DOCTYPE check is bypassed by UTF-16/UTF-32 (NUL-interleaved), which expat
# auto-detects and then expands entities from, so the text is decoded first and anything else is refused.
try:
text = xml.decode("utf-8-sig")
Expand All @@ -74,6 +77,11 @@ def _check_model(xml: bytes) -> None:
root = ElementTree.fromstring(text.encode("utf-8"))
except ElementTree.ParseError as exc:
raise ContainerError("bad_xml") from exc
return root


def _check_model(xml: bytes) -> None:
root = parse_xml(xml)
if root.tag != f"{{{CORE_NS}}}model":
raise ContainerError("unsupported_3mf_version")

Expand Down Expand Up @@ -139,4 +147,4 @@ def read_3mf(data: bytes) -> ThreeMFManifest:
understood.append("Metadata/project_settings.config")
records = tuple(MemberDigest(n, hashlib.sha256(blobs[n]).hexdigest()) for n in sorted(blobs))
passed = tuple(rec for rec in records if rec.name not in understood)
return ThreeMFManifest(records, tuple(understood), passed, model, settings)
return ThreeMFManifest(records, tuple(understood), passed, model, settings, blobs)
71 changes: 71 additions & 0 deletions backend/snapstudio_core/creative/formats.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,71 @@
"""The explicit list of input formats the Creative inspector supports, and what each one reads.

This table is the contract returned by `POST /creative/formats` and mirrored in
docs/internal/CREATIVE_COMPAT.md. Support is never inferred from generic ZIP inspection: a format is
listed only with the carrier, the documented markers or keys, what is established and what is not.
"""
from __future__ import annotations

from . import generators, readers

EVIDENCE = "fixture-tested"
_CARRIER = "3MF (ZIP) with 3D/3dmodel.model in the 3MF core namespace"

SUPPORTED_FORMATS: tuple[dict, ...] = (
{"key": "ditherforge", "label": "DitherForge", "carrier": _CARRIER, "selection": "automatic",
"identified_by": list(generators.MARKERS["ditherforge"]),
"reads": ["application tag and variant", "object part files", "triangle and painted-triangle counts",
"paint extruders used (documented 1-2 character paint_color values)",
"object names and extruders from model_settings.config",
"filament_colour, filament_type, printer_settings_id, print_settings_id"],
"kept_untouched": ["every other part and settings key, by name and SHA-256"],
"not_read": ["geometry beyond counts", "longer paint_color strings (split-triangle encoding)",
"settings JSON and collection TXT written beside the 3MF"],
"prepare_limits": ["Prepare works on the Bambu-path export (Application tag BambuStudio-<version>+ditherforge-<version>).",
"The generic-path export writes part id 1 under a component with objectid 2 or more. Studio's "
"structure check does not accept that, so such a file is inspect-only: Prepare refuses it and "
"writes nothing."],
"upstream": "rtwfroody/ditherforge (MIT) 4d3552a434e8084d9b5fe573959a3493325be29f"},
{"key": "kromacut", "label": "Kromacut", "carrier": _CARRIER, "selection": "automatic",
"identified_by": list(generators.MARKERS["kromacut"]),
"reads": ["layer height and first layer height metadata", "colour layer object count and assembly object",
"parts and their extruders from model_settings.config", "base material colours",
"filament_colour, layer_height, initial_layer_print_height"],
"kept_untouched": ["Metadata/kromacut.config and every other part, by name and SHA-256"],
"not_read": ["the payload of Metadata/kromacut.config", "mesh geometry",
"optional custom metadata files"],
"upstream": "vycdev/Kromacut (AGPL-3.0, format only) 94874755426ee7f33b3684a5544e7fab0e2e73f7"},
{"key": "sindricad", "label": "SindriCAD", "carrier": _CARRIER, "selection": "automatic",
"identified_by": list(generators.MARKERS["sindricad"]),
"reads": ["named bodies with palette slot (pindex) and extruder", "palette base materials",
"per-face paint (documented 1-2 character paint_color values)",
"filament_colour and filament_type"],
"kept_untouched": ["every other part and settings key, by name and SHA-256"],
"not_read": ["mesh geometry beyond counts", "longer paint_color strings"],
"upstream": "MakerViking/sindricad (AGPL-3.0, format only) 8b2e9dc4f82fba58b39c206c993534c487cc1eab"},
{"key": "forcaslicer", "label": "FOrcaSlicer", "carrier": _CARRIER, "selection": "automatic",
"identified_by": ["published fos_*, mms_* and color_patch_* keys in project_settings.config"],
"reads": sorted(readers._FORCA_KEYS), "kept_untouched": ["all other keys and parts"],
"not_read": ["unknown fos_* keys", "plain nozzle_diameter as a physical value"], "upstream": None},
{"key": "lixnix", "label": "LixNix Full Multi-Nozzle", "carrier": _CARRIER, "selection": "automatic",
"identified_by": sorted(readers._LIX_KEYS), "reads": sorted(readers._LIX_KEYS),
"kept_untouched": ["all other keys and parts"], "not_read": ["effective heights", "unpublished variants"],
"upstream": None},
{"key": "fullspectrum", "label": "FullSpectrum 0.9.12", "carrier": _CARRIER, "selection": "automatic",
"identified_by": sorted(readers._FULLSPECTRUM_KEYS), "reads": ["mixed_filament_definitions rows (simulated recipes)"],
"kept_untouched": ["all other keys and parts"],
"not_read": ["ratios", "pattern semantics", "execution", "the draft vnext schema"], "upstream": None},
{"key": "imagemap", "label": "OrcaSlicer ImageMap", "carrier": _CARRIER, "selection": "manual only",
"identified_by": [], "reads": ["3MF artifact identity (size, SHA-256, member list)"],
"kept_untouched": ["every part, by name and SHA-256"],
"not_read": ["the zone shape: the exact serialized carrier is not established, so no zone claim is made"],
"upstream": None},
{"key": "lumina", "label": "Lumina Layers", "carrier": _CARRIER, "selection": "manual only",
"identified_by": [], "reads": ["3MF artifact identity (size, SHA-256, member list)"],
"kept_untouched": ["every part, by name and SHA-256"],
"not_read": ["generation provenance", "session behaviour", "file-ID lifetime"], "upstream": None},
)

KEYS = tuple(f["key"] for f in SUPPORTED_FORMATS)
MANUAL_ONLY = tuple(f["key"] for f in SUPPORTED_FORMATS if f["selection"] == "manual only")
LABELS = {f["key"]: f["label"] for f in SUPPORTED_FORMATS}
Loading
Loading