Final 1.0.0 checksum and PDF fix note

README.md

@@ -1,402 +1,403 @@
----
-license: apache-2.0
-language:
-- en
-- multilingual
-base_model:
-- Qwen/Qwen3-1.7B
-base_model_relation: quantized
-library_name: llama.cpp
-pipeline_tag: text-generation
-quantized_by: hkblockchaintechnology
-tags:
-- gguf
-- llama.cpp
-- cpu-inference
-- q4_k_m
-- qwen3
-- offline
-- local-first
-- low-end-hardware
-- document-generation
----
-
-# tiny-agent-gguf
-
-Quantized language models for **Tiny Agent** — a Windows application that gives
-you Word, Excel and PowerPoint with an AI assistant that runs on your own CPU,
-with no GPU, no cloud API and no account.
-
-**The app (1.34 GB):** [Download `TinyAgentSetup-1.0.0.exe`](https://huggingface.co/datasets/hkblockchaintechnology/tiny-agent/resolve/main/releases/TinyAgentSetup-1.0.0.exe)
-([file page](https://huggingface.co/datasets/hkblockchaintechnology/tiny-agent/blob/main/releases/TinyAgentSetup-1.0.0.exe)).
-It is in the **dataset** repository, not this model repository, under
-`releases/`. The file browser does not preview `.exe` files, so use the direct
-link if you cannot see it. SHA-256:
-`fbdaff515097fbd1317e3c9ba169a44a6a3c7a507124793b2e95a7c5a711b735`.
-The installer is not code-signed; Windows SmartScreen may ask you to choose
-**More info -> Run anyway**. A [portable ZIP (1.44 GB)](https://huggingface.co/datasets/hkblockchaintechnology/tiny-agent/resolve/main/releases/TinyAgent-1.0.0-portable.zip)
-is also published, SHA-256
-`0fdf56bd89b1025b8f4f03ace0003b45d46ca80b3949f6a67e67f47ef782a9c0`.
-All files and checksums: [`releases/README.md`](https://huggingface.co/datasets/hkblockchaintechnology/tiny-agent/blob/main/releases/README.md).
-
-This repository supplies the model that installer uses — or that you can point any
-local `llama-server` at.
-
-**The signature idea:** Tiny Agent is an Office-style workspace with the assistant
-present in *every* workflow — **Create, Edit, Polish and Batch** — rather than a
-chat window bolted onto a menu. Every workflow ends in an ordinary `.docx`,
-`.xlsx` or `.pptx` file that real Office applications open, and every edit is
-verified against the file's structure before it is offered to you.
-
-**Release status, 1.0.0 (rebuilt 19 October 2026):** 4/4 AI edits verified; real
-Microsoft Office opened and exported all 4 outputs; 12/12 repeated plans usable;
-56/56 file-level audit checks. The installer was rebuilt after PDF fixes for the
-page tree, list markers, table wrapping/page breaks, and spreadsheet export limits;
-the frozen app, portable ZIP and installer all pass their end-to-end harnesses,
-including a PDF export with real pages and extractable text. Measured comparison:
-[`docs/COMPARISON-REPORT.md`](https://huggingface.co/datasets/hkblockchaintechnology/tiny-agent/blob/main/docs/COMPARISON-REPORT.md).
-
-These files are **quantizations of existing Apache-2.0 models**, not new models.
-Nothing here is fine-tuned: we convert and quantize, so the knowledge, biases
-and limitations are inherited unchanged from the base model.
-
-## TL;DR
-
-| | |
-|---|---|
-| What it is | Qwen3-1.7B converted to GGUF and quantized to 4-bit |
-| What it's for | Filling short, schema-constrained JSON slots in the Tiny Agent pipeline |
-| Licence | Apache-2.0 — free to redistribute with a product |
-| Runs on | CPU only, no GPU. ~1.2 GB RAM for the 4-bit build |
-| Speed | 6.5 tok/s on a 2014-era 4-core desktop; **11.5 tok/s** with speculative decoding |
-| Not for | Being asked to "write me a report" in a single prompt |
-
-## Files in this repository
-
-| File | Size | What it is |
-|---|---|---|
-| `qwen3-1.7b-Q4_K_M.gguf` | **1.28 GB** | the default model |
-| `qwen3-0.6b-Q4_K_M.gguf` | **0.48 GB** | smaller and roughly 2x faster |
-| `qwen3-1.7b-eagle3.gguf` | **0.28 GB** | EAGLE3 speculative draft for the 1.7B model |
-
-Sizes are the real blob sizes, not estimates. All three are Apache-2.0 and safe
-to redistribute inside a product.
-
-SHA-256, for verifying a download:
-
-| File | SHA-256 |
-|---|---|
-| `qwen3-1.7b-Q4_K_M.gguf` | `245362960ec00bfe277c0e06ba9811a5f1a580f6238d3bc50b6fd3a82f031051` |
-| `qwen3-0.6b-Q4_K_M.gguf` | `e4c97785c11e2d8547a54fe104f4bedcdf3358d7e95d3f36876ed6caa96ab851` |
-| `qwen3-1.7b-eagle3.gguf` | `7fd1b0338f7790fa1f8b372ee72060162c4db74e4efbd89f5b28ebb9a01b4c0b` |
-
-## What it can do
-
-Measured by actually running it — these are observed behaviours, not claims:
-
-| Task | Verdict | Notes |
-|---|---|---|
-| Return strictly valid JSON matching a schema | ✅ reliable | Enforced by a llama.cpp grammar, so it is structurally impossible to emit malformed JSON |
-| Plan a document outline (3–6 sections) | ✅ reliable | Produces sensible, ordered headings |
-| Write 1–3 paragraphs of grammatical prose on a topic | ✅ good | Coherent and readable; occasionally generic |
-| Condense source material into 3–5 short bullets | ✅ good | Best when given explicit research notes |
-| Follow small constraints ("under 12 words", "no markdown") | ✅ usually | Occasionally needs the constraint repeated |
-| Write a *whole* multi-page document in one pass | ❌ no | It drifts, repeats and loses structure — see the design note below |
-| Be factually accurate from memory alone | ❌ no | It will invent plausible specifics. Grounding in retrieved text is what makes output trustworthy |
-| Do arithmetic, analysis or comparisons | ❌ no | Use Python for that |
-| Cite its sources unprompted | ❌ no | Citations are attached by the pipeline, not the model |
-| Keep a consistent voice across many sections | ⚠️ partial | Sections are generated independently, so tone can drift |
-
-## Where the assistant sits: every workflow, not a chat box
-
-The model is one component of an Office-style application, and the interface is
-built so the assistant is available at each step rather than in a separate tab:
-
-| Surface | The user does | The model does | Plain Python does |
-|---|---|---|---|
-| **Create** | writes a paragraph brief | plans the outline and short text slots | styles, tables, charts, pagination, file writing |
-| **Edit** | opens an existing file and says what changes | returns only the allowed replacement/row/slide groups | applies them to a copy and fingerprints the result |
-| **Polish** | asks for a review | offers editorial suggestions | finds empty slides, blank cells and other mechanical defects |
-| **Batch** | writes one instruction and selects files | plans each file independently | applies, verifies and reports per file |
-
-That is the signature of the product: **an Office workspace with AI in every
-workflow**, not an assistant that produces text for a human to paste. The local
-model is deliberately small because the surrounding code owns structure, file
-format and verification.
-
-## Why this model, and not something bigger
-
-Tested rather than assumed. Six CPU-sized models were run through the real
-pipeline against identical frozen research notes, and scored on how faithfully
-they filled the JSON slots:
-
-| model | grounding | repetition | verdict |
-|---|---|---|---|
-| **qwen3:1.7b** | **0.460** | 0.065 | **best of the six** |
-| phi4-mini:3.8b | 0.375 | 0.062 | slower, grounded less |
-| granite4:micro | 0.353 | 0.050 | worst instruction-following on shape |
-| qwen3:4b | 0.327 | **0.128** | 2.4x the parameters, worst repetition |
-| qwen3:0.6b | 0.213 | 0.000 | thin, but ~2.4x faster |
-| llama3.2:3b | 0.562* | 0.000 | failed: 2 sections, 118 words, stopped |
-
-*\*tiny-sample artefact; it returned the wrong shape.*
-
-`Qwen3-1.7B` grounds retrieved facts best while staying fastest of the
-faithful options. On this hardware the bottleneck is **tokens per second, not
-parameters of world knowledge**, so a larger model buys nothing measurable and
-costs multiples of the time per document. Full method and raw data:
-[`docs/MODEL-BENCH.md`](https://huggingface.co/datasets/hkblockchaintechnology/tiny-agent/blob/main/docs/MODEL-BENCH.md).
-
-## How Tiny Agent uses it
-
-The model is never asked to write a document, and it never touches a file. It is
-asked one small question at a time, and deterministic Python assembles the result:
-
-```
- 1. route    which KINDS of change could this instruction need?
-             (replacements | newHeadings | newParagraphs | rows | totals
-              | slides | charts | theme)                    <- deterministic
- 2. plan     the model fills ONLY those slots, JSON enforced by a llama.cpp
-             grammar, so a malformed plan is structurally impossible
- 3. apply    python-docx / openpyxl / python-pptx write a NEW file  <- deterministic
- 4. verify   fingerprint the file before and after, and report anything that
-             changed WITHOUT being asked                      <- deterministic
-```
-
-Step 1 is what makes a model this size dependable: rather than a flat form with
-eight optional sections to wander around, it is handed only the two or three the
-instruction actually needs. Steps 3 and 4 mean its output can be *checked* rather
-than trusted, which is the difference between a demo and a tool you would point at
-real work.
-
-Measured with the real model in the product pipeline:
-
-| Run | Result |
-|---|---|
-| Competitive benchmark, i5-7200U (2 cores / 4 threads, 8 GB, no GPU) | **4 of 4** tasks verified; **13.8–34.5 s**, mean **19.8 s** |
-| Real Microsoft Office opened the four outputs | **4 of 4**, no repair step |
-| Real Microsoft Office exported them to PDF | **4 of 4**, content intact |
-| Repeatability harness, reference hardware | **12 of 12** plans produced a usable document (3 runs each of a Word edit, a spreadsheet edit, a deck edit and a new Word table) |
-| Warm plan | **2.5–5 s** typical; slowest measured 27 s (new Word table) |
-
-The detailed head-to-head, including where Office and WPS win, is in
-[`docs/COMPARISON-REPORT.md`](https://huggingface.co/datasets/hkblockchaintechnology/tiny-agent/blob/main/docs/COMPARISON-REPORT.md).
-
-One measured failure worth publishing, because it is the kind of thing a card
-usually leaves out: offered a single optional group, this model answered with prose
-in `summary` and left the group empty — twice in a row, on every run. Naming the
-group in the retry prompt did not fix it; making that one group **required** in the
-retry grammar did, immediately. That is the whole design thesis in one incident:
-the fix belongs in the shape of the output, not in the politeness of the request.
-
-Each step is a JSON-schema-constrained call. For example, a plan's contract is
-handed to llama.cpp as a grammar, so the shape is enforced by the decoder rather
-than requested in the prompt:
-
-```json
-{
-  "type": "object",
-  "properties": {
-    "newParagraphs": {
-      "type": "array",
-      "minItems": 1,
-      "items": {"type": "string"}
-    }
-  },
-  "required": ["newParagraphs"]
-}
-```
-
-That is why a 1.7B model is usable for a real task: structure, formatting, file
-writing and verification are handled by code, and the model only supplies short
-strings where a small model is genuinely competent.
-
-## Hardware and measured speed
-
-Reference machine — deliberately weak, and the actual development target:
-
-| | |
-|---|---|
-| CPU | Intel Core i5-4460 (Haswell, 4 cores / 4 threads, AVX2) |
-| RAM | 16 GB DDR3-1333 |
-| GPU | none used |
-| Storage | 7200 rpm HDD |
-
-| Model | File size | Cold load | **Generation** |
-|---|---|---|---|
-| Qwen3-1.7B Q4_K_M | 1.28 GB | ~13 s | **6.50 tok/s** |
-| Qwen3-1.7B Q4_K_M **+ n-gram speculation** | 1.28 GB | ~13 s | **11.46 tok/s** (1.76x) |
-| Qwen3-1.7B Q4_K_M + EAGLE3 draft | +0.28 GB | ~13 s | **4.00 tok/s — slower**, see below |
-| Qwen3-0.6B Q4_K_M | 0.48 GB | ~6 s | ~24 tok/s (measured via Ollama) |
-
-The generation figures were measured with the exact CPU-only `llama.cpp` build
-that ships in the product, 4 threads, a 4096-token context and a 220-token
-budget. The n-gram row is the mean of repeat runs on the same request.
-
-### What that means in practice
-
-Measured end to end on the shipped runtime, web research enabled, 11 sources
-retrieved:
-
-| Job | Wall clock |
-|---|---|
-| 3-section researched Word report | **202 s** |
-| 3-slide deck | ~112 s |
-
-The effective rate is well below the raw tokens/second because prompt
-processing over injected research context dominates, and every job makes
-several calls in sequence. That is why the interface streams progress: two to
-four minutes is perfectly acceptable for a "generate document" button, but only
-if the user can see which stage is running.
-
-### Speculative decoding is not optional on a CPU
-
-Speculative decoding drafts several tokens cheaply and verifies them in one
-forward pass of the real model. On a CPU — where a forward pass is expensive and
-a batch is comparatively cheap — this is the single largest speedup available,
-and it costs nothing in output quality.
-
-`llama-server -m qwen3-1.7b-Q4_K_M.gguf --spec-type ngram-mod` needs **no extra
-download** and measured **6.50 → 11.46 tok/s**. It mines repeated token patterns
-from the context, so it is a *warm-session* win: the first request of a session
-gains almost nothing (7.33 tok/s) and the third reaches 11.46 tok/s as the
-shared hash pool fills. That suits a document generator exactly, because a job
-is several calls in a row sharing a long system prompt and emitting repetitive
-JSON.
-
-EAGLE3 is the theoretically stronger option: a one-layer draft that reads the
-target model's hidden states and should therefore achieve a much higher
-acceptance rate. This repo ships `qwen3-1.7b-eagle3.gguf` and it is used like
-this:
-
-```bash
-llama-server -m qwen3-1.7b-Q4_K_M.gguf -md qwen3-1.7b-eagle3.gguf \
-    --spec-type draft-eagle3 --spec-draft-n-max 8
-```
-
-**It measured slower on a CPU, and this card will not pretend otherwise.**
-
-| Configuration | Speed | Draft acceptance |
-|---|---|---|
-| No speculation | 6.50 tok/s | — |
-| n-gram (`ngram-mod`) | **11.46 tok/s** | 0.53 (warm) |
-| EAGLE3 draft | **4.00 tok/s** | 0.089 |
-
-Acceptance was only 8.9%, and the draft shares the same 4 physical cores as the
-target, so it steals more throughput than it saves. EAGLE3 is a large win on a
-GPU — where the tiny draft runs nearly free beside the target — and a
-regression on a 4-thread CPU.
-
-This was re-checked on a much faster machine (a 20-core server CPU running
-CPU-only, 4 threads) using our own converted GGUF: baseline 21.90 tok/s, n-gram
-21.60 tok/s on a cold single run, EAGLE3 **16.30 tok/s (0.74x)**. So EAGLE3 is
-slower regardless of target conversion, and n-gram's benefit genuinely depends
-on a warm, repetitive session — which is the normal case for this tool.
-
-**Prefer n-gram speculation on CPU; treat the EAGLE3 file as an experiment.**
-
-Practical consequences:
-
-* **Cold load costs ~13 s on a spinning disk.** Keep the model resident between
-  requests rather than reloading per call.
-* Use one thread per *physical* core. More threads than physical cores is slower.
-* Qwen3 is a reasoning model. Left alone it spends most of its budget on hidden
-  thinking tokens, so **disable thinking** (`think=false`, or
-  `chat_template_kwargs={"enable_thinking": false}`).
-* A grounded 3-section report takes ~140 s end to end. That is acceptable for a
-  "generate document" button, but only with progress reporting.
-
-## Quick start
-
-**llama.cpp server** (OpenAI-compatible, supports JSON-schema constrained output):
-
-```bash
-llama-server -m qwen3-1.7b-Q4_K_M.gguf -c 4096 -t 4 --port 8080
-```
-
-**llama.cpp CLI:**
-
-```bash
-llama-cli -m qwen3-1.7b-Q4_K_M.gguf -c 4096 -t 4 \
-  -p "Return only JSON: {\"heading\": str, \"paragraphs\": [str]} for a section about heat pumps."
-```
-
-**Ollama** (optional — the product does not need it):
-
-```bash
-ollama pull hf.co/hkblockchaintechnology/tiny-agent-gguf
-```
-
-The official CPU-only `llama.cpp` Windows release is an **18.8 MB** zip (a 46 MB
-folder unpacked) and needs no GPU, CUDA toolkit or Python environment — that is
-the intended way to ship this.
-
-## Prompting notes for a model this size
-
-1. **One question per call.** Asking for several things at once is where small
-   models fall apart.
-2. **Constrain the output shape.** Use a JSON schema or GBNF grammar. It removes
-   an entire class of parsing failures.
-3. **Disable thinking.** Qwen3 will otherwise spend its whole budget reasoning.
-4. **Give it the facts.** Put retrieved text in the prompt; it cannot supply
-   accurate specifics from memory.
-5. **Ask for less text.** 2–3 short paragraphs per section works; "write a
-   detailed 2000-word report" does not.
-6. **Expect and clean up artefacts.** It adds list numbering to headings and
-   sometimes leaks markdown into prose fields. Strip these deterministically
-   during assembly rather than fighting them with prompt wording.
-
-## Limitations
-
-* **Hallucination.** Without grounding, specifics (figures, dates, product
-  names) are unreliable and often invented. Tiny Agent mitigates this by injecting
-  retrieved web text and attaching a source list, but it does not eliminate it.
-* **Inherited knowledge cutoff and biases.** Because this is a quantization, the
-  base model's training data, cutoff and biases apply unchanged.
-* **Language.** The base model is multilingual, but the pipeline prompts and all
-  validation were done in English.
-* **Repetition.** Sections written in separate calls sometimes restate the same
-  point. Human editing is expected.
-* **Not a general chat model.** It is tuned here for structured slot-filling, not
-  for open-ended conversation.
-* **Quantization degrades quality slightly** versus the full-precision base
-  model. 4-bit is the point where quality and speed balance best on this class
-  of hardware.
-
-## Training data
-
-No training or fine-tuning was performed. This repository contains quantized
-conversions of:
-
-* [`Qwen/Qwen3-1.7B`](https://huggingface.co/Qwen/Qwen3-1.7B)
-* [`Qwen/Qwen3-0.6B`](https://huggingface.co/Qwen/Qwen3-0.6B)
-
-and a converted speculative draft:
-
-* [`AngelSlim/Qwen3-1.7B_eagle3`](https://huggingface.co/AngelSlim/Qwen3-1.7B_eagle3)
-  (Apache-2.0, Tencent AngelSlim) — converted to GGUF with
-  `convert_hf_to_gguf.py --target-model-dir Qwen/Qwen3-1.7B`. It is a *draft*
-  model: it proposes tokens that the 1.7B model verifies, and it never changes
-  the output, only the speed. It cannot be used on its own.
-
-Refer to the base model cards for training data, evaluation results and
-limitations.
-
-Why these models: both are **Apache-2.0**, so they can be redistributed with a
-commercial product without additional conditions. Llama, Gemma and several other
-otherwise-capable small models are deliberately **not** bundled, because their
-licences carry redistribution terms that are unsuitable for shipping to end
-users.
-
-## License and attribution
-
-Apache-2.0, inherited from the base models. Copyright in the base weights
-belongs to the Qwen team; these are derivative quantizations redistributed under
-the same licence.
-
-## Related
-
-* Project source, benchmarks and generated documents: [`hkblockchaintechnology/tiny-agent`](https://huggingface.co/datasets/hkblockchaintechnology/tiny-agent)
-* Windows installer (1.34 GB, in the dataset repository): [`TinyAgentSetup-1.0.0.exe`](https://huggingface.co/datasets/hkblockchaintechnology/tiny-agent/resolve/main/releases/TinyAgentSetup-1.0.0.exe)
-* User guide: [`TinyAgent-UserGuide.pdf`](https://huggingface.co/datasets/hkblockchaintechnology/tiny-agent/blob/main/docs/TinyAgent-UserGuide.pdf)
-* Measured comparison with Microsoft Office and WPS Office: [`COMPARISON-REPORT.md`](https://huggingface.co/datasets/hkblockchaintechnology/tiny-agent/blob/main/docs/COMPARISON-REPORT.md)
+---
+license: apache-2.0
+language:
+- en
+- multilingual
+base_model:
+- Qwen/Qwen3-1.7B
+base_model_relation: quantized
+library_name: llama.cpp
+pipeline_tag: text-generation
+quantized_by: hkblockchaintechnology
+tags:
+- gguf
+- llama.cpp
+- cpu-inference
+- q4_k_m
+- qwen3
+- offline
+- local-first
+- low-end-hardware
+- document-generation
+---
+
+# tiny-agent-gguf
+
+Quantized language models for **Tiny Agent** — a Windows application that gives
+you Word, Excel and PowerPoint with an AI assistant that runs on your own CPU,
+with no GPU, no cloud API and no account.
+
+**The app (1.34 GB):** [Download `TinyAgentSetup-1.0.0.exe`](https://huggingface.co/datasets/hkblockchaintechnology/tiny-agent/resolve/main/releases/TinyAgentSetup-1.0.0.exe)
+([file page](https://huggingface.co/datasets/hkblockchaintechnology/tiny-agent/blob/main/releases/TinyAgentSetup-1.0.0.exe)).
+It is in the **dataset** repository, not this model repository, under
+`releases/`. The file browser does not preview `.exe` files, so use the direct
+link if you cannot see it. SHA-256:
+`8f6f5ac3d01464ba7e1c2e4ae1ebb270a1559c26d0f94a29ae5572f067cf2503`.
+The installer is not code-signed; Windows SmartScreen may ask you to choose
+**More info -> Run anyway**. A [portable ZIP (1.44 GB)](https://huggingface.co/datasets/hkblockchaintechnology/tiny-agent/resolve/main/releases/TinyAgent-1.0.0-portable.zip)
+is also published, SHA-256
+`82c0afa4e00d85e719c08194410858579b28e8df0646c71c6b52da28941f2419`.
+All files and checksums: [`releases/README.md`](https://huggingface.co/datasets/hkblockchaintechnology/tiny-agent/blob/main/releases/README.md).
+
+This repository supplies the model that installer uses — or that you can point any
+local `llama-server` at.
+
+**The signature idea:** Tiny Agent is an Office-style workspace with the assistant
+present in *every* workflow — **Create, Edit, Polish and Batch** — rather than a
+chat window bolted onto a menu. Every workflow ends in an ordinary `.docx`,
+`.xlsx` or `.pptx` file that real Office applications open, and every edit is
+verified against the file's structure before it is offered to you.
+
+**Release status, 1.0.0 (rebuilt 19 October 2026):** 4/4 AI edits verified; real
+Microsoft Office opened and exported all 4 outputs; 12/12 repeated plans usable;
+56/56 file-level audit checks. The installer was rebuilt after PDF fixes for the
+page tree, list markers, table wrapping/page breaks, headerless/empty tables, and
+spreadsheet export limits;
+the frozen app, portable ZIP and installer all pass their end-to-end harnesses,
+including a PDF export with real pages and extractable text. Measured comparison:
+[`docs/COMPARISON-REPORT.md`](https://huggingface.co/datasets/hkblockchaintechnology/tiny-agent/blob/main/docs/COMPARISON-REPORT.md).
+
+These files are **quantizations of existing Apache-2.0 models**, not new models.
+Nothing here is fine-tuned: we convert and quantize, so the knowledge, biases
+and limitations are inherited unchanged from the base model.
+
+## TL;DR
+
+| | |
+|---|---|
+| What it is | Qwen3-1.7B converted to GGUF and quantized to 4-bit |
+| What it's for | Filling short, schema-constrained JSON slots in the Tiny Agent pipeline |
+| Licence | Apache-2.0 — free to redistribute with a product |
+| Runs on | CPU only, no GPU. ~1.2 GB RAM for the 4-bit build |
+| Speed | 6.5 tok/s on a 2014-era 4-core desktop; **11.5 tok/s** with speculative decoding |
+| Not for | Being asked to "write me a report" in a single prompt |
+
+## Files in this repository
+
+| File | Size | What it is |
+|---|---|---|
+| `qwen3-1.7b-Q4_K_M.gguf` | **1.28 GB** | the default model |
+| `qwen3-0.6b-Q4_K_M.gguf` | **0.48 GB** | smaller and roughly 2x faster |
+| `qwen3-1.7b-eagle3.gguf` | **0.28 GB** | EAGLE3 speculative draft for the 1.7B model |
+
+Sizes are the real blob sizes, not estimates. All three are Apache-2.0 and safe
+to redistribute inside a product.
+
+SHA-256, for verifying a download:
+
+| File | SHA-256 |
+|---|---|
+| `qwen3-1.7b-Q4_K_M.gguf` | `245362960ec00bfe277c0e06ba9811a5f1a580f6238d3bc50b6fd3a82f031051` |
+| `qwen3-0.6b-Q4_K_M.gguf` | `e4c97785c11e2d8547a54fe104f4bedcdf3358d7e95d3f36876ed6caa96ab851` |
+| `qwen3-1.7b-eagle3.gguf` | `7fd1b0338f7790fa1f8b372ee72060162c4db74e4efbd89f5b28ebb9a01b4c0b` |
+
+## What it can do
+
+Measured by actually running it — these are observed behaviours, not claims:
+
+| Task | Verdict | Notes |
+|---|---|---|
+| Return strictly valid JSON matching a schema | ✅ reliable | Enforced by a llama.cpp grammar, so it is structurally impossible to emit malformed JSON |
+| Plan a document outline (3–6 sections) | ✅ reliable | Produces sensible, ordered headings |
+| Write 1–3 paragraphs of grammatical prose on a topic | ✅ good | Coherent and readable; occasionally generic |
+| Condense source material into 3–5 short bullets | ✅ good | Best when given explicit research notes |
+| Follow small constraints ("under 12 words", "no markdown") | ✅ usually | Occasionally needs the constraint repeated |
+| Write a *whole* multi-page document in one pass | ❌ no | It drifts, repeats and loses structure — see the design note below |
+| Be factually accurate from memory alone | ❌ no | It will invent plausible specifics. Grounding in retrieved text is what makes output trustworthy |
+| Do arithmetic, analysis or comparisons | ❌ no | Use Python for that |
+| Cite its sources unprompted | ❌ no | Citations are attached by the pipeline, not the model |
+| Keep a consistent voice across many sections | ⚠️ partial | Sections are generated independently, so tone can drift |
+
+## Where the assistant sits: every workflow, not a chat box
+
+The model is one component of an Office-style application, and the interface is
+built so the assistant is available at each step rather than in a separate tab:
+
+| Surface | The user does | The model does | Plain Python does |
+|---|---|---|---|
+| **Create** | writes a paragraph brief | plans the outline and short text slots | styles, tables, charts, pagination, file writing |
+| **Edit** | opens an existing file and says what changes | returns only the allowed replacement/row/slide groups | applies them to a copy and fingerprints the result |
+| **Polish** | asks for a review | offers editorial suggestions | finds empty slides, blank cells and other mechanical defects |
+| **Batch** | writes one instruction and selects files | plans each file independently | applies, verifies and reports per file |
+
+That is the signature of the product: **an Office workspace with AI in every
+workflow**, not an assistant that produces text for a human to paste. The local
+model is deliberately small because the surrounding code owns structure, file
+format and verification.
+
+## Why this model, and not something bigger
+
+Tested rather than assumed. Six CPU-sized models were run through the real
+pipeline against identical frozen research notes, and scored on how faithfully
+they filled the JSON slots:
+
+| model | grounding | repetition | verdict |
+|---|---|---|---|
+| **qwen3:1.7b** | **0.460** | 0.065 | **best of the six** |
+| phi4-mini:3.8b | 0.375 | 0.062 | slower, grounded less |
+| granite4:micro | 0.353 | 0.050 | worst instruction-following on shape |
+| qwen3:4b | 0.327 | **0.128** | 2.4x the parameters, worst repetition |
+| qwen3:0.6b | 0.213 | 0.000 | thin, but ~2.4x faster |
+| llama3.2:3b | 0.562* | 0.000 | failed: 2 sections, 118 words, stopped |
+
+*\*tiny-sample artefact; it returned the wrong shape.*
+
+`Qwen3-1.7B` grounds retrieved facts best while staying fastest of the
+faithful options. On this hardware the bottleneck is **tokens per second, not
+parameters of world knowledge**, so a larger model buys nothing measurable and
+costs multiples of the time per document. Full method and raw data:
+[`docs/MODEL-BENCH.md`](https://huggingface.co/datasets/hkblockchaintechnology/tiny-agent/blob/main/docs/MODEL-BENCH.md).
+
+## How Tiny Agent uses it
+
+The model is never asked to write a document, and it never touches a file. It is
+asked one small question at a time, and deterministic Python assembles the result:
+
+```
+ 1. route    which KINDS of change could this instruction need?
+             (replacements | newHeadings | newParagraphs | rows | totals
+              | slides | charts | theme)                    <- deterministic
+ 2. plan     the model fills ONLY those slots, JSON enforced by a llama.cpp
+             grammar, so a malformed plan is structurally impossible
+ 3. apply    python-docx / openpyxl / python-pptx write a NEW file  <- deterministic
+ 4. verify   fingerprint the file before and after, and report anything that
+             changed WITHOUT being asked                      <- deterministic
+```
+
+Step 1 is what makes a model this size dependable: rather than a flat form with
+eight optional sections to wander around, it is handed only the two or three the
+instruction actually needs. Steps 3 and 4 mean its output can be *checked* rather
+than trusted, which is the difference between a demo and a tool you would point at
+real work.
+
+Measured with the real model in the product pipeline:
+
+| Run | Result |
+|---|---|
+| Competitive benchmark, i5-7200U (2 cores / 4 threads, 8 GB, no GPU) | **4 of 4** tasks verified; **13.8–34.5 s**, mean **19.8 s** |
+| Real Microsoft Office opened the four outputs | **4 of 4**, no repair step |
+| Real Microsoft Office exported them to PDF | **4 of 4**, content intact |
+| Repeatability harness, reference hardware | **12 of 12** plans produced a usable document (3 runs each of a Word edit, a spreadsheet edit, a deck edit and a new Word table) |
+| Warm plan | **2.5–5 s** typical; slowest measured 27 s (new Word table) |
+
+The detailed head-to-head, including where Office and WPS win, is in
+[`docs/COMPARISON-REPORT.md`](https://huggingface.co/datasets/hkblockchaintechnology/tiny-agent/blob/main/docs/COMPARISON-REPORT.md).
+
+One measured failure worth publishing, because it is the kind of thing a card
+usually leaves out: offered a single optional group, this model answered with prose
+in `summary` and left the group empty — twice in a row, on every run. Naming the
+group in the retry prompt did not fix it; making that one group **required** in the
+retry grammar did, immediately. That is the whole design thesis in one incident:
+the fix belongs in the shape of the output, not in the politeness of the request.
+
+Each step is a JSON-schema-constrained call. For example, a plan's contract is
+handed to llama.cpp as a grammar, so the shape is enforced by the decoder rather
+than requested in the prompt:
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "newParagraphs": {
+      "type": "array",
+      "minItems": 1,
+      "items": {"type": "string"}
+    }
+  },
+  "required": ["newParagraphs"]
+}
+```
+
+That is why a 1.7B model is usable for a real task: structure, formatting, file
+writing and verification are handled by code, and the model only supplies short
+strings where a small model is genuinely competent.
+
+## Hardware and measured speed
+
+Reference machine — deliberately weak, and the actual development target:
+
+| | |
+|---|---|
+| CPU | Intel Core i5-4460 (Haswell, 4 cores / 4 threads, AVX2) |
+| RAM | 16 GB DDR3-1333 |
+| GPU | none used |
+| Storage | 7200 rpm HDD |
+
+| Model | File size | Cold load | **Generation** |
+|---|---|---|---|
+| Qwen3-1.7B Q4_K_M | 1.28 GB | ~13 s | **6.50 tok/s** |
+| Qwen3-1.7B Q4_K_M **+ n-gram speculation** | 1.28 GB | ~13 s | **11.46 tok/s** (1.76x) |
+| Qwen3-1.7B Q4_K_M + EAGLE3 draft | +0.28 GB | ~13 s | **4.00 tok/s — slower**, see below |
+| Qwen3-0.6B Q4_K_M | 0.48 GB | ~6 s | ~24 tok/s (measured via Ollama) |
+
+The generation figures were measured with the exact CPU-only `llama.cpp` build
+that ships in the product, 4 threads, a 4096-token context and a 220-token
+budget. The n-gram row is the mean of repeat runs on the same request.
+
+### What that means in practice
+
+Measured end to end on the shipped runtime, web research enabled, 11 sources
+retrieved:
+
+| Job | Wall clock |
+|---|---|
+| 3-section researched Word report | **202 s** |
+| 3-slide deck | ~112 s |
+
+The effective rate is well below the raw tokens/second because prompt
+processing over injected research context dominates, and every job makes
+several calls in sequence. That is why the interface streams progress: two to
+four minutes is perfectly acceptable for a "generate document" button, but only
+if the user can see which stage is running.
+
+### Speculative decoding is not optional on a CPU
+
+Speculative decoding drafts several tokens cheaply and verifies them in one
+forward pass of the real model. On a CPU — where a forward pass is expensive and
+a batch is comparatively cheap — this is the single largest speedup available,
+and it costs nothing in output quality.
+
+`llama-server -m qwen3-1.7b-Q4_K_M.gguf --spec-type ngram-mod` needs **no extra
+download** and measured **6.50 → 11.46 tok/s**. It mines repeated token patterns
+from the context, so it is a *warm-session* win: the first request of a session
+gains almost nothing (7.33 tok/s) and the third reaches 11.46 tok/s as the
+shared hash pool fills. That suits a document generator exactly, because a job
+is several calls in a row sharing a long system prompt and emitting repetitive
+JSON.
+
+EAGLE3 is the theoretically stronger option: a one-layer draft that reads the
+target model's hidden states and should therefore achieve a much higher
+acceptance rate. This repo ships `qwen3-1.7b-eagle3.gguf` and it is used like
+this:
+
+```bash
+llama-server -m qwen3-1.7b-Q4_K_M.gguf -md qwen3-1.7b-eagle3.gguf \
+    --spec-type draft-eagle3 --spec-draft-n-max 8
+```
+
+**It measured slower on a CPU, and this card will not pretend otherwise.**
+
+| Configuration | Speed | Draft acceptance |
+|---|---|---|
+| No speculation | 6.50 tok/s | — |
+| n-gram (`ngram-mod`) | **11.46 tok/s** | 0.53 (warm) |
+| EAGLE3 draft | **4.00 tok/s** | 0.089 |
+
+Acceptance was only 8.9%, and the draft shares the same 4 physical cores as the
+target, so it steals more throughput than it saves. EAGLE3 is a large win on a
+GPU — where the tiny draft runs nearly free beside the target — and a
+regression on a 4-thread CPU.
+
+This was re-checked on a much faster machine (a 20-core server CPU running
+CPU-only, 4 threads) using our own converted GGUF: baseline 21.90 tok/s, n-gram
+21.60 tok/s on a cold single run, EAGLE3 **16.30 tok/s (0.74x)**. So EAGLE3 is
+slower regardless of target conversion, and n-gram's benefit genuinely depends
+on a warm, repetitive session — which is the normal case for this tool.
+
+**Prefer n-gram speculation on CPU; treat the EAGLE3 file as an experiment.**
+
+Practical consequences:
+
+* **Cold load costs ~13 s on a spinning disk.** Keep the model resident between
+  requests rather than reloading per call.
+* Use one thread per *physical* core. More threads than physical cores is slower.
+* Qwen3 is a reasoning model. Left alone it spends most of its budget on hidden
+  thinking tokens, so **disable thinking** (`think=false`, or
+  `chat_template_kwargs={"enable_thinking": false}`).
+* A grounded 3-section report takes ~140 s end to end. That is acceptable for a
+  "generate document" button, but only with progress reporting.
+
+## Quick start
+
+**llama.cpp server** (OpenAI-compatible, supports JSON-schema constrained output):
+
+```bash
+llama-server -m qwen3-1.7b-Q4_K_M.gguf -c 4096 -t 4 --port 8080
+```
+
+**llama.cpp CLI:**
+
+```bash
+llama-cli -m qwen3-1.7b-Q4_K_M.gguf -c 4096 -t 4 \
+  -p "Return only JSON: {\"heading\": str, \"paragraphs\": [str]} for a section about heat pumps."
+```
+
+**Ollama** (optional — the product does not need it):
+
+```bash
+ollama pull hf.co/hkblockchaintechnology/tiny-agent-gguf
+```
+
+The official CPU-only `llama.cpp` Windows release is an **18.8 MB** zip (a 46 MB
+folder unpacked) and needs no GPU, CUDA toolkit or Python environment — that is
+the intended way to ship this.
+
+## Prompting notes for a model this size
+
+1. **One question per call.** Asking for several things at once is where small
+   models fall apart.
+2. **Constrain the output shape.** Use a JSON schema or GBNF grammar. It removes
+   an entire class of parsing failures.
+3. **Disable thinking.** Qwen3 will otherwise spend its whole budget reasoning.
+4. **Give it the facts.** Put retrieved text in the prompt; it cannot supply
+   accurate specifics from memory.
+5. **Ask for less text.** 2–3 short paragraphs per section works; "write a
+   detailed 2000-word report" does not.
+6. **Expect and clean up artefacts.** It adds list numbering to headings and
+   sometimes leaks markdown into prose fields. Strip these deterministically
+   during assembly rather than fighting them with prompt wording.
+
+## Limitations
+
+* **Hallucination.** Without grounding, specifics (figures, dates, product
+  names) are unreliable and often invented. Tiny Agent mitigates this by injecting
+  retrieved web text and attaching a source list, but it does not eliminate it.
+* **Inherited knowledge cutoff and biases.** Because this is a quantization, the
+  base model's training data, cutoff and biases apply unchanged.
+* **Language.** The base model is multilingual, but the pipeline prompts and all
+  validation were done in English.
+* **Repetition.** Sections written in separate calls sometimes restate the same
+  point. Human editing is expected.
+* **Not a general chat model.** It is tuned here for structured slot-filling, not
+  for open-ended conversation.
+* **Quantization degrades quality slightly** versus the full-precision base
+  model. 4-bit is the point where quality and speed balance best on this class
+  of hardware.
+
+## Training data
+
+No training or fine-tuning was performed. This repository contains quantized
+conversions of:
+
+* [`Qwen/Qwen3-1.7B`](https://huggingface.co/Qwen/Qwen3-1.7B)
+* [`Qwen/Qwen3-0.6B`](https://huggingface.co/Qwen/Qwen3-0.6B)
+
+and a converted speculative draft:
+
+* [`AngelSlim/Qwen3-1.7B_eagle3`](https://huggingface.co/AngelSlim/Qwen3-1.7B_eagle3)
+  (Apache-2.0, Tencent AngelSlim) — converted to GGUF with
+  `convert_hf_to_gguf.py --target-model-dir Qwen/Qwen3-1.7B`. It is a *draft*
+  model: it proposes tokens that the 1.7B model verifies, and it never changes
+  the output, only the speed. It cannot be used on its own.
+
+Refer to the base model cards for training data, evaluation results and
+limitations.
+
+Why these models: both are **Apache-2.0**, so they can be redistributed with a
+commercial product without additional conditions. Llama, Gemma and several other
+otherwise-capable small models are deliberately **not** bundled, because their
+licences carry redistribution terms that are unsuitable for shipping to end
+users.
+
+## License and attribution
+
+Apache-2.0, inherited from the base models. Copyright in the base weights
+belongs to the Qwen team; these are derivative quantizations redistributed under
+the same licence.
+
+## Related
+
+* Project source, benchmarks and generated documents: [`hkblockchaintechnology/tiny-agent`](https://huggingface.co/datasets/hkblockchaintechnology/tiny-agent)
+* Windows installer (1.34 GB, in the dataset repository): [`TinyAgentSetup-1.0.0.exe`](https://huggingface.co/datasets/hkblockchaintechnology/tiny-agent/resolve/main/releases/TinyAgentSetup-1.0.0.exe)
+* User guide: [`TinyAgent-UserGuide.pdf`](https://huggingface.co/datasets/hkblockchaintechnology/tiny-agent/blob/main/docs/TinyAgent-UserGuide.pdf)
+* Measured comparison with Microsoft Office and WPS Office: [`COMPARISON-REPORT.md`](https://huggingface.co/datasets/hkblockchaintechnology/tiny-agent/blob/main/docs/COMPARISON-REPORT.md)