# GroundTruth — Crisis Verification Agent for Slack

> Every agent answers. **GroundTruth verifies.**

During disasters, the deadliest thing in a coordination channel isn't slow information — it's **wrong information**. GroundTruth is a Slack agent that fact-checks every actionable instruction in a crisis channel against official advisories using retrieval-augmented verification, replies in-thread with a cited verdict, escalates dangerous misinformation, and keeps a tamper-evident audit log.

Built for the **Slack Agent Builder Challenge 2026** — *Slack Agent for Good* track.

## Verdicts

| Verdict | Meaning | Action taken |
|---|---|---|
| ✅ VERIFIED | Consistent with a cited official advisory | Threaded confirmation + citation |
| ⚠️ UNVERIFIED | No official source covers this claim | Threaded caution notice |
| 🚨 DANGEROUS | Contradicts official guidance | Threaded correction + auto-escalation to `#crisis-alerts` |

Every verdict is appended to a **hash-chained audit log** (`audit/verdicts.jsonl`) — change any historical record and the chain breaks, so post-crisis accountability is provable.

## Architecture

![Architecture](docs/architecture.png)

```
Slack #crisis-ops ──messages──▶ GroundTruth Agent (Bolt, Socket Mode)
                                 │  claim extraction (actionable-only filter)
                                 ▼
                    Verification engine  ◀── also exposed as an MCP server
                    embed → retrieve (advisory corpus) → verdict
                                 │
        ┌────────────────────────┼──────────────────────┐
        ▼                        ▼                       ▼
  Threaded verdict card    #crisis-alerts          Hash-chained
  (Block Kit + citation)   escalation (🚨 only)    audit log (JSONL)
```

- **Retrieval:** sentence-transformers (`all-MiniLM-L6-v2`) if installed, TF-IDF fallback otherwise — the test suite runs on the fallback, no heavy downloads needed.
- **MCP:** the same engine is exposed as an MCP server (`mcp_server.py`) with `verify_claim` and `corpus_info` tools, so any MCP-capable agent can use GroundTruth as a verification tool.

## Quickstart (10 minutes)

1. **Create the Slack app:** [api.slack.com/apps](https://api.slack.com/apps) → *Create New App* → **From an app manifest** → pick your sandbox workspace → paste `manifest.json`.
2. **Tokens:** Install the app to the workspace → copy the **Bot User OAuth Token** (`xoxb-…`). Then *Basic Information → App-Level Tokens* → generate a token with `connections:write` scope (`xapp-…`).
3. **Configure:**
   ```bash
   cp .env.example .env    # paste both tokens; set ALERTS_CHANNEL
   pip install -r requirements.txt
   ```
4. **Create channels** `#crisis-ops` and `#crisis-alerts` in the workspace and `/invite @GroundTruth` into both.
5. **Run:**
   ```bash
   python app.py
   ```
6. **Demo it:** post in `#crisis-ops`:
   > Water at Relief Camp B is safe to drink

   GroundTruth replies 🚨 in-thread with the contradicting advisory citation and escalates to `#crisis-alerts`. Try `/groundtruth check Riverside Bridge is open` for the on-demand path.

## Tests

```bash
python -m pytest tests/ -q     # 7 tests: verdicts, claim filter, audit chain
```

## Demo corpus

`data/advisories/` contains an **original demo corpus** written for this hackathon in the style of official flood advisories (clearly marked `DEMO CORPUS`). In deployment, drop real advisories from your authority (NDMA / WHO / state EOC) into the folder — the engine indexes any `.md` files at startup.

## Limitations (honest MVP notes)

- Contradiction detection is a transparent **lexical polarity heuristic** over the retrieved passage. It handles the common crisis pattern ("X is safe" vs "X is NOT safe") well, but a production build should replace `_stance()` with an NLI cross-encoder.
- Claim extraction is keyword-based; a production build would use an LLM pass (Slack AI) for higher recall.
- The corpus is static at startup; live advisory ingestion via the Real-Time Search API is the next milestone.

## Roadmap

Multi-language claims (Hindi/Gujarati) · live advisory ingestion (RTS API) · NLI-based stance model · per-channel corpus scoping.

## Credits

Built by **Ravi Gohel** (B.Tech CSE — AI/ML, Marwadi University) for the Slack Agent Builder Challenge 2026, with AI-assisted development. Verification approach informed by the author's research on safe/unsafe instruction classification with RAG grounding.

MIT License.