Upload README.md with huggingface_hub

README.md

@@ -1,5 +1,7 @@
 ---
 license: apache-2.0
+language:
+  - en
 tags:
   - security
   - ai-agents
@@ -7,70 +9,234 @@ tags:
   - nanomind
   - opena2a
   - threat-detection
+  - onnx
+  - text-classification
 datasets:
   - opena2a/nanomind-training
 metrics:
   - accuracy
   - f1
+pipeline_tag: text-classification
+library_name: onnxruntime
 model-index:
   - name: nanomind-security-classifier
     results:
       - task:
           type: text-classification
           name: AI Agent Threat Classification
+        dataset:
+          type: opena2a/nanomind-training
+          name: NanoMind Security Corpus sft-v10
         metrics:
           - name: Eval Accuracy
             type: accuracy
-            value: 0.9673
+            value: 0.9845
+          - name: Macro F1
+            type: f1
+            value: 0.9778
 ---
 
-# nanomind-security-classifier v0.4.0
+# NanoMind Security Classifier v0.5.0
 
-Base 10-class threat classifier for AI agent security scanning
+A fast, lightweight threat classifier purpose-built for AI agent security scanning. Classifies SKILL.md files, MCP server configurations, SOUL.md governance docs, and agent tool descriptions into 10 security categories in under 1ms.
 
