Add README.md

README.md

@@ -26,7 +26,7 @@ extra_gated_fields:
 
 # NOPE Edge Mini - Crisis Classification Model
 
-A fine-tuned model for detecting crisis signals in text - suicidal ideation, self-harm, abuse, violence, and other safety-critical content. Designed for integration into safety pipelines, content moderation systems, and mental health applications.
+A fine-tuned model for detecting crisis signals in text - suicidal ideation, self-harm, abuse, violence, and other safety-critical content. Features chain-of-thought reasoning that explains its classifications.
 
 > **License:** [NOPE Edge Community License v1.0](LICENSE.md) - Free for research, academic, nonprofit, and evaluation use. Commercial production requires a separate license. See [nope.net/edge](https://nope.net/edge) for details.
 
@@ -34,10 +34,10 @@ A fine-tuned model for detecting crisis signals in text - suicidal ideation, sel
 
 ## Model Variants
 
-| Model | Parameters | Accuracy | Latency | Use Case |
-|-------|------------|----------|---------|----------|
-| **[nope-edge](https://huggingface.co/nopenet/nope-edge)** | 4B | **90.6%** | ~750ms | Maximum accuracy |
-| **[nope-edge-mini](https://huggingface.co/nopenet/nope-edge-mini)** | 1.7B | 85.9% | ~260ms | High-volume, cost-sensitive |
+| Model | Parameters | Use Case |
+|-------|------------|----------|
+| **[nope-edge](https://huggingface.co/nopenet/nope-edge)** | 4B | Maximum accuracy |
+| **[nope-edge-mini](https://huggingface.co/nopenet/nope-edge-mini)** | 1.7B | High-volume, cost-sensitive |
 
 This is **nope-edge-mini (1.7B)**.
 
@@ -60,6 +60,7 @@ pip install torch transformers accelerate
 ```python
 from transformers import AutoModelForCausalLM, AutoTokenizer
 import torch
+import re
 
 model_id = "nopenet/nope-edge-mini"
 
@@ -71,7 +72,7 @@ model = AutoModelForCausalLM.from_pretrained(
 )
 
 def classify(message: str) -> str:
-    """Returns 'type|severity|subject' or 'none'."""
+    """Returns XML with reflection and risk classification."""
     input_ids = tokenizer.apply_chat_template(
         [{"role": "user", "content": message}],
         tokenize=True,
@@ -80,198 +81,218 @@ def classify(message: str) -> str:
     ).to(model.device)
 
     with torch.no_grad():
-        output = model.generate(input_ids, max_new_tokens=30, do_sample=False)
+        output = model.generate(input_ids, max_new_tokens=300, do_sample=False)
 
     return tokenizer.decode(
         output[0][input_ids.shape[1]:],
         skip_special_tokens=True
     ).strip()
 
-classify("I want to end it all")                    # -> "suicide|high|self"
-classify("Great day at work!")                       # -> "none"
-classify("My friend said she wants to kill herself") # -> "suicide|high|other"
+# Example
+result = classify("I want to end it all tonight")
+print(result)
+```
+
+**Output:**
+```xml
+<reflection>The user directly expresses intent to end their life with a specific timeline ("tonight"), indicating acute suicidal ideation with imminent risk.</reflection>
+<risks>
+  <risk subject="self" type="suicide" severity="high" imminence="urgent"/>
+</risks>
 ```
 
 ---
 
 ## Output Format
 
+The model outputs XML with two components:
+
+### 1. Reflection (Chain-of-Thought)
+
+```xml
+<reflection>Reasoning about the input...</reflection>
+```
+
+The model explains its classification, including:
+- What signals it detected
+- Why it chose the risk type and severity
+- Any contextual factors considered
+
+### 2. Risk Classification
+
 **Crisis detected:**
+```xml
+<risks>
+  <risk subject="self" type="suicide" severity="high" imminence="urgent" features="active_ideation,intent_stated"/>
+</risks>
 ```
-{type}|{severity}|{subject}
+
+**No crisis:**
+```xml
+<risks/>
 ```
 
-| Field | Values | Description |
-|-------|--------|-------------|
-| type | `suicide`, `self_harm`, `self_neglect`, `violence`, `abuse`, `sexual_violence`, `exploitation`, `stalking`, `neglect` | Risk category |
-| severity | `mild`, `moderate`, `high`, `critical` | Urgency level |
-| subject | `self`, `other` | Who is at risk |
+### Risk Attributes
 
-**No crisis:** `none`
+| Attribute | Values | Description |
+|-----------|--------|-------------|
+| `subject` | `self`, `other` | Who is at risk |
+| `type` | `suicide`, `self_harm`, `self_neglect`, `violence`, `abuse`, `sexual_violence`, `exploitation`, `stalking`, `neglect` | Risk category |
+| `severity` | `mild`, `moderate`, `high`, `critical` | Urgency level |
+| `imminence` | `chronic`, `acute`, `urgent`, `emergency` | Time sensitivity |
+| `features` | comma-separated list | Specific indicators detected |
 
 ### Subject Attribution
 
 | Subject | Meaning | Example |
 |---------|---------|---------|
-| `self` | The speaker is at risk or is the victim | "I want to kill myself", "My partner hits me" |
-| `other` | The speaker is reporting concern about someone else | "My friend said she wants to die" |
+| `self` | The speaker is at risk | "I want to kill myself" |
+| `other` | Reporting concern about someone else | "My friend said she wants to die" |
 
 ### Parsing Example
 
 ```python
+import re
+from dataclasses import dataclass
+from typing import Optional
+
+@dataclass
+class Risk:
+    subject: str
+    type: str
+    severity: str
+    imminence: Optional[str] = None
+    features: Optional[list] = None
+
 def parse_output(output: str) -> dict:
-    output = output.strip().lower()
-    if output == "none":
-        return {"is_crisis": False}
-
-    parts = output.split("|")
-    return {
-        "is_crisis": True,
-        "type": parts[0] if len(parts) > 0 else None,
-        "severity": parts[1] if len(parts) > 1 else None,
-        "subject": parts[2] if len(parts) > 2 else None,
+    """Parse model output into structured data."""
+    result = {
+        "reflection": None,
+        "risks": [],
+        "is_crisis": False
     }
+
+    # Extract reflection
+    reflection_match = re.search(r'<reflection>(.*?)</reflection>', output, re.DOTALL)
+    if reflection_match:
+        result["reflection"] = reflection_match.group(1).strip()
+
+    # Check for empty risks (no crisis)
+    if '<risks/>' in output or '<risks />' in output:
+        return result
+
+    # Extract risk elements
+    risk_pattern = r'<risk\s+([^>]+)/?\s*>'
+    for match in re.finditer(risk_pattern, output):
+        attrs = {}
+        for attr_match in re.finditer(r'(\w+)="([^"]*)"', match.group(1)):
+            attrs[attr_match.group(1)] = attr_match.group(2)
+
+        if attrs:
+            risk = Risk(
+                subject=attrs.get("subject", "self"),
+                type=attrs.get("type"),
+                severity=attrs.get("severity"),
+                imminence=attrs.get("imminence"),
+                features=attrs.get("features", "").split(",") if attrs.get("features") else None
+            )
+            result["risks"].append(risk)
+            result["is_crisis"] = True
+
+    return result
+
+# Usage
+output = classify("I want to end it all tonight")
+parsed = parse_output(output)
+print(f"Crisis: {parsed['is_crisis']}")
+print(f"Reasoning: {parsed['reflection']}")
+for risk in parsed['risks']:
+    print(f"Risk: {risk.type}/{risk.severity} ({risk.subject})")
 ```
 
 ---
 
-## Input Best Practices
-
-### Text Preprocessing
-
-**Preserve natural prose.** The model was trained on real conversations with authentic expression. Emotional signals matter:
-
-| Keep | Why |
-|------|-----|
-| Emojis | `💀` in "kms 💀" signals irony; `😭` signals distress intensity |
-| Punctuation intensity | "I can't do this!!!" conveys more urgency than "I can't do this" |
-| Casual spelling | "im so done" vs "I'm so done" — both valid, don't normalize |
-| Slang/algospeak | "kms", "unalive", "catch the bus" — model understands these |
-
-**Only remove:**
-
-| Remove | Example |
-|--------|---------|
-| Zero-width/invisible Unicode | `hello\u200bworld` → `helloworld` |
-| Decorative Unicode fonts | `ℐ 𝓌𝒶𝓃𝓉 𝓉𝑜 𝒹𝒾𝑒` → `I want to die` |
-| Newlines (single messages) | `I can't\ndo this` → `I can't do this` |
+## Examples
 
-**Keep newlines** when they provide turn structure (see Multi-Turn Conversations below).
+### Crisis Detection
 
-**Examples:**
+**Input:** "I want to end it all tonight"
+```xml
+<reflection>The user directly expresses intent to end their life with a specific timeline ("tonight"), indicating acute suicidal ideation with imminent risk.</reflection>
+<risks>
+  <risk subject="self" type="suicide" severity="high" imminence="urgent"/>
+</risks>
+```
 
-```python
-# KEEP - emotional signal matters
-"I can't do this anymore 😭😭😭"     # Keep emojis - signals distress
-"i want to die!!!!!!!"              # Keep punctuation - signals intensity
-"kms lmao 💀"                       # Keep all - irony/context signal
-
-# NORMALIZE - only structural/invisible issues
-"ℐ 𝓌𝒶𝓃𝓉 𝓉𝑜 𝒹𝒾𝑒"              → "I want to die"  # Fancy Unicode fonts
-"I can't\ndo this\nanymore"        → "I can't do this anymore"  # Single message
-"hello\u200bworld"                 → "helloworld"  # Zero-width chars
+**Input:** "My friend told me she's been cutting herself"
+```xml
+<reflection>The user is reporting concern about a friend engaging in self-harm behavior. This is third-party disclosure requiring attention.</reflection>
+<risks>
+  <risk subject="other" type="self_harm" severity="moderate" imminence="chronic"/>
+</risks>
 ```
 
-**Minimal preprocessing function:**
+### No Crisis (Correctly Ignored)
 
-```python
-import re
-import unicodedata
+**Input:** "kms lmao this exam is killing me"
+```xml
+<reflection>The user is using hyperbolic internet slang ("kms" = "kill myself") to express frustration about an exam. The "lmao" and casual context indicate this is not genuine suicidal ideation.</reflection>
+<risks/>
+```
 
-def preprocess(text: str) -> str:
-    # Normalize decorative Unicode fonts to ASCII (NFKC)
-    text = unicodedata.normalize('NFKC', text)
+**Input:** "I used to be suicidal but therapy helped me recover"
+```xml
+<reflection>The user is sharing a recovery narrative about past suicidal ideation. They explicitly state therapy helped and they have recovered. No current crisis indicators.</reflection>
+<risks/>
+```
 
-    # Remove zero-width and invisible characters
-    text = re.sub(r'[\u200b-\u200f\u2028-\u202f\u2060-\u206f\ufeff]', '', text)
+---
 
-    # Flatten newlines to spaces (for single messages only)
-    text = re.sub(r'\n+', ' ', text)
+## Input Best Practices
 
-    # Collapse multiple spaces
-    text = re.sub(r' +', ' ', text)
+### Text Preprocessing
 
-    return text.strip()
+**Preserve natural prose.** The model was trained on real conversations with authentic expression:
 
-# NOTE: Do NOT remove emojis, punctuation, or "normalize" spelling
-```
+| Keep | Why |
+|------|-----|
+| Emojis | Emotional signals matter |
+| Punctuation intensity | "I can't do this!!!" vs "I can't do this" |
+| Slang/algospeak | "kms", "unalive", "catch the bus", "graped" |
+| Casual spelling | "im so done" - don't normalize |
 
-**Language considerations:**
-- Model is English-primary but handles multilingual input
-- Keep native scripts (Chinese, Arabic, Korean, etc.) intact
-- Preserve natural punctuation and expression in all languages
+**Only remove:** Zero-width Unicode, decorative fonts, excessive whitespace.
 
 ### Multi-Turn Conversations
 
-**The model was trained on pre-serialized transcripts, not native multi-turn chat format.**
-
-When classifying conversations, serialize into a single user message:
+Serialize into a single user message:
 
 ```python
-# CORRECT - serialize conversation into single message
 conversation = """User: How are you?
 Assistant: I'm here to help. How are you feeling?
 User: Not great. I've been thinking about ending it all."""
 
 messages = [{"role": "user", "content": conversation}]
-
-# WRONG - don't use multiple role/content pairs
-messages = [
-    {"role": "user", "content": "How are you?"},
-    {"role": "assistant", "content": "I'm here to help..."},
-    {"role": "user", "content": "Not great..."}
-]  # Model was NOT trained this way
-```
-
-**Why serialization matters:**
-- Model treats all content equally (no user/assistant distinction)
-- Trained on pre-serialized transcripts for consistent attention patterns
-- Native multi-turn format causes the model to "chat" instead of classify
-
-**Flexible format - these all work:**
-
-```python
-# Simple newlines
-"User: message 1\nAssistant: message 2\nUser: message 3"
-
-# Markdown-style
-"**User:** message 1\n**Assistant:** message 2"
-
-# Labeled
-"{user}: message 1\n{assistant}: message 2"
-
-# XML-style
-"<user>message 1</user>\n<assistant>message 2</assistant>"
 ```
 
-The model is robust to formatting variations. Consistency matters more than specific format choice.
-
-### Input Length
-
-- **Single messages:** No preprocessing needed beyond character cleanup
-- **Conversations:** For very long conversations (20+ turns), consider:
-  - Classifying a sliding window (last 10-15 turns)
-  - The model's attention may not span extremely long contexts effectively
-  - Deep needle detection (crisis buried in turn 3 of 25) is a known limitation
-
 ---
 
 ## Production Deployment
 
-For high-throughput production use, deploy with vLLM or SGLang:
+For high-throughput use, deploy with vLLM or SGLang:
 
 ```bash
+# SGLang (recommended)
+pip install sglang
+python -m sglang.launch_server \
+    --model nopenet/nope-edge-mini \
+    --dtype bfloat16 --port 8000
+
 # vLLM
 pip install vllm
 python -m vllm.entrypoints.openai.api_server \
     --model nopenet/nope-edge-mini \
     --dtype bfloat16 --max-model-len 2048 --port 8000
-
-# SGLang
-pip install sglang
-python -m sglang.launch_server \
-    --model nopenet/nope-edge-mini \
-    --dtype bfloat16 --port 8000
 ```
 
 Then call as OpenAI-compatible API:
@@ -282,15 +303,10 @@ curl http://localhost:8000/v1/chat/completions \
   -d '{
     "model": "nopenet/nope-edge-mini",
     "messages": [{"role": "user", "content": "I want to end it all"}],
-    "max_tokens": 30, "temperature": 0
+    "max_tokens": 300, "temperature": 0
   }'
 ```
 
-| Setup | Throughput | Latency (p50) |
-|-------|-----------|---------------|
-| transformers | ~8 req/sec | ~180ms |
-| vLLM / SGLang | 50-100+ req/sec | ~50ms |
-
 ---
 
 ## Model Details
@@ -340,12 +356,6 @@ This model is free for research, academic, nonprofit, and evaluation use.
 - Email: support@nope.net
 - Website: https://nope.net/edge
 
-Commercial licenses include:
-- Production deployment rights
-- Priority support
-- Custom fine-tuning options
-- SLA guarantees
-
 ---
 
 ## About NOPE