Skip to content

Commit 07984e8

Browse files
SimonSchubertSimonSchubert
committed
Add commands
1 parent eec64b4 commit 07984e8

5 files changed

Lines changed: 417 additions & 0 deletions

File tree

‎assets/commands/ds4-agent.md‎

Lines changed: 94 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,94 @@
1+
# TAGLINE
2+
3+
Interactive coding agent for DwarfStar local LLM inference
4+
5+
# TLDR
6+
7+
**Start the agent** with a model and large context
8+
9+
```ds4-agent -m [ds4flash.gguf] --ctx [100000]```
10+
11+
**Run a single non-interactive turn**
12+
13+
```ds4-agent -m [ds4flash.gguf] --non-interactive -p "[fix the failing test]"```
14+
15+
**Lower GPU power** for quieter runs
16+
17+
```ds4-agent -m [ds4flash.gguf] --power [50]```
18+
19+
**Write a debug trace** of prompts and tool calls
20+
21+
```ds4-agent -m [ds4flash.gguf] --trace [agent.trace]```
22+
23+
**Change working directory** before loading assets
24+
25+
```ds4-agent -m [ds4flash.gguf] --chdir [/path/to/project]```
26+
27+
**Disable thinking** for direct answers
28+
29+
```ds4-agent -m [ds4flash.gguf] --nothink```
30+
31+
# SYNOPSIS
32+
33+
**ds4-agent** [_options_]
34+
35+
# PARAMETERS
36+
37+
**-m**, **--model** _FILE_
38+
> Path to the GGUF model. Default: **ds4flash.gguf**.
39+
40+
**-c**, **--ctx** _N_
41+
> Allocated context length in tokens.
42+
43+
**-p**, **--prompt** _TEXT_
44+
> Submit an initial prompt after startup (or a single turn with **--non-interactive**).
45+
46+
**--non-interactive**
47+
> Run without the TUI. With **-p**: one turn then exit; without **-p**: read repeated prompts from stdin.
48+
49+
**-sys**, **--system** _TEXT_
50+
> Extra system prompt text. Empty string disables the extra text.
51+
52+
**--trace** _FILE_
53+
> Write prompt, token, and DSML tool-call debug output.
54+
55+
**--chdir** _DIR_
56+
> Change working directory before loading runtime assets (useful so relative project paths resolve correctly).
57+
58+
**--power** _N_
59+
> GPU duty-cycle target from 1 to 100. Default: **100**.
60+
61+
**--metal** | **--cuda** | **--rocm** | **--cpu**
62+
> Select the inference backend explicitly.
63+
64+
**--ssd-streaming**
65+
> Stream model weights from SSD when full residency does not fit.
66+
67+
**--think** / **--think-max** / **--nothink**
68+
> Control model thinking/reasoning mode.
69+
70+
# DESCRIPTION
71+
72+
**ds4-agent** is the integrated coding agent that ships with **DwarfStar** (**ds4**). It loads the same specialized GGUF models as the interactive **ds4** CLI and **ds4-server**, then runs a tool-using agent loop aimed at local development work (reading files, editing, running commands via the model's DSML tool protocol).
73+
74+
In the interactive TUI you can manage long-lived sessions with slash commands: **/save** and **/list** / **/switch** for session persistence under **~/.ds4/kvcache**, **/compact** to shrink context, **/history**, **/new**, and **/power**. The agent is designed to work with the project's end-to-end local stack rather than as a generic agent framework.
75+
76+
# CAVEATS
77+
78+
Marked **alpha** quality by upstream relative to the rest of DwarfStar. Requires a DwarfStar-compatible GGUF and a suitable GPU backend for practical speed. Tool use and long sessions can consume large amounts of context and disk for KV checkpoints. The sibling interactive inference binary is also named **ds4**, which collides with unrelated DualShock 4 utilities of the same name.
79+
80+
# HISTORY
81+
82+
**ds4-agent** was added to the **DwarfStar** project after the core inference CLI and HTTP server, as part of the goal of shipping model + engine + agent together for local coding workflows on high-memory machines and SSD-streamed setups.
83+
84+
# SEE ALSO
85+
86+
[ds4-server](/man/ds4-server)(1), [ds4-bench](/man/ds4-bench)(1), [ds4-eval](/man/ds4-eval)(1), [ollama](/man/ollama)(1), [llama-cli](/man/llama-cli)(1)
87+
88+
# RESOURCES
89+
90+
```[Source code](https://github.com/antirez/ds4)```
91+
92+
```[Documentation](https://github.com/antirez/ds4/blob/main/docs/ENGINE_REFERENCE.md)```
93+
94+
<!-- verified: 2026-07-18 -->

‎assets/commands/ds4-bench.md‎

Lines changed: 103 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,103 @@
1+
# TAGLINE
2+
3+
Prefill and generation speed benchmark for DwarfStar
4+
5+
# TLDR
6+
7+
**Sweep prefill/generation speed** across context frontiers
8+
9+
```ds4-bench --prompt-file [long.txt] --ctx-max [32768]```
10+
11+
**Write results as CSV**
12+
13+
```ds4-bench --prompt-file [long.txt] --ctx-max [32768] --csv [speed.csv]```
14+
15+
**Prefill only** (no generation tokens)
16+
17+
```ds4-bench --prompt-file [long.txt] --gen-tokens [0]```
18+
19+
**Measure with reduced GPU power**
20+
21+
```ds4-bench --prompt-file [long.txt] --power [70]```
22+
23+
**Benchmark a chat-rendered prompt**
24+
25+
```ds4-bench --chat-prompt-file [prompt.txt] --ctx-max [16384]```
26+
27+
**SSD-streamed model** on a memory-constrained machine
28+
29+
```ds4-bench -m [ds4flash.gguf] --ssd-streaming --prompt-file [long.txt]```
30+
31+
# SYNOPSIS
32+
33+
**ds4-bench** [_options_]
34+
35+
# PARAMETERS
36+
37+
**-m**, **--model** _FILE_
38+
> Path to the GGUF model. Default: **ds4flash.gguf**.
39+
40+
**--prompt-file** _FILE_
41+
> Raw benchmark text; the token sequence is sliced at each measured frontier.
42+
43+
**--chat-prompt-file** _FILE_
44+
> Render _FILE_ as one no-thinking chat user message instead of raw text.
45+
46+
**-sys**, **--system** _TEXT_
47+
> System prompt used only with **--chat-prompt-file**.
48+
49+
**--ctx-start** _N_
50+
> First measured context frontier. Default: **2048**.
51+
52+
**--ctx-max** _N_
53+
> Last measured context frontier. Default: **32768**.
54+
55+
**--ctx-alloc** _N_
56+
> Allocated context size. Default: **ctx-max + gen-tokens + 1**.
57+
58+
**--step-incr** _N_
59+
> Linear step between frontiers when **--step-mul** is 1. Default: **2048**.
60+
61+
**--step-mul** _F_
62+
> Multiplicative step between frontiers. Default: **1** (linear).
63+
64+
**--gen-tokens** _N_
65+
> Greedy decode tokens per frontier. **0** for pure prefill. Default: **128**.
66+
67+
**--csv** _FILE_
68+
> Write CSV to _FILE_ instead of stdout.
69+
70+
**--power** _N_
71+
> GPU duty-cycle target from 1 to 100.
72+
73+
**--metal** | **--cuda** | **--rocm** | **--cpu**
74+
> Select the inference backend explicitly.
75+
76+
**--ssd-streaming**
77+
> Opt into SSD-backed model streaming for the benchmark run.
78+
79+
# DESCRIPTION
80+
81+
**ds4-bench** measures prefill and generation throughput for the **DwarfStar** (**ds4**) inference engine across a sweep of context lengths. You supply a long prompt file; the tool tokenizes it once, then at each frontier runs prefill (and optional greedy decode) so you can compare tokens/s as context grows.
82+
83+
It is the project's standard speed-bench entry point for Metal, CUDA, and ROCm paths, and for comparing full-resident versus **--ssd-streaming** configurations. Results can be printed to the terminal or written as CSV for charts and regression tracking in **speed-bench/** workflows.
84+
85+
# CAVEATS
86+
87+
Needs a DwarfStar-compatible GGUF and enough memory (or SSD bandwidth) for the chosen **--ctx-alloc**. Timings depend heavily on backend, power limit, thermal state, and cold vs warm expert cache; treat single runs as indicative, not absolute rankings across hardware. Prefill-only mode (**--gen-tokens 0**) does not exercise the decode path.
88+
89+
# HISTORY
90+
91+
**ds4-bench** is part of the **DwarfStar** toolkit by **Salvatore Sanfilippo** (**antirez**) and contributors, used to gate performance work on large MoE models (DeepSeek V4 Flash/PRO and experimental forks) where long-context prefill cost dominates.
92+
93+
# SEE ALSO
94+
95+
[ds4-server](/man/ds4-server)(1), [ds4-eval](/man/ds4-eval)(1), [ds4-agent](/man/ds4-agent)(1), [llama-cli](/man/llama-cli)(1)
96+
97+
# RESOURCES
98+
99+
```[Source code](https://github.com/antirez/ds4)```
100+
101+
```[Documentation](https://github.com/antirez/ds4/tree/main/speed-bench)```
102+
103+
<!-- verified: 2026-07-18 -->

‎assets/commands/ds4-eval.md‎

Lines changed: 100 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,100 @@
1+
# TAGLINE
2+
3+
Quality evaluation harness for DwarfStar model outputs
4+
5+
# TLDR
6+
7+
**Run the first N built-in evaluation questions**
8+
9+
```ds4-eval --questions [10] --ctx [100000]```
10+
11+
**Disable thinking and cap generation length**
12+
13+
```ds4-eval --plain --nothink --tokens [512]```
14+
15+
**Write a full evaluation trace**
16+
17+
```ds4-eval --questions [10] --trace [eval.trace]```
18+
19+
**Regrade a previous trace** without reloading the model
20+
21+
```ds4-eval --regrade-trace [eval.trace]```
22+
23+
**CPU diagnostic pass** on a single question
24+
25+
```ds4-eval --cpu --questions [1] --tokens [32]```
26+
27+
**Run selected case numbers** in order
28+
29+
```ds4-eval --case-sequence [1,3,5] --ctx [100000]```
30+
31+
# SYNOPSIS
32+
33+
**ds4-eval** [_options_]
34+
35+
# PARAMETERS
36+
37+
**-m**, **--model** _FILE_
38+
> Path to the GGUF model. Default: **ds4flash.gguf**.
39+
40+
**-c**, **--ctx** _N_
41+
> Allocated context length in tokens.
42+
43+
**-n**, **--tokens** _N_
44+
> Maximum generated tokens per question.
45+
46+
**--questions** _N_
47+
> Run only the first _N_ embedded evaluation questions.
48+
49+
**--case-sequence** _LIST_
50+
> Comma-separated 1-based case numbers to run in that order.
51+
52+
**--trace** _FILE_
53+
> Write a detailed evaluation trace.
54+
55+
**--regrade-trace** _FILE_
56+
> Regrade a prior trace without loading the model again.
57+
58+
**--plain**
59+
> Disable the split-screen ANSI UI.
60+
61+
**--think** / **--think-max** / **--nothink**
62+
> Control thinking/reasoning mode for answers.
63+
64+
**--metal** | **--cuda** | **--rocm** | **--cpu**
65+
> Select the inference backend explicitly.
66+
67+
**--power** _N_
68+
> GPU duty-cycle target from 1 to 100.
69+
70+
**--pause-ms** _N_
71+
> Pause after each result in the TTY UI. Default: **350**.
72+
73+
**--self-test-extractors**
74+
> Run answer-extractor self-tests and exit.
75+
76+
# DESCRIPTION
77+
78+
**ds4-eval** is the quality-evaluation tool for **DwarfStar** (**ds4**). It runs a built-in set of questions against the loaded GGUF, extracts answers, and grades them so contributors can catch regressions when changing kernels, quantizations, or sampling defaults.
79+
80+
Unlike **ds4-bench** (speed), **ds4-eval** focuses on correctness and answer quality. Traces can be saved and regraded later with **--regrade-trace**, which is useful when iterating on grading logic without paying the full inference cost again. A plain mode drops the ANSI UI for log-friendly CI or remote sessions.
81+
82+
# CAVEATS
83+
84+
Requires a DwarfStar-compatible GGUF for meaningful scores. Embedded cases and extractors are project-specific; they are not a general LLM leaderboard. CPU mode is slow and intended for diagnostics. Thinking modes and context size strongly affect both quality and runtime.
85+
86+
# HISTORY
87+
88+
**ds4-eval** ships with **DwarfStar** by **Salvatore Sanfilippo** (**antirez**) and contributors as part of the project's emphasis on official-vector validation and regression testing alongside speed benchmarks.
89+
90+
# SEE ALSO
91+
92+
[ds4-bench](/man/ds4-bench)(1), [ds4-server](/man/ds4-server)(1), [ds4-agent](/man/ds4-agent)(1), [llama-cli](/man/llama-cli)(1)
93+
94+
# RESOURCES
95+
96+
```[Source code](https://github.com/antirez/ds4)```
97+
98+
```[Documentation](https://github.com/antirez/ds4/blob/main/docs/ENGINE_REFERENCE.md)```
99+
100+
<!-- verified: 2026-07-18 -->

0 commit comments

Comments
 (0)