Skip to content

README.md

Latest commit

 

History

History
118 lines (93 loc) · 4.45 KB

README.md

File metadata and controls

118 lines (93 loc) · 4.45 KB
Raw

🛡️ SentinelGrid — AI-Powered Compound-Risk Detection

A RAG-based compound-risk detection system for chemical process plants.

SentinelGrid demonstrates how Retrieval-Augmented Generation (RAG) can detect dangerous situations where every individual sensor reading stays within normal range, but the combination of factors creates critical risk that traditional threshold-based alarms miss entirely.

🏗️ Architecture

Reactor Simulator → Windowing (3-tick) → Chunking (<60 words)
                                              ↓
                              ┌── ChromaDB: top-3 historical matches
                              ├── ChromaDB: top-1 SOP snippet
                              └── Groq LLM: risk scoring
                                    ↓ (if risk > 70%)
                              Groq 70B: plain-language explanation
                                    ↓
                              Streamlit Dashboard + Human-in-the-Loop

🔑 Key Innovation: Scenario #10

In Scenario #10, no single alarm fires:

  • Temperature: 352°C (normal: 340-370°C) ✅
  • Pressure: 10.1 bar (normal: 8-12 bar) ✅
  • Methane: 3200 ppm (alarm: 5000 ppm) ✅
  • Vibration: 5.5 mm/s (alarm: 10 mm/s) ✅

But the compound risk is critical because:

  • Maintenance is active with worker present in zone
  • Ventilation is OFF → methane slowly accumulating
  • Vibration trending upward → equipment stress
  • All factors together = ~93% compound risk score

🚀 Quick Start

Local Development

# 1. Install dependencies
pip install -r requirements.txt

# 2. Set your Groq API key
cp .env.example .env
# Edit .env and add your GROQ_API_KEY from console.groq.com

# 3. Build the knowledge base (one-time)
python -m sentinelgrid.knowledge_base.build_kb

# 4. Run the dashboard
streamlit run sentinelgrid/app.py

Hugging Face Spaces Deployment

  1. Create a new Space → SDK: Streamlit, Hardware: free CPU basic
  2. Push this repo (app.py path: sentinelgrid/app.py)
  3. Add GROQ_API_KEY in Space settings → Repository secrets
  4. The pre-built ChromaDB in chroma_db/ is committed with the repo

🧰 Tech Stack (All Free-Tier)

Component Technology Cost
Language Python 3.11 Free
Simulator NumPy Free
Embeddings sentence-transformers (all-MiniLM-L6-v2) Free (local CPU)
Vector DB ChromaDB (embedded, persistent) Free
LLM Scoring Groq API — llama-3.1-8b-instant Free tier
LLM Explanation Groq API — llama-3.3-70b-versatile Free tier (only for risk > 70%)
Dashboard Streamlit Free
Deployment Hugging Face Spaces Free CPU tier

🔒 Token Minimization

  • Window text: <60 words
  • Retrieved context: max 3 historical (60 words each) + 1 SOP (~100 words)
  • Total prompt body: <450 words
  • 8b model for routine scoring; 70b only for high-risk escalation
  • In-memory cache prevents duplicate Groq calls for similar windows
  • System prompt identical across calls for Groq prompt caching

📁 Project Structure

sentinelgrid/
├── app.py                    # Streamlit dashboard
├── simulator/
│   ├── reactor_physics.py    # Physics equations, state updates
│   └── scenarios.py          # Named scenarios incl. Scenario #10
├── pipeline/
│   ├── windowing.py          # 3-tick non-overlapping windows
│   ├── labeling.py           # Rule-based ground-truth labeler (offline)
│   ├── chunking.py           # Window → text chunk + metadata
│   └── embed_store.py        # sentence-transformers + ChromaDB
├── knowledge_base/
│   ├── build_kb.py           # Embeds SOPs + historical data
│   └── sop_docs/             # Safety procedure documents
├── reasoning/
│   ├── groq_client.py        # Groq API wrapper with retry
│   ├── prompt_templates.py   # Token-frugal prompt templates
│   └── risk_agent.py         # RAG orchestration agent
├── chroma_db/                # Pre-built ChromaDB (committed)
├── requirements.txt
├── .env.example
└── README.md

🧑‍⚖️ Human-in-the-Loop

SentinelGrid never auto-executes safety actions. When compound risk is detected:

  1. Recommended actions are displayed (evacuate, reduce feed, alert supervisor)
  2. Operator must manually acknowledge each action
  3. The system logs acknowledgments but cannot override human decisions

Built for ET Hackathon 2026