| --- |
| license: apache-2.0 |
| language: |
| - zh |
| - en |
| tags: |
| - safety |
| - guardrail |
| - agents |
| - command-line |
| - text-classification |
| - mlx |
| metrics: |
| - f1 |
| - accuracy |
| --- |
| # TinyGuard-Command (base + fine-tuned) |
|
|
| **Bilingual AI-agent command-risk classifier trained completely from scratch** · 9.1M parameters · MLX/Metal · Apache-2.0 (code) · fully synthetic training data |
|
|
| [中文说明](MODEL_CARD-commands.zh.md) |
|
|
| ## Model description |
|
|
| TinyGuard-Command is a pre-execution guardrail for AI coding agents: input (task context, shell/PowerShell command), 3-way output `safe / confirm / deny`. Unlike regex rules it is **context-aware** and robust to encoding/rewrite evasion. |
|
|
| - Backbone: TinyGuard-Encoder (ModernBERT-style, 6 layers · hidden 256 · 16k byte-level BPE · seq 512), pretrained from scratch for 8,000 steps / 131M tokens (fineweb-edu + wikipedia zh/en). No pretrained weights used anywhere. |
| - Fine-tune: 12,399 synthetic+hand-written bilingual labeled examples (near-miss pairs, context-decisive cases, regex-evasion rewrites, anti-overrefusal samples), 3 epochs. |
|
|
| ## Results (held-out data only, never seen in training) |
|
|
| | Benchmark | Metric | TinyGuard | Regex baseline | |
| |---|---|---|---| |
| | Golden seed set, 38 rows (isolated) | intervention recall / precision / F1 | **100% / 96% / 0.98** | 50% / 100% / 0.67 | |
| | Adversarial set, 48 rows (base64 / variable indirection / pipe obfuscation / subshell / encoded execution) | intervention recall / precision / F1 | **94% / 85% / 0.89** | 26% / 89% / 0.40 | |
| | Validation set, 619 rows | acc / macro-F1 | 93.2% / 0.927 | — | |
|
|
| False-positive behavior: safe samples are "confirmed" rather than "denied" (conservative bias). Single inference is millisecond-scale on Apple Silicon. |
|
|
| ## Usage |
|
|
| Weights: [`QuanxinLi/TinyGuard-Command`](https://huggingface.co/QuanxinLi/TinyGuard-Command) · |
| Code & training pipeline: [`Quanxin-Lee/TinyGuard`](https://github.com/Quanxin-Lee/TinyGuard) |
|
|
| ```python |
| # quickstart (transformers/MLX dual format) — see the GitHub repo for the full walkthrough |
| ``` |
|
|
| ## Limitations |
|
|
| - Training data is synthetic/hand-written; long-tail real-world enterprise commands are underrepresented. |
| - 2/48 misses remain on the adversarial set (content-dependent cases like `sh -c $(cat file)`) and 5/48 false interventions. |
| - deny/confirm boundaries (test-db DROP vs prod-db DROP) depend on context quality. |
|
|
| ## Training details & data statement |
|
|
| All data is synthetic/hand-written — no real user data. The full training pipeline, four audit scripts (three deep-scan rounds) and every dataset ship with the repository. |
|
|
