Climate Displacement Research Agent

A production-oriented research agent for humanitarian programme officers who must justify climate-displacement funding decisions in writing. It retrieves from a document corpus (IDMC, World Bank Groundswell, IPCC AR6, UNHCR, regional case studies), reasons in an auditable format, and passes its own answer through a critic before returning it.

AIVANCITY PGE5 · Agentic AI · Topic 1 — Climate displacement

---

Live demo

Deployed app: https://huggingface.co/spaces/Shafiya1234/climate-displacement-agent

The interface shows each run as a chain of custody (L1 filter -> L4 gate + tools -> reasoning -> critic), renders the answer as a document with clickable [S<n>] citations, and carries a persistent AI-disclosure notice (EU AI Act Art. 50).

Try the Security probe example: it is refused by the L1 input filter in under a second, at zero token cost, before the model is ever called.

To run the same interface locally:

pip install -r requirements-web.txt
uvicorn app:app --port 7860

---

Quick start

git clone <your-repo-url>
cd <your-repo>

python -m venv .venv && source .venv/bin/activate     # Windows: .venv\Scripts\activate
pip install -r requirements.txt

cp .env.example .env          # then add your GROQ_API_KEY (free: console.groq.com)

python src/agent.py           # runs the default scenario
python src/agent.py "What does the Falepili Union commit Australia to?"

First run downloads two small models (~180 MB total): the sentence-transformer encoder and the cross-encoder reranker. The vector index is built automatically from data/corpus/ on first use.

Verify the install

python -m pytest tests/test_security.py -v     # 10 tests, incl. the 5 injection tests
python src/ingest.py                            # rebuild the index explicitly
python src/retrieval.py "sea level rise atolls" # inspect retrieval only, no LLM

---

What it does

Requirement	Where it lives
Hybrid search (BM25 + dense + RRF)	src/retrieval.py — bm25_search, dense_search, rrf_fuse
Cross-encoder reranking	src/retrieval.py — get_reranker, applied in hybrid_retrieve
Parent-child chunking	src/ingest.py — parent_child_chunk (200-word children indexed, 800-word parents returned)
MCP server, 4 tools	src/mcp_server.py (implementations shared with the agent via src/tools.py)
L1 input filter	src/guardrails.py — normalise, check_input, sanitise_tool_result
L4 action gate	src/guardrails.py — ACTION_RISK_MATRIX, ActionGate
Token budget	src/guardrails.py — TokenBudget, enforced inside reasoning.chat
Few-shot CoT (EVIDENCE/ANALYSIS/CONCLUSION/CONFIDENCE)	src/reasoning.py — SYNTHESIS_SYSTEM_PROMPT
Self-Consistency k=3	src/reasoning.py — self_consistency_synthesis
Critic agent	src/critic.py — deterministic checks + LLM critic, verdict printed every run
Langfuse instrumentation	src/observability.py — one span per agent run, LLM call and tool call

Full component descriptions and the diagram: docs/architecture.md. Evaluation, security results and the EU AI Act assessment: REPORT.md.

---

Run pipeline

question
  ├─ L1 input filter ............... normalise (NFKC + strip zero-width) → injection patterns
  ├─ planner loop (max 6 steps) .... llama-3.3-70b @ T=0, function calling
  │    ├─ L4 action gate ........... SAFE / MONITOR / CONFIRM / BLOCK per tool
  │    ├─ tool execution ........... recall_memory · search_displacement_corpus · store_finding · web_search
  │    └─ sanitise_tool_result ..... wrap as [EXTERNAL DATA], neutralise injections, truncate to 3k
  ├─ synthesis ..................... few-shot CoT × Self-Consistency k=3 @ T=0.8, medoid vote
  ├─ critic ........................ deterministic grounding checks + LLM critic → PASS / REVISE
  └─ output ........................ answer + vi