Upload README.md with huggingface_hub

README.md

@@ -1,3 +1,166 @@
 ---
 license: mit
+language:
+  - en
+tags:
+  - instruction-quality
+  - lint
+  - code-review
+  - agent-instructions
+  - gguf
+  - qwen3.5
+base_model: Qwen/Qwen3.5-0.8B
+pipeline_tag: text-generation
+library_name: llama-cpp-python
+model-index:
+  - name: writ-lint-0.8B
+    results: []
 ---
+
+# writ-lint-0.8B
+
+A fine-tuned [Qwen3.5-0.8B](https://huggingface.co/Qwen/Qwen3.5-0.8B) model that evaluates the quality of AI agent instructions and generates actionable improvement feedback.
+
+Part of the **Tier 2.5 hybrid architecture** in [enwrit](https://github.com/enwrit/writ) -- the communication layer for AI agents.
+
+## How It Works
+
+This model is one half of a hybrid scoring system:
+
+1. **LightGBM** (bundled in the `enwrit` CLI) predicts headline + 6 dimension scores (~1ms)
+2. **writ-lint-0.8B** (this model) generates issues (ERROR/WARNING/INFO) and improvement suggestions, using the instruction text and LightGBM-predicted scores as context
+
+The model focuses entirely on generating actionable feedback, not scores. Scores from LightGBM are passed in the prompt so the model can target weak dimensions.
+
+## Usage
+
+### Via the enwrit CLI (recommended)
+
+```bash
+pip install enwrit
+pip install llama-cpp-python  # CPU inference, ~10s per instruction
+
+writ lint AGENTS.md --deep-local
+```
+
+The model is auto-downloaded to `~/.writ/models/` on first use.
+
+### Direct inference with llama-cpp-python
+
+```python
+from llama_cpp import Llama
+import json
+
+model = Llama(
+    model_path="writ-lint-0.8B-Q4_K_M.gguf",
+    n_ctx=4096,
+    n_gpu_layers=-1,  # GPU acceleration (0 for CPU-only)
+    verbose=False,
+)
+
+prompt = """<|im_start|>system
+You are an expert instruction quality evaluator. Given an instruction and its quality scores, generate specific issues and improvement suggestions.<|im_end|>
+<|im_start|>user
+## Instruction to evaluate
+
+{instruction_text}
+
+## Quality scores (predicted)
+
+Headline: 52/100
+Clarity: 58 | Structure: 65 | Coverage: 42 | Brevity: 71 | Examples: 28 | Verification: 35
+
+Analyze the instruction. Return JSON with "issues" (level + message) and "suggestions".<|im_end|>
+<|im_start|>assistant
+"""
+
+output = model.create_completion(
+    prompt,
+    max_tokens=1024,
+    temperature=0.3,
+    response_format={"type": "json_object"},
+)
+
+feedback = json.loads(output["choices"][0]["text"])
+print(json.dumps(feedback, indent=2))
+```
+
+## Output Format
+
+```json
+{
+  "issues": [
+    {"level": "ERROR", "message": "Missing concrete code examples for error handling patterns."},
+    {"level": "WARNING", "message": "Verification steps are subjective rather than binary."},
+    {"level": "INFO", "message": "Consider adding a 'Rules' section for behavioral constraints."}
+  ],
+  "suggestions": [
+    "Add a 'Code Examples' section with 'Good vs Bad' patterns for the most critical rules.",
+    "Replace subjective verification with specific CLI commands (e.g., `pytest`, `ruff check`).",
+    "Include numeric thresholds for measurable constraints (e.g., 'max 100 lines per function')."
+  ]
+}
+```
+
+## Training Details
+
+| Parameter | Value |
+|---|---|
+| Base model | [Qwen/Qwen3.5-0.8B](https://huggingface.co/Qwen/Qwen3.5-0.8B) |
+| Method | LoRA (r=32, alpha=64, dropout=0) via [Unsloth](https://github.com/unslothai/unsloth) |
+| Training data | 6,536 Tier 3 AI evaluations (Gemini-scored instructions) |
+| Issues in training data | 30,830 (avg 4.7 per instruction) |
+| Suggestions in training data | 19,602 (avg 3.0 per instruction) |
+| Non-coding examples | 145 seed instructions across 15 domains |
+| Epochs | 1 |
+| Batch size | 1 (gradient accumulation: 16, effective batch: 16) |
+| Max sequence length | 4096 tokens |
+| Learning rate | 2e-4 (cosine schedule, 10% warmup) |
+| Precision | bf16 |
+| Quantization | Q4_K_M (GGUF) |
+| Training hardware | NVIDIA RTX 5090 (32GB VRAM) |
+| Training time | ~5.5 hours |
+
+## Evaluation
+
+Compared against retrieval-based approaches (v1/v2/v3) on a held-out validation set:
+
+| Approach | Relevance | All-Feedback Specificity | Issues/Instruction | Type |
+|---|---|---|---|---|
+| v1_shap_knn | 0.157 | 0.129 | N/A | retrieval |
+| v2_hybrid | 0.266 | 0.136 | N/A | retrieval |
+| v3_tfidf | 0.262 | 0.144 | N/A | retrieval |
+| **writ-lint-0.8B** | **0.236** | **0.364** | **4.7** | **generative** |
+
+Key strengths:
+- 100% JSON parse success (via constrained decoding)
+- Generates novel, context-specific feedback (not limited to seen examples)
+- Weak-dimension targeting: 0.47 (issues correlate with low-scoring dimensions)
+- Low domain mismatch: 0.014 (doesn't give coding feedback to non-coding instructions)
+
+## Scoring Dimensions
+
+The 6 quality dimensions (scored by LightGBM, targeted by this model):
+
+| Dimension | What it measures |
+|---|---|
+| **Clarity** | Unambiguous language, precise terminology, defined jargon |
+| **Structure** | Logical sections, hierarchy, scannable formatting |
+| **Coverage** | Completeness of rules, edge cases, responsibilities |
+| **Brevity** | Concise without sacrificing meaning, no redundancy |
+| **Examples** | Code samples, input/output patterns, good vs bad |
+| **Verification** | Testable criteria, CLI commands, specific thresholds |
+
+## Files
+
+- `writ-lint-0.8B-Q4_K_M.gguf` -- Quantized model for inference (504 MB)
+
+## Links
+
+- [enwrit CLI](https://github.com/enwrit/writ) -- Open-source CLI tool
+- [enwrit.com](https://enwrit.com) -- Platform with Hub, AI scoring, and more
+- [PyPI](https://pypi.org/project/enwrit/) -- `pip install enwrit`
+
+## License
+
+MIT