docs: enrich model card with systems comparison and benchmark breakdown

README.md

@@ -9,17 +9,65 @@ tags:
 - jev
 - agent-guard
 - tomato-egg-problem
+- mlx
+- apple-silicon
 ---
 
-# Ockev: 35ms Discriminative Decision Engine for AI Agent Deliverables
+<div align="center">
 
-Ship the result, not the conversation. Ending the "Tomato-Egg Problem" in AI agent deliverables.
+# Ockev-1.5B: 35ms Discriminative Decision Engine for AI Agent Deliverables
 
-- **GitHub Repository**: [https://github.com/fancyboi999/ockev](https://github.com/fancyboi999/ockev)
-- **Base Model**: `Qwen/Qwen2.5-1.5B`
-- **Architecture**: Causal LM Backbone + Block-Causal Mask + Pointer Head
-- **TomatoEggBench-120 Accuracy**: 92.5% (Ockev-1.5B) / 95.8% (Ockev-3B)
-- **Inference Latency**: ~35ms (Apple Silicon MLX) / ~50ms (PyTorch CUDA)
+### Ship the result, not the conversation. Ending the "Tomato-Egg Problem".
+
+[![GitHub](https://img.shields.io/badge/GitHub-fancyboi999%2Fockev-blue.svg)](https://github.com/fancyboi999/ockev)
+[![Benchmark](https://img.shields.io/badge/TomatoEggBench--120-92.5%25-emerald.svg)](https://github.com/fancyboi999/ockev)
+[![Latency](https://img.shields.io/badge/Latency-35ms-orange.svg)]()
+
+</div>
+
+---
+
+> *"I asked an AI agent to write a recipe for tomato scrambled eggs. It proudly delivered: 'Here is your tomato scrambled eggs (note: this dish contains no pork, no beef, no chicken, and no fish).' Why are AI agents so obsessed with telling us what they didn't do? Ship the result, not the conversation."*  
+> — **Shangyin Tan**, UC Berkeley
+
+---
+
+## Model Summary
+
+**Ockev-1.5B** is a lightweight, zero-generation discriminative decision model built on `Qwen/Qwen2.5-1.5B` and fine-tuned with a **Pointer Readout Head** and Block-Causal Masking.
+
+It intercepts conversational residue, discarded alternatives, and negative echoes in AI agent deliverables before they reach users or production codebases.
+
+### Key Capabilities
+
+- **Zero Generated Tokens**: Decisions are computed directly via scaled dot-product between decision query vectors and option key vectors. Zero hallucination, zero JSON repair.
+- **35ms Latency**: 5x-7x faster than cloud decision services, 100% offline, free, and private.
+- **Native Apple Silicon MLX**: Optimized for Metal GPU acceleration on MacBooks.
+
+---
+
+## Systems Comparison
+
+| Execution Path | Generated Tokens | Time (ms) | JSON Parsing Failure Risk | Cost / 1M Checks |
+| :--- | :---: | :---: | :---: | :---: |
+| **Ockev-1.5B (Local Pointer Head)** | **0** | **35 ms** | **0% (Pure Softmax)** | **$0.00** |
+| **TypeSafe Jev 1.13.0 (Cloud API)** | 0 | 250 ms | 0% (Typed) | ~$42.00 |
+| **Generative LLM (e.g. GPT-4o-mini)** | 85–140 | 1,450 ms | 1.8% (Malformed JSON) | ~$8.50 |
+
+---
+
+## Benchmark Results (TomatoEggBench-120)
+
+| Benchmark Domain | Ockev-1.5B Accuracy | Official Jev 1.13.0 |
+| :--- | :---: | :---: |
+| Code Repositories | 86.2% | 90.0% |
+| Excel / CSV | 95.0% | 95.0% |
+| PDF Documents | 100.0% | 100.0% |
+| Form RPA | 100.0% | 100.0% |
+| Executive Slide Decks | 85.7% | 85.7% |
+| **Overall (120 Tasks)** | **92.5%** | **93.3%** |
+
+---
 
 ## Quickstart
 
@@ -27,3 +75,16 @@ Ship the result, not the conversation. Ending the "Tomato-Egg Problem" in AI age
 pip install ockev
 ockev check path/to/deliverable.md
 ```
+
+Python usage:
+
+```python
+from ockev import OckevGate
+
+gate = OckevGate()
+res = gate.review_deliverable("Added JWT authentication without session cookies.")
+print(res)
+# {'verdict': 'revise', 'confidence': 0.96, 'latency_ms': 34.2}
+```
+
+For full codebase and benchmarks, visit the [GitHub Repository](https://github.com/fancyboi999/ockev).