Skip to content

Rebuild the object in a reference image as a code-only, procedural, quality-gated, animation-ready Three.js model. Token-efficient image-to-3D.

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__.py
new file mode 100644
index 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.py
new file mode 100644
index 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.py
new file mode 100644
index 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.py
index cf24c34..4724a2d 100644
--- a/forge/_shared/workflow_state.py
+++ b/forge/_shared/workflow_state.py
@@ -3,11 +3,16 @@ from __future__ import annotations
import json
import os
import shlex
+import sys
import tempfile
from copy import deepcopy
from pathlib import Path
from typing import Any, Final
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+
+from domains import DomainRegistryError, domain_profile # noqa: E402
+
SCHEMA_VERSION: Final = 1
STEP_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 exc
if 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 exc
checklist = 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.py
index 93496c8..eeba404 100644
--- a/forge/state.py
+++ b/forge/state.py
@@ -9,6 +9,7 @@ from pathlib import Path
ROOT = Path(__file__).resolve().parent
sys.path.insert(0, str(ROOT / "_shared"))
+from domains import registered_domains # noqa: E402
from workflow_state import ( # noqa: E402
WorkflowStateError,
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.py
new file mode 100644
index 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()