Agent skill for creative 3D visualization: turn an idea into a Three.js/Blender scene worth exploring. Claude Code + Codex plugin, 223 recipes, 440 knowledge records, 22 proved kits, 37 runnable studies.
import copy
import importlib.util
import json
from pathlib import Path
import sys
import tempfile
import unittest
SCRIPTS = Path(__file__).resolve().parents[1] / 'skills/3dviz-pro-max/scripts'
sys.path.insert(0, str(SCRIPTS))
from catalog import load_catalog
from resolve import resolve
spec = importlib.util.spec_from_file_location('design_context', SCRIPTS / 'design-context.py')
context = importlib.util.module_from_spec(spec)
spec.loader.exec_module(context)
import quality_brief # noqa: E402 (imported through the same scripts path)
HOST = {'quality_ceiling': 'T3', 'quality_ceiling_reason': 'Blender 5.2.1 >= 4.2 found',
'capture_mode_expected': 'gpu'}
HOST_T2 = {'quality_ceiling': 'T2', 'quality_ceiling_reason': 'no runnable Blender',
'capture_mode_expected': 'swiftshader'}
WATERMILL = 'knowledge.blueprint-watermill'
TREE = 'knowledge.blueprint-tree-round'
LOOKS = ['knowledge.style-ghibli-painterly-pastoral']
class ContextTests(unittest.TestCase):
def setUp(self):
self.manifest, self.records, self.sources = load_catalog(collection='all')
self.by_id = {record['id']: record for record in self.records}
def test_resolve_exact_selection_and_only_cited_sources(self):
rid = 'recipe.linear-transformation-3d'
result = resolve([rid, rid], self.manifest, self.records, self.sources)
self.assertEqual([r['id'] for r in result['records']], [rid])
expected = {ref['source_id'] for claim in result['records'][0]['claims']
for ref in claim['source_refs']}
self.assertEqual({s['id'] for s in result['sources']}, expected)
changed = copy.deepcopy(self.sources)
for source in changed:
if source['id'] in expected:
source['scope'] += ' Clarified scope.'
updated = resolve([rid], self.manifest, self.records, changed)
self.assertNotEqual(result['bundle_hash'], updated['bundle_hash'])
with self.assertRaisesRegex(ValueError, 'Unknown record'):
resolve(['recipe.missing'], self.manifest, self.records, self.sources)
with self.assertRaises(ValueError) as caught:
resolve(['recipe.fantasy-village'], self.manifest, self.records, self.sources)
self.assertRegex(str(caught.exception), 'did you mean')
def test_related_traversal_is_one_hop_and_detects_dangling_links(self):
records = copy.deepcopy(self.records[:3])
first, second, third = [r['id'] for r in records]
records[0]['related_ids'] = [second]
records[1]['related_ids'] = [third]
result = resolve([first], self.manifest, records, self.sources, related=True)
self.assertEqual([r['id'] for r in result['records']], [first, second])
records[0]['related_ids'] = ['recipe.missing']
with self.assertRaisesRegex(ValueError, 'Dangling relationship'):
resolve([first], self.manifest, records, self.sources, related=True)
def test_context_honors_family_and_exclusions_without_claiming_design(self):
result = context.gather('gravity contact', self.manifest, self.records, self.sources,
kinds=['physical-behavior'],
exclude_ids=['knowledge.gravity-contact'])
knowledge = result['candidate_groups']['physical-behavior']['results']
self.assertTrue(all(r['kind'] == 'physical-behavior' for r in knowledge))
self.assertNotIn('knowledge.gravity-contact', result['context']['selected_ids'])
self.assertEqual(context.gather('zebrasentinel', self.manifest, self.records,
self.sources)['status'], 'no-match')
with self.assertRaises(ValueError):
context.gather(' ', self.manifest, self.records, self.sources)
def test_blueprints_filter_by_look_without_ranking(self):
looks = ['knowledge.style-ghibli-painterly-pastoral']
result = context.gather('cosy riverside village at dusk', self.manifest, self.records,
self.sources, blueprints=True, looks=looks)
rows = result['blueprints']
self.assertGreaterEqual(len(rows), 5)
self.assertEqual([r['id'] for r in rows], sorted(r['id'] for r in rows))
for row in rows:
self.assertTrue(row['asset'].startswith('templates/kits/'))
self.assertEqual(len(row['footprint_m']), 2)
self.assertTrue(row['sockets'])
self.assertEqual(set(row['detail_ladder']), {'silhouette', 'medium', 'fine'})
self.assertIn(looks[0], self.by_id[row['id']]['fits_looks'])
self.assertIn('Reuse, adapt, reject or combine', result['next_step'])
# No score, no top-k: a filter must not present itself as a judgement.
self.assertNotIn('score', rows[0])
def test_blueprints_edges_empty_unfiltered_and_unknown_look(self):
unmatched = context.gather('village', self.manifest, self.records, self.sources,
blueprints=True, looks=['knowledge.style-neon-noir-rain'])
self.assertEqual(unmatched['blueprints'], [])
self.assertEqual(unmatched['status'],
context.gather('village', self.manifest, self.records,
self.sources)['status'])
every = context.gather('village', self.manifest, self.records, self.sources,
blueprints=True)
self.assertEqual(len(every['blueprints']),
len([r for r in self.records
if r.get('knowledge_kind') == 'blueprint' and r['status'] == 'active']))
plain = context.gather('village', self.manifest, self.records, self.sources)
self.assertNotIn('blueprints', plain)
self.assertNotIn('Assemble from', plain['next_step'])
with self.assertRaisesRegex(ValueError, 'Unknown record IDs'):
context.gather('village', self.manifest, self.records, self.sources,
blueprints=True, looks=['knowledge.style-does-not-exist'])
with self.assertRaisesRegex(ValueError, 'style, theme or lighting'):
context.gather('village', self.manifest, self.records, self.sources,
blueprints=True, looks=['knowledge.blueprint-watermill'])
with self.assertRaisesRegex(ValueError, 'only applies with'):
context.gather('village', self.manifest, self.records, self.sources,
looks=['knowledge.style-ghibli-painterly-pastoral'])
def brief(self, host=HOST, delivery='web-desktop', heroes=(WATERMILL,)):
result = context.gather('cosy riverside village at dusk', self.manifest, self.records,
self.sources, blueprints=True, looks=LOOKS, host=host,
delivery=delivery, heroes=list(heroes))
return result['quality_brief']
def test_the_brief_names_a_tier_and_a_reason_for_every_listed_blueprint(self):
brief = self.brief()
listed = {row['id'] for row in context.gather(
'cosy riverside village at dusk', self.manifest, self.records, self.sources,
blueprints=True, looks=LOOKS)['blueprints']}
self.assertEqual(set(brief['per_blueprint']), listed)
for rid, row in brief['per_blueprint'].items():
self.assertIn(row['role'], ('hero', 'mid', 'background'))
self.assertIn(row['tier'], ('T0', 'T1', 'T2', 'T3'))
self.assertTrue(row['reason'].strip(), rid)
self.assertEqual((brief['ceiling'], brief['delivery'], brief['capture_mode_expected']),
('T3', 'web-desktop', 'gpu'))
self.assertIn('4,773 draw calls', brief['draw_call_note'])
self.assertIn('InstancedMesh', brief['draw_call_note'])
self.assertIn('not limits', brief['note'])
self.assertEqual(set(brief['role_rules']), {'hero', 'mid', 'background'})
def test_a_tier_the_record_calls_missing_is_never_recommended(self):
row = self.brief()['per_blueprint'][WATERMILL]
# The watermill declares a shipped T3 since phase 9C, so the hero gets the ceiling; the
# barrel below still declares T3 missing and must drop to its highest proved tier.
# tier and the reason says which status it stepped over.
self.assertEqual((row['role'], row['tier']), ('hero', 'T3'))
self.assertIn('T3', row['reason'])
for rid, entry in self.brief()['per_blueprint'].items():
tiers = quality_brief.tier_view(self.by_id[rid])
declared = tiers.get(entry['tier'])
self.assertIsNotNone(declared, rid)
self.assertNotIn(declared['status'], quality_brief.UNAVAILABLE, rid)
def test_a_record_with_no_tiers_block_is_recommended_at_t1(self):
# Since phase 9D every shipped blueprint declares tiers, so the legacy shape is
# synthesised here rather than borrowed from the catalog: strip one record's tiers
# and the brief must fall back to T1 with the reason that says why.
records = copy.deepcopy(self.records)
stripped = None
for record in records:
if (record.get('knowledge_kind') == 'blueprint' and record.get('tiers')
and set(LOOKS).intersection(record.get('fits_looks', []))):
record.pop('tiers')
stripped = record['id']
break
self.assertIsNotNone(stripped, 'the catalog needs at least one blueprint with tiers')
brief = context.gather('cosy riverside village at dusk', self.manifest, records,
self.sources, blueprints=True, looks=LOOKS, host=HOST,
delivery='web-desktop',
heroes=[WATERMILL])['quality_brief']
row = brief['per_blueprint'][stripped]
self.assertEqual(row['tier'], 'T1', stripped)
self.assertIn('declares no T2 yet', row['reason'])
def test_instanced_repeats_are_background_and_web_mobile_drops_them_to_t0(self):
self.assertEqual(self.brief()['scope'], 'shipped-kit-pipelines')
desktop = self.brief()['per_blueprint'][TREE]
self.assertEqual((desktop['role'], desktop['tier']), ('background', 'T1'))
self.assertIn('one draw call', desktop['reason'])
mobile = self.brief(delivery='web-mobile')['per_blueprint'][TREE]
self.assertEqual(mobile['tier'], 'T0')
self.assertIn('web-mobile', mobile['reason'])
def test_the_delivery_target_caps_the_hero_and_the_ceiling_lowers_it(self):
self.assertEqual(self.brief(delivery='presentation')['per_blueprint'][WATERMILL]['tier'],
'T2')
capped = self.brief(delivery='presentation')['per_blueprint'][WATERMILL]['reason']
self.assertIn('presentation caps it at T2', capped)
lower = self.brief(host=HOST_T2)['per_blueprint'][WATERMILL]
self.assertEqual((lower['tier'], self.brief(host=HOST_T2)['ceiling']), ('T3', 'T2'))
self.assertIn('proved shipped T3 GLB', lower['reason'])
self.assertIn('host bake ceiling T2', lower['reason'])
def test_shipped_glb_reuse_requires_proof_and_an_existing_asset(self):
record = copy.deepcopy(self.by_id[WATERMILL])
for status, path in [('not-proved', record['tiers']['T3']['asset']['path']),
('proved', 'templates/kits/gltf/absent.glb')]:
record['tiers']['T3']['status'] = status
record['tiers']['T3']['asset']['path'] = path
tier, _ = quality_brief.recommend(record, 'hero', 'T2', 'web-desktop')
self.assertEqual(tier, 'T2')
self.assertNotIn('custom geometry only', context.ASSEMBLY_STEP)
def test_a_plain_run_still_has_no_quality_brief(self):
result = context.gather('village', self.manifest, self.records, self.sources,
blueprints=True, looks=LOOKS)
self.assertNotIn('quality_brief', result)
def test_the_brief_flags_refuse_the_combinations_that_cannot_mean_anything(self):
with self.assertRaisesRegex(ValueError, 'only apply with'):
context.gather('village', self.manifest, self.records, self.sources, host=HOST)
with self.assertRaisesRegex(ValueError, 'only apply with'):
context.gather('village', self.manifest, self.records, self.sources,
heroes=[WATERMILL])
with self.assertRaisesRegex(ValueError, 'host-probe.py'):
context.gather('village', self.manifest, self.records, self.sources,
blueprints=True, heroes=[WATERMILL])
with self.assertRaisesRegex(ValueError, 'Unknown delivery target'):
context.gather('village', self.manifest, self.records, self.sources,
blueprints=True, host=HOST, delivery='billboard')
with self.assertRaisesRegex(ValueError, 'not listed blueprints'):
context.gather('village', self.manifest, self.records, self.sources, blueprints=True,
looks=LOOKS, host=HOST, heroes=['knowledge.blueprint-nope'])
def test_an_unreadable_host_file_names_the_probe_command(self):
with tempfile.TemporaryDirectory() as tmp:
missing = Path(tmp) / 'host.json'
with self.assertRaisesRegex(ValueError, 'host-probe.py'):
quality_brief.load_host(missing)
missing.write_text('not json')
with self.assertRaisesRegex(ValueError, 'host-probe.py'):
quality_brief.load_host(missing)
missing.write_text(json.dumps({'os': {}}))
with self.assertRaisesRegex(ValueError, 'no quality_ceiling'):
quality_brief.load_host(missing)
missing.write_text(json.dumps(HOST))
self.assertEqual(quality_brief.load_host(missing)['quality_ceiling'], 'T3')
def test_the_tier_view_matches_the_validator(self):
from blueprint_validation import blueprint_tiers
for rid in (WATERMILL, TREE):
self.assertEqual(quality_brief.tier_view(self.by_id[rid]),
blueprint_tiers(self.by_id[rid]))
def test_resolve_prints_a_runnable_snippet_for_every_blueprint(self):
ids = [r['id'] for r in self.records if r.get('knowledge_kind') == 'blueprint']
self.assertEqual(len(ids), 22)
result = resolve(ids, self.manifest, self.records, self.sources)
for rid in ids:
usage = result['blueprints'][rid]
record = self.by_id[rid]
self.assertEqual(usage['asset'], record['asset']['path'])
self.assertEqual(usage['sockets'], [s['name'] for s in record['sockets']])
self.assertEqual(usage['params'], {p['name']: p['default'] for p in record['params']})
self.assertIn(f"import {{ {usage['factory']} }} from './", usage['snippet'])
self.assertIn('scene.add(group);', usage['snippet'])
# The import path is the callable module relative to templates/kits/, so a copied-out
# kit folder resolves it unchanged. A .glb record imports its loader wrapper and awaits.
imported = usage['snippet'].split("from './")[1].split("';")[0]
self.assertTrue(usage['module'].endswith(imported))
self.assertTrue(usage['module'].endswith('.js'))
self.assertEqual(usage['awaits'], record['asset']['kind'] == 'gltf-asset')
self.assertEqual(f'await {usage["factory"]}(' in usage['snippet'], usage['awaits'])
self.assertTrue((SCRIPTS.parents[0] / usage['module']).is_file())
if __name__ == '__main__':
unittest.main()