-Part of the [OpenA2A](https://opena2a.org) security ecosystem.
-Used by [HackMyAgent](https://github.com/opena2a-org/hackmyagent) for AI agent security scanning.
+Part of the [OpenA2A](https://github.com/opena2a-org) security ecosystem.
 
-## Metrics
+## What This Model Does
+
+NanoMind analyzes the text content of AI agent configurations and detects security threats:
+
+```
+Input:  MCP server config with hidden data forwarding endpoint
+Output: exfiltration (confidence: 0.97)
+
+Input:  Normal SOUL.md governance policy
+Output: benign (confidence: 0.99)
+```
+
+It runs at the scanning layer of [HackMyAgent](https://github.com/opena2a-org/hackmyagent) and [OpenA2A CLI](https://github.com/opena2a-org/opena2a), classifying every piece of agent content before it reaches production.
+
+## Key Metrics
 
 | Metric | Value |
 |--------|-------|
-| Eval accuracy | 96.73% |
-| Training samples | 3337 |
-| Eval samples | 398 |
-| Attack classes | 10 |
-| Training corpus | sft-v9 |
+| **Eval accuracy** | **98.45%** |
+| **Macro F1** | **0.9778** |
+| **False positives** | **0** on 33 benign Unicode inputs |
+| **Inference latency** | **< 1ms** (p99 on CPU) |
+| **Model size** | **8.3 MB** (ONNX + weights + tokenizer) |
+| Training samples | 3168 |
+| Eval samples | 194 |
+| Training corpus | sft-v10 |
+
+## Threat Taxonomy (10 classes)
+
+| Class | Description |
+|-------|-------------|
+| `exfiltration` | Data forwarding to unauthorized external endpoints |
+| `injection` | Instruction override, jailbreak, prompt injection |
+| `privilege_escalation` | Unauthorized access elevation |
+| `persistence` | Permanent unauthorized state manipulation |
+| `credential_abuse` | Credential harvesting, phishing, token theft |
+| `lateral_movement` | Remote config/instruction fetching, C2 patterns |
+| `social_engineering` | Urgency, authority, or pressure manipulation |
+| `policy_violation` | Governance bypass, boundary violations |
+| `steganography` | Unicode-based attacks (zero-width chars, homoglyphs, bidi overrides) |
+| `benign` | Normal, safe agent behavior |
 
 ## Architecture
 
-- **Type:** Mamba TME (8 blocks, d_model=128, d_state=64)
-- **Inference:** ONNX (Node.js via onnxruntime-node) or NPZ weights
-- **Latency:** Sub-2ms on CPU
+| Parameter | Value |
+|-----------|-------|
+| Type | Mamba SSM (Selective State Space Model) |
+| Architecture | TME (Ternary Mamba Encoder) |
+| Blocks | 8 MambaBlocks with gated projection |
+| Dimensions | d_model=128, d_inner=256, d_state=64 |
+| Vocabulary | 6,000 tokens (word-level) |
+| Parameters | 2,089,482 |
+| Inference | ONNX Runtime (cross-platform) or MLX (Apple Silicon) |
 
-## Attack Classes (10)
+The model processes text through: Embedding -> 8x MambaBlock (in_proj -> SiLU gate -> dt_proj -> out_proj + LayerNorm residual) -> Mean pooling -> LayerNorm -> Linear classifier -> Softmax.
 
-exfiltration, injection, privilege_escalation, persistence, credential_abuse, lateral_movement, social_engineering, policy_violation, benign
+## Quick Start
 
-## Usage
+### Via HackMyAgent (recommended)
 
 ```bash
-# Install HackMyAgent (includes NanoMind inference)
 npm install -g hackmyagent
 
-# Scan an MCP server or AI agent project
+# Scan an AI agent project for threats
 hackmyagent scan ./my-agent --deep
+```
+
+### Via OpenA2A CLI
 
-# Or use via OpenA2A CLI
+```bash
 npx opena2a scan ./my-agent
 ```
 
+### Direct ONNX Inference (Python)
+
+```python
+import json
+import numpy as np
+import onnxruntime as ort
+
+# Load model
+session = ort.InferenceSession("nanomind-tme.onnx")
+vocab = json.load(open("tokenizer.json"))
+
+# Tokenize
+text = "your agent config text here"
+tokens = text.lower().split()
+ids = [vocab.get(t, 1) for t in tokens[:128]]
+ids += [0] * (128 - len(ids))  # pad
+input_ids = np.array([ids], dtype=np.int64)
+
+# Predict
+logits = session.run(None, {"input_ids": input_ids})[0][0]
+classes = ["exfiltration", "injection", "privilege_escalation", "persistence",
+           "credential_abuse", "lateral_movement", "social_engineering",
+           "policy_violation", "benign", "steganography"]
+pred = classes[np.argmax(logits)]
+conf = np.exp(logits) / np.exp(logits).sum()
+print(f"{pred} (confidence: {conf[np.argmax(logits)]:.3f})")
+```
+
+### Direct ONNX Inference (Node.js)
+
+```javascript
+const ort = require("onnxruntime-node");
+const vocab = require("./tokenizer.json");
+
+async function classify(text) {
+  const session = await ort.InferenceSession.create("nanomind-tme.onnx");
+  const tokens = text.toLowerCase().split(" ");
+  const ids = tokens.slice(0, 128).map(t => vocab[t] || 1);
+  while (ids.length < 128) ids.push(0);
+
+  const input = new ort.Tensor("int64", BigInt64Array.from(ids.map(BigInt)), [1, 128]);
+  const result = await session.run({ input_ids: input });
+  const logits = Array.from(result.logits.data);
+
+  const classes = ["exfiltration", "injection", "privilege_escalation", "persistence",
+    "credential_abuse", "lateral_movement", "social_engineering",
+    "policy_violation", "benign", "steganography"];
+  const maxIdx = logits.indexOf(Math.max(...logits));
+  return { class: classes[maxIdx], logits };
+}
+```
+
 ## Training
 
-Trained on Apple Silicon (MLX) using curated security corpus from:
-- [DVAA](https://github.com/opena2a-org/damn-vulnerable-ai-agent) attack payloads
-- [AgentPwn](https://agentpwn.com) honeypot captures
-- [OASB](https://oasb.org) benchmark dataset
-- OpenA2A Registry skill descriptions
+### Data Sources
+
+| Source | Samples | Description |
+|--------|---------|-------------|
+| [OASB](https://oasb.org) | ~400 | Open Agent Security Benchmark attack/benign corpus |
+| [DVAA](https://github.com/opena2a-org/damn-vulnerable-ai-agent) | ~200 | Deliberately vulnerable agent scenarios |
+| [AgentPwn](https://agentpwn.com) | ~100 | Real honeypot-captured attack payloads |
+| Synthetic | ~1,500 | Generated SKILL.md, MCP config, SOUL.md samples |
+| Stego corpus | ~550 | Zero-width, homoglyph, bidi, tag character attacks |
+| FP-reduction | 106 | Targeted benign samples for false positive elimination |
+
+### Training Process
+
+- **Hardware:** Apple M4 Max, 32 GB, MLX GPU acceleration
+- **Framework:** [MLX](https://github.com/ml-explore/mlx) (Apple Silicon native)
+- **Strategy:** Fine-tuned from v0.4.0 weights with lower learning rate (0.0005)
+- **Schedule:** Cosine decay with linear warmup (5 epochs)
+- **Regularization:** Dropout 0.1, early stopping (patience=60)
+
+### Corpus Evolution
+
+| Version | Samples | Classes | Key Change |
+|---------|---------|---------|------------|
+| sft-v4 | 1,028 | 9 | Initial release |
+| sft-v5 | ~1,100 | 9 | Added OASB data |
+| sft-v8 | 4,500 | 9 | Multi-source, balanced |
+| sft-v9 | 3,566 | 10 | Added steganography class |
+| **sft-v10** | **3,566** | **10** | **FP-reduction: +106 targeted benign** |
+
+## Changelog
+
+### v0.5.0 (2026-04-09)
+FP reduction: 7 false positives eliminated via targeted benign training data (base64, emoji, Cyrillic, Arabic, governance, error messages, security tools). Fine-tuned from v0.4.0.
+
+### v0.4.0 (2026-04-07)
+Added steganography as 10th attack class. Trained on sft-v9 corpus with 370+ steganographic attack samples and 370+ benign Unicode samples.
+
+### v0.3.0 (2026-04-01)
+Added ONNX export with external data format for efficient deployment.
+
+### v0.2.0 (2026-03-20)
+Upgraded from MLP to Mamba TME architecture. 97.01% accuracy.
+
+## File Manifest
+
+| File | Size | Description |
+|------|------|-------------|
+| `nanomind-tme.onnx` | 140 KB | ONNX model graph |
+| `nanomind-tme.onnx.data` | 8.0 MB | External weight data |
+| `tokenizer.json` | 165 KB | Word-level vocabulary (6,000 tokens) |
+| `nanomind-tme-classifier.npz` | 8.0 MB | Best checkpoint (MLX/NumPy weights) |
+
+## Limitations
+
+- **Small eval set:** 194 samples. Per-class metrics may be noisy for classes with < 15 support.
+- **Word-level tokenizer:** Cannot detect character-level steganographic attacks (e.g., single Cyrillic homoglyphs embedded in Latin words). Relies on contextual patterns instead.
+- **Base64 sensitivity:** Long base64 strings can look like encoded/hidden content. v0.5.0 added targeted training but novel base64 patterns may still trigger false positives.
+- **English-centric vocabulary:** Vocabulary is trained primarily on English text. Non-English package descriptions rely on Unicode pattern recognition rather than semantic understanding.
+- **No adversarial robustness testing:** Not tested against adversarial examples designed to evade detection.
+
+## Responsible Use
+
+This model is designed to **assist** security review, not replace it. All findings should be verified by a human before taking action. The model may produce false positives on legitimate content that uses security-related terminology in defensive contexts.
+
+Do not use this model to:
+- Block packages or agents without human review
+- Make automated access control decisions
+- Replace security audits or penetration testing
 
 ## License
 
@@ -83,7 +249,15 @@ Apache-2.0. Free for commercial and non-commercial use.
   title = {NanoMind Security Classifier},
   author = {OpenA2A},
   url = {https://github.com/opena2a-org/nanomind},
-  version = {0.4.0},
+  version = {0.5.0},
   year = {2026}
 }
 ```
+
+## Links
+
+- [NanoMind GitHub](https://github.com/opena2a-org/nanomind) -- Model code, specifications, documentation
+- [HackMyAgent](https://github.com/opena2a-org/hackmyagent) -- Primary consumer (AI agent security scanner)
+- [OpenA2A](https://github.com/opena2a-org/opena2a) -- CLI toolkit for AI agent security
+- [OASB](https://oasb.org) -- Open Agent Security Benchmark
+- [DVAA](https://github.com/opena2a-org/damn-vulnerable-ai-agent) -- Training data source (vulnerable agent scenarios)