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.
JavaScript 3d-generationai-agentsanimationavatardigital-humangenerative-aiglbgltfimage-to-3dllmmcpmcp-servermodel-context-protocolsolanatext-to-3dthreejsweb-componentswebglwebxrx402
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()