Card: SEO (H1 com keywords, model-index, Ollama primeiro, tabela de arquivos, navegacao do projeto)

README.md

@@ -5,30 +5,105 @@ language:
   - pt
 base_model: Qwen/Qwen3-0.6B-Base
 pipeline_tag: text-generation
+library_name: gguf
+inference: false
+quantized_by: Edelmar Schneider
 tags:
   - jq
   - json
+  - text-to-jq
+  - natural-language-to-code
   - code-generation
   - text-to-code
   - gguf
   - qwen3
+  - ollama
+  - llama.cpp
+  - offline
+  - privacy
+  - structured-data
+  - portuguese
+metrics:
+  - pass@1
+model-index:
+  - name: jq-coder-0.6B
+    results:
+      - task:
+          type: text-generation
+          name: Natural language to jq
+        dataset:
+          type: DominuZ/jq-bench
+          name: jq-bench (human slice, 30 real StackOverflow tasks)
+          split: test
+        metrics:
+          - type: pass@1
+            name: pass@1 strict (execution-verified)
+            value: 0.333
+            verified: false
+          - type: pass@1
+            name: pass@1 task-solved (execution-verified)
+            value: 0.367
+            verified: false
+      - task:
+          type: text-generation
+          name: Natural language to jq
+        dataset:
+          type: gauthierpiarrette/nl2jq-bench
+          name: nl2jq-bench v1.0.0 (external, frozen, 400 items)
+          split: test
+        metrics:
+          - type: pass@1
+            name: pass@1 (execution-verified, one-shot)
+            value: 0.305
+            verified: false
 ---
 
-# jq-coder-0.6B
+# jq-coder-0.6B — Natural Language to jq, 100% Offline (GGUF)
 
-**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.
+*Part of the **jq-coder** project — [all artifacts](https://huggingface.co/collections/DominuZ/jq-coder-natural-language-to-jq-offline-6a582d4af58d35f838b45d80) ·
+[`jqc` CLI (prebuilt binaries)](https://github.com/EdelmarSchneider/jq-coder-cli) ·
+[jq-bench benchmark](https://huggingface.co/datasets/DominuZ/jq-bench)*
 
-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).
+**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`](https://jqlang.org/) 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.
 
-## Quickstart
+To our knowledge it is the **first NL→jq model with GGUF builds on Hugging Face**. It
+ships with [**jq-bench**](https://huggingface.co/datasets/DominuZ/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).
 
-With [llama.cpp](https://github.com/ggml-org/llama.cpp):
+## Model overview
+
+| | |
+|---|---|
+| Parameters | 0.6B (full fine-tune of Qwen3-0.6B-Base) |
+| Recommended file | `jq-coder-v14-release-Q8_0.gguf` (~640 MB) |
+| Runs on | CPU-only is fine; any llama.cpp-compatible runtime |
+| Context | 4k used in practice (request + JSON sample) |
+| Languages | English + Brazilian Portuguese |
+| Output | one executable jq filter, nothing else |
+
+## Quickstart — 10 seconds with Ollama
+
+```bash
+ollama run hf.co/DominuZ/jq-coder-0.6B:Q8_0
+```
+
+## Or the `jqc` CLI — one binary, batteries included
+
+Prebuilt binaries for Windows, Linux and macOS (Apple Silicon) on the
+[Releases page](https://github.com/EdelmarSchneider/jq-coder-cli/releases). It embeds
+llama.cpp and runs the generated filter for you; the model downloads on first use.
+
+```bash
+jqc "get the id of every order" orders.json
+```
+
+## Or llama.cpp / LM Studio
 
 ```bash
 llama-server -m jq-coder-v14-release-Q8_0.gguf --port 8091 -ngl 99
@@ -46,13 +121,19 @@ curl -s http://127.0.0.1:8091/v1/chat/completions -d '{
 }'
 ```
 
-Or with [Ollama](https://ollama.com), straight from this repo:
+In [LM Studio](https://lmstudio.ai/), open this repo via "Use this model".
 
-```bash
-ollama run hf.co/DominuZ/jq-coder-0.6B:Q8_0
-```
+## Files
 
-Or use the [**Standalone CLI Tool + Code**](https://github.com/EdelmarSchneider/jq-coder-cli)
+| File | Size | Verdict |
+|---|---|---|
+| [jq-coder-v14-release-Q8_0.gguf](https://huggingface.co/DominuZ/jq-coder-0.6B/resolve/main/jq-coder-v14-release-Q8_0.gguf) | ~640 MB | **Recommended** — matches f16 on every metric (measured, not assumed) |
+| [jq-coder-v14-release-f16.gguf](https://huggingface.co/DominuZ/jq-coder-0.6B/resolve/main/jq-coder-v14-release-f16.gguf) | ~1.2 GB | Reference precision |
+| jq-coder-v13-release-{Q8_0,f16}.gguf | | Legacy (previous release, kept for pinned revisions) |
+
+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
 
@@ -86,6 +167,10 @@ the generated filter with real jq. Input JSON:
 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
@@ -107,15 +192,13 @@ written by an LLM guessing jq:
 Result: **36,879 verified pairs**, bilingual EN/PT-BR 50/50, full fine-tune (not LoRA)
 of Qwen3-0.6B-Base.
 
-## Evaluation — jq-bench
+## Evaluation
 
-Both metrics are computed **by execution**: the generated filter runs against held-out
+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.
 
-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).
+### jq-bench (ours — human slice of 30 real StackOverflow tasks)
 
 | Artifact (v14) | human slice, strict | human slice, task-solved¹ | in-distribution (400) |
 |---|---|---|---|
@@ -125,22 +208,20 @@ attribution).
 ¹ *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](https://huggingface.co/datasets/gauthierpiarrette/nl2jq-bench)
+— 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 v14 data iteration targeted missing
-*constructs* — `any`/`all`, filtered aggregations, `if-then-else` derived fields,
-mid-level element paths (`.features[].properties.name`), string splitting — after the
-v13 iteration had fixed the dominant envelope/root-shape failures. 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.
+fresh, fully independent set (v13: 32.0%). The human slice remains the canonical metric.
 
 ## Honest limitations