Rebuild the object in a reference image as a code-only, procedural, quality-gated, animation-ready Three.js model. Token-efficient image-to-3D.
Python 3dai-agentsclaude-codecomputer-graphicsgenerativeimage-to-3dprocedural-generationthreejstypescriptwebgl
feat: contribute domain profiles through a registry instead of a closed set
kokorolx052dac5a3c0a
diff --git a/forge/_shared/domains/__init__.py b/forge/_shared/domains/__init__.pynew file mode 100644index 0000000..c6f06c8--- /dev/null+++ b/forge/_shared/domains/__init__.py@@ -0,0 +1,98 @@+"""Domain profiles the base pipeline can run.++The base pipeline names no domain. It asks this registry what is available, and a domain contributes+its own steps, its own evidence collection and its own track. Each module in this package declares a+single `DOMAIN` mapping; registration is by presence, not by the base holding a list of names.++This is the extension point the CS2 extraction needs. Today both entries are in-repo. When a domain+moves out to a plugin, its module leaves this directory and the harness supplies the same mapping+instead -- the base pipeline does not change either way, which is the property being bought here.++Required keys:+ id the profile identifier a run is started with+Optional keys, each defaulting to "contributes nothing":+ setupSteps ((step_id, command), ...) spliced into the setup phase+ setupAnchorBefore base step id to splice before; required when setupSteps is non-empty+ passSteps ((step_id, command), ...) spliced into every correction pass+ passAnchorBefore base step id to splice before; required when passSteps is non-empty+ specCollection an extra local-evidence collection to search+"""++from __future__ import annotations++import importlib.util+from pathlib import Path+from typing import Any, Final++_PACKAGE_DIR: Final = Path(__file__).resolve().parent++_REQUIRED: Final = ("id",)+_ALLOWED: Final = {+ "id",+ "setupSteps",+ "setupAnchorBefore",+ "passSteps",+ "passAnchorBefore",+ "specCollection",+}+++class DomainRegistryError(ValueError):+ pass+++def _load_module(path: Path) -> Any:+ spec = importlib.util.spec_from_file_location(f"_img2_domain_{path.stem}", path)+ if spec is None or spec.loader is None:+ raise DomainRegistryError(f"cannot load domain module {path}")+ module = importlib.util.module_from_spec(spec)+ spec.loader.exec_module(module)+ return module+++def _validate(entry: Any, source: Path) -> dict[str, Any]:+ if not isinstance(entry, dict):+ raise DomainRegistryError(f"{source.name}: DOMAIN must be a mapping")+ for key in _REQUIRED:+ if not entry.get(key):+ raise DomainRegistryError(f"{source.name}: DOMAIN is missing required key {key!r}")+ unknown = sorted(set(entry) - _ALLOWED)+ if unknown:+ # Refused rather than ignored: a typo'd key would otherwise silently contribute nothing.+ raise DomainRegistryError(f"{source.name}: DOMAIN has unknown key(s) {unknown}")+ for steps_key, anchor_key in (("setupSteps", "setupAnchorBefore"), ("passSteps", "passAnchorBefore")):+ if entry.get(steps_key) and not entry.get(anchor_key):+ raise DomainRegistryError(f"{source.name}: {steps_key} needs {anchor_key}")+ return entry+++def registered_domains() -> dict[str, dict[str, Any]]:+ """Every domain profile available to this checkout, keyed by id."""+ found: dict[str, dict[str, Any]] = {}+ for path in sorted(_PACKAGE_DIR.glob("*.py")):+ if path.name == "__init__.py":+ continue+ module = _load_module(path)+ entry = getattr(module, "DOMAIN", None)+ if entry is None:+ raise DomainRegistryError(f"{path.name}: a domain module must declare DOMAIN")+ entry = _validate(entry, path)+ if entry["id"] in found:+ # Two providers claiming one id is ambiguous; the base must not pick one.+ raise DomainRegistryError(f"domain id {entry['id']!r} is declared twice")+ found[entry["id"]] = entry+ return found+++def domain_profile(profile: str) -> dict[str, Any] | None:+ """The registered domain for `profile`, or None for the generic pipeline."""+ if profile == "generic":+ return None+ domains = registered_domains()+ if profile not in domains:+ known = ", ".join(sorted(["generic", *domains]))+ raise DomainRegistryError(+ f"no installed provider serves profile {profile!r}; available: {known}. "+ "Install the domain plugin that provides it, or start the run as generic."+ )+ return domains[profile]diff --git a/forge/_shared/domains/character.py b/forge/_shared/domains/character.pynew file mode 100644index 0000000..6d4db6b--- /dev/null+++ b/forge/_shared/domains/character.py@@ -0,0 +1,26 @@+"""Character domain profile.++Converted to a provider in the same change as CS2, deliberately: an extension point whose only+consumer is one hardcoded in-repo domain is a rename, not an abstraction. Character stays in-repo --+it is not being extracted -- but it reaches the pipeline through the same registry a plugin uses, so+the seam has two consumers from the day it exists.+"""++from __future__ import annotations++from typing import Any, Final++DOMAIN: Final[dict[str, Any]] = {+ "id": "character",+ "setupSteps": (+ (+ "character-contract-read",+ "Read grimoire/character/reconstruction.md and grimoire/character/likeness_maximization.md completely",+ ),+ (+ "character-landmarks",+ "python3 forge/stage1_intake/extract_landmarks.py {reference} --out anatomy.json --overlay landmarks.png",+ ),+ ),+ "setupAnchorBefore": "local-spec-search",+}diff --git a/forge/_shared/domains/cs2.py b/forge/_shared/domains/cs2.pynew file mode 100644index 0000000..cff2779--- /dev/null+++ b/forge/_shared/domains/cs2.py@@ -0,0 +1,31 @@+"""CS2 domain profile.++An in-repo provider for now. This module is what leaves the repository when CS2 becomes its own+plugin -- at which point the harness supplies the same mapping and the base pipeline is unchanged.+"""++from __future__ import annotations++from typing import Any, Final++DOMAIN: Final[dict[str, Any]] = {+ "id": "cs2",+ "setupSteps": (+ ("cs2-contract-read", "Read grimoire/intake/cs2_intake_contract.md completely"),+ ("cs2-authoritative-classification", "Obtain an authoritative CS2 family/subtype classification record"),+ (+ "cs2-manifest",+ "python3 forge/stage1_intake/cs2_manifest.py {reference} --classification classification.json --out cs2-intake.json",+ ),+ ),+ "setupAnchorBefore": "local-spec-search",+ "passSteps": (+ (+ "cs2-review",+ "python3 forge/stage4_review/cs2_review.py --manifest cs2-intake.json --metrics cs2-review-inputs.json"+ " --scene forge/tests/fixtures/knife_review_scene.json --out cs2-review.json",+ ),+ ),+ "passAnchorBefore": "ai-review-recorded",+ "specCollection": "cs2",+}diff --git a/forge/_shared/workflow_state.py b/forge/_shared/workflow_state.pyindex cf24c34..4724a2d 100644--- a/forge/_shared/workflow_state.py+++ b/forge/_shared/workflow_state.py@@ -3,11 +3,16 @@ from __future__ import annotationsimport jsonimport osimport shlex+import sysimport tempfilefrom copy import deepcopyfrom pathlib import Pathfrom typing import Any, Final+sys.path.insert(0, str(Path(__file__).resolve().parent))++from domains import DomainRegistryError, domain_profile # noqa: E402+SCHEMA_VERSION: Final = 1STEP_STATUSES: Final = {"pending", "done", "skipped"}@@ -38,23 +43,6 @@ SETUP_STEPS: Final = (("strict-validation", "python3 forge/stage2_spec/validate_sculpt_spec.py {spec} --strict-quality"),)-CHARACTER_STEPS: Final = (- (- "character-contract-read",- "Read grimoire/character/reconstruction.md and grimoire/character/likeness_maximization.md completely",- ),- (- "character-landmarks",- "python3 forge/stage1_intake/extract_landmarks.py {reference} --out anatomy.json --overlay landmarks.png",- ),-)--CS2_STEPS: Final = (- ("cs2-contract-read", "Read grimoire/intake/cs2_intake_contract.md completely"),- ("cs2-authoritative-classification", "Obtain an authoritative CS2 family/subtype classification record"),- ("cs2-manifest", "python3 forge/stage1_intake/cs2_manifest.py {reference} --classification classification.json --out cs2-intake.json"),-)-PASS_STEPS: Final = (("build-current-pass", "python3 forge/stage3_build/generate_threejs_factory.py {spec} --out src/createObjectModel.ts --pass-id {pass_id}"),("render-capture", "Render {pass_id} and capture the fixed review view plus meaningful orbit views"),@@ -66,13 +54,6 @@ PASS_STEPS: Final = (("pipeline-sync", "python3 forge/stage3_build/orchestrate_passes.py sync {spec} --in-place"),)-CS2_PASS_STEPS: Final = (- (- "cs2-review",- "python3 forge/stage4_review/cs2_review.py --manifest cs2-intake.json --metrics cs2-review-inputs.json --scene forge/tests/fixtures/knife_review_scene.json --out cs2-review.json",- ),-)-FINAL_STEPS: Final = (("part-coverage", "python3 forge/stage4_review/check_part_coverage.py --spec {spec} --manifest parts.json"),("action-ready", "Verify explodable/clickable hierarchy, pivots, sockets, and root.userData.sculptRuntime"),@@ -83,6 +64,29 @@ class WorkflowStateError(ValueError):pass+def _anchor_index(rows: list[Any], anchor: str, profile: str, key) -> int:+ for index, row in enumerate(rows):+ if key(row) == anchor:+ return index+ # An unknown anchor is a contribution the base cannot place. Failing loud beats appending at the+ # end, which would put a domain's setup step after the steps that depend on it.+ raise WorkflowStateError(f"profile {profile!r} anchors a step before unknown base step {anchor!r}")+++def _splice(rows: list[dict[str, Any]], steps, anchor: str | None, profile: str, *, scope: str) -> list[dict[str, Any]]:+ if not steps:+ return rows+ at = _anchor_index(rows, anchor, profile, lambda r: r["id"])+ return rows[:at] + [_step(*item, scope=scope) for item in steps] + rows[at:]+++def _splice_raw(rows: list[Any], steps, anchor: str | None, profile: str) -> list[Any]:+ if not steps:+ return rows+ at = _anchor_index(rows, anchor, profile, lambda r: r[0])+ return rows[:at] + list(steps) + rows[at:]++def _step(step_id: str, command: str, *, scope: str) -> dict[str, Any]:return {"id": step_id,@@ -102,20 +106,18 @@ def new_state(max_per_pass: int = 3,max_total: int = 6,) -> dict[str, Any]:- if profile not in {"generic", "cs2", "character"}:- raise WorkflowStateError("profile must be generic, cs2, or character")+ try:+ domain = domain_profile(profile)+ except DomainRegistryError as exc:+ raise WorkflowStateError(str(exc)) from excif max_per_pass < 1 or max_total < 1 or max_per_pass > max_total:raise WorkflowStateError("loop limits require 1 <= max-per-pass <= max-total")+setup = [_step(*item, scope="setup") for item in SETUP_STEPS]- insertion = next(index for index, item in enumerate(setup) if item["id"] == "local-spec-search")- if profile == "cs2":- setup[insertion:insertion] = [_step(*item, scope="setup") for item in CS2_STEPS]- elif profile == "character":- setup[insertion:insertion] = [_step(*item, scope="setup") for item in CHARACTER_STEPS]pass_steps = list(PASS_STEPS)- if profile == "cs2":- review_index = next(index for index, item in enumerate(pass_steps) if item[0] == "ai-review-recorded")- pass_steps[review_index:review_index] = list(CS2_PASS_STEPS)+ if domain is not None:+ setup = _splice(setup, domain.get("setupSteps"), domain.get("setupAnchorBefore"), profile, scope="setup")+ pass_steps = _splice_raw(pass_steps, domain.get("passSteps"), domain.get("passAnchorBefore"), profile)state = {"schemaVersion": SCHEMA_VERSION,"status": "active",@@ -146,8 +148,12 @@ def validate_state(state: Any) -> dict[str, Any]:raise WorkflowStateError("state must be a JSON object")if state.get("schemaVersion") != SCHEMA_VERSION:raise WorkflowStateError(f"unsupported state schemaVersion: {state.get('schemaVersion')!r}")- if state.get("profile") not in {"generic", "cs2", "character"}:- raise WorkflowStateError("state profile is invalid")+ # A state file written before its domain moved out must fail by naming the missing provider,+ # never by silently downgrading the run to generic.+ try:+ domain_profile(state.get("profile"))+ except DomainRegistryError as exc:+ raise WorkflowStateError(str(exc)) from excchecklist = state.get("checklist")if not isinstance(checklist, list) or not checklist:raise WorkflowStateError("state checklist must be a non-empty list")diff --git a/forge/state.py b/forge/state.pyindex 93496c8..eeba404 100644--- a/forge/state.py+++ b/forge/state.py@@ -9,6 +9,7 @@ from pathlib import PathROOT = Path(__file__).resolve().parentsys.path.insert(0, str(ROOT / "_shared"))+from domains import registered_domains # noqa: E402from workflow_state import ( # noqa: E402WorkflowStateError,load_state,@@ -26,7 +27,9 @@ def build_parser() -> argparse.ArgumentParser:init = commands.add_parser("init")init.add_argument("--state", type=Path, default=Path(".img2threejs/state.json"))init.add_argument("--reference", required=True)- init.add_argument("--profile", choices=("generic", "cs2", "character"), default="generic")+ # Choices come from the registry, so installing a domain makes its profile available here without+ # editing the base CLI. new_state() re-checks and names the available set on a bad value.+ init.add_argument("--profile", choices=("generic", *sorted(registered_domains())), default="generic")init.add_argument("--spec", default="")init.add_argument("--max-per-pass", type=int, default=3)init.add_argument("--max-total", type=int, default=6)diff --git a/forge/tests/test_domain_registry.py b/forge/tests/test_domain_registry.pynew file mode 100644index 0000000..16b05a0--- /dev/null+++ b/forge/tests/test_domain_registry.py@@ -0,0 +1,99 @@+"""The domain registry is the seam that lets the base pipeline stop naming domains.++These are the refusal cases. The happy paths are covered by test_workflow_state.py's checklist+assertions, which already pin the 21 / 23 / 25 step counts per profile.+"""++from __future__ import annotations++import sys+import textwrap+import unittest+from pathlib import Path++ROOT = Path(__file__).resolve().parents[1]+sys.path.insert(0, str(ROOT / "_shared"))++import domains # noqa: E402+from domains import DomainRegistryError, domain_profile, registered_domains # noqa: E402+from workflow_state import WorkflowStateError, new_state # noqa: E402+++class Registry(unittest.TestCase):+ def test_the_base_pipeline_names_no_domain(self) -> None:+ # The whole point of the change: grep the base state machine for domain names.+ for name in ("workflow_state.py", "state.py"):+ path = ROOT / "_shared" / name if name == "workflow_state.py" else ROOT / name+ body = path.read_text().lower()+ for domain in ("cs2", "character"):+ self.assertNotIn(domain, body, f"{name} still names the {domain!r} domain")++ def test_generic_resolves_to_no_domain(self) -> None:+ self.assertIsNone(domain_profile("generic"))++ def test_both_in_repo_domains_are_registered(self) -> None:+ # Two consumers, one of them destined to leave the repo. A seam with one consumer is a rename.+ self.assertEqual(sorted(registered_domains()), ["character", "cs2"])++ def test_an_unregistered_profile_fails_loud_and_names_what_is_available(self) -> None:+ with self.assertRaises(DomainRegistryError) as ctx:+ domain_profile("valorant")+ message = str(ctx.exception)+ self.assertIn("valorant", message)+ self.assertIn("no installed provider", message)+ self.assertIn("generic", message)++ def test_new_state_refuses_an_unregistered_profile_rather_than_downgrading(self) -> None:+ with self.assertRaises(WorkflowStateError) as ctx:+ new_state("ref.png", profile="valorant")+ self.assertIn("valorant", str(ctx.exception))++ def test_an_unknown_anchor_is_refused_not_appended(self) -> None:+ # Appending at the end would place a domain's setup step after the steps that consume it.+ with self.assertRaises(WorkflowStateError) as ctx:+ self._with_temp_domain(+ "anchortest",+ 'DOMAIN = {"id": "anchortest", "setupSteps": (("x", "y"),), "setupAnchorBefore": "no-such-step"}',+ lambda: new_state("ref.png", profile="anchortest"),+ )+ self.assertIn("no-such-step", str(ctx.exception))++ def test_an_unknown_key_is_refused_not_ignored(self) -> None:+ with self.assertRaises(DomainRegistryError) as ctx:+ self._with_temp_domain(+ "keytest",+ 'DOMAIN = {"id": "keytest", "setupStpes": ()}',+ registered_domains,+ )+ self.assertIn("setupStpes", str(ctx.exception))++ def test_steps_without_an_anchor_are_refused(self) -> None:+ with self.assertRaises(DomainRegistryError) as ctx:+ self._with_temp_domain(+ "anchorless",+ 'DOMAIN = {"id": "anchorless", "passSteps": (("a", "b"),)}',+ registered_domains,+ )+ self.assertIn("passAnchorBefore", str(ctx.exception))++ def test_two_providers_claiming_one_id_is_ambiguous(self) -> None:+ with self.assertRaises(DomainRegistryError) as ctx:+ self._with_temp_domain(+ "dupe",+ 'DOMAIN = {"id": "cs2"}',+ registered_domains,+ )+ self.assertIn("declared twice", str(ctx.exception))++ def _with_temp_domain(self, stem: str, body: str, action):+ """Drop a domain module into the package for one assertion, then remove it."""+ path = Path(domains.__file__).resolve().parent / f"zz_{stem}.py"+ path.write_text(textwrap.dedent(body) + "\n")+ try:+ return action()+ finally:+ path.unlink()+++if __name__ == "__main__":+ unittest.main()