Commit TinyGuard-Command

README.md

@@ -0,0 +1,57 @@
+---
+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.

README.zh.md

@@ -0,0 +1,57 @@
+---
+license: apache-2.0
+language:
+  - zh
+  - en
+tags:
+  - safety
+  - guardrail
+  - agents
+  - command-line
+  - text-classification
+  - mlx
+metrics:
+  - f1
+  - accuracy
+---
+# TinyGuard-Command（基座 + 微调）
+
+**从零训练的双语 AI-Agent 命令风险分类器** · 9.1M 参数 · MLX/Metal · Apache-2.0（代码）· 训练数据全合成
+
+[English](MODEL_CARD-commands.md)
+
+## 模型描述
+
+TinyGuard-Command 是给 AI 编码助手用的执行前护栏：输入（任务上下文，shell/PowerShell 命令），三分类输出 `safe / confirm / deny`。与正则规则不同，它**上下文感知**且对编码/改写绕过有鲁棒性。
+
+- 基座：TinyGuard-Encoder（ModernBERT 风格，6 层 · hidden 256 · 16k byte-level BPE · seq 512），从零预训练 8000 步 / 1.31 亿 tokens（fineweb-edu + wikipedia zh/en），无任何预训练权重初始化。
+- 微调：12399 条合成+手写双语标注（形近对、上下文决定、正则绕过、防过拒样本），3 epochs。
+
+## 成绩（全部为留出数据，从未参与训练）
+
+| 评测集 | 指标 | TinyGuard | 正则基线 |
+|---|---|---|---|
+| 金种子 38 条（隔离） | 干预 recall / precision / F1 | **100% / 96% / 0.98** | 50% / 100% / 0.67 |
+| 对抗集 48 条（base64/变量间接/管道混淆/子 shell/编码执行） | 干预 recall / precision / F1 | **94% / 85% / 0.89** | 26% / 89% / 0.40 |
+| 验证集 619 条 | acc / macro-F1 | 93.2% / 0.927 | — |
+
+误报行为：安全样本被"确认"而非"拒绝"（保守偏向）。Apple Silicon 上单次推理毫秒级。
+
+## 用法
+
+权重：[`QuanxinLi/TinyGuard-Command`](https://huggingface.co/QuanxinLi/TinyGuard-Command) ·
+代码与训练管线：[`Quanxin-Lee/TinyGuard`](https://github.com/Quanxin-Lee/TinyGuard)
+
+```python
+# quickstart（transformers/MLX 双格式）——完整流程见 GitHub 仓库
+```
+
+## 局限
+
+- 训练数据为合成+人工构造，未见真实企业环境长尾命令。
+- 对抗集上仍漏 2/48（如内容依赖的 `sh -c $(cat file)`）与误报 5/48。
+- deny 边界样本（如测试库 DROP vs 生产库 DROP）依赖上下文质量。
+
+## 训练细节与数据声明
+
+数据 100% 合成/人工编写，无真实用户数据。训练管线、审计脚本（含三轮深度扫描）与全部数据集随仓库开源。

config.json

@@ -0,0 +1,26 @@
+{
+ "architectures": [
+  "TinyGuardClassifier"
+ ],
+ "model_type": "tinyguard",
+ "hidden_size": 256,
+ "num_hidden_layers": 6,
+ "num_attention_heads": 4,
+ "intermediate_size": 1024,
+ "vocab_size": 16384,
+ "max_position_embeddings": 512,
+ "num_classes": 3,
+ "pad_token_id": 0,
+ "framework": "mlx",
+ "license": "apache-2.0",
+ "id2label": {
+  "0": "safe",
+  "1": "confirm",
+  "2": "deny"
+ },
+ "label2id": {
+  "safe": 0,
+  "confirm": 1,
+  "deny": 2
+ }
+}

inference.py

@@ -0,0 +1,5 @@
+"""TinyGuard inference quickstart (requires pip install mlx)"""
+import mlx.core as mx, mlx.nn as nn
+from huggingface_hub import hf_hub_download
+import json, sys
+# See the repo quickstart for the full walkthrough; placeholder stub here.

model.safetensors

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:33622ba7056e80383b4ea545090c7cc9ce5b1f6ef7d91b0c08e180b0768f02a2
+size 36246180