Skip to content

Add ds4-doctor self-diagnostic binary #556

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
AnandSundar wants to merge 6 commits into
base: main
Choose a base branch
from
Open

Add ds4-doctor self-diagnostic binary #556

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
7c18cfd
feat(ds4-doctor): add skeleton binary with options parsing and help d…
AnandSundar Jul 12, 2026
346f1b6
feat(ds4-doctor): add backend compile check (U2)
AnandSundar Jul 12, 2026
9831bf5
feat(ds4-doctor): add model file integrity check (U3)
AnandSundar Jul 12, 2026
f5c0e09
feat(ds4-doctor): add port, memory, and kv-disk checks (U4)
AnandSundar Jul 12, 2026
bcfc3b2
feat(ds4-doctor): add JSON renderer, tabular human renderer, and exit…
AnandSundar Jul 12, 2026
dbd0e8f
feat(ds4-doctor): add test runner entry and README documentation (U6)
Jul 12, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
38 changes: 26 additions & 12 deletions Makefile
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -43,12 +43,12 @@ endif
.PHONY: all help clean test cpu cuda cuda-spark cuda-generic cuda-regression strix-halo rocm

ifeq ($(UNAME_S),Darwin)
all: ds4 ds4-server ds4-bench ds4-eval ds4-agent
all: ds4 ds4-server ds4-bench ds4-eval ds4-agent ds4-doctor

help:
@echo "DS4 build targets:"
@echo " make Build Metal ./ds4, ./ds4-server, ./ds4-bench, ./ds4-eval, and ./ds4-agent"
@echo " make cpu Build CPU-only ./ds4, ./ds4-server, ./ds4-bench, ./ds4-eval, and ./ds4-agent"
@echo " make Build Metal ./ds4, ./ds4-server, ./ds4-bench, ./ds4-eval, ./ds4-agent, and ./ds4-doctor"
@echo " make cpu Build CPU-only ./ds4, ./ds4-server, ./ds4-bench, ./ds4-eval, ./ds4-agent, and ./ds4-doctor"
@echo " make test Build and run tests"
@echo " make clean Remove build outputs"

Expand All @@ -67,12 +67,16 @@ ds4-eval: ds4_eval.o ds4_help.o $(CORE_OBJS)
ds4-agent: ds4_agent.o ds4_help.o ds4_web.o ds4_kvstore.o linenoise.o $(CORE_OBJS)
$(CC) $(CFLAGS) -o $@ ds4_agent.o ds4_help.o ds4_web.o ds4_kvstore.o linenoise.o $(CORE_OBJS) $(METAL_LDLIBS)

cpu: ds4_cli_cpu.o ds4_server_cpu.o ds4_bench_cpu.o ds4_eval_cpu.o ds4_agent_cpu.o ds4_help.o ds4_web.o ds4_kvstore.o linenoise.o rax.o $(CPU_CORE_OBJS)
ds4-doctor: ds4_doctor.o ds4_help.o
$(CC) $(CFLAGS) -o $@ ds4_doctor.o ds4_help.o $(LDLIBS)

cpu: ds4_cli_cpu.o ds4_server_cpu.o ds4_bench_cpu.o ds4_eval_cpu.o ds4_agent_cpu.o ds4_doctor_cpu.o ds4_help.o ds4_web.o ds4_kvstore.o linenoise.o rax.o $(CPU_CORE_OBJS)
$(CC) $(CFLAGS) -o ds4 ds4_cli_cpu.o ds4_help.o linenoise.o $(CPU_CORE_OBJS) $(LDLIBS)
$(CC) $(CFLAGS) -o ds4-server ds4_server_cpu.o ds4_help.o ds4_kvstore.o rax.o $(CPU_CORE_OBJS) $(LDLIBS)
$(CC) $(CFLAGS) -o ds4-bench ds4_bench_cpu.o ds4_help.o $(CPU_CORE_OBJS) $(LDLIBS)
$(CC) $(CFLAGS) -o ds4-eval ds4_eval_cpu.o ds4_help.o $(CPU_CORE_OBJS) $(LDLIBS)
$(CC) $(CFLAGS) -o ds4-agent ds4_agent_cpu.o ds4_help.o ds4_web.o ds4_kvstore.o linenoise.o $(CPU_CORE_OBJS) $(LDLIBS)
$(CC) $(CFLAGS) -o ds4-doctor ds4_doctor_cpu.o ds4_help.o $(LDLIBS)

