Skip to content

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.py
index 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.py
index 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_server
from importlib.machinery import SourceFileLoader