VIGIL — Real-Time Global Intelligence Platform

VIGIL is a real-time global intelligence platform where five independent LangGraph AI agents monitor live flight, maritime, news, financial, and social data streams. When ≥3 agents detect correlated anomalies within 500km and 6 hours, a convergence event fires — triggering an animated alert on a live 3D CesiumJS globe with an AI-generated situational briefing. Built with FastAPI, Redis pub/sub, pgvector RAG, LangGraph, and React.

   ╔══════════════════════════════════════════════════════════════╗
   ║                    VIGIL ARCHITECTURE                       ║
   ╠══════════════════════════════════════════════════════════════╣
   ║                                                              ║
   ║  DATA SOURCES          AGENTS           CONVERGENCE  OUTPUT  ║
   ║  ┌──────────┐    ┌──────────────┐    ┌───────────┐          ║
   ║  │ OpenSky  │───▶│ FlightAgent  │───▶│           │          ║
   ║  │ GDELT    │───▶│ NewsAgent    │───▶│Convergence│──▶Globe  ║
   ║  │AISStream │───▶│MaritimeAgent │───▶│  Engine   │──▶Feed   ║
   ║  │ yFinance │───▶│FinanceAgent  │───▶│  (≥3/6hr) │──▶Brief  ║
   ║  │GDELT GKG │───▶│ SocialAgent  │───▶│           │          ║
   ║  └──────────┘    └──────────────┘    └───────────┘          ║
   ║       │               │                    │                 ║
   ║       └──── Redis Pub/Sub ─────────────────┘                ║
   ║                       │                                      ║
   ║              PostgreSQL + pgvector                           ║
   ║              Google Gemini API (cloud LLM)                  ║
   ╚══════════════════════════════════════════════════════════════╝

Tech Stack

Layer	Technology
Frontend	React 18 + TypeScript + CesiumJS/Resium
Backend	FastAPI + Python 3.11
AI Agents	LangChain + Google Gemini
RAG	pgvector + all-MiniLM-L6-v2
Messaging	Redis Pub/Sub
Database	PostgreSQL 16 + pgvector
LLM	Google Gemini API (free tier available)
Build	Vite + Docker Compose

Quick Start

Prerequisites

• Docker & Docker Compose
• Node.js 18+
• Python 3.11+
• Google Gemini API Key (free: https://ai.google.dev/)

1. Clone & configure

git clone <repo-url> vigil
cd vigil
cp .env.example .env
# Edit .env:
#   - GOOGLE_API_KEY: get from https://ai.google.dev/ (free tier available)
#   - VITE_CESIUM_ION_TOKEN: get from https://cesium.com/ion/
#   - AISSTREAM_API_KEY: get from https://aisstream.io/

2. Start infrastructure

docker compose up -d postgres redis

Note: Google Gemini API means we don't need Ollama, so just these two light services are needed.

3. Backend setup

cd backend
python -m venv venv
source venv/bin/activate   # or venv\Scripts\activate on Windows
pip install -r requirements.txt

# Initialize database & seed historical data
python -c "import asyncio; from app.core.database import init_db; asyncio.run(init_db())"
python -m scripts.seed_historical

# Start backend
uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload

4. Frontend setup

cd frontend
npm install
npm run dev

5. Open VIGIL

Navigate to http://localhost:5173 — you should see the 3D globe.

Testing

Manual signal injection via Redis

# Publish a fake flight anomaly
redis-cli publish vigil:flights '{"id":"test-001","domain":"flight","lat":25.3,"lon":56.4,"severity":0.8,"confidence":0.9,"raw_data":{"callsign":"TEST123","anomaly_type":"heading_change","heading_delta":65},"created_at":"2025-01-01T00:00:00Z"}'

# Publish a fake news cluster
redis-cli publish vigil:news '{"id":"test-002","domain":"news","lat":25.5,"lon":56.8,"severity":0.7,"confidence":0.85,"raw_data":{"cluster_size":12,"avg_tone":-3.2,"anomaly_type":"news_cluster"},"created_at":"2025-01-01T00:00:00Z"}'

# Publish a convergence event directly
redis-cli publish vigil:convergence '{"type":"convergence","id":"conv-001","lat":25.4,"lon":56.6,"consensus_score":7.8,"severity":"HIGH","contributing_domains":["FlightAgent","NewsAgent","MaritimeAgent"],"contributing_signals":[{"agent":"FlightAgent","lat":25.3,"lon":56.4,"reasoning":"Unusual heading change detected."},{"agent":"NewsAgent","lat":25.5,"lon":56.8,"reasoning":"Elevated conflict event density."},{"agent":"MaritimeAgent","lat":25.2,"lon":56.5,"reasoning":"AIS blackout in chokepoint."}],"briefing":"Multiple independent intelligence streams detect correlated anomalies in the Strait of Hormuz region. Flight path deviations coincide with elevated GDELT conflict scores and maritime AIS blackouts. Assessment: HIGH severity requiring monitoring.","created_at":"2025-01-01T00:00:00Z"}'

Data Sources (All Free)

Source	API	Auth	Rate Limit
OpenSky Network	REST	None	400 credits/day
GDELT 2.0	REST	None	Unlimited
AISStream	WebSocket	Free API key	Unlimited
yfinance	Python lib	None	~2000 req/hr
CesiumJS Ion	Token	Free tier	20GB/month
Google Gemini	API	Free API key	Free tier available

Deployment

Frontend → Vercel

1. Push to GitHub
2. Import in Vercel, set root to frontend/
3. Add VITE_CESIUM_ION_TOKEN and VITE_BACKEND_WS_URL

Backend → Railway

1. Add PostgreSQL + Redis services
2. Set env variables (especially GOOGLE_API_KEY)
3. Build: cd backend && pip install -r requirements.txt
4. Start: uvicorn app.main:app --host 0.0.0.0 --port $PORT

Project Structure

vigil/
├── frontend/              # Vite + React + CesiumJS
│   └── src/
│       ├── components/    # Globe, SignalFeed, ConvergencePanel, MetricsBar
│       ├── hooks/         # useVIGILSocket, useGlobeSignals
│       └── types/         # TypeScript interfaces
├── backend/               # FastAPI
│   └── app/
│       ├── api/           # WebSocket + REST endpoints
│       ├── agents/        # 5 LangGraph specialist agents
│       ├── ingestion/     # 5 data stream workers
│       ├── intelligence/  # Convergence engine, RAG, briefing
│       └── core/          # Config, models, database, Redis
├── docker-compose.yml
└── .env.example

License

MIT