cuda-regression:
@echo "cuda-regression requires a CUDA build"
Expand All @@ -86,26 +90,26 @@ help:
@echo " make cuda CUDA_ARCH=sm_N Build CUDA with an explicit nvcc -arch value"
@echo " make strix-halo Build ROCm for Strix Halo / gfx1151"
@echo " make rocm Alias for make strix-halo"
@echo " make cpu Build CPU-only ./ds4, ./ds4-server, ./ds4-bench, ./ds4-eval, and ./ds4-agent"
@echo " make cpu Build CPU-only ./ds4, ./ds4-server, ./ds4-bench, ./ds4-eval, ./ds4-agent, and ./ds4-doctor"
@echo " make test Build and run tests"
@echo " make clean Remove build outputs"

cuda-spark:
$(MAKE) -B ds4 ds4-server ds4-bench ds4-eval ds4-agent CUDA_ARCH=
$(MAKE) -B ds4 ds4-server ds4-bench ds4-eval ds4-agent ds4-doctor CUDA_ARCH=

cuda-generic:
$(MAKE) -B ds4 ds4-server ds4-bench ds4-eval ds4-agent CUDA_ARCH=native
$(MAKE) -B ds4 ds4-server ds4-bench ds4-eval ds4-agent ds4-doctor CUDA_ARCH=native

cuda:
@if [ -z "$(strip $(CUDA_ARCH))" ]; then \
echo "error: specify CUDA_ARCH, for example: make cuda CUDA_ARCH=sm_120"; \
echo " or use make cuda-spark / make cuda-generic"; \
exit 2; \
fi
$(MAKE) -B ds4 ds4-server ds4-bench ds4-eval ds4-agent CUDA_ARCH="$(CUDA_ARCH)"
$(MAKE) -B ds4 ds4-server ds4-bench ds4-eval ds4-agent ds4-doctor CUDA_ARCH="$(CUDA_ARCH)"

strix-halo:
$(MAKE) -B ds4 ds4-server ds4-bench ds4-eval ds4-agent \
$(MAKE) -B ds4 ds4-server ds4-bench ds4-eval ds4-agent ds4-doctor \
CORE_OBJS="ds4.o ds4_distributed.o ds4_ssd.o ds4_rocm.o" \
CFLAGS="$(CFLAGS) -DDS4_ROCM_BUILD" \
DS4_LINK="$(HIPCC) $(ROCM_CFLAGS)" \
Expand All @@ -128,12 +132,16 @@ ds4-eval: ds4_eval.o ds4_help.o $(CORE_OBJS)
ds4-agent: ds4_agent.o ds4_help.o ds4_web.o ds4_kvstore.o linenoise.o $(CORE_OBJS)
$(DS4_LINK) -o $@ $^ $(DS4_LINK_LIBS)

cpu: ds4_cli_cpu.o ds4_server_cpu.o ds4_bench_cpu.o ds4_eval_cpu.o ds4_agent_cpu.o ds4_help.o ds4_web.o ds4_kvstore.o linenoise.o rax.o $(CPU_CORE_OBJS)
ds4-doctor: ds4_doctor.o ds4_help.o
$(CC) $(CFLAGS) -o $@ ds4_doctor.o ds4_help.o $(LDLIBS)

cpu: ds4_cli_cpu.o ds4_server_cpu.o ds4_bench_cpu.o ds4_eval_cpu.o ds4_agent_cpu.o ds4_doctor_cpu.o ds4_help.o ds4_web.o ds4_kvstore.o linenoise.o rax.o $(CPU_CORE_OBJS)
$(CC) $(CFLAGS) -o ds4 ds4_cli_cpu.o ds4_help.o linenoise.o $(CPU_CORE_OBJS) $(LDLIBS)
$(CC) $(CFLAGS) -o ds4-server ds4_server_cpu.o ds4_help.o ds4_kvstore.o rax.o $(CPU_CORE_OBJS) $(LDLIBS)
$(CC) $(CFLAGS) -o ds4-bench ds4_bench_cpu.o ds4_help.o $(CPU_CORE_OBJS) $(LDLIBS)
$(CC) $(CFLAGS) -o ds4-eval ds4_eval_cpu.o ds4_help.o $(CPU_CORE_OBJS) $(LDLIBS)
$(CC) $(CFLAGS) -o ds4-agent ds4_agent_cpu.o ds4_help.o ds4_web.o ds4_kvstore.o linenoise.o $(CPU_CORE_OBJS) $(LDLIBS)
$(CC) $(CFLAGS) -o ds4-doctor ds4_doctor_cpu.o ds4_help.o $(LDLIBS)

cuda-regression: tests/cuda_long_context_smoke
./tests/cuda_long_context_smoke
Expand All @@ -154,6 +162,9 @@ ds4_distributed.o: ds4_distributed.c ds4_distributed.h ds4.h ds4_ssd.h
ds4_help.o: ds4_help.c ds4_help.h
$(CC) $(CFLAGS) -c -o $@ ds4_help.c

ds4_doctor.o: ds4_doctor.c ds4_help.h
$(CC) $(CFLAGS) -c -o $@ ds4_doctor.c

