turboquant/docs/edge-crisis-deployment.md

Edge Crisis Detection — Deployment Guide

Part of: turboquant#99 (1-Bit Models + Edge) Issue: #102

Overview

Deploy a minimal crisis detection system on edge devices for offline use. When internet is unavailable but someone is in crisis, a local device can detect distress signals and display cached crisis resources.

Target Hardware

Device	RAM	Notes
Raspberry Pi 4	4GB	Recommended. Runs keyword + Falcon-H1-Tiny-90M
Raspberry Pi 4	2GB	Keyword detection only (no LLM)
Old Android phone	2GB+	Termux + llama.cpp, Falcon-H1-Tiny-90M
Any x86 SBC	2GB+	Full keyword + optional small model

Model Selection

Tier 0: Keyword Detection (any device, <10MB)

• No model needed — pure pattern matching
• Instant response (<1ms)
• Works on 512MB RAM devices
• Covers 80%+ of explicit crisis language
• Use when: RAM < 2GB or first-boot before model download

Tier 1: Falcon-H1-Tiny-90M (~180MB quantized)

• Detects nuanced/implicit distress that keywords miss
• Runs on 2GB+ RAM (Pi 4 4GB recommended)
• ~200ms inference on Pi 4 (CPU)
• Quantized Q4_K_M via llama.cpp
• Use when: RAM >= 2GB, want higher recall

Tier 2: Bonsai-1.7B (~900MB quantized)

• Best accuracy for ambiguous cases
• Needs 3GB+ RAM
• ~1.5s inference on Pi 4
• Use when: RAM >= 4GB, false-positive tolerance is low

Recommendation

Start with Tier 0 + Tier 1. Keyword catches obvious cases instantly, Falcon-H1 catches implicit cases with 200ms latency. Together they cover

95% of crisis signals with negligible resource use.

Installation

Raspberry Pi 4

# 1. System setup
sudo apt update && sudo apt install -y python3 python3-pip git cmake

# 2. Clone this directory
git clone https://forge.alexanderwhitestone.com/Timmy_Foundation/turboquant.git
cd turboquant

# 3. Python keyword detector runs with zero dependencies (pure stdlib)

# 4. (Optional) Build llama.cpp for Tier 1 model
git clone https://github.com/ggerganov/llama.cpp
cd llama.cpp && make -j4 && cd ..

# 5. Download model (Tier 1)
mkdir -p models
# Falcon-H1-Tiny-90M GGUF — find latest on HuggingFace
# wget -O models/falcon-h1-tiny-90m-q4km.gguf <URL>

# 6. Test offline crisis detection
python3 scripts/crisis_detector.py --test

Android (Termux)

pkg install python git cmake
# Follow Pi steps above, but build llama.cpp with:
cmake -B build -DLLAMA_NATIVE=OFF && cmake --build build -j$(nproc)

Auto-Start on Boot (Pi)

# Add to /etc/rc.local (before 'exit 0'):
python3 /home/pi/turboquant/scripts/crisis_detector.py --daemon &

Or create a systemd service:

# /etc/systemd/system/crisis-detector.service
[Unit]
Description=Edge Crisis Detector
After=network.target

[Service]
ExecStart=/usr/bin/python3 /home/pi/turboquant/scripts/crisis_detector.py --daemon
Restart=always
User=pi

[Install]
WantedBy=multi-user.target

sudo systemctl enable crisis-detector
sudo systemctl start crisis-detector

Offline Resource Cache

The file data/crisis_resources.json is bundled with the deployment. It contains:

• 988 Suicide & Crisis Lifeline — call or text 988
• Crisis Text Line — text HOME to 741741
• International Association for Suicide Prevention — global directory
• Cached local resources (customize per deployment location)

These display immediately when a crisis is detected — no network required.

How It Works

User input
    |
    v
+-------------------+
| Keyword Matcher   | <- Tier 0: instant, no model
| (regex/pattern)   |
+--------+----------+
  match? --yes--> Show crisis resources
    |
    no
    v
+-------------------+
| Falcon-H1-Tiny    | <- Tier 1: ~200ms on Pi 4
| (if available)    |
+--------+----------+
  crisis? --yes--> Show crisis resources
    |
    no
    v
  Continue normally

Testing Offline

# Disconnect from internet
sudo ip link set wlan0 down

# Run the test suite
python3 scripts/crisis_detector.py --test

# Expected: all tests pass, resources display correctly

# Reconnect
sudo ip link set wlan0 up

File Structure

turboquant/
+-- scripts/
|   +-- crisis_detector.py      # Main detector (keyword + optional LLM)
+-- data/
|   +-- crisis_resources.json   # Offline resource cache
+-- tests/
|   +-- test_edge_crisis.py     # Offline verification tests
+-- docs/
    +-- edge-crisis-deployment.md  # This file

Customization

Adding Local Resources

Edit data/crisis_resources.json:

{
  "local_resources": [
    {
      "name": "City Crisis Center",
      "phone": "555-0123",
      "address": "123 Main St",
      "hours": "24/7"
    }
  ]
}

Adjusting Sensitivity

In scripts/crisis_detector.py:

# Keyword threshold: how many keywords trigger a match
KEYWORD_THRESHOLD = 1  # 1 = any keyword triggers (high recall)
                       # 2 = need 2+ keywords (higher precision)

# LLM threshold (Tier 1/2): confidence score cutoff
LLM_THRESHOLD = 0.6    # 0.6 = default (balanced)
                       # 0.4 = more sensitive
                       # 0.8 = more precise

Privacy

• No data leaves the device. All detection runs locally.
• No logs of user input are stored by default.
• Enable logging only for debugging (--log flag).
• No network calls are made by the crisis detector.
• Resource display is a local text render.

License

Same as parent project. Crisis detection code and resource data are provided for humanitarian purposes.