jq-coder-0.6B

jq-coder-0.6B — Natural Language to jq, 100% Offline (GGUF)

Part of the jq-coder project — all artifacts · jqc CLI (prebuilt binaries) · jq-bench benchmark

Convert natural language to jq filters without your JSON ever leaving your machine. jq-coder is a 0.6B full fine-tune of Qwen3-0.6B-Base that turns a plain-language request plus a JSON sample into an executable jq filter, on CPU, in a fraction of a second. An offline jq filter generator, built for the JSON you can't send to a cloud API: production payloads, logs with PII, anything under NDA.

To our knowledge it is the first NL→jq model with GGUF builds on Hugging Face. It ships with jq-bench, an execution-verified benchmark built from real StackOverflow questions — and, as a bonus, it also understands requests in Brazilian Portuguese (the only NL→jq model that does).

Model overview

Quickstart — 10 seconds with Ollama

ollama run D0minuZ/jq-coder

The Ollama library build ships the system prompt and temperature 0 preconfigured — just type your request (+ a JSON sample). Running straight from this repo also works: ollama run hf.co/DominuZ/jq-coder-0.6B:Q8_0.

Or the jqc CLI — one binary, batteries included

cargo install jqc, or prebuilt binaries for Windows, Linux and macOS (Apple Silicon) on the Releases page. It embeds llama.cpp and runs the generated filter for you; the model downloads on first use.

jqc "get the id of every order" orders.json

Since v0.2.0 it can also write the result back into the file (--write: shows a diff, asks first, keeps a .bak, writes atomically) and offers an interactive session (jqc orders.json): chain requests against a working buffer with apply/undo, and the file on disk only changes when you confirm :w.

Or llama.cpp / LM Studio

llama-server -m jq-coder-v14-release-Q8_0.gguf --port 8091 -ngl 99

curl -s http://127.0.0.1:8091/v1/chat/completions -d '{
  "messages": [
    {"role": "system",
     "content": "You translate natural-language requests into jq filters. Reply with only the jq filter."},
    {"role": "user",
     "content": "get the id of every order\n\nJSON sample:\n{\"orders\": [{\"id\": 1, \"status\": \"done\"}]}"}
  ],
  "temperature": 0
}'

In LM Studio, open this repo via "Use this model".

Files

Q4_K_M was measured and rejected: it preserves in-distribution accuracy but breaks exactly the hard compositions. Small models do not survive aggressive quantization unharmed — we measured instead of assuming, and we don't publish what failed the gate.

Prompt format

ChatML (the chat template is embedded in the GGUF). The contract has two parts:

• system: You translate natural-language requests into jq filters. Reply with only the jq filter.
• user: the request, then a blank line, then JSON sample: and a sample of the JSON you want to query.

The JSON sample is mandatory. The model was trained to read field names and shapes from it — without a sample it will hallucinate fields. A truncated sample is fine as long as it shows the structure you are asking about.

Examples

All examples below were run against the published Q8_0 GGUF and verified by executing the generated filter with real jq. Input JSON:

{"orders": [{"id": 1, "status": "done", "total": 120.5},
            {"id": 2, "status": "pending", "total": 40.0}]}

The model conditions on the JSON sample, so the same request over a differently shaped document correctly yields a different filter.

Bonus — Brazilian Portuguese: the model was trained bilingually (EN/PT-BR 50/50), so requests like "some o total de todos os pedidos" work out of the box, as shown above. English remains the primary interface and documentation language.

How it was trained

Reverse generation with ground truth by execution — the training data was never written by an LLM guessing jq:

1. A grammar of 148 program families, anchored in real-world usage (top-voted StackOverflow [jq] questions, the llm-jq / jiq / gpt-jq corpora, the official jq manual), samples candidate programs.
2. Each program is executed with real jq 1.8 against families of synthetic JSON documents — the output is the ground truth, for free.
3. Three quality guards filter the pairs: (G1) non-degeneracy (exit 0, non-empty, non-constant output across distinct documents), (G2) coverage anchored in real corpora, (G3) NL↔program consistency via round-trip with an independent second model.
4. Only then does a teacher LLM write the natural-language request (the cheap, safe part). Teachers are locally served open-weights models (Apache 2.0, distillation permitted).

Result: 36,879 verified pairs, bilingual EN/PT-BR 50/50, full fine-tune (not LoRA) of Qwen3-0.6B-Base.

Evaluation

All metrics are computed by execution: the generated filter runs against held-out JSON documents and the canonical output (jq -cS) is diffed against gold. No LLM-as-judge anywhere.

jq-bench (ours — human slice of 30 real StackOverflow tasks)

¹ strict = byte-identical to gold after canonicalization; task-solved additionally accepts equivalent output shapes (stream vs. array wrapper, etc.).

nl2jq-bench (external, frozen, 400 items)

On nl2jq-bench v1.0.0 — an independent frozen benchmark by another author, evaluated one-shot with greedy decoding per its protocol — v14 scores pass@1 0.305, valid@1 0.778 (tiers: T1 0.53 · T2 0.38 · T3 0.28 · T4 0.24 · T5 0.083). The T5 gap is honest and diagnosed: that tier is built from constructs (reduce, foreach, recursive .., update-assignment) that our v14 training grammar does not cover yet — they are the target of the next data iteration.

Two internal diagnostics of ~200 realistic probes each (execution-verified, authored independently of the training pipeline) track progress across data iterations: the v14 iteration scores 63.7% on the older set (v13: 52.5%; v12: 31.4%) and 50.0% on a fresh, fully independent set (v13: 32.0%). The human slice remains the canonical metric.

Honest limitations

• Long compositions still fail (~2/3 of the human slice): array subtraction (. - [...]), to_entries with object reconstruction + tonumber, compound merges with del, recursive descent (..). The model interpolates between neighboring compositions it saw in training; requests far from everything it saw come out wrong or hallucinated. (v14 added any/all, filtered aggregations and conditional field derivation — those now work in typical shapes but still break inside longer chains.)
• Aggregations under nested fields can come out as listings instead of sums.
• The request must mention fields by their real names in the JSON; the JSON sample in the prompt is mandatory.
• English and Brazilian Portuguese only.
• It generates filters, not shell invocations: no -r/-s/--arg handling.

Always review generated filters before running them against data you care about — especially destructive ones (del, assignments).

License and attribution

• Model weights: CC BY 4.0. Commercial use welcome. If you share the weights or a derivative (re-hosts, quantizations, further fine-tunes), credit Edelmar Schneider, link back to this page, and indicate changes. The base model, Qwen/Qwen3-0.6B-Base, is Apache 2.0 and its notices are retained.
• jq-bench (evaluation dataset): CC BY-SA 4.0, with per-item attribution (StackOverflow URL / author / votes).

If this model or benchmark is useful in your work, please cite:

@misc{jqcoder2026,
  title   = {jq-coder: a 0.6B offline natural-language-to-jq model and jq-bench},
  author  = {Edelmar Schneider},
  year    = {2026},
  url     = {https://huggingface.co/DominuZ/jq-coder-0.6B}
}