Run frontier MoE models on hardware you already own — pure C, zero deps, experts streamed from disk. Tiny engine, immense model. 🐦
C
planner: add DeepSeek V4 geometry adapter (issue #1066) -- completes all 4 families
SebaWag655dde79fca6
diff --git a/c/family_registry.py b/c/family_registry.pyindex 3734e604..f5ec4cfe 100644--- a/c/family_registry.py+++ b/c/family_registry.py@@ -324,6 +324,75 @@ def _inkling_geometry(config, context, _model_dir):return PlannerGeometry(state, fixed, workspace, experts)++def _dsv4_geometry(config, context, _model_dir):+ """DeepSeek V4: sliding-window ring + per-layer compressor/indexer states.++ Mirrors the engine's own ``context_bytes()`` (deepseek_v4.c:1271-1284)+ exactly -- this is the resident cache the C runtime sizes at load:++ base = num_hidden_layers * sliding_window * head_dim * 4+ per layer: ratio = compress_ratios[layer]+ compressed = ceil(context / ratio)+ total += compressed * head_dim * 4+ if ratio == 4:+ total += compressed * index_head_dim * 4++ The window ring (``base``) does not depend on the context: it is a fixed+ circular buffer, so it belongs in fixed_state_bytes. The compressor and+ indexer states scale with ``context / ratio`` and belong in+ context_state_bytes.++ Workspace mirrors the batched-attention scratch set+ (deepseek_v4.c:2741-2750): qa (q_rank), q (q_width), kv (head_dim),+ attended (q_width), oa (oa_width), norm (max(q_rank, head_dim)) -- with+ q_width = heads * head_dim and oa_width = o_groups * o_lora_rank. With+ batch == context at prefill the peak is the sum of the batch-wide float+ buffers plus the single norm buffer.++ Experts: configured_experts = n_routed_experts.+ """+ layers = _required_int(config, "num_hidden_layers", "deepseek_v4")+ experts = _required_int(config, "n_routed_experts", "deepseek_v4")+ hidden = _required_int(config, "hidden_size", "deepseek_v4")+ heads = _required_int(config, "num_attention_heads", "deepseek_v4")+ head_dim = _required_int(config, "head_dim", "deepseek_v4")+ q_rank = _required_int(config, "q_lora_rank", "deepseek_v4")+ o_groups = _required_int(config, "o_groups", "deepseek_v4")+ o_rank = _required_int(config, "o_lora_rank", "deepseek_v4")+ window = _required_int(config, "sliding_window", "deepseek_v4")+ index_hd = _required_int(config, "index_head_dim", "deepseek_v4")++ ratios = config.get("compress_ratios")+ if not isinstance(ratios, list) or len(ratios) != layers:+ raise ValueError(+ "deepseek_v4: compress_ratios must be a list matching "+ "num_hidden_layers")++ # Fixed window ring: n_layers * window * head_dim fp32.+ fixed = layers * window * head_dim * 4++ # Compressor + indexer states, scaling with context / ratio.+ state = 0+ for ratio in ratios:+ if not isinstance(ratio, bool) and isinstance(ratio, int) and ratio > 0:+ compressed = (context + ratio - 1) // ratio+ state += compressed * head_dim * 4+ if ratio == 4:+ state += compressed * index_hd * 4+ elif ratio != 0:+ raise ValueError("deepseek_v4: compress_ratios entries must be "+ "non-negative integers")++ # Batched-attention scratch (prefill, batch == context).+ q_width = heads * head_dim+ oa_width = o_groups * o_rank+ workspace = (context * (q_rank + 2 * q_width + head_dim + oa_width) ++ max(q_rank, head_dim)) * 4++ return PlannerGeometry(state, fixed, workspace, experts)++_GLM_EXPERT = re.compile(r"(?:^|\.)model\.layers\.(\d+)\.mlp\.experts\.(\d+)\.")@@ -507,8 +576,8 @@ FAMILIES = (cli_adapter="deepseek_v4",gateway_adapter="deepseek_v4",planner_id="deepseek_v4",- planner_geometry=None,- planner_unsupported_reason="DeepSeek V4 uses its C resident-tier planner; Python parity is not yet proven",+ planner_geometry=_dsv4_geometry,+ planner_unsupported_reason="",expert_inventory=_individual_expert_inventory(_V4_EXPERT),config_section="root",limits=FamilyLimits(4096, 1048576, 1024, 16384, 1, 8, "CTX"),diff --git a/c/tests/test_family_registry.py b/c/tests/test_family_registry.pyindex 1edc48c4..489741e9 100644--- a/c/tests/test_family_registry.py+++ b/c/tests/test_family_registry.py@@ -206,7 +206,7 @@ class FamilyRegistryTest(unittest.TestCase):self.assertEqual(geometry.workspace_bytes, 0)def test_unproven_production_planners_refuse_instead_of_inventing_zero(self):- for model_type in ("deepseek_v4",):+ for model_type in ():family = family_for_config({"model_type": model_type})resolved = type("R", (), {"descriptor": family, "family_config": {},"model_dir": "."})()@@ -598,6 +598,145 @@ class FamilyRegistryTest(unittest.TestCase):with self.assertRaises(ValueError):planner_geometry(resolved, 32)+ def test_dsv4_geometry_matches_engine_context_bytes(self):+ # 4 layers: ratios [0, 2, 4, 4] -> no-compress, compressor, indexer, indexer+ config = {+ "model_type": "deepseek_v4",+ "hidden_size": 2048,+ "num_hidden_layers": 4,+ "num_attention_heads": 16,+ "head_dim": 32,+ "q_lora_rank": 16,+ "o_groups": 4,+ "o_lora_rank": 64,+ "sliding_window": 8,+ "index_head_dim": 24,+ "n_routed_experts": 32,+ "compress_ratios": [0, 2, 4, 4],+ }+ by_id, by_type = _build_registry(FAMILIES)+ family = by_type[config["model_type"]]+ self.assertEqual(family, by_id["deepseek_v4"])+ resolved = type("R", (), {"descriptor": family, "family_config": config,+ "model_dir": "."})()+ geometry = planner_geometry(resolved, 32)+ # Fixed window ring: 4 layers * window 8 * head_dim 32 * 4+ self.assertEqual(geometry.fixed_state_bytes, 4 * 8 * 32 * 4)+ # Compressor states: ceil(32/2)=16 * hd * 4 + ceil(32/4)=8 * hd * 4 * 2+ state = 16 * 32 * 4 + 8 * 32 * 4 + 8 * 32 * 4+ # Indexer states (ratio==4): ceil(32/4)=8 * index_hd 24 * 4, for 2 layers+ state += 8 * 24 * 4 + 8 * 24 * 4+ self.assertEqual(geometry.context_state_bytes, state)+ self.assertEqual(geometry.configured_experts, 32)++ def test_dsv4_geometry_fixed_ring_does_not_scale_with_context(self):+ config = {+ "model_type": "deepseek_v4",+ "hidden_size": 2048,+ "num_hidden_layers": 4,+ "num_attention_heads": 16,+ "head_dim": 32,+ "q_lora_rank": 16,+ "o_groups": 4,+ "o_lora_rank": 64,+ "sliding_window": 8,+ "index_head_dim": 24,+ "n_routed_experts": 32,+ "compress_ratios": [0, 2, 4, 4],+ }+ by_id, _ = _build_registry(FAMILIES)+ family = by_id["deepseek_v4"]+ resolved = type("R", (), {"descriptor": family, "family_config": config,+ "model_dir": "."})()+ small = planner_geometry(resolved, 16)+ large = planner_geometry(resolved, 64)+ # Window ring is context-independent+ self.assertEqual(small.fixed_state_bytes, large.fixed_state_bytes)+ # Compressed states scale ~linearly with context (ceil divisions)+ ratio = large.context_state_bytes / small.context_state_bytes+ self.assertAlmostEqual(ratio, 4, delta=0.5)++ def test_dsv4_geometry_workspace_matches_attention_scratch(self):+ config = {+ "model_type": "deepseek_v4",+ "hidden_size": 2048,+ "num_hidden_layers": 4,+ "num_attention_heads": 16,+ "head_dim": 32,+ "q_lora_rank": 16,+ "o_groups": 4,+ "o_lora_rank": 64,+ "sliding_window": 8,+ "index_head_dim": 24,+ "n_routed_experts": 32,+ "compress_ratios": [0, 2, 4, 4],+ }+ by_id, _ = _build_registry(FAMILIES)+ family = by_id["deepseek_v4"]+ resolved = type("R", (), {"descriptor": family, "family_config": config,+ "model_dir": "."})()+ geometry = planner_geometry(resolved, 32)+ ctx = 32+ q_width = 16 * 32 # heads * head_dim+ oa_width = 4 * 64 # o_groups * o_lora_rank+ expected = (ctx * (16 + 2 * q_width + 32 + oa_width) ++ max(16, 32)) * 4+ self.assertEqual(geometry.workspace_bytes, expected)++ def test_dsv4_geometry_rejects_bad_compress_ratios(self):+ config = {+ "model_type": "deepseek_v4",+ "hidden_size": 2048,+ "num_hidden_layers": 4,+ "num_attention_heads": 16,+ "head_dim": 32,+ "q_lora_rank": 16,+ "o_groups": 4,+ "o_lora_rank": 64,+ "sliding_window": 8,+ "index_head_dim": 24,+ "n_routed_experts": 32,+ "compress_ratios": [0, 2], # wrong length+ }+ by_id, _ = _build_registry(FAMILIES)+ family = by_id["deepseek_v4"]+ resolved = type("R", (), {"descriptor": family, "family_config": config,+ "model_dir": "."})()+ with self.assertRaises(ValueError):+ planner_geometry(resolved, 32)++ def test_dsv4_geometry_rejects_missing_keys(self):+ by_id, _ = _build_registry(FAMILIES)+ family = by_id["deepseek_v4"]+ resolved = type("R", (), {"descriptor": family, "family_config": {},+ "model_dir": "."})()+ with self.assertRaises(ValueError):+ planner_geometry(resolved, 32)++ def test_dsv4_geometry_all_uncompressed_layers_have_only_ring(self):+ config = {+ "model_type": "deepseek_v4",+ "hidden_size": 2048,+ "num_hidden_layers": 4,+ "num_attention_heads": 16,+ "head_dim": 32,+ "q_lora_rank": 16,+ "o_groups": 4,+ "o_lora_rank": 64,+ "sliding_window": 8,+ "index_head_dim": 24,+ "n_routed_experts": 32,+ "compress_ratios": [0, 0, 0, 0],+ }+ by_id, _ = _build_registry(FAMILIES)+ family = by_id["deepseek_v4"]+ resolved = type("R", (), {"descriptor": family, "family_config": config,+ "model_dir": "."})()+ geometry = planner_geometry(resolved, 64)+ # No compressors: context state is zero, only the ring is resident+ self.assertEqual(geometry.context_state_bytes, 0)+ self.assertEqual(geometry.fixed_state_bytes, 4 * 8 * 32 * 4)+def test_cli_and_gateway_dispatch_follow_the_registry(self):import openai_serverfrom importlib.machinery import SourceFileLoader