Upload README.md with huggingface_hub

README.md

@@ -1,8 +1,78 @@
 ---
+language:
+  - en
 license: apache-2.0
-base_model:
-- Qwen/Qwen3-4B-Instruct-2507
+base_model: Qwen/Qwen3-4B-Instruct-2507
 pipeline_tag: text-generation
-language:
-- en
----
+tags:
+  - gguf
+  - transcript-cleaning
+  - dictation
+  - speech-to-text
+  - llama.cpp
+---
+
+# Flowbee Cut — technical dictation cleaner
+
+Fine-tune of [Qwen3-4B-Instruct-2507](https://huggingface.co/Qwen/Qwen3-4B-Instruct-2507)
+that cleans raw speech-to-text transcripts for [Flowbee](https://github.com/auswm85/flowbee),
+a local-first macOS dictation utility. It removes fillers and stutters,
+resolves self-corrections, and writes technical speech in its correct form:
+
+| spoken                                  | written                   |
+| --------------------------------------- | ------------------------- |
+| "rename it to camel case get user data" | Rename it to getUserData. |
+| "run cargo test dash dash release"      | Run cargo test --release. |
+| "open main dot rs"                      | Open main.rs.             |
+| "we deploy behind engine x"             | We deploy behind nginx.   |
+
+**This is not a chat model.** It was trained to do exactly one thing under
+one system prompt, and it will clean — never answer — instruction-shaped
+transcripts ("write a unit test for the auth module" comes back as cleaned
+text, not a unit test).
+
+## Usage contract
+
+The model expects the exact Flowbee Cut system prompt it was trained with
+(the `coder` prompt in `scripts/cut-eval/prompts.mjs` of the Flowbee repo),
+with the raw transcript as the sole user message, `temperature 0`. Behavior
+under other prompts is untested. Serve with llama.cpp:
+
+```sh
+llama-server -m flowbee-cut-<version>.Q4_K_M.gguf -ngl 99 -c 4096
+```
+
+## Training
+
+- LoRA (r=16, attention projections, completion-only loss) on ~4,400
+  synthetic pairs of messy spoken transcript → clean text: instruction-shaped
+  technical dictation, CLI commands and flags, spoken identifiers and case
+  directives, glossary-conditioned phonetic repairs, everyday dictation, and
+  passthrough negatives. Adapter merged into the base weights, quantized to
+  Q4_K_M.
+- Trained, evaluated, and published automatically by CI (GitHub Actions →
+  Modal GPU). A release is published only if it clears a held-out 22-case
+  evaluation battery; the current release scores **21/22**.
+
+## Files
+
+- `flowbee-cut-<version>.Q4_K_M.gguf` — versioned releases (~2.5 GB).
+- `latest.json` — machine-read manifest (version, file, sha256, eval score).
+  The Flowbee app checks it on startup and downloads new releases, verifying
+  the sha256 before the file touches a GGUF parser. Do not rename or delete
+  these files by hand.
+
+## Limitations
+
+- **English only.** Training data is English; the base model is multilingual
+  but this fine-tune's behavior on non-English transcripts is untested.
+- Tuned for software-engineering vocabulary; exotic garbled jargon without a
+  glossary hint is passed through verbatim by design (never deleted, never
+  guessed).
+- Trained on synthetic data seeded with real dictation failures; expect
+  occasional misses on unusual phrasing (e.g. a garbled term directly
+  adjacent to a modifier).
+
+## License
+
+Apache-2.0