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

build: integrate V4 targets and tests with the current colibri tree

DrewZ2430625d9904
diff --git a/.gitignore b/.gitignore
index f62b3792..b2646483 100644
--- a/.gitignore
+++ b/.gitignore
@@ -30,6 +30,17 @@ c/tests/test_*
!c/tests/test_*.cu
!c/tests/test_*.mm
!c/tests/test_*.py
+c/deepseek_v4
+c/deepseek_v4.exe
+c/COLI_V4_UNIT_*.o
+c/safetensors_index.o
+c/tensor_io.o
+c/native_quant.o
+c/native_quant_parallel.o
+c/native_quant_dual.o
+c/native_quant_batch_avx512.o
+c/native_quant_fp4_rows16.o
+c/build/ownership/
result
# oracoli tiny generati (make_glm_oracle.py) e dati benchmark scaricati
@@ -39,9 +50,13 @@ c/glm_tiny_i4/
c/glm_tiny_mix/
c/glm_bench_medium/
c/bench/
+c/tests/deepseek_v4_oracle.json
+c/tests/deepseek_v4_oracle.tmp_ids.json
# pesi modello / artefatti di run
*.safetensors
+!c/deepseek_v4_tiny/model.safetensors
+!c/deepseek_v4_tiny/dspark/model.safetensors
stats*.txt
*.log
@@ -68,3 +83,5 @@ olmoe_merged/
olmoe_i4/
c/olmoe_merged/
c/olmoe_i4/
+.venv*/
+.bench/
diff --git a/Makefile b/Makefile
index 9a20b7ad..7c9eb3a7 100644
--- a/Makefile
+++ b/Makefile
@@ -1,4 +1,4 @@
-.PHONY: all glm portable test check cuda-test clean install uninstall
+.PHONY: all glm deepseek-v4 portable test check cuda-test clean install uninstall
-all glm portable test check cuda-test clean install uninstall:
+all glm deepseek-v4 portable test check cuda-test clean install uninstall:
$(MAKE) -C c $@
\ No newline at end of file
diff --git a/c/Makefile b/c/Makefile
index a598d923..714ac114 100644
--- a/c/Makefile
+++ b/c/Makefile
@@ -199,10 +199,27 @@ else
PYTHON ?= python3
endif
CUDA_OBJ =
+
+# DeepSeek V4 is a separate x86-64 runtime. Portable infrastructure tests run
+# everywhere; the engine and token-exact fixture run only on Linux/Windows.
+COLI_V4_SUPPORTED :=
+ifneq (,$(X86_64))
+ifneq (,$(IS_WIN)$(LINUX))
+COLI_V4_SUPPORTED := 1
+endif
+endif
+
+V4_INFRA_TEST_BINS = tests/test_expert_store_ops$(EXE) \
+ tests/test_safetensors_index$(EXE) tests/test_native_quant$(EXE) \
+ tests/test_tensor_io$(EXE)
TEST_BINS = tests/test_json$(EXE) tests/test_st$(EXE) tests/test_st_mirror$(EXE) tests/test_st_pread$(EXE) tests/test_tier$(EXE) tests/test_grammar$(EXE) tests/test_schema_gbnf$(EXE) tests/test_decode_batch$(EXE) tests/test_idot$(EXE) tests/test_i4_grouped$(EXE) tests/test_stops$(EXE) tests/test_topp$(EXE) tests/test_sample_nan$(EXE) tests/test_temp_env$(EXE) tests/test_tok_o200k$(EXE) tests/test_kv_alloc$(EXE) tests/test_int3$(EXE) tests/test_int3_load$(EXE) tests/test_i4_acc512$(EXE) tests/test_compat_direct$(EXE) tests/test_dsa_select$(EXE) tests/test_logit_nan$(EXE) tests/test_pipe_block$(EXE) tests/test_e8_kernel$(EXE)
+TEST_BINS += $(V4_INFRA_TEST_BINS)
ifneq (,$(LINUX))
TEST_BINS += tests/test_uring$(EXE)
endif
+ifeq ($(COLI_V4_SUPPORTED),1)
+TEST_BINS += tests/test_deepseek_v4$(EXE) tests/test_v4_ownership$(EXE)
+endif
# Windows CUDA DLL path: host links the loader, NOT cudart.
ifneq ($(IS_WIN),)
@@ -257,6 +274,40 @@ endif
all: colibri$(EXE)
+.PHONY: deepseek-v4 deepseek-v4-oracle deepseek-v4-tiny-check deepseek-v4-clean
+ifeq ($(COLI_V4_SUPPORTED),1)
+deepseek-v4:
+ $(MAKE) -f Makefile.deepseek-v4 ARCH=$(ARCH) deepseek-v4
+
+deepseek-v4-clean:
+ $(MAKE) -f Makefile.deepseek-v4 deepseek-v4-clean
+
+deepseek-v4-tiny-check:
+ $(MAKE) -f Makefile.deepseek-v4 deepseek-v4-clean
+ $(MAKE) -f Makefile.deepseek-v4 ARCH=$(if $(strip $(ARCH)),$(ARCH),$(PORTABLE_ARCH)) deepseek-v4
+ $(PYTHON) tests/test_deepseek_v4_tiny.py \
+ --binary ./$(if $(IS_WIN),deepseek_v4.exe,deepseek_v4) \
+ --fixture ./deepseek_v4_tiny
+
+deepseek-v4-oracle: deepseek-v4
+ @test -n "$(MODEL)" || { echo "usage: make deepseek-v4-oracle MODEL=/path/to/checkpoint" >&2; exit 2; }
+ $(PYTHON) tools/make_deepseek_v4_oracle.py --model "$(MODEL)" \
+ --binary ./$(if $(IS_WIN),deepseek_v4.exe,deepseek_v4) \
+ --output tests/deepseek_v4_oracle.json \
+ --memory-gb $(or $(MEMORY_GB),32) \
+ --prompt "$(or $(ORACLE_PROMPT),The capital of France is)" \
+ --continuation "$(or $(ORACLE_CONTINUATION), Paris.)" \
+ --greedy $(or $(ORACLE_GREEDY),20) \
+ --check-dspark
+else
+deepseek-v4 deepseek-v4-oracle:
+ @echo "$@ is supported only on x86-64 Linux and Windows/MSYS2" >&2; exit 1
+deepseek-v4-clean:
+ @:
+deepseek-v4-tiny-check:
+ @echo "SKIP deepseek-v4-tiny-check: V4 runtime requires x86-64 Linux or Windows/MSYS2"
+endif
+
# phony targets — 'glm' kept for backward compatibility
colibri: colibri$(EXE)
glm: colibri$(EXE)
@@ -427,6 +478,61 @@ tests/test_i4_acc512$(EXE): tests/test_i4_acc512.c
tests/test_compat_direct$(EXE): tests/test_compat_direct.c compat.h
$(CC) $(CFLAGS) $< -o $@ $(LDFLAGS)
+tests/test_expert_store_ops$(EXE): tests/test_expert_store_ops.c expert_store.h tensor.h
+ $(CC) $(CFLAGS) $< -o $@ $(LDFLAGS)
+
+tests/test_safetensors_index$(EXE): tests/test_safetensors_index.c safetensors_index.c safetensors_index.h json.h
+ $(CC) $(CFLAGS) safetensors_index.c $< -o $@ $(LDFLAGS)
+
+tests/test_native_quant$(EXE): tests/test_native_quant.c native_quant.c native_quant.h tensor.h
+ $(CC) $(CFLAGS) native_quant.c $< -o $@ $(LDFLAGS)
+
+tests/test_tensor_io$(EXE): tests/test_tensor_io.c tensor_io.c tensor_io.h native_quant.c native_quant.h safetensors_index.c safetensors_index.h tensor.h json.h
+ $(CC) $(CFLAGS) safetensors_index.c native_quant.c tensor_io.c $< \
+ -o $@ $(LDFLAGS)
+
+ifeq ($(COLI_V4_SUPPORTED),1)
+include Makefile.deepseek-v4.units
+V4_TEST_LINK_OBJS = \
+ COLI_V4_UNIT_MATH.o \
+ COLI_V4_UNIT_SPARSE_ATTENTION.o \
+ COLI_V4_UNIT_RESOURCE_PLAN.o \
+ COLI_V4_UNIT_PROMPT.o \
+ $(addsuffix .o,$(V4_TEST_UNITS)) \
+ safetensors_index.o native_quant.o
+
+tests/test_deepseek_v4$(EXE): tests/test_deepseek_v4.c deepseek_v4.c deepseek_v4.h \
+ deepseek_v4_dspark.h Makefile.deepseek-v4.units
+ $(MAKE) -f Makefile.deepseek-v4 ARCH=$(ARCH) deepseek-v4-test-objs \
+ COLI_V4_UNIT_MATH.o COLI_V4_UNIT_SPARSE_ATTENTION.o \
+ COLI_V4_UNIT_RESOURCE_PLAN.o COLI_V4_UNIT_PROMPT.o \
+ safetensors_index.o
+ $(CC) $(CFLAGS) native_quant.c -c -o native_quant.o
+ $(CC) $(CFLAGS) $< $(V4_TEST_LINK_OBJS) -o $@ -pthread $(LDFLAGS)
+
+V4_OWN_DIR = build/ownership
+V4_OWN_CFLAGS = $(CFLAGS) -DCOLI_V4_TEST_HOOKS
+V4_OWNERSHIP_OBJS = \
+ $(V4_OWN_DIR)/COLI_V4_UNIT_RUNTIME.o \
+ $(V4_OWN_DIR)/COLI_V4_UNIT_CONFIG.o \
+ $(V4_OWN_DIR)/safetensors_index.o
+
+$(V4_OWN_DIR):
+ mkdir -p $(V4_OWN_DIR)
+
+$(V4_OWN_DIR)/COLI_V4_UNIT_RUNTIME.o: deepseek_v4.c deepseek_v4.h deepseek_v4_internal.h | $(V4_OWN_DIR)
+ $(CC) $(V4_OWN_CFLAGS) -DCOLI_V4_UNIT_RUNTIME -c deepseek_v4.c -o $@
+
+$(V4_OWN_DIR)/COLI_V4_UNIT_CONFIG.o: deepseek_v4.c deepseek_v4.h deepseek_v4_internal.h | $(V4_OWN_DIR)
+ $(CC) $(V4_OWN_CFLAGS) -DCOLI_V4_UNIT_CONFIG -c deepseek_v4.c -o $@
+
+$(V4_OWN_DIR)/safetensors_index.o: safetensors_index.c safetensors_index.h | $(V4_OWN_DIR)
+ $(CC) $(CFLAGS) -c safetensors_index.c -o $@
+
+tests/test_v4_ownership$(EXE): tests/test_v4_ownership.c $(V4_OWNERSHIP_OBJS)
+ $(CC) $(V4_OWN_CFLAGS) $< $(V4_OWNERSHIP_OBJS) -o $@ -pthread $(LDFLAGS)
+endif
+
tests/test_dsa_select$(EXE): tests/test_dsa_select.c colibri.c st.h uring.h json.h tok.h tok_unicode.h compat.h grammar.h tier.h quant.h sample.h kv_persist.h telemetry.h
$(CC) $(CFLAGS) $< -o $@ $(LDFLAGS)
@@ -458,6 +564,7 @@ test-python:
$(PYTHON) -m unittest discover -s tests -p 'test_*.py'
test: test-c test-python
+ $(MAKE) deepseek-v4-tiny-check
# --- Efficiency / regression suite (issue: "test the program for inefficiencies") ---
# The tiny-model assertions live in test_inefficiency.py and run as part of
@@ -507,4 +614,5 @@ clean:
bench: iobench$(EXE)
@if [ -n "$(ARGS)" ]; then ./iobench$(EXE) $(ARGS); else echo "built iobench$(EXE) — run: ./iobench$(EXE) <file> <MB> <iters> <threads> <direct 0|1>"; fi
-.PHONY: all colibri glm cuda-test hip-test gpu-compile cuda-bench cuda-dll portable test-c test-python test check clean install uninstall bench
+.PHONY: all colibri glm deepseek-v4 deepseek-v4-clean deepseek-v4-oracle deepseek-v4-tiny-check \
+ cuda-test hip-test gpu-compile cuda-bench cuda-dll portable test-c test-python test check clean install uninstall bench
diff --git a/c/compat.h b/c/compat.h
index 1b56f5fb..e473a4bc 100644
--- a/c/compat.h
+++ b/c/compat.h
@@ -95,6 +95,7 @@ static inline int compat_open_direct(const char *path){
* is defense-in-depth: if anyone adds a future CRT-based read path, O_BINARY
* prevents 0x0A bytes from being silently translated to \r\n. */
#define COMPAT_O_RDONLY (O_RDONLY | O_BINARY)
+#define COMPAT_O_BINARY O_BINARY
/* --- posix_fadvise: Windows has no direct equivalent. Semantics:
* WILLNEED -> warm the OS page cache so a later synchronous pread finds the
@@ -370,5 +371,8 @@ static inline char *compat_mkdtemp(char *tmpl){
#ifndef COMPAT_O_RDONLY
#define COMPAT_O_RDONLY O_RDONLY
#endif
+#ifndef COMPAT_O_BINARY
+#define COMPAT_O_BINARY 0
+#endif
#endif /* COMPAT_H */
diff --git a/c/tests/test_deepseek_v4.c b/c/tests/test_deepseek_v4.c
new file mode 100644
index 00000000..2a353b15
--- /dev/null
+++ b/c/tests/test_deepseek_v4.c
@@ -0,0 +1,730 @@
+/* Merged DeepSeek V4 unit tests (GLM-style single harness). */
+#include "../deepseek_v4_internal.h"
+#include "../deepseek_v4_dspark.h"
+#include "../compat.h"
+#include "../native_quant.h"
+
+#include <assert.h>
+#include <fcntl.h>
+#include <math.h>
+#include <stdint.h>
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+#include <unistd.h>
+
+/* ==== begin test_deepseek_v4_attention_cache.c ==== */
+/* umbrella headers */
+/* <math.h> */
+/* <stdio.h> */
+static int test_attention_cache(void) {
+ ColiDeepSeekV4AttentionCache *cache = NULL;
+ if (coli_v4_attention_cache_create(&cache, 4, 4, 2, 16) != 0) return 1;
+ float query[2] = {1, 0};
+ float sink[1] = {0};
+ float output[2];
+ for (int position = 0; position < 4; position++) {
+ float window[2] = {(float)position, 1.0f};
+ float compressed[2] = {1.5f, 1.0f};
+ if (coli_v4_attention_cache_step(cache, output, query, window,
+ position == 3 ? compressed : NULL,
+ sink, 1, position, 1.0f) != 0)
+ return 1;
+ }
+ if (!isfinite(output[0]) || !isfinite(output[1]) || output[0] <= 1.5f)
+ return 1;
+ if (coli_v4_attention_cache_step(cache, output, query,
+ (float[2]){4, 1}, (float[2]){2, 1},
+ sink, 1, 4, 1.0f) == 0)
+ return 1;
+ coli_v4_attention_cache_reset(cache);
+ coli_v4_attention_cache_destroy(cache);
+ puts("DeepSeek-V4 attention cache tests: ok");
+ return 0;
+}
+/* ==== end test_deepseek_v4_attention_cache.c ==== */
+
+static int test_dspark_position_window(void) {
+ enum { WINDOW = 8 };
+ int positions[WINDOW];
+ int valid = 0;
+ for (int slot = 0; slot < WINDOW; slot++) positions[slot] = -1;
+ const int sequence[] = {0, 1, 2, 3, 8, 11, 17, 17};
+ for (size_t item = 0; item < sizeof(sequence) / sizeof(sequence[0]); item++) {
+ int position = sequence[item];
+ int slot = coli_v4_dspark_position_window_put(
+ positions, WINDOW, &valid, position);
+ if (slot != position % WINDOW) return 1;
+ int occupied = 0;
+ int64_t minimum = (int64_t)position - WINDOW + 1;
+ for (int index = 0; index < WINDOW; index++) {
+ if (positions[index] < 0) continue;
+ if ((int64_t)positions[index] < minimum ||
+ positions[index] > position)
+ return 1;
+ occupied++;
+ }
+ if (valid != occupied) return 1;
+ }
+ if (valid != 2 || positions[1] != 17 || positions[3] != 11)
+ return 1;
+ if (coli_v4_dspark_position_window_put(NULL, WINDOW, &valid, 18) >= 0 ||
+ coli_v4_dspark_position_window_put(positions, 0, &valid, 18) >= 0 ||
+ coli_v4_dspark_position_window_put(positions, WINDOW, &valid, -1) >= 0)
+ return 1;
+ puts("DeepSeek-V4 DSpark position window tests: ok");
+ return 0;
+}
+
+/* ==== begin test_deepseek_v4_config.c ==== */
+/* umbrella headers */
+/* <stdio.h> */
+static int expect_config_rejected(const char *base, const char *needle,
+ const char *replacement, const char *label) {
+ const char *match = strstr(base, needle);
+ if (!match) {
+ fprintf(stderr, "%s: test replacement target not found\n", label);
+ return 1;
+ }
+ size_t prefix = (size_t)(match - base);
+ const char *suffix = match + strlen(needle);
+ size_t length = prefix + strlen(replacement) + strlen(suffix) + 1;
+ char *mutated = malloc(length);
+ if (!mutated) return 1;
+ memcpy(mutated, base, prefix);
+ strcpy(mutated + prefix, replacement);
+ strcpy(mutated + prefix + strlen(replacement), suffix);
+ ColiDeepSeekV4Config config;
+ char error[256] = {0};
+ int accepted =
+ coli_v4_config_parse(&config, mutated, error, sizeof(error)) == 0;
+ free(mutated);
+ if (accepted) {
+ fprintf(stderr, "%s: malformed config was accepted\n", label);
+ return 1;
+ }
+ return 0;
+}
+
+static int test_config(int argc, char **argv) {
+ static const char config_json[] =
+ "{\"model_type\":\"deepseek_v4\",\"expert_dtype\":\"fp4\","
+ "\"scoring_func\":\"sqrtsoftplus\",\"topk_method\":\"noaux_tc\","
+ "\"hidden_size\":128,\"num_hidden_layers\":3,"
+ "\"num_attention_heads\":4,\"head_dim\":32,\"q_lora_rank\":64,"
+ "\"qk_rope_head_dim\":8,\"o_groups\":2,\"o_lora_rank\":64,"
+ "\"sliding_window\":16,\"index_n_heads\":4,\"index_head_dim\":16,"
+ "\"index_topk\":8,\"n_routed_experts\":8,\"num_experts_per_tok\":2,"
+ "\"n_shared_experts\":1,\"moe_intermediate_size\":32,"
+ "\"num_hash_layers\":1,\"num_nextn_predict_layers\":1,"
+ "\"hc_mult\":4,\"hc_sinkhorn_iters\":5,\"vocab_size\":256,"
+ "\"max_position_embeddings\":4096,\"rms_norm_eps\":1e-6,"
+ "\"hc_eps\":1e-6,\"routed_scaling_factor\":1.5,\"swiglu_limit\":10,"
+ "\"rope_theta\":10000,\"compress_rope_theta\":40000,"
+ "\"compress_ratios\":[0,4,128,0],"
+ "\"rope_scaling\":{\"original_max_position_embeddings\":1024,"
+ "\"beta_fast\":32,\"beta_slow\":1,\"factor\":4},"
+ "\"quantization_config\":{\"fmt\":\"e4m3\",\"scale_fmt\":\"ue8m0\"}}";
+ ColiDeepSeekV4Config config;
+ char error[256];
+ if (coli_v4_config_parse(&config, config_json, error, sizeof(error)) != 0) {
+ fprintf(stderr, "%s\n", error);
+ return 1;
+ }
+ if (config.hidden_size != 128 || config.num_hidden_layers != 3 ||
+ config.n_routed_experts != 8 || config.num_experts_per_tok != 2 ||
+ config.compress_ratio_count != 4 || config.compress_ratios[1] != 4 ||
+ config.compress_ratios[2] != 128 || config.rope_factor != 4.0f)
+ return 1;
+ static const struct {
+ const char *label;
+ const char *needle;
+ const char *replacement;
+ } malformed_numbers[] = {
+ {"integer-nan", "\"hidden_size\":128", "\"hidden_size\":NaN"},
+ {"integer-infinity", "\"hidden_size\":128", "\"hidden_size\":1e309"},
+ {"integer-fraction", "\"hidden_size\":128", "\"hidden_size\":1.5"},
+ {"integer-overflow", "\"hidden_size\":128", "\"hidden_size\":2147483648"},
+ {"integer-underflow", "\"hidden_size\":128", "\"hidden_size\":-2147483649"},
+ {"float-nan", "\"rms_norm_eps\":1e-6", "\"rms_norm_eps\":NaN"},
+ {"float-infinity", "\"rms_norm_eps\":1e-6", "\"rms_norm_eps\":1e309"},
+ {"float-overflow", "\"rms_norm_eps\":1e-6", "\"rms_norm_eps\":1e39"},
+ {"ratio-nan", "\"compress_ratios\":[0,4,128,0]",
+ "\"compress_ratios\":[0,NaN,128,0]"},
+ {"ratio-fraction", "\"compress_ratios\":[0,4,128,0]",
+ "\"compress_ratios\":[0,1.5,128,0]"},
+ {"ratio-overflow", "\"compress_ratios\":[0,4,128,0]",
+ "\"compress_ratios\":[0,2147483648,128,0]"},
+ };
+ for (size_t i = 0;
+ i < sizeof(malformed_numbers) / sizeof(malformed_numbers[0]); i++)
+ if (expect_config_rejected(
+ config_json, malformed_numbers[i].needle,
+ malformed_numbers[i].replacement,
+ malformed_numbers[i].label))
+ return 1;
+ if (argc > 1) {
+ if (coli_v4_config_load(&config, argv[1], error, sizeof(error)) != 0) {
+ fprintf(stderr, "%s\n", error);
+ return 1;
+ }
+ if (config.hidden_size != 4096 || config.num_hidden_layers != 43 ||
+ config.n_routed_experts != 256 || config.num_experts_per_tok != 6 ||
+ config.compress_ratio_count != 44 || config.compress_ratios[2] != 4 ||
+ config.compress_ratios[3] != 128 || config.hc_mult != 4)
+ return 1;
+ }
+ puts("DeepSeek-V4 config tests: ok");
+ return 0;
+}
+/* ==== end test_deepseek_v4_config.c ==== */
+
+/* ==== begin test_deepseek_v4_expert.c ==== */
+/* umbrella headers */
+/* shared */
+/* <math.h> */
+/* <stdint.h> */
+/* <stdio.h> */
+/* <string.h> */
+static void make_tensor(ColiTensorView *view, uint8_t *data, uint8_t *scales,
+ int rows, int columns, uint8_t code) {
+ memset(data, (int)(code | (code << 4)), (size_t)rows * columns / 2);
+ memset(scales, 0x7f, (size_t)rows * columns / 32);
+ *view = (ColiTensorView){
+ COLI_TENSOR_FP4_NATIVE_BLOCK, COLI_SCALE_UE8M0,
+ data, scales, (size_t)rows * columns / 2,
+ (size_t)rows * columns / 32, rows, columns, 1, 32
+ };
+}
+
+static int test_expert(void) {
+ enum { DIMENSION = 128, INTERMEDIATE = 128 };
+ uint8_t gate_data[INTERMEDIATE * DIMENSION / 2];
+ uint8_t up_data[INTERMEDIATE * DIMENSION / 2];
+ uint8_t down_data[DIMENSION * INTERMEDIATE / 2];
+ uint8_t gate_scale[INTERMEDIATE * DIMENSION / 32];
+ uint8_t up_scale[INTERMEDIATE * DIMENSION / 32];
+ uint8_t down_scale[DIMENSION * INTERMEDIATE / 32];
+ ColiExpertView expert = {0};
+ make_tensor(&expert.gate, gate_data, gate_scale,
+ INTERMEDIATE, DIMENSION, 1); /* +0.5 */
+ make_tensor(&expert.up, up_data, up_scale,
+ INTERMEDIATE, DIMENSION, 1);
+ make_tensor(&expert.down, down_data, down_scale,
+ DIMENSION, INTERMEDIATE, 1);
+ float input[DIMENSION], output[DIMENSION];
+ for (int index = 0; index < DIMENSION; index++) input[index] = 0.01f;
+ if (coli_v4_expert_forward_ref(output, &expert, input, 0.75f, 10.0f) != 0)
+ return 1;
+ for (int index = 0; index < DIMENSION; index++)
+ if (!isfinite(output[index]) || output[index] != output[0]) return 1;
+ if (!(output[0] > 0.0f)) return 1;
+ puts("DeepSeek-V4 expert tests: ok");
+ return 0;
+}
+/* ==== end test_deepseek_v4_expert.c ==== */
+
+/* ==== begin test_deepseek_v4_expert_store.c ==== */
+/* _GNU_SOURCE */
+/* umbrella headers */
+/* shared */
+/* <fcntl.h> */
+/* <stdint.h> */
+/* <stdio.h> */
+/* <stdlib.h> */
+/* <string.h> */
+/* <unistd.h> */
+static int write_all(int fd, const void *data, size_t length) {
+ const unsigned char *bytes = data;
+ while (length) {
+ ssize_t count = write(fd, bytes, length);
+ if (count <= 0) return -1;
+ bytes += count;
+ length -= (size_t)count;
+ }
+ return 0;
+}
+
+static int write_fixture(const char *path) {
+ static const char header[] =
+ "{"
+ "\"layers.0.ffn.experts.0.w1.scale\":{\"dtype\":\"F8_E8M0\",\"shape\":[1,1],\"data_offsets\":[0,1]},"
+ "\"layers.0.ffn.experts.0.w2.scale\":{\"dtype\":\"F8_E8M0\",\"shape\":[1,1],\"data_offsets\":[1,2]},"
+ "\"layers.0.ffn.experts.0.w3.scale\":{\"dtype\":\"F8_E8M0\",\"shape\":[1,1],\"data_offsets\":[2,3]},"
+ "\"resident\":{\"dtype\":\"F32\",\"shape\":[1],\"data_offsets\":[3,7]},"
+ "\"layers.0.ffn.experts.0.w1.weight\":{\"dtype\":\"I8\",\"shape\":[1,16],\"data_offsets\":[7,23]},"
+ "\"layers.0.ffn.experts.0.w2.weight\":{\"dtype\":\"I8\",\"shape\":[1,16],\"data_offsets\":[23,39]},"
+ "\"layers.0.ffn.experts.0.w3.weight\":{\"dtype\":\"I8\",\"shape\":[1,16],\"data_offsets\":[39,55]}"
+ "}";
+ unsigned char payload[55];
+ for (int i = 0; i < 55; i++) payload[i] = (unsigned char)i;
+ uint64_t header_length = sizeof(header) - 1;
+ int fd = open(path, O_CREAT | O_TRUNC | O_WRONLY | COMPAT_O_BINARY, 0600);
+ if (fd < 0) return -1;
+ int result = write_all(fd, &header_length, sizeof(header_length)) ||
+ write_all(fd, header, (size_t)header_length) ||
+ write_all(fd, payload, sizeof(payload));
+ close(fd);
+ return result ? -1 : 0;
+}
+
+static int test_expert_store(void) {
+ /* Native MinGW binaries do not resolve the MSYS /tmp mount. */
+ char directory[] = "colibri-v4-store-XXXXXX";
+ char path[256], error[256];
+ if (!mkdtemp(directory)) { perror("mkdtemp"); return 1; }
+ snprintf(path, sizeof(path), "%s/model.safetensors", directory);
+ if (write_fixture(path) != 0) { perror("write_fixture"); return 1; }
+
+ ColiDeepSeekV4ExpertStoreOptions options = {
+ directory, 1, 1, 51, -1, 0
+ };
+ ColiExpertStore *store = NULL;
+ if (coli_deepseek_v4_expert_store_open(&options, &store,
+ error, sizeof(error)) != 0) {
+ fprintf(stderr, "%s\n", error);
+ return 1;
+ }
+ ColiExpertKey key = {0, 0};
+ ColiExpertView view;
+ if (store->ops->prefetch(store, &key, 1) != 1) {
+ fprintf(stderr, "prefetch failed\n"); return 1;
+ }
+ if (coli_expert_lookup(store, key, &view) != 0) {
+ fprintf(stderr, "lookup failed\n"); return 1;
+ }
+ if (view.gate.format != COLI_TENSOR_FP4_NATIVE_BLOCK ||
+ view.gate.rows != 1 || view.gate.columns != 32 ||
+ view.gate.data_bytes != 16 || view.gate.scale_bytes != 1 ||
+ ((const unsigned char *)view.gate.scales)[0] != 0 ||
+ ((const unsigned char *)view.gate.data)[0] != 7 ||
+ ((const unsigned char *)view.down.data)[0] != 23 ||
+ ((const unsigned char *)view.up.data)[0] != 39)
+ { fprintf(stderr, "expert view mismatch: format=%d rows=%lld columns=%lld data=%zu scales=%zu bytes=%u/%u/%u/%u\n",
+ (int)view.gate.format, (long long)view.gate.rows,
+ (long long)view.gate.columns, view.gate.data_bytes,
+ view.gate.scale_bytes,
+ ((const unsigned char *)view.gate.scales)[0],
+ ((const unsigned char *)view.gate.data)[0],
+ ((const unsigned char *)view.down.data)[0],
+ ((const unsigned char *)view.up.data)[0]); return 1; }
+ coli_expert_release(store, &view);
+ {
+ static const ColiExpertView zero;
+ if (memcmp(&view, &zero, sizeof(view)) != 0) {
+ fprintf(stderr, "release did not clear view\n");
+ return 1;
+ }
+ }
+ /* Double release of a cleared view is a no-op. */
+ coli_expert_release(store, &view);
+ if (coli_expert_lookup(store, key, &view) != 0) return 1;
+ coli_expert_release(store, &view);
+ /* Invalid key lookup must fail and clear the view. */
+ memset(&view, 0x3c, sizeof(view));
+ if (coli_expert_lookup(store, (ColiExpertKey){9, 9}, &view) == 0) return 1;
+ {
+ static const ColiExpertView zero;
+ if (memcmp(&view, &zero, sizeof(view)) != 0) {
+ fprintf(stderr, "failed lookup did not clear view\n");
+ return 1;
+ }
+ }
+ ColiExpertStoreStats stats;
+ store->ops->stats(store, &stats);
+ if (stats.requests != 2 || stats.hits != 1 || stats.misses != 1 ||
+ stats.prefetched != 1 || stats.bytes_read != 51 ||
+ stats.resident_bytes != 51 || stats.capacity_bytes != 51)
+ { fprintf(stderr, "expert stats mismatch: requests=%llu hits=%llu misses=%llu prefetched=%llu bytes=%llu resident=%llu capacity=%llu\n",
+ (unsigned long long)stats.requests,
+ (unsigned long long)stats.hits,
+ (unsigned long long)stats.misses,
+ (unsigned long long)stats.prefetched,
+ (unsigned long long)stats.bytes_read,
+ (unsigned long long)stats.resident_bytes,
+ (unsigned long long)stats.capacity_bytes); return 1; }
+ store->ops->destroy(store);
+ unlink(path);
+ rmdir(directory);
+ puts("DeepSeek-V4 ExpertStore tests: ok");
+ return 0;
+}
+/* ==== end test_deepseek_v4_expert_store.c ==== */
+
+/* ==== begin test_deepseek_v4_kv_cache.c ==== */
+/* umbrella headers */
+/* <stdio.h> */
+static int test_kv_cache(void) {
+ ColiDeepSeekV4KVCache *cache = NULL;
+ if (coli_v4_kv_cache_create(&cache, 4, 4, 2, 16) != 0) return 1;
+ float value[2];
+ for (int position = 0; position < 6; position++) {
+ value[0] = (float)position;
+ value[1] = (float)-position;
+ if (coli_v4_kv_cache_put_window(cache, position, value) < 0) return 1;
+ if ((position + 1) % 4 == 0 &&
+ coli_v4_kv_cache_put_compressed(cache, position, value) < 4)
+ return 1;
+ }
+ int indices[8];
+ int count = coli_v4_kv_cache_indices(cache, 1, indices, 8);
+ if (count != 4 || indices[0] != 0 || indices[1] != 1 ||
+ indices[2] != -1 || indices[3] != -1) return 1;
+ count = coli_v4_kv_cache_indices(cache, 3, indices, 8);
+ if (count != 5 || indices[0] != 0 || indices[3] != 3 || indices[4] != 4)
+ return 1;
+ count = coli_v4_kv_cache_indices(cache, 5, indices, 8);
+ if (count != 5 || indices[0] != 2 || indices[1] != 3 ||
+ indices[2] != 0 || indices[3] != 1 || indices[4] != 4)
+ return 1;
+ const float *values = coli_v4_kv_cache_values(cache);
+ if (values[0] != 4.0f || values[2] != 5.0f || values[8] != 3.0f)
+ return 1;
+ coli_v4_kv_cache_reset(cache);
+ if (coli_v4_kv_cache_values(cache)[0] != 0.0f) return 1;
+ coli_v4_kv_cache_destroy(cache);
+ puts("DeepSeek-V4 KV cache tests: ok");
+ return 0;
+}
+/* ==== end test_deepseek_v4_kv_cache.c ==== */
+
+/* ==== begin test_deepseek_v4_layer.c ==== */
+/* <assert.h> */
+/* <stdio.h> */
+/* <string.h> */
+/* umbrella headers */
+static const ColiDeepSeekV4TensorSpec *find_spec(
+ const ColiDeepSeekV4LayerPlan *plan, const char *suffix) {
+ for (size_t i = 0; i < plan->tensor_count; i++)
+ if (strstr(plan->tensors[i].name, suffix)) return &plan->tensors[i];
+ return NULL;
+}
+
+static int test_layer(void) {
+ ColiDeepSeekV4Config config = {0};
+ config.hidden_size = 4096;
+ config.num_hidden_layers = 43;
+ config.num_attention_heads = 64;
+ config.head_dim = 512;
+ config.q_lora_rank = 1024;
+ config.o_groups = 8;
+ config.o_lora_rank = 1024;
+ config.index_n_heads = 64;
+ config.index_head_dim = 128;
+ config.n_routed_experts = 256;
+ config.num_experts_per_tok = 6;
+ config.n_shared_experts = 1;
+ config.moe_intermediate_size = 2048;
+ config.num_hash_layers = 3;
+ config.hc_mult = 4;
+ config.vocab_size = 129280;
+ config.compress_ratio_count = 43;
+ config.compress_ratios[2] = 4;
+ config.compress_ratios[3] = 128;
+
+ char error[256];
+ ColiDeepSeekV4LayerPlan plan;
+ assert(coli_v4_layer_plan(&plan, &config, 0, error, sizeof(error)) == 0);
+ assert(plan.uses_hash_router && !plan.has_compressor && !plan.has_indexer);
+ assert(plan.tensor_count == 29);
+ const ColiDeepSeekV4TensorSpec *hash = find_spec(&plan, "tid2eid");
+ assert(hash && hash->dtype == COLI_ST_I64);
+ assert(hash->shape[0] == 129280 && hash->shape[1] == 6);
+
+ assert(coli_v4_layer_plan(&plan, &config, 2, error, sizeof(error)) == 0);
+ assert(plan.uses_hash_router && plan.has_compressor && plan.has_indexer);
+ assert(plan.tensor_count == 40);
+ const ColiDeepSeekV4TensorSpec *index_q = find_spec(&plan, "indexer.wq_b.weight");
+ assert(index_q && index_q->shape[0] == 8192 && index_q->shape[1] == 1024);
+ const ColiDeepSeekV4TensorSpec *ape = find_spec(&plan, "attn.compressor.ape");
+ assert(ape && ape->shape[0] == 4 && ape->shape[1] == 1024);
+
+ assert(coli_v4_layer_plan(&plan, &config, 3, error, sizeof(error)) == 0);
+ assert(!plan.uses_hash_router && plan.has_compressor && !plan.has_indexer);
+ assert(plan.tensor_count == 33);
+ ape = find_spec(&plan, "attn.compressor.ape");
+ assert(ape && ape->shape[0] == 128 && ape->shape[1] == 512);
+ assert(find_spec(&plan, "ffn.gate.bias") != NULL);
+
+ puts("deepseek_v4_layer tests passed");
+ return 0;
+}
+/* ==== end test_deepseek_v4_layer.c ==== */
+
+/* ==== begin test_deepseek_v4_math.c ==== */
+/* umbrella headers */
+/* <math.h> */
+/* <stdio.h> */
+/* <string.h> */
+static int close_enough(float left, float right, float tolerance) {
+ return fabsf(left - right) <= tolerance;
+}
+
+static int test_math(void) {
+ enum { HC = 4, DIMENSION = 3, MIXES = (2 + HC) * HC };
+ float input[HC * DIMENSION] = {
+ 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12
+ };
+ float function[MIXES * HC * DIMENSION];
+ float base[MIXES];
+ float scale[3] = {1, 1, 1};
+ float reduced[DIMENSION], post[HC], comb[HC * HC];
+ memset(function, 0, sizeof(function));
+ memset(base, 0, sizeof(base));
+ if (coli_v4_hc_pre(reduced, post, comb, input, function,
+ scale, base, HC, DIMENSION, 20, 1e-6f, 1e-6f) != 0)
+ return 1;
+ for (int column = 0; column < DIMENSION; column++) {
+ float expected = 0.500001f * (input[column] + input[DIMENSION + column] +
+ input[2 * DIMENSION + column] +
+ input[3 * DIMENSION + column]);
+ if (!close_enough(reduced[column], expected, 2e-5f)) return 1;
+ }
+ for (int index = 0; index < HC; index++)
+ if (!close_enough(post[index], 1.0f, 1e-6f)) return 1;
+ for (int row = 0; row < HC; row++) {
+ float row_sum = 0.0f, column_sum = 0.0f;
+ for (int column = 0; column < HC; column++) {
+ row_sum += comb[row * HC + column];
+ column_sum += comb[column * HC + row];
+ }
+ if (!close_enough(row_sum, 1.0f, 1e-5f) ||
+ !close_enough(column_sum, 1.0f, 1e-5f)) return 1;
+ }
+ float branch[DIMENSION] = {0.25f, -0.5f, 0.75f};
+ float expanded[HC * DIMENSION];
+ if (coli_v4_hc_post(expanded, branch, input, post, comb,
+ HC, DIMENSION) != 0) return 1;
+ for (int copy = 0; copy < HC; copy++)
+ for (int column = 0; column < DIMENSION; column++) {
+ float average = (input[column] + input[DIMENSION + column] +
+ input[2 * DIMENSION + column] +
+ input[3 * DIMENSION + column]) / 4.0f;
+ if (!close_enough(expanded[copy * DIMENSION + column],
+ branch[column] + average, 2e-5f)) return 1;
+ }
+
+ float norm_weight[DIMENSION] = {1.0f, 1.5f, 0.5f};
+ float normalized[DIMENSION];
+ if (coli_v4_rmsnorm(normalized, branch, norm_weight,
+ DIMENSION, 1e-6f) != 0) return 1;
+ float inverse_rms = 1.0f / sqrtf(
+ (branch[0] * branch[0] + branch[1] * branch[1] +
+ branch[2] * branch[2]) / DIMENSION + 1e-6f);
+ for (int index = 0; index < DIMENSION; index++)
+ if (!close_enough(normalized[index],
+ branch[index] * inverse_rms * norm_weight[index],
+ 1e-6f)) return 1;
+
+ float rope_cos[12], rope_sin[12];
+ float rope_values[8] = {1, 2, 3, 4, -1, 0.5f, 2, -3};
+ float rope_original[8];
+ memcpy(rope_original, rope_values, sizeof(rope_values));
+ if (coli_v4_rope_precompute(rope_cos, rope_sin, 4, 6, 4,
+ 10000.0f, 2.0f, 32, 1) != 0 ||
+ coli_v4_rope_apply(rope_values, 2, 4,
+ rope_cos + 2, rope_sin + 2, 0) != 0 ||
+ coli_v4_rope_apply(rope_values, 2, 4,
+ rope_cos + 2, rope_sin + 2, 1) != 0)
+ return 1;
+ for (int index = 0; index < 8; index++)
+ if (!close_enough(rope_values[index], rope_original[index], 1e-5f)) return 1;
+ if (coli_v4_rope_precompute(rope_cos, rope_sin, 3, 6, 0,
+ 10000.0f, 1.0f, 32, 1) == 0)
+ return 1;
+
+ float hidden[2] = {0.5f, -1.0f};
+ float router[8] = {1, 0, 0, 1, -1, 0, 0, -1};
+ float bias[4] = {10.0f, 0.0f, 9.0f, 0.0f};
+ float route_weights[2];
+ int route_indices[2];
+ if (coli_v4_route(route_weights, route_indices, hidden, router, bias,
+ NULL, 4, 2, 2, 1.5f) != 0) return 1;
+ if (route_indices[0] != 0 || route_indices[1] != 2 ||
+ !close_enough(route_weights[0] + route_weights[1], 1.5f, 1e-6f))
+ return 1;
+ int forced[2] = {3, 1};
+ if (coli_v4_route(route_weights, route_indices, hidden, router, NULL,
+ forced, 4, 2, 2, 1.5f) != 0 ||
+ route_indices[0] != 3 || route_indices[1] != 1) return 1;
+
+ float gates[3] = {-20.0f, 2.0f, 20.0f};
+ float ups[3] = {-20.0f, 3.0f, 20.0f};
+ float activated[3];
+ if (coli_v4_swiglu(activated, gates, ups, 3, 10.0f) != 0) return 1;
+ if (!close_enough(activated[0],
+ -20.0f / (1.0f + expf(20.0f)) * -10.0f, 1e-6f) ||
+ !close_enough(activated[1],
+ 2.0f / (1.0f + expf(-2.0f)) * 3.0f, 1e-6f) ||
+ !close_enough(activated[2],
+ 10.0f / (1.0f + expf(-10.0f)) * 10.0f, 1e-5f))
+ return 1;
+ puts("DeepSeek-V4 math tests: ok");
+ return 0;
+}
+/* ==== end test_deepseek_v4_math.c ==== */
+
+/* ==== begin test_deepseek_v4_prompt.c ==== */
+/* umbrella headers */
+/* <stdio.h> */
+/* <stdlib.h> */
+/* <string.h> */
+static int expect(const char *user, const char *system,
+ ColiDeepSeekV4PromptMode mode, const char *expected) {
+ char *actual = NULL;
+ size_t length = 0;
+ int result = coli_v4_prompt_build(
+ &actual, &length, user, system, mode);
+ int failed = result || !actual || strcmp(actual, expected) ||
+ length != strlen(expected);
+ free(actual);
+ return failed;
+}
+
+static int test_prompt(void) {
+ if (expect("Hello", NULL, COLI_V4_PROMPT_CHAT,
+ "<|begin▁of▁sentence|><|User|>Hello"
+ "<|Assistant|></think>") ||
+ expect("Hello", "Be concise.", COLI_V4_PROMPT_THINKING,
+ "<|begin▁of▁sentence|>Be concise.<|User|>Hello"
+ "<|Assistant|><think>") ||
+ expect("raw", "ignored", COLI_V4_PROMPT_RAW, "raw"))
+ return 1;
+ puts("DeepSeek V4 prompt tests: ok");
+ return 0;
+}
+/* ==== end test_deepseek_v4_prompt.c ==== */
+
+/* ==== begin test_deepseek_v4_resource_plan.c ==== */
+/* umbrella headers */
+/* <stdint.h> */
+/* <stdio.h> */
+#define MIB UINT64_C(1048576)
+#define GIB UINT64_C(1073741824)
+
+static ColiDeepSeekV4ResourceInputs fixture(uint64_t available) {
+ ColiDeepSeekV4ResourceInputs input = {
+ available, 0, 160 * MIB, 600 * MIB, 13369344,
+ 43, 6, 256,
+ };
+ return input;
+}
+
+static int test_resource_plan(void) {
+ char error[256];
+ ColiDeepSeekV4ResourcePlan low, high, capped, auto_24, capped_24;
+ ColiDeepSeekV4ResourceInputs input = fixture(8 * GIB);
+ if (coli_v4_resource_plan_compute(&low, &input, error, sizeof(error)) ||
+ low.slots_per_layer < 6 || low.projected_bytes > 8 * GIB)
+ return 1;
+ input = fixture(64 * GIB);
+ if (coli_v4_resource_plan_compute(&high, &input, error, sizeof(error)) ||
+ high.slots_per_layer <= low.slots_per_layer ||
+ high.projected_bytes > 64 * GIB)
+ return 1;
+ input = fixture(64 * GIB);
+ input.user_limit_bytes = 8 * GIB;
+ if (coli_v4_resource_plan_compute(&capped, &input, error, sizeof(error)) ||
+ capped.planner_available_bytes != 8 * GIB ||
+ capped.system_reserve_bytes != 0 ||
+ capped.slots_per_layer < low.slots_per_layer ||
+ capped.projected_bytes > 8 * GIB)
+ return 1;
+ input = fixture(24 * GIB);
+ if (coli_v4_resource_plan_compute(&auto_24, &input, error, sizeof(error)))
+ return 1;
+ input = fixture(64 * GIB);
+ input.user_limit_bytes = 24 * GIB;
+ if (coli_v4_resource_plan_compute(
+ &capped_24, &input, error, sizeof(error)) ||
+ capped_24.system_reserve_bytes != 0 ||
+ capped_24.slots_per_layer <= auto_24.slots_per_layer ||
+ capped_24.projected_bytes > 24 * GIB)
+ return 1;
+ input = fixture(4 * GIB);
+ if (coli_v4_resource_plan_compute(&capped, &input, error, sizeof(error)) == 0)
+ return 1;
+ puts("DeepSeek V4 resource plan tests: ok");
+ return 0;
+}
+/* ==== end test_deepseek_v4_resource_plan.c ==== */
+
+/* ==== begin test_deepseek_v4_sparse_attention.c ==== */
+/* umbrella headers */
+/* shared */
+/* <math.h> */
+/* <stdio.h> */
+static int close_enough_sparse(float left, float right) {
+ return fabsf(left - right) <= 1e-6f;
+}
+
+static int test_sparse_attention(void) {
+ float query[2] = {1, 0};
+ float kv[6] = {1, 0, 0, 1, 1, 1};
+ float sink[1] = {0};
+ int indices[3] = {0, 2, -1};
+ float output[2];
+ if (coli_v4_sparse_attention_ref(output, query, kv, sink, indices,
+ 1, 2, 3, 3, 1.0f) != 0)
+ return 1;
+ float denominator = 2.0f + expf(-1.0f);
+ if (!close_enough_sparse(output[0], coli_bf16_round(2.0f / denominator)) ||
+ !close_enough_sparse(output[1], coli_bf16_round(1.0f / denominator)))
+ return 1;
+ int invalid[1] = {3};
+ if (coli_v4_sparse_attention_ref(output, query, kv, sink, invalid,
+ 1, 2, 3, 1, 1.0f) == 0)
+ return 1;
+ puts("DeepSeek-V4 sparse attention tests: ok");
+ return 0;
+}
+/* ==== end test_deepseek_v4_sparse_attention.c ==== */
+
+int main(int argc, char **argv) {
+ if (test_attention_cache() != 0) {
+ fprintf(stderr, "FAIL: test_attention_cache\n");
+ return 1;
+ }
+ if (test_dspark_position_window() != 0) {
+ fprintf(stderr, "FAIL: test_dspark_position_window\n");
+ return 1;
+ }
+ if (test_config(argc, argv) != 0) {
+ fprintf(stderr, "FAIL: test_config\n");
+ return 1;
+ }
+ if (test_expert() != 0) {
+ fprintf(stderr, "FAIL: test_expert\n");
+ return 1;
+ }
+ if (test_expert_store() != 0) {
+ fprintf(stderr, "FAIL: test_expert_store\n");
+ return 1;
+ }
+ if (test_kv_cache() != 0) {
+ fprintf(stderr, "FAIL: test_kv_cache\n");
+ return 1;
+ }
+ if (test_layer() != 0) {
+ fprintf(stderr, "FAIL: test_layer\n");
+ return 1;
+ }
+ if (test_math() != 0) {
+ fprintf(stderr, "FAIL: test_math\n");
+ return 1;
+ }
+ if (test_prompt() != 0) {
+ fprintf(stderr, "FAIL: test_prompt\n");
+ return 1;
+ }
+ if (test_resource_plan() != 0) {
+ fprintf(stderr, "FAIL: test_resource_plan\n");
+ return 1;
+ }
+ if (test_sparse_attention() != 0) {
+ fprintf(stderr, "FAIL: test_sparse_attention\n");
+ return 1;
+ }
+ puts("DeepSeek-V4 tests: ok");
+ return 0;
+}
diff --git a/c/tests/test_make_deepseek_v4_oracle.py b/c/tests/test_make_deepseek_v4_oracle.py
new file mode 100644
index 00000000..64ee5552
--- /dev/null
+++ b/c/tests/test_make_deepseek_v4_oracle.py
@@ -0,0 +1,59 @@
+import importlib.util
+import json
+import tempfile
+import types
+import unittest
+from pathlib import Path
+from unittest import mock
+
+
+SCRIPT = Path(__file__).parents[1] / "tools" / "make_deepseek_v4_oracle.py"
+SPEC = importlib.util.spec_from_file_location("make_deepseek_v4_oracle", SCRIPT)
+ORACLE = importlib.util.module_from_spec(SPEC)
+assert SPEC.loader is not None
+SPEC.loader.exec_module(ORACLE)
+
+
+class DSparkIdentityTests(unittest.TestCase):
+ def run_validation(self, generated: list[list[int]]) -> int:
+ with tempfile.TemporaryDirectory() as directory:
+ oracle_path = Path(directory) / "oracle.json"
+ oracle_path.write_text(
+ json.dumps({"prompt_ids": [1], "full_ids": [1, 2, 3]}),
+ encoding="utf-8",
+ )
+ outputs = list(generated)
+
+ def fake_run(binary, args, env=None):
+ if "--record-oracle" in args:
+ output = Path(args[args.index("--record-oracle") + 1])
+ tokens = outputs.pop(0)
+ output.write_text(
+ json.dumps({
+ "prompt_ids": [1],
+ "full_ids": [1, *tokens],
+ }),
+ encoding="utf-8",
+ )
+ return types.SimpleNamespace(returncode=0)
+
+ with mock.patch.object(ORACLE, "run_c", side_effect=fake_run):
+ return ORACLE.validate(
+ Path("deepseek_v4"),
+ "/model",
+ oracle_path,
+ teacher_forcing=2,
+ greedy=2,
+ memory_gb=None,
+ check_dspark=True,
+ )
+
+ def test_empty_outputs_do_not_pass_identity(self):
+ self.assertNotEqual(self.run_validation([[], []]), 0)
+
+ def test_exact_full_length_outputs_pass_identity(self):
+ self.assertEqual(self.run_validation([[2, 3], [2, 3]]), 0)
+
+
+if __name__ == "__main__":
+ unittest.main()
diff --git a/c/tests/test_v4_cli.py b/c/tests/test_v4_cli.py
new file mode 100644
index 00000000..16d9eb8f
--- /dev/null
+++ b/c/tests/test_v4_cli.py
@@ -0,0 +1,99 @@
+import importlib.machinery
+import importlib.util
+import argparse
+import subprocess
+import sys
+import tempfile
+import unittest
+from pathlib import Path
+
+
+HERE = Path(__file__).resolve().parent.parent
+CLI = HERE / "v4"
+
+
+def load_cli():
+ loader = importlib.machinery.SourceFileLoader("v4_cli", str(CLI))
+ spec = importlib.util.spec_from_loader(loader.name, loader)
+ module = importlib.util.module_from_spec(spec)
+ loader.exec_module(module)
+ return module
+
+
+class V4CliTest(unittest.TestCase):
+ def run_cli(self, *args):
+ return subprocess.run(
+ [sys.executable, str(CLI), *args],
+ cwd=HERE,
+ text=True,
+ capture_output=True,
+ check=False,
+ timeout=10,
+ )
+
+ def test_chat_help_uses_explicit_model_and_ram(self):
+ result = self.run_cli("chat", "--help")
+ self.assertEqual(result.returncode, 0, result.stderr)
+ self.assertIn("--model", result.stdout)
+ self.assertIn("--ram", result.stdout)
+
+ def test_model_is_required(self):
+ result = self.run_cli("chat", "--ram", "24")
+ self.assertNotEqual(result.returncode, 0)
+ self.assertIn("--model", result.stderr)
+
+ def test_missing_model_is_reported_before_engine(self):
+ with tempfile.TemporaryDirectory() as directory:
+ missing = str(Path(directory) / "missing")
+ result = self.run_cli("chat", "--model", missing, "--ram", "24")
+ self.assertNotEqual(result.returncode, 0)
+ self.assertIn("model not found", result.stderr)
+
+ def test_multi_turn_prompt_format(self):
+ cli = load_cli()
+ history = cli.new_history("Be concise.")
+ prompt = cli.turn_prompt(history, "Hello", False)
+ self.assertEqual(
+ prompt,
+ cli.BOS + "Be concise." + cli.USER + "Hello" + cli.ASSISTANT + "</think>",
+ )
+ history = cli.completed_history(prompt, "Hi!")
+ next_prompt = cli.turn_prompt(history, "Again", True)
+ self.assertEqual(
+ next_prompt,
+ prompt + "Hi!" + cli.EOS + cli.USER + "Again" + cli.ASSISTANT + "<think>",
+ )
+
+ def test_compact_stats_uses_wall_ttft_and_ram_plan(self):
+ cli = load_cli()
+ log = (
+ "ram_tiers available=24.00GiB dense=resident projected=23.95GiB\n"
+ "prefill_timing startup=2.0s wall_to_first=15.500s "
+ "target_tok_s=2.0 combined_tok_s=1.250000\n"
+ "decode_timing tokens=4 seconds=4.0 tok_s=1.000000\n"
+ "summary dspark_rounds=1 proposed=4 accepted=2 rate=0.500 enabled=1\n"
+ )
+ self.assertEqual(
+ cli.compact_stats(log),
+ "RAM 23.95/24.00 GiB | TTFT 15.50s | prefill 1.250 tok/s | "
+ "decode 1.000 tok/s | DSpark acceptance 50.0%",
+ )
+
+ def test_engine_command_prefers_prompt_file(self):
+ cli = load_cli()
+ args = argparse.Namespace(model=str(HERE), ngen=32, ram=0, stop_sentence=False)
+ command = cli.engine_command(args, raw=True, prompt_file=r"C:\tmp\prompt.txt")
+ self.assertIn("--prompt-file", command)
+ self.assertIn(r"C:\tmp\prompt.txt", command)
+ self.assertNotIn("你好", command)
+
+ def test_write_prompt_file_is_utf8(self):
+ cli = load_cli()
+ path = cli.write_prompt_file("你好")
+ try:
+ self.assertEqual(Path(path).read_text(encoding="utf-8"), "你好")
+ finally:
+ Path(path).unlink(missing_ok=True)
+
+if __name__ == "__main__":
+ unittest.main()
diff --git a/c/tests/test_v4_ownership.c b/c/tests/test_v4_ownership.c
new file mode 100644
index 00000000..3695ad2c
--- /dev/null
+++ b/c/tests/test_v4_ownership.c
@@ -0,0 +1,361 @@
+/* Ownership / lifecycle regression tests for DeepSeek V4 engine + session.
+ * Built with -DCOLI_V4_TEST_HOOKS against objects under build/ownership/. */
+#include "../deepseek_v4_internal.h"
+#include "../compat.h"
+
+#include <fcntl.h>
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+#include <unistd.h>
+
+int coli_v4_test_runner_close_count = 0;
+
+/* Stubs for symbols referenced by RUNTIME but unused in these tests. */
+int coli_v4_expert_store_open_planned(
+ ColiV4Engine *engine,
+ const ColiDeepSeekV4ExpertStoreOptions *options,
+ ColiExpertStore **store,
+ char *error,
+ size_t error_size) {
+ (void)engine;
+ (void)options;
+ (void)store;
+ if (error && error_size)
+ snprintf(error, error_size, "expert store stub");
+ return -1;
+}
+
+void coli_v4_layer_resident_reference_free(
+ ColiV4Engine *engine, ColiDeepSeekV4LayerWeights *weights) {
+ (void)engine;
+ (void)weights;
+}
+
+void coli_v4_dspark_heads_close(ColiV4DSparkHeads *heads) {
+ (void)heads;
+}
+
+/* Ownership tests use blank runners; count closes through the real helper path. */
+void coli_v4_dspark_runner_close(ColiV4DSparkRunner *runner) {
+ if (!runner) return;
+ coli_v4_test_runner_close_count++;
+ free(runner);
+}
+
+static int write_all(int fd, const void *data, size_t length) {
+ const unsigned char *bytes = (const unsigned char *)data;
+ while (length) {
+ ssize_t count = write(fd, bytes, length);
+ if (count <= 0) return -1;
+ bytes += count;
+ length -= (size_t)count;
+ }
+ return 0;
+}
+
+static int write_config(const char *directory) {
+ static const char json[] =
+ "{\"model_type\":\"deepseek_v4\",\"expert_dtype\":\"fp4\","
+ "\"scoring_func\":\"sqrtsoftplus\",\"topk_method\":\"noaux_tc\","
+ "\"hidden_size\":128,\"num_hidden_layers\":1,"
+ "\"num_attention_heads\":4,\"head_dim\":32,\"q_lora_rank\":64,"
+ "\"qk_rope_head_dim\":8,\"o_groups\":2,\"o_lora_rank\":64,"
+ "\"sliding_window\":16,\"index_n_heads\":4,\"index_head_dim\":16,"
+ "\"index_topk\":8,\"n_routed_experts\":8,\"num_experts_per_tok\":2,"
+ "\"n_shared_experts\":1,\"moe_intermediate_size\":32,"
+ "\"num_hash_layers\":1,\"num_nextn_predict_layers\":1,"
+ "\"hc_mult\":4,\"hc_sinkhorn_iters\":5,\"vocab_size\":256,"
+ "\"max_position_embeddings\":4096,\"rms_norm_eps\":1e-6,"
+ "\"hc_eps\":1e-6,\"routed_scaling_factor\":1.5,\"swiglu_limit\":10,"
+ "\"rope_theta\":10000,\"compress_rope_theta\":40000,"
+ "\"compress_ratios\":[0,0],"
+ "\"rope_scaling\":{\"original_max_position_embeddings\":1024,"
+ "\"beta_fast\":32,\"beta_slow\":1,\"factor\":4},"
+ "\"quantization_config\":{\"fmt\":\"e4m3\",\"scale_fmt\":\"ue8m0\"}}";
+ char path[512];
+ snprintf(path, sizeof(path), "%s/config.json", directory);
+ int fd = open(path, O_CREAT | O_TRUNC | O_WRONLY | COMPAT_O_BINARY, 0600);
+ if (fd < 0) return -1;
+ int result = write_all(fd, json, sizeof(json) - 1);
+ close(fd);
+ return result;
+}
+
+static int write_safetensors(const char *directory) {
+ static const char header[] =
+ "{\"dense.fp8\":{\"dtype\":\"F8_E4M3\",\"shape\":[2,2],"
+ "\"data_offsets\":[0,4]},"
+ "\"expert.fp4\":{\"dtype\":\"I8\",\"shape\":[2,1],"
+ "\"data_offsets\":[4,6]},"
+ "\"expert.scale\":{\"dtype\":\"F8_E8M0\",\"shape\":[2,1],"
+ "\"data_offsets\":[6,8]}}";
+ static const unsigned char payload[] = {1, 2, 3, 4, 5, 6, 7, 8};
+ char path[512];
+ snprintf(path, sizeof(path), "%s/model-00001-of-00001.safetensors",
+ directory);
+ uint64_t header_length = sizeof(header) - 1;
+ int fd = open(path, O_CREAT | O_TRUNC | O_WRONLY | COMPAT_O_BINARY, 0600);
+ if (fd < 0) return -1;
+ int result = write_all(fd, &header_length, sizeof(header_length)) ||
+ write_all(fd, header, (size_t)header_length) ||
+ write_all(fd, payload, sizeof(payload));
+ close(fd);
+ return result;
+}
+
+static int write_tokenizer(const char *directory) {
+ static const char json[] =
+ "{\"model\":{\"type\":\"BPE\",\"vocab\":{\"a\":0,\"b\":1,\"ab\":2},"
+ "\"merges\":[\"a b\"]},"
+ "\"added_tokens\":[{\"id\":3,\"content\":\"<eos>\",\"special\":true}]}";
+ char path[512];
+ snprintf(path, sizeof(path), "%s/tokenizer.json", directory);
+ int fd = open(path, O_CREAT | O_TRUNC | O_WRONLY | COMPAT_O_BINARY, 0600);
+ if (fd < 0) return -1;
+ int result = write_all(fd, json, sizeof(json) - 1);
+ close(fd);
+ return result;
+}
+
+static int make_fixture(char *directory, size_t directory_size) {
+ /* Native MinGW binaries do not resolve the MSYS /tmp mount. */
+ char template[] = "colibri-v4-own-XXXXXX";
+ if (!mkdtemp(template)) return -1;
+ if (strlen(template) + 1 > directory_size) return -1;
+ memcpy(directory, template, strlen(template) + 1);
+ if (write_config(directory) || write_safetensors(directory) ||
+ write_tokenizer(directory))
+ return -1;
+ return 0;
+}
+
+static void cleanup_fixture(const char *directory) {
+ char path[512];
+ snprintf(path, sizeof(path), "%s/config.json", directory);
+ unlink(path);
+ snprintf(path, sizeof(path), "%s/model-00001-of-00001.safetensors",
+ directory);
+ unlink(path);
+ snprintf(path, sizeof(path), "%s/tokenizer.json", directory);
+ unlink(path);
+ rmdir(directory);
+}
+
+static int test_index_closed_on_expert_fail(void) {
+ char directory[128], error[256];
+ if (make_fixture(directory, sizeof(directory))) return 1;
+
+ coli_v4_test_fail_expert_store_open = 1;
+ coli_v4_test_skip_expert_store_open = 0;
+ coli_v4_test_closed_owned_index = 0;
+
+ ColiV4Engine *engine = NULL;
+ ColiV4EngineOpenOptions options = {.target_model_dir = directory};
+ int rc = coli_v4_engine_open(&engine, &options, error, sizeof(error));
+ coli_v4_test_fail_expert_store_open = 0;
+ if (rc == 0 || engine) {
+ fprintf(stderr, "expected expert-open failure, got success\n");
+ coli_v4_engine_destroy(engine);
+ cleanup_fixture(directory);
+ return 1;
+ }
+ if (coli_v4_test_closed_owned_index != 1) {
+ fprintf(stderr, "expected owned index close once, got %d\n",
+ coli_v4_test_closed_owned_index);
+ cleanup_fixture(directory);
+ return 1;
+ }
+ cleanup_fixture(directory);
+ puts("ownership: index closed after expert-open failure: ok");
+ return 0;
+}
+
+static int test_engine_owns_model_path(void) {
+ char directory[128], error[256];
+ if (make_fixture(directory, sizeof(directory))) return 1;
+
+ char *path = strdup(directory);
+ if (!path) return 1;
+
+ coli_v4_test_fail_expert_store_open = 0;
+ coli_v4_test_skip_expert_store_open = 1;
+ ColiV4Engine *engine = NULL;
+ ColiV4EngineOpenOptions options = {.target_model_dir = path};
+ if (coli_v4_engine_open(&engine, &options, error, sizeof(error))) {
+ fprintf(stderr, "engine open failed: %s\n", error);
+ free(path);
+ cleanup_fixture(directory);
+ return 1;
+ }
+ free(path);
+
+ const char *owned = coli_v4_engine_target_model_dir(engine);
+ if (!owned || strcmp(owned, directory) != 0) {
+ fprintf(stderr, "engine lost model path after caller free\n");
+ coli_v4_engine_destroy(engine);
+ cleanup_fixture(directory);
+ return 1;
+ }
+ if (!coli_v4_engine_config(engine) ||
+ coli_v4_engine_config(engine)->hidden_size != 128) {
+ fprintf(stderr, "engine config unusable after caller free\n");
+ coli_v4_engine_destroy(engine);
+ cleanup_fixture(directory);
+ return 1;
+ }
+ coli_v4_engine_destroy(engine);
+ coli_v4_test_skip_expert_store_open = 0;
+ cleanup_fixture(directory);
+ puts("ownership: engine copies model path: ok");
+ return 0;
+}
+
+static int test_session_lifetime_accounting(void) {
+ char directory[128], error[256];
+ if (make_fixture(directory, sizeof(directory))) return 1;
+
+ coli_v4_test_skip_expert_store_open = 1;
+ ColiV4Engine *engine = NULL;
+ ColiV4EngineOpenOptions options = {.target_model_dir = directory};
+ if (coli_v4_engine_open(&engine, &options, error, sizeof(error))) {
+ fprintf(stderr, "engine open failed: %s\n", error);
+ cleanup_fixture(directory);
+ return 1;
+ }
+
+ ColiV4Session *session = coli_v4_test_session_bare_create(engine);
+ if (!session) {
+ fprintf(stderr, "bare session create failed\n");
+ coli_v4_engine_destroy(engine);
+ cleanup_fixture(directory);
+ return 1;
+ }
+ if (engine->active_sessions != 1) {
+ fprintf(stderr, "expected active_sessions=1 after attach, got %d\n",
+ engine->active_sessions);
+ coli_v4_test_session_bare_destroy(session);
+ coli_v4_engine_destroy(engine);
+ cleanup_fixture(directory);
+ return 1;
+ }
+
+ coli_v4_test_session_bare_destroy(session);
+ if (engine->active_sessions != 0) {
+ fprintf(stderr, "expected active_sessions=0 after detach, got %d\n",
+ engine->active_sessions);
+ coli_v4_engine_destroy(engine);
+ cleanup_fixture(directory);
+ return 1;
+ }
+ coli_v4_engine_destroy(engine);
+ coli_v4_test_skip_expert_store_open = 0;
+ cleanup_fixture(directory);
+ puts("ownership: session lifetime accounting: ok");
+ return 0;
+}
+
+static int test_runner_closed_after_shared_heads_fail(void) {
+ char directory[128], error[256];
+ if (make_fixture(directory, sizeof(directory))) return 1;
+
+ coli_v4_test_skip_expert_store_open = 1;
+ ColiV4Engine *engine = NULL;
+ ColiV4EngineOpenOptions options = {.target_model_dir = directory};
+ if (coli_v4_engine_open(&engine, &options, error, sizeof(error))) {
+ fprintf(stderr, "engine open failed: %s\n", error);
+ cleanup_fixture(directory);
+ return 1;
+ }
+
+ ColiV4Session *session = coli_v4_test_session_bare_create(engine);
+ if (!session) {
+ coli_v4_engine_destroy(engine);
+ cleanup_fixture(directory);
+ return 1;
+ }
+
+ coli_v4_test_runner_close_count = 0;
+ ColiV4DSparkRunner *runner = calloc(1, sizeof(void *) * 8);
+ if (!runner) {
+ coli_v4_test_session_bare_destroy(session);
+ coli_v4_engine_destroy(engine);
+ cleanup_fixture(directory);
+ return 1;
+ }
+ /* Mirror session_generate: take runner before shared-head bind fails. */
+ coli_v4_session_take_runner(session, runner);
+ if (!coli_v4_session_peek_runner(session)) {
+ fprintf(stderr, "session should own runner after take\n");
+ coli_v4_test_session_bare_destroy(session);
+ coli_v4_engine_destroy(engine);
+ cleanup_fixture(directory);
+ return 1;
+ }
+ /* Simulated shared-head bind failure: leave runner on session, then destroy. */
+ coli_v4_test_session_bare_destroy(session);
+ if (coli_v4_test_runner_close_count != 1) {
+ fprintf(stderr, "expected runner close once via clear_runner, got %d\n",
+ coli_v4_test_runner_close_count);
+ coli_v4_engine_destroy(engine);
+ cleanup_fixture(directory);
+ return 1;
+ }
+ coli_v4_engine_destroy(engine);
+ coli_v4_test_skip_expert_store_open = 0;
+ cleanup_fixture(directory);
+ puts("ownership: runner closed after shared-heads fail: ok");
+ return 0;
+}
+
+static int test_session_tokenizer_freed(void) {
+ char directory[128];
+ if (make_fixture(directory, sizeof(directory))) return 1;
+
+ char tokenizer_path[512];
+ snprintf(tokenizer_path, sizeof(tokenizer_path), "%s/tokenizer.json",
+ directory);
+
+ for (int round = 0; round < 2; round++) {
+ /* Mirror coli_v4_session_create / coli_v4_session_destroy tokenizer
+ * ownership without pulling the full attention/runtime link set. */
+ ColiV4Session session;
+ memset(&session, 0, sizeof(session));
+ tok_load(&session.tokenizer, tokenizer_path);
+ session.tokenizer_ready = 1;
+
+ if (!session.tokenizer_ready || !session.tokenizer.json_root ||
+ session.tokenizer.n_ids < 4 || !session.tokenizer.merges.e ||
+ tok_id_of(&session.tokenizer, "<eos>") != 3 ||
+ hm_get(&session.tokenizer.vocab, "ab", 2) != 2) {
+ fprintf(stderr, "tokenizer not owned after load\n");
+ cleanup_fixture(directory);
+ return 1;
+ }
+
+ if (session.tokenizer_ready) {
+ tok_free(&session.tokenizer);
+ session.tokenizer_ready = 0;
+ }
+ if (session.tokenizer.json_root || session.tokenizer.merges.e ||
+ session.tokenizer.vocab.e || session.tokenizer.id2str) {
+ fprintf(stderr, "tokenizer not cleared after tok_free\n");
+ cleanup_fixture(directory);
+ return 1;
+ }
+ }
+
+ cleanup_fixture(directory);
+ puts("ownership: session tokenizer freed across create/destroy: ok");
+ return 0;
+}
+
+int main(void) {
+ if (test_index_closed_on_expert_fail()) return 1;
+ if (test_engine_owns_model_path()) return 1;
+ if (test_session_lifetime_accounting()) return 1;
+ if (test_runner_closed_after_shared_heads_fail()) return 1;
+ if (test_session_tokenizer_freed()) return 1;
+ puts("DeepSeek-V4 ownership tests: ok");
+ return 0;
+}
diff --git a/c/tools/clean.py b/c/tools/clean.py
index 463618fb..178b364a 100644
--- a/c/tools/clean.py
+++ b/c/tools/clean.py
@@ -10,6 +10,7 @@ import shutil
# Files (relative to c/) to remove if present.
FILES = [
+ "colibri", "colibri.exe",
"olmoe", "olmoe.exe",
"glm", "glm.exe",
"iobench", "iobench.exe",
@@ -18,22 +19,28 @@ FILES = [
"backend_cuda_bench", "backend_cuda_bench.exe",
"backend_metal.o", "backend_metal_test",
"coli_cuda.dll", "coli_cuda.lib", "coli_cuda.exp",
+ "deepseek_v4", "deepseek_v4.exe",
+ "safetensors_index.o", "tensor_io.o",
+ "native_quant.o", "native_quant_parallel.o", "native_quant_dual.o",
+ "native_quant_batch_avx512.o", "native_quant_fp4_rows16.o",
]
-# Test binaries match this pattern. Only remove executables (.exe on Windows,
+# Test binaries and V4 unit objects match these patterns. Only remove binaries (.exe on Windows,
# no extension on Unix) — never .c or .py source files.
-TEST_GLOBS = ["tests/test_*.exe"]
+ARTIFACT_GLOBS = ["tests/test_*", "COLI_V4_UNIT_*.o"]
+BINARY_EXTENSIONS = {"", ".exe", ".o"}
# Directories to remove.
-DIRS = ["tests/__pycache__"]
+DIRS = ["tests/__pycache__", "build/ownership"]
removed = 0
for f in FILES:
if os.path.exists(f):
os.remove(f)
removed += 1
-for pattern in TEST_GLOBS:
+for pattern in ARTIFACT_GLOBS:
for f in glob.glob(pattern):
- os.remove(f)
- removed += 1
+ if os.path.isfile(f) and os.path.splitext(f)[1] in BINARY_EXTENSIONS:
+ os.remove(f)
+ removed += 1
for d in DIRS:
if os.path.isdir(d):
shutil.rmtree(d)
diff --git a/c/tools/make_deepseek_v4_oracle.py b/c/tools/make_deepseek_v4_oracle.py
new file mode 100644
index 00000000..afe63760
--- /dev/null
+++ b/c/tools/make_deepseek_v4_oracle.py
@@ -0,0 +1,228 @@
+#!/usr/bin/env python3
+"""Build / validate a DeepSeek V4 oracle fixture for colibri.
+
+This is intentional heavy validation — not part of light `make check`.
+
+Comparison contract (documented in the JSON and docs/deepseek-v4.md):
+ - top-1 token exact match for teacher-forcing and greedy windows
+ - optional DSpark on/off greedy token identity
+ - logits max-abs / top-k ranking are reserved for a future transformers
+ oracle (`source=transformers`); coli-self fixtures only claim token match
+
+Preferred source when transformers + DeepseekV4ForCausalLM are available:
+ record reference tokens from the official implementation.
+
+Fallback (current default on most machines):
+ drive the C engine with --record-oracle / --no-dspark (source=coli-self).
+ That proves reproducibility and DSpark losslessness vs the target path, not
+ bit-exact parity with Hugging Face.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import subprocess
+import sys
+from pathlib import Path
+
+
+def try_transformers_oracle(model: str, prompt: str, max_new: int) -> dict | None:
+ try:
+ import torch
+ from transformers import AutoModelForCausalLM, AutoTokenizer
+ except Exception as exc: # noqa: BLE001 — optional dependency
+ print(f"[oracle] transformers unavailable ({exc}); using coli-self",
+ file=sys.stderr)
+ return None
+
+ try:
+ tokenizer = AutoTokenizer.from_pretrained(model, trust_remote_code=True)
+ model_obj = AutoModelForCausalLM.from_pretrained(
+ model, trust_remote_code=True, torch_dtype=torch.bfloat16
+ ).eval()
+ except Exception as exc: # noqa: BLE001
+ print(f"[oracle] cannot load HF DeepSeek V4 ({exc}); using coli-self",
+ file=sys.stderr)
+ return None
+
+ # Match colibri's default non-thinking chat template as closely as practical.
+ encoded = tokenizer(prompt, return_tensors="pt")
+ prompt_ids = encoded["input_ids"][0].tolist()
+ with torch.no_grad():
+ out = model_obj.generate(
+ **encoded, max_new_tokens=max_new, do_sample=False, use_cache=True
+ )
+ full = out[0].tolist()
+ logits = model_obj(torch.tensor([full]), use_cache=False).logits[0]
+ tf_pred = logits.argmax(-1).tolist()
+ return {
+ "source": "transformers",
+ "model": model,
+ "prompt": prompt,
+ "comparison": {
+ "top1_token": "exact",
+ "logits": "max abs error may be reported by future tooling",
+ "dspark": "greedy tokens must match --no-dspark",
+ },
+ "prompt_ids": prompt_ids,
+ "full_ids": full,
+ "tf_pred": tf_pred,
+ }
+
+
+def run_c(binary: Path, args: list[str], env: dict | None = None) -> subprocess.CompletedProcess:
+ cmd = [str(binary), *args]
+ print("[oracle] exec:", " ".join(cmd), file=sys.stderr)
+ merged = os.environ.copy()
+ if env:
+ merged.update(env)
+ return subprocess.run(cmd, check=False, env=merged)
+
+
+def coli_self_oracle(
+ binary: Path,
+ model: str,
+ prompt: str,
+ output: Path,
+ max_new: int,
+ memory_gb: float | None,
+) -> dict:
+ args = [model, prompt, "--max-tokens", str(max_new),
+ "--record-oracle", str(output), "--no-dspark"]
+ if memory_gb is not None:
+ args.extend(["--memory-gb", str(memory_gb)])
+ proc = run_c(binary, args)
+ if proc.returncode != 0:
+ raise SystemExit(f"coli-self record failed with exit {proc.returncode}")
+ return json.loads(output.read_text(encoding="utf-8"))
+
+
+def validate(
+ binary: Path,
+ model: str,
+ oracle_path: Path,
+ teacher_forcing: int,
+ greedy: int,
+ memory_gb: float | None,
+ check_dspark: bool,
+) -> int:
+ args = [
+ model,
+ "--oracle", str(oracle_path),
+ "--teacher-forcing", str(teacher_forcing),
+ "--greedy", str(greedy),
+ ]
+ if memory_gb is not None:
+ args.extend(["--memory-gb", str(memory_gb)])
+ proc = run_c(binary, args)
+ if proc.returncode != 0:
+ print("[oracle] token validation FAILED", file=sys.stderr)
+ return proc.returncode
+
+ if not check_dspark:
+ print("[oracle] token validation OK (DSpark check skipped)", file=sys.stderr)
+ return 0
+
+ data = json.loads(oracle_path.read_text(encoding="utf-8"))
+ prompt = data.get("prompt") or "What is the capital of France?"
+ full = data["full_ids"]
+ prompt_ids = data["prompt_ids"]
+ want = full[len(prompt_ids):len(prompt_ids) + greedy]
+
+ def collect(no_dspark: bool) -> list[int]:
+ out_path = oracle_path.with_suffix(".tmp_ids.json")
+ cmd = [model, prompt, "--max-tokens", str(greedy),
+ "--record-oracle", str(out_path)]
+ # Explicit either way: record-oracle alone must not imply --no-dspark,
+ # otherwise the on/off identity check is a no-op.
+ if no_dspark:
+ cmd.append("--no-dspark")
+ if memory_gb is not None:
+ cmd.extend(["--memory-gb", str(memory_gb)])
+ result = run_c(binary, cmd)
+ if result.returncode != 0:
+ raise SystemExit(f"DSpark compare run failed ({no_dspark=})")
+ payload = json.loads(out_path.read_text(encoding="utf-8"))
+ out_path.unlink(missing_ok=True)
+ got = payload["full_ids"][len(payload["prompt_ids"]):]
+ return got[:greedy]
+
+ off = collect(True)
+ on = collect(False)
+ expected = want[:greedy]
+ off_ok = len(off) == len(expected) and off == expected
+ on_ok = len(on) == len(expected) and on == expected
+ same = off == on
+ all_ok = off_ok and on_ok and same
+ print(
+ f"[oracle] DSpark on/off identity: {'OK' if all_ok else 'FAIL'} "
+ f"(no_dspark vs fixture {'OK' if off_ok else 'FAIL'}, "
+ f"dspark vs fixture {'OK' if on_ok else 'FAIL'}, "
+ f"on/off equality {'OK' if same else 'FAIL'})",
+ file=sys.stderr,
+ )
+ return 0 if all_ok else 1
+
+
+def main() -> int:
+ parser = argparse.ArgumentParser(description=__doc__)
+ parser.add_argument("--model", required=True)
+ parser.add_argument("--output", required=True)
+ parser.add_argument("--binary", default="./deepseek_v4")
+ parser.add_argument("--prompt", default="What is the capital of France?")
+ parser.add_argument("--max-new", type=int, default=32)
+ parser.add_argument("--memory-gb", type=float, default=None)
+ parser.add_argument("--validate", action="store_true")
+ parser.add_argument("--teacher-forcing", type=int, default=32)
+ parser.add_argument("--greedy", type=int, default=20)
+ parser.add_argument("--check-dspark", action="store_true")
+ parser.add_argument(
+ "--prefer-transformers",
+ action="store_true",
+ help="Try Hugging Face first; fall back to coli-self on failure",
+ )
+ args = parser.parse_args()
+
+ binary = Path(args.binary)
+ if os.name == "nt" and binary.suffix == "" and not binary.exists():
+ candidate = binary.with_suffix(".exe")
+ if candidate.exists():
+ binary = candidate
+ if not binary.exists():
+ raise SystemExit(f"binary not found: {binary}")
+ # Path("./deepseek_v4") stringifies to "deepseek_v4". subprocess would
+ # then search PATH instead of executing the binary in the current directory.
+ binary = binary.resolve()
+
+ output = Path(args.output)
+ output.parent.mkdir(parents=True, exist_ok=True)
+
+ fixture = None
+ if args.prefer_transformers:
+ fixture = try_transformers_oracle(args.model, args.prompt, args.max_new)
+ if fixture is not None:
+ output.write_text(json.dumps(fixture, indent=2) + "\n", encoding="utf-8")
+ print(f"[oracle] wrote transformers fixture → {output}", file=sys.stderr)
+
+ if fixture is None:
+ fixture = coli_self_oracle(
+ binary, args.model, args.prompt, output, args.max_new, args.memory_gb
+ )
+ print(f"[oracle] wrote coli-self fixture → {output}", file=sys.stderr)
+
+ if not args.validate:
+ return 0
+ return validate(
+ binary,
+ args.model,
+ output,
+ args.teacher_forcing,
+ args.greedy,
+ args.memory_gb,
+ args.check_dspark,
+ )
+
+
+if __name__ == "__main__":
+ sys.exit(main())
diff --git a/c/v4 b/c/v4
new file mode 100644
index 00000000..b4f2f630
--- /dev/null
+++ b/c/v4
@@ -0,0 +1,299 @@
+#!/usr/bin/env python3
+"""DeepSeek V4 command-line launcher for colibri."""
+
+import argparse
+import json
+import os
+import re
+import subprocess
+import sys
+import tempfile
+
+
+HERE = os.path.dirname(os.path.abspath(__file__))
+EXE = ".exe" if sys.platform == "win32" else ""
+ENGINE = os.path.join(HERE, "deepseek_v4" + EXE)
+
+BOS = "<\uff5cbegin\u2581of\u2581sentence\uff5c>"
+USER = "<\uff5cUser\uff5c>"
+ASSISTANT = "<\uff5cAssistant\uff5c>"
+EOS = "<\uff5cend\u2581of\u2581sentence\uff5c>"
+
+
+def configure_stdio_utf8():
+ """Make PowerShell / Windows consoles accept Chinese input and output."""
+ os.environ.setdefault("PYTHONIOENCODING", "utf-8")
+ os.environ.setdefault("PYTHONUTF8", "1")
+ if sys.platform == "win32":
+ try:
+ import ctypes
+
+ ctypes.windll.kernel32.SetConsoleCP(65001)
+ ctypes.windll.kernel32.SetConsoleOutputCP(65001)
+ except (AttributeError, OSError):
+ pass
+ for stream in (sys.stdin, sys.stdout, sys.stderr):
+ if stream is None:
+ continue
+ reconfigure = getattr(stream, "reconfigure", None)
+ if not callable(reconfigure):
+ continue
+ try:
+ reconfigure(encoding="utf-8", errors="replace")
+ except (AttributeError, OSError, ValueError):
+ pass
+
+
+def positive_int(text):
+ value = int(text)
+ if value < 1:
+ raise argparse.ArgumentTypeError("must be greater than zero")
+ return value
+
+
+def positive_float(text):
+ value = float(text)
+ if value <= 0:
+ raise argparse.ArgumentTypeError("must be greater than zero")
+ return value
+
+
+def validate_model(model):
+ if not os.path.isdir(model):
+ raise SystemExit(f"model not found: {model}")
+ config_path = os.path.join(model, "config.json")
+ tokenizer_path = os.path.join(model, "tokenizer.json")
+ if not os.path.isfile(config_path):
+ raise SystemExit(f"config.json is missing from {model}")
+ if not os.path.isfile(tokenizer_path):
+ raise SystemExit(f"tokenizer.json is missing from {model}")
+ try:
+ with open(config_path, "r", encoding="utf-8") as stream:
+ config = json.load(stream)
+ except (OSError, ValueError) as error:
+ raise SystemExit(f"cannot read {config_path}: {error}") from error
+ architectures = config.get("architectures") or []
+ is_v4 = config.get("model_type") == "deepseek_v4" or any(
+ str(name).startswith("DeepseekV4") for name in architectures
+ )
+ if not is_v4:
+ raise SystemExit(f"model is not a DeepSeek V4 checkpoint: {model}")
+
+
+def validate_engine():
+ if not os.path.isfile(ENGINE):
+ raise SystemExit(
+ "DeepSeek V4 engine is not built. Run: make deepseek-v4"
+ )
+
+
+def new_history(system_prompt):
+ return BOS + (system_prompt or "")
+
+
+def turn_prompt(history, message, thinking):
+ prefix = "<think>" if thinking else "</think>"
+ return history + USER + message + ASSISTANT + prefix
+
+
+def completed_history(prompt, answer):
+ return prompt + answer + EOS
+
+
+def engine_command(args, prompt=None, raw=True, prompt_file=None):
+ command = [ENGINE, os.path.abspath(args.model)]
+ if prompt_file:
+ command.extend(("--prompt-file", prompt_file))
+ elif prompt is not None:
+ command.append(prompt)
+ else:
+ raise ValueError("prompt or prompt_file is required")
+ command.extend(("--max-tokens", str(args.ngen)))
+ if raw:
+ command.append("--raw-prompt")
+ if args.ram:
+ command.extend(("--memory-gb", f"{args.ram:g}"))
+ if getattr(args, "stop_sentence", False):
+ command.append("--stop-sentence")
+ return command
+
+
+def write_prompt_file(prompt):
+ handle = tempfile.NamedTemporaryFile(
+ mode="w",
+ encoding="utf-8",
+ suffix=".txt",
+ delete=False,
+ newline="\n",
+ )
+ try:
+ handle.write(prompt)
+ handle.flush()
+ return handle.name
+ finally:
+ handle.close()
+
+
+def compact_stats(log):
+ fields = []
+ memory = re.search(
+ r"ram_tiers available=([0-9.]+)GiB .* projected=([0-9.]+)GiB", log
+ )
+ prefill = re.search(
+ r"prefill_timing .* wall_to_first=([0-9.]+)s "
+ r"target_tok_s=[0-9.]+ combined_tok_s=([0-9.]+)", log
+ )
+ decode = re.search(r"decode_timing tokens=(\d+) seconds=[0-9.]+ tok_s=([0-9.]+)", log)
+ summary = re.search(
+ r"dspark_rounds=\d+ proposed=(\d+) accepted=(\d+) rate=([0-9.]+)", log
+ )
+ if memory:
+ fields.append(f"RAM {float(memory.group(2)):.2f}/{float(memory.group(1)):.2f} GiB")
+ if prefill:
+ fields.append(f"TTFT {float(prefill.group(1)):.2f}s")
+ fields.append(f"prefill {float(prefill.group(2)):.3f} tok/s")
+ if decode:
+ fields.append(f"decode {float(decode.group(2)):.3f} tok/s")
+ if summary and int(summary.group(1)):
+ fields.append(f"DSpark acceptance {100.0 * float(summary.group(3)):.1f}%")
+ return " | ".join(fields)
+
+
+def emit_text(text):
+ """Write Unicode text through the UTF-8 text stream when possible."""
+ try:
+ sys.stdout.write(text)
+ sys.stdout.flush()
+ return
+ except UnicodeEncodeError:
+ pass
+ sys.stdout.buffer.write(text.encode("utf-8", errors="replace"))
+ sys.stdout.buffer.flush()
+
+
+def emit_bytes(chunk):
+ """Stream engine UTF-8 bytes; decode via text stdout after UTF-8 setup."""
+ try:
+ sys.stdout.buffer.write(chunk)
+ sys.stdout.buffer.flush()
+ except (AttributeError, OSError, ValueError):
+ emit_text(chunk.decode("utf-8", errors="replace"))
+
+
+def generate(args, prompt, raw=True, stream=True):
+ validate_model(args.model)
+ validate_engine()
+ # Always pass the prompt through a UTF-8 file. Windows argv uses the ANSI
+ # code page for MinGW main(), which corrupts Chinese from PowerShell.
+ prompt_path = write_prompt_file(prompt)
+ try:
+ with tempfile.TemporaryFile(mode="w+b") as error_log:
+ process = subprocess.Popen(
+ engine_command(args, raw=raw, prompt_file=prompt_path),
+ stdout=subprocess.PIPE,
+ stderr=error_log,
+ bufsize=0,
+ )
+ chunks = []
+ while True:
+ chunk = process.stdout.read(256)
+ if not chunk:
+ break
+ chunks.append(chunk)
+ if stream:
+ emit_bytes(chunk)
+ return_code = process.wait()
+ error_log.seek(0)
+ diagnostics = error_log.read().decode("utf-8", errors="replace")
+ finally:
+ try:
+ os.unlink(prompt_path)
+ except OSError:
+ pass
+ answer = b"".join(chunks).decode("utf-8", errors="replace").rstrip("\r\n")
+ if return_code:
+ tail = "\n".join(diagnostics.rstrip().splitlines()[-12:])
+ raise SystemExit(tail or f"DeepSeek V4 engine exited with status {return_code}")
+ return answer, diagnostics
+
+
+def cmd_run(args):
+ prompt = " ".join(args.prompt).strip()
+ if not prompt:
+ raise SystemExit('usage: v4 run --model PATH "your prompt"')
+ _, diagnostics = generate(args, prompt, raw=False)
+ stats = compact_stats(diagnostics)
+ if stats:
+ print(f"[stats] {stats}", file=sys.stderr)
+ return 0
+
+
+def cmd_chat(args):
+ validate_model(args.model)
+ validate_engine()
+ history = new_history(args.system)
+ ram_label = f"{args.ram:g} GiB" if args.ram else "auto"
+ print(f"DeepSeek V4 chat | {os.path.basename(os.path.normpath(args.model))} | RAM {ram_label}")
+ print("Commands: :reset clears history, :q exits.")
+ print("Note: conversation history is re-prefilled on each turn.\n")
+ while True:
+ try:
+ message = input("You> ").strip()
+ except (EOFError, KeyboardInterrupt):
+ print()
+ break
+ if not message:
+ continue
+ if message in (":q", ":quit", ":exit"):
+ break
+ if message == ":reset":
+ history = new_history(args.system)
+ print("History cleared.\n")
+ continue
+ prompt = turn_prompt(history, message, args.thinking)
+ print("Assistant> ", end="", flush=True)
+ answer, diagnostics = generate(args, prompt, raw=True)
+ history = completed_history(prompt, answer)
+ stats = compact_stats(diagnostics)
+ if stats:
+ print(f"[stats] {stats}", file=sys.stderr)
+ print()
+ return 0
+
+
+def add_runtime_arguments(parser):
+ parser.add_argument("--model", required=True, help="DeepSeek V4 model directory")
+ parser.add_argument("--ram", type=positive_float, default=0, metavar="GIB",
+ help="process RAM limit in GiB (default: auto)")
+ parser.add_argument("--ngen", type=positive_int, default=128, metavar="N",
+ help="maximum response tokens (default: 128)")
+
+
+def make_parser():
+ parser = argparse.ArgumentParser(
+ prog="v4", description="run DeepSeek V4 Flash locally with colibri"
+ )
+ subparsers = parser.add_subparsers(dest="command", required=True)
+ chat = subparsers.add_parser("chat", help="interactive multi-turn chat")
+ add_runtime_arguments(chat)
+ chat.add_argument("--system", default="", help="system message")
+ chat.add_argument("--thinking", action="store_true", help="enable thinking mode")
+ chat.set_defaults(handler=cmd_chat)
+
+ run = subparsers.add_parser("run", help="one-shot generation")
+ add_runtime_arguments(run)
+ run.add_argument("--stop-sentence", action="store_true",
+ help="stop at the first sentence terminator")
+ run.add_argument("prompt", nargs="*")
+ run.set_defaults(handler=cmd_run)
+ return parser
+
+
+def main():
+ configure_stdio_utf8()
+ args = make_parser().parse_args()
+ return args.handler(args)
+
+
+if __name__ == "__main__":
+ raise SystemExit(main())