ds4_server.o: ds4_server.c ds4.h ds4_ssd.h ds4_distributed.h ds4_help.h ds4_kvstore.h rax.h
$(CC) $(CFLAGS) -c -o $@ ds4_server.c

Expand Down Expand Up @@ -205,6 +216,9 @@ ds4_eval_cpu.o: ds4_eval.c ds4.h ds4_ssd.h ds4_distributed.h ds4_help.h
ds4_agent_cpu.o: ds4_agent.c ds4.h ds4_ssd.h ds4_distributed.h ds4_help.h ds4_kvstore.h ds4_web.h linenoise.h
$(CC) $(CFLAGS) -DDS4_NO_GPU -c -o $@ ds4_agent.c

ds4_doctor_cpu.o: ds4_doctor.c ds4_help.h
$(CC) $(CFLAGS) -c -o $@ ds4_doctor.c

ds4_metal.o: ds4_metal.m ds4_gpu.h $(METAL_SRCS)
$(CC) $(OBJCFLAGS) -c -o $@ ds4_metal.m

Expand All @@ -231,7 +245,7 @@ else
$(NVCC) $(NVCCFLAGS) -o $@ ds4_agent_test.o ds4_help.o ds4_web.o ds4_kvstore.o linenoise.o $(CORE_OBJS) $(CUDA_LDLIBS)
endif

test: ds4_test ds4_agent_test ds4-eval q4k-dot-test
test: ds4_test ds4_agent_test ds4-eval ds4-doctor q4k-dot-test
./ds4-eval --self-test-extractors
./ds4_agent_test
./ds4_test
Expand All @@ -241,4 +255,4 @@ q4k-dot-test: tests/test_q4k_dot.c
./tests/test_q4k_dot

clean:
rm -f ds4 ds4-server ds4-bench ds4-eval ds4-agent ds4_cpu ds4_native ds4_server_test ds4_test ds4_agent_test tests/test_q4k_dot *.o tests/cuda_long_context_smoke tests/cuda_long_context_smoke.o
rm -f ds4 ds4-server ds4-bench ds4-eval ds4-agent ds4-doctor ds4_cpu ds4_native ds4_server_test ds4_test ds4_agent_test tests/test_q4k_dot *.o tests/cuda_long_context_smoke tests/cuda_long_context_smoke.o
39 changes: 39 additions & 0 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -667,6 +667,45 @@ DeepSeek V4 Flash still solve a representative mix of hard science, broad
knowledge, exact math, and security-code problems while using the same inference
path users run?

## Self-Diagnostics

`ds4-doctor` is a small read-only diagnostic command that checks the local
installation before a real inference run. It does not load the model, does not
touch the network, and does not write to disk. The default run walks five
checks: the compile-time backend (`Metal` / `CUDA` / `ROCm` / `CPU`), the GGUF
header of the model file you point it at, whether the default server port
(`127.0.0.1:8000`) is bindable, total system RAM, and the optional KV-disk
directory. It is safe to run inside CI on machines without a GPU.

```sh
./ds4-doctor
./ds4-doctor -m ./ds4flash.gguf
./ds4-doctor -m ./ds4flash.gguf --kv-disk-dir /tmp/ds4-kv --json
```

Each check produces one of four states: `ok`, `warn`, `fail`, `skip` (a check
that did not run, e.g. the model path was not given). Human-readable output
includes an ANSI-coloured status column when stdout is a TTY; pass `--color`
to force it on. `--json` emits one self-describing line with a top-level
`status`, a `summary` counter, and a `checks` array:

```json
{"status":"ok","summary":"5 checks: 4 ok, 0 warn, 0 fail, 1 skip","checks":[
{"id":"backend","title":"Backend compile","status":"ok","duration_ms":0,"message":"Metal backend compiled in (Apple Silicon)"},
{"id":"model","title":"Model file integrity","status":"ok","duration_ms":3,"message":"81.32 GiB, v3, 715 tensors, 24 metadata kvs"},
{"id":"port","title":"Default server port","status":"ok","duration_ms":0,"message":"127.0.0.1:8000 bindable (default for ds4-server)"},
{"id":"memory","title":"Total system RAM","status":"ok","duration_ms":0,"message":"128.00 GiB total RAM"},
{"id":"kv-disk","title":"KV-disk directory","status":"skip","duration_ms":0,"message":"no --kv-disk-dir provided"}
]}
```

Exit codes match the worst severity, so scripts can branch without parsing
output: `0` if every check is `ok` or `skip`, `1` if at least one check is
`warn` and none is `fail`, `2` if any check is `fail`. `--timeout N` bounds
individual checks to `N` milliseconds (default 5000, max 600000).

Run `./ds4-doctor --help` for the full option list.

## CLI

One-shot prompt:
Expand Down
Loading