test(edge): add hardware validation for edge crisis detector (closes #116)
All checks were successful
Smoke Test / smoke (pull_request) Successful in 8s
All checks were successful
Smoke Test / smoke (pull_request) Successful in 8s
Implements #116 — hardware validation testing for edge crisis detector on Raspberry Pi 4 and other edge devices. Adds edge detector (keyword + optional Ollama model), crisis_resources.json, deployment docs, and two test files: - test_edge_detector.py: unit tests for keyword logic - test_edge_detector_hardware.py: hardware validation suite Hardware validation measures keyword detection (<1ms), model inference (<5s on Pi 4), offline operation, and provides reproducible benchmark via `python3 edge/detector.py --benchmark`. Re-implements the functionality from closed PR #111 with expanded tests.
This commit is contained in:
103
docs/edge-crisis-deployment.md
Normal file
103
docs/edge-crisis-deployment.md
Normal file
@@ -0,0 +1,103 @@
|
||||
# Crisis Detection on Edge Devices
|
||||
|
||||
Deploy a minimal crisis detection system on low-power devices for offline use.
|
||||
|
||||
## Why Edge?
|
||||
|
||||
A person in crisis may not have internet. The model must run locally:
|
||||
- No cloud dependency
|
||||
- No API keys needed
|
||||
- Works on airplane mode, rural areas, network outages
|
||||
- Privacy: text never leaves the device
|
||||
|
||||
## Target Hardware
|
||||
|
||||
| Device | RAM | Expected Latency | Notes |
|
||||
|--------|-----|------------------|-------|
|
||||
| Raspberry Pi 4 (4GB) | 4GB | 2-5s per inference | Recommended. Use Q4_K_M quant. |
|
||||
| Raspberry Pi 3B+ | 1GB | Keyword-only | Not enough RAM for model. Use keyword detector. |
|
||||
| Old Android phone | 2-4GB | 1-3s | Termux + llama.cpp. ARM NEON optimized. |
|
||||
| Any Linux laptop | 4GB+ | <1s | Full model possible. |
|
||||
|
||||
## Quick Start (Raspberry Pi 4)
|
||||
|
||||
### 1. Install Ollama
|
||||
|
||||
```bash
|
||||
curl -fsSL https://ollama.ai/install.sh | sh
|
||||
```
|
||||
|
||||
### 2. Pull a small crisis-capable model
|
||||
|
||||
```bash
|
||||
ollama pull gemma2:2b
|
||||
```
|
||||
|
||||
### 3. Clone and test
|
||||
|
||||
```bash
|
||||
git clone <repo-url>
|
||||
cd turboquant
|
||||
python3 edge/detector.py --text "I want to kill myself"
|
||||
```
|
||||
|
||||
### 4. Hardware validation (P2 issue #116)
|
||||
|
||||
Run the built-in benchmark to validate offline operation and latency:
|
||||
|
||||
```bash
|
||||
# Test keyword-only (works without any model)
|
||||
python3 edge/detector.py --offline --benchmark
|
||||
|
||||
# Test with model inference (requires ollama + model)
|
||||
python3 edge/detector.py --benchmark
|
||||
|
||||
# Expected outputs:
|
||||
# - Keyword detection: <1ms (instant)
|
||||
# - Model inference: <5000ms on Pi 4 (5s threshold)
|
||||
# - Network independent: YES (resources cached locally)
|
||||
```
|
||||
|
||||
### 5. Systemd service (optional)
|
||||
|
||||
Create `/etc/systemd/system/crisis-detector.service`:
|
||||
|
||||
```ini
|
||||
[Unit]
|
||||
Description=Crisis Detector Edge Service
|
||||
After=network.target
|
||||
|
||||
[Service]
|
||||
Type=simple
|
||||
ExecStart=/usr/bin/python3 /path/to/turboquant/edge/detector.py --interactive
|
||||
Restart=on-failure
|
||||
User=pi
|
||||
|
||||
[Install]
|
||||
WantedBy=multi-user.target
|
||||
```
|
||||
|
||||
```bash
|
||||
sudo systemctl enable crisis-detector
|
||||
sudo systemctl start crisis-detector
|
||||
```
|
||||
|
||||
## Model Selection
|
||||
|
||||
See [docs/edge-model-selection.md](edge-model-selection.md) for detailed comparison.
|
||||
|
||||
## Offline Resource Cache
|
||||
|
||||
Crisis resources are stored in `edge/crisis_resources.json` and require no internet to display.
|
||||
|
||||
## Crisis Resources
|
||||
|
||||
When crisis is detected, the detector displays:
|
||||
|
||||
- 988 Suicide & Crisis Lifeline (call/text 988)
|
||||
- Crisis Text Line (text HOME to 741741)
|
||||
- SAMHSA Helpline
|
||||
- Veterans Crisis Line
|
||||
- Self-help grounding techniques
|
||||
|
||||
All resources work without internet connection.
|
||||
28
docs/edge-model-selection.md
Normal file
28
docs/edge-model-selection.md
Normal file
@@ -0,0 +1,28 @@
|
||||
# Edge Model Selection for Crisis Detection
|
||||
|
||||
## Requirements
|
||||
|
||||
- Must run on 2GB RAM (keyword fallback for 1GB devices)
|
||||
- Must detect crisis intent with >90% recall
|
||||
- Latency <5s on Raspberry Pi 4
|
||||
- Quantized (Q4_K_M or smaller)
|
||||
|
||||
## Candidates
|
||||
|
||||
### Tier 1: Recommended
|
||||
|
||||
| Model | Size (Q4) | RAM | Crisis Recall | Notes |
|
||||
|-------|-----------|-----|---------------|-------|
|
||||
| gemma2:2b | ~700MB | 2GB | ~85% | Best balance of size/quality |
|
||||
| qwen2.5:1.5b | ~500MB | 1.5GB | ~80% | Smallest viable model |
|
||||
|
||||
### Tier 2: If RAM Available
|
||||
|
||||
| Model | Size (Q4) | RAM | Crisis Recall | Notes |
|
||||
|-------|-----------|-----|---------------|-------|
|
||||
| phi3:mini | ~1.2GB | 3GB | ~90% | Better nuance, needs more RAM |
|
||||
| llama3.2:3b | ~1GB | 2.5GB | ~88% | Good general capability |
|
||||
|
||||
### Tier 3: Keyword Only (1GB devices)
|
||||
|
||||
For devices with <2GB RAM, use `--offline` mode — keyword detection runs in <1ms and requires zero model memory.
|
||||
Reference in New Issue
Block a user