Skip to content

Open-source platform for 3D AI agents. Turn text or a photo into a rigged, animated GLB avatar, give it an LLM brain, memory and a wallet, and embed it anywhere with one web component. Remote MCP server, x402 payments, Three.js, browser-native.

11.4 KB
Raw Blame
import os
import tempfile
import unittest
from pathlib import Path

from services.model_sources import (
    installed_weight_variants,
    missing_weight_variant,
    model_sources_are_downloaded,
    normalize_model_sources,
    normalize_weight_group_references,
    normalize_weight_groups,
    normalize_weight_variants,
    resolve_model_root,
    resolve_weight_group_root,
    resolve_weight_storage_root,
    validate_source_file_plan,
    validate_model_node_ids,
    weight_group_sources_are_downloaded,
)


def valid_node() -> dict:
    return {
        "model_sources": [
            {
                "id": "primary",
                "provider": "huggingface",
                "repo_id": "org/main",
                "destination": ".",
                "checks": ["pipeline.json"],
            },
            {
                "id": "encoder",
                "provider": "huggingface",
                "repo_id": "org/encoder",
                "revision": "refs/pr/1",
                "destination": "auxiliary/encoder",
                "include_prefixes": ["config.json", "weights/"],
                "checks": ["config.json", "model.safetensors"],
            },
        ]
    }


class ModelSourcesTests(unittest.TestCase):
    def test_managed_node_ids_reject_case_aliases(self):
        for ids in (("Fast", "fast"), ("fast", "fast")):
            with self.subTest(ids=ids), self.assertRaisesRegex(ValueError, "portable-unique"):
                validate_model_node_ids([{"id": node_id} for node_id in ids])

    def test_validates_new_sources_without_reinterpreting_legacy_fields(self) -> None:
        sources = normalize_model_sources(valid_node())
        self.assertEqual([source["id"] for source in sources or []], ["primary", "encoder"])
        self.assertIsNone(normalize_model_sources({
            "hf_repo": "legacy/repo",
            "download_check": "../generate/model.safetensors",
            "hf_skip_prefixes": ["weights/**"],
        }))

    def test_rejects_unsafe_and_non_portable_declarations(self) -> None:
        source = valid_node()["model_sources"][0]
        for destination in ("../outside", "aux/CON", "aux/name.", "C:/models"):
            with self.subTest(destination=destination), self.assertRaises(ValueError):
                normalize_model_sources({
                    "model_sources": [{**source, "destination": destination}]
                })
        with self.assertRaisesRegex(ValueError, "provider"):
            normalize_model_sources({
                "model_sources": [{**source, "provider": "url"}]
            })
        with self.assertRaisesRegex(ValueError, "portable-unique"):
            normalize_model_sources({
                "model_sources": [source, {**source, "id": "PRIMARY"}]
            })
        with self.assertRaisesRegex(ValueError, "checks"):
            normalize_model_sources({
                "model_sources": [{**source, "checks": []}]
            })

    def test_rejects_portable_cross_source_file_collisions(self) -> None:
        sources = normalize_model_sources(valid_node()) or []
        with self.assertRaisesRegex(ValueError, "portable target collision"):
            validate_source_file_plan(sources, {
                "primary": ["pipeline.json", "Auxiliary/Encoder/model.safetensors"],
                "encoder": ["config.json", "model.safetensors"],
            })

    def test_rejects_checks_excluded_from_the_download_plan(self) -> None:
        sources = normalize_model_sources(valid_node()) or []
        with self.assertRaisesRegex(ValueError, "excluded from its download plan"):
            validate_source_file_plan(sources, {
                "primary": ["pipeline.json"],
                "encoder": ["config.json"],
            })

    def test_requires_all_checks_and_rejects_symlinked_extension_ancestry(self) -> None:
        sources = normalize_model_sources(valid_node()) or []
        with tempfile.TemporaryDirectory(prefix="forge-model-sources-") as tmp:
            models = Path(tmp) / "models"
            model_root = models / "pixal3d" / "generate"
            encoder = model_root / "auxiliary" / "encoder"
            encoder.mkdir(parents=True)
            (model_root / "pipeline.json").write_text("{}", encoding="utf-8")
            (encoder / "config.json").write_text("{}", encoding="utf-8")
            self.assertFalse(model_sources_are_downloaded(models, "pixal3d/generate", sources))
            (encoder / "model.safetensors").write_bytes(b"x")
            self.assertTrue(model_sources_are_downloaded(models, "pixal3d/generate", sources))

            (encoder / "model.safetensors").write_bytes(b"")
            self.assertFalse(model_sources_are_downloaded(models, "pixal3d/generate", sources))
            (encoder / "model.safetensors").unlink()
            (encoder / "model.safetensors").mkdir()
            self.assertFalse(model_sources_are_downloaded(models, "pixal3d/generate", sources))

            for child in sorted((models / "pixal3d").rglob("*"), reverse=True):
                child.unlink() if child.is_file() else child.rmdir()
            (models / "pixal3d").rmdir()
            outside = Path(tmp) / "outside"
            (outside / "generate").mkdir(parents=True)
            try:
                os.symlink(outside, models / "pixal3d", target_is_directory=True)
            except (NotImplementedError, OSError) as exc:
                self.skipTest(f"Symlinks unavailable: {exc}")
            with self.assertRaisesRegex(ValueError, "symlink"):
                resolve_model_root(models, "pixal3d/generate")
            self.assertFalse(model_sources_are_downloaded(models, "pixal3d/generate", sources))

    def test_validates_group_references_and_rejects_portable_aliases(self) -> None:
        groups = normalize_weight_groups({
            "weight_groups": [{
                "id": "Base-Weights",
                "model_sources": valid_node()["model_sources"],
            }]
        })
        self.assertEqual(
            normalize_weight_group_references(
                {"weight_groups": ["base-weights"]}, groups
            ),
            ["Base-Weights"],
        )
        with self.assertRaisesRegex(ValueError, "unknown weight group"):
            normalize_weight_group_references(
                {"weight_groups": ["missing"]}, groups
            )
        with self.assertRaisesRegex(ValueError, "portable-unique"):
            normalize_weight_groups({
                "weight_groups": [
                    {"id": "base", "model_sources": valid_node()["model_sources"]},
                    {"id": "BASE", "model_sources": valid_node()["model_sources"]},
                ]
            })

    def test_shared_group_uses_reserved_extension_storage_root(self) -> None:
        group = (normalize_weight_groups({
            "weight_groups": [{
                "id": "base",
                "model_sources": [{
                    "id": "primary",
                    "provider": "huggingface",
                    "repo_id": "org/base",
                    "destination": ".",
                    "checks": ["model.bin"],
                }],
            }]
        }) or [])[0]
        with tempfile.TemporaryDirectory(prefix="forge-shared-sources-") as tmp:
            models = Path(tmp) / "models"
            group_root = models / "demo" / "_shared" / "base"
            self.assertEqual(resolve_weight_group_root(models, "demo", "base"), group_root)
            self.assertEqual(
                resolve_weight_storage_root(models, "demo/_shared/base"), group_root
            )
            with self.assertRaisesRegex(ValueError, "reserved"):
                resolve_model_root(models, "demo/_shared")
            self.assertFalse(weight_group_sources_are_downloaded(models, "demo", group))
            group_root.mkdir(parents=True)
            (group_root / "model.bin").write_bytes(b"weights")
            self.assertTrue(weight_group_sources_are_downloaded(models, "demo", group))

    def test_weight_variants_validate_and_report_the_missing_selection(self) -> None:
        def variant(quant: str) -> dict:
            return {
                "id": quant,
                "include_prefixes": [f"dit/model_{quant}.gguf"],
                "checks": [f"dit/model_{quant}.gguf"],
            }

        node = {
            "hf_repo": "org/model-gguf",
            "download_check": "pipeline.json",
            "params_schema": [
                {"id": "quant", "type": "select", "options": [{"value": "Q4"}, {"value": "Q5"}]}
            ],
            "weight_variants": {"param": "quant", "options": [variant("Q4"), variant("Q5")]},
        }
        variants = normalize_weight_variants(node) or {}
        self.assertEqual(variants["default"], "Q4")
        self.assertIsNone(normalize_weight_variants({"hf_repo": "org/model"}))

        def with_options(options: list, **extra) -> dict:
            return {**node, "weight_variants": {"param": "quant", "options": options, **extra}}

        overlapping = {**variant("Q5"), "include_prefixes": ["dit/"]}
        for broken, message in (
            ({**node, "hf_repo": ""}, "requires hf_repo"),
            ({**node, "model_sources": []}, "cannot be combined"),
            ({**node, "weight_groups": ["base"]}, "cannot be combined with weight_groups"),
            ({**node, "download_check": "dit/model_Q4.gguf"}, "download_check"),
            (with_options([variant("Q4"), overlapping]), "share files"),
            (with_options([variant("Q4")], default="Q8"), "default"),
            (with_options([{**variant("Q4"), "checks": ["x.gguf"]}]), "not covered"),
            (with_options([{**variant("Q4"), "size_gb": True}]), "size_gb"),
            (with_options([{**variant("Q4"), "vram_gb": 0}]), "vram_gb"),
            (with_options([{**variant("Q4"), "vram_gb": "6"}]), "vram_gb"),
            ({**node, "params_schema": []}, "must name a params_schema entry"),
            (
                {**node, "params_schema": [{"id": "quant", "options": [{"value": "Q5"}]}]},
                "must offer every weight variant id",
            ),
        ):
            with self.subTest(message=message), self.assertRaisesRegex(ValueError, message):
                normalize_weight_variants(broken)

        # A param that declares no options is left to the node to interpret.
        self.assertIsNotNone(
            normalize_weight_variants({**node, "params_schema": [{"id": "quant", "type": "string"}]})
        )
        self.assertNotIn("vram_gb", variants["options"][0])
        with_vram = normalize_weight_variants(with_options([{**variant("Q4"), "vram_gb": 6.5}])) or {}
        self.assertEqual(with_vram["options"][0]["vram_gb"], 6.5)

        with tempfile.TemporaryDirectory(prefix="forge-weight-variants-") as tmp:
            models = Path(tmp) / "models"
            dit = models / "trellis" / "generate" / "dit"
            dit.mkdir(parents=True)
            (dit / "model_Q5.gguf").write_bytes(b"q5")
            (dit / "model_Q4.gguf").write_bytes(b"")
            self.assertEqual(installed_weight_variants(models, "trellis/generate", variants), ["Q5"])
            missing = missing_weight_variant(models, "trellis/generate", variants, {})
            self.assertEqual((missing or {}).get("id"), "Q4")
            for params in ({"quant": "Q5"}, {"quant": "fp16"}):
                with self.subTest(params=params):
                    self.assertIsNone(missing_weight_variant(models, "trellis/generate", variants, params))
            self.assertIsNone(missing_weight_variant(models, "trellis/generate", None, {"quant": "Q4"}))


if __name__ == "__main__":
    unittest.main()