Upload README.md with huggingface_hub

README.md

@@ -0,0 +1,173 @@
+---
+license: cc-by-4.0
+language:
+  - en
+  - pt
+base_model: Qwen/Qwen3-0.6B-Base
+pipeline_tag: text-generation
+tags:
+  - jq
+  - json
+  - code-generation
+  - text-to-code
+  - gguf
+  - qwen3
+---
+
+# jq-coder-0.6B
+
+**Translates natural-language requests (English + Brazilian Portuguese) into executable
+`jq` filters — 100% offline.** For the JSON you can't send to a cloud API: production
+payloads, logs with PII, anything under NDA.
+
+Every existing NL→jq tool (llm-jq, gpt-jq, jiq) ships your JSON to a hosted LLM. This
+is a 0.6B full fine-tune of Qwen3-0.6B-Base that runs on your own machine — CPU-only is
+fine — and answers in a fraction of a second. To our knowledge it is the first dedicated
+NL→jq model published on Hugging Face, and it ships with the first benchmark of the
+niche, [**jq-bench**](https://huggingface.co/datasets/DominuZ/jq-bench).
+
+## Quickstart
+
+With [llama.cpp](https://github.com/ggml-org/llama.cpp):
+
+```bash
+llama-server -m jq-coder-v13-release-Q8_0.gguf --port 8091 -ngl 99
+```
+
+```bash
+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
+}'
+```
+
+Or with [Ollama](https://ollama.com), straight from this repo:
+
+```bash
+ollama run hf.co/DominuZ/jq-coder-0.6B:Q8_0
+```
+
+## 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:
+
+```json
+{"orders": [{"id": 1, "status": "done", "total": 120.5},
+            {"id": 2, "status": "pending", "total": 40.0}]}
+```
+
+| Request | Generated filter |
+|---|---|
+| get the id of every order | `.orders[] \| .id` |
+| keep only the orders whose status is done | `[.orders[] \| select(.status == "done")]` |
+| some o total de todos os pedidos | `[.orders[].total] \| add` |
+| remova o campo total de cada pedido | `del(.orders[].total)` |
+
+The model conditions on the JSON sample, so the same request over a differently shaped
+document correctly yields a different filter.
+
+## 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 **108 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: **27,480 verified pairs**, bilingual EN/PT-BR 50/50, full fine-tune (not LoRA)
+of Qwen3-0.6B-Base.
+
+## Evaluation — jq-bench
+
+Both 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.
+
+The human slice of **jq-bench** is 30 real StackOverflow tasks, hand-curated,
+independent of the training grammar, never seen in training (CC BY-SA 4.0, per-item
+attribution).
+
+| Artifact (v13) | human slice, strict | human slice, task-solved¹ | in-distribution (400) |
+|---|---|---|---|
+| f16 | 9/30 | 10/30 | 394/400 |
+| **Q8_0 (recommended)** | **9/30** | **10/30** | **394/400** |
+
+¹ *strict* = byte-identical to gold after canonicalization; *task-solved* additionally
+accepts equivalent output shapes (stream vs. array wrapper, etc.).
+
+An internal diagnostic of 204 realistic probes (execution-verified, authored
+independently of the training pipeline) measured the last data iteration at **52.5%**
+(up from 31.4%), with transformations under nested fields going from 12.5% to 54%. The
+human slice remains the canonical metric.
+
+## Quantization
+
+**Q8_0 matches f16 on every metric** and is the recommended build (~640 MB).
+
+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.
+
+## Honest limitations
+
+- **Long compositions fail** (~2/3 of the human slice): `all(...)`, array subtraction
+  (`. - [...]`), `to_entries` with object reconstruction + `tonumber`, compound merges
+  with `del`. The model interpolates between neighboring compositions it saw in
+  training; requests far from everything it saw come out wrong or hallucinated.
+- 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](https://huggingface.co/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:
+
+```bibtex
+@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}
+}
+```