Oculus IQ

OculusIQ is a multi-agent operations intelligence system where specialized AI agents collaborate, share memory, and predict disruptions to enable proactive decision-making.

Comment

⚡ TL;DR for judges

AI Demo Walkthrough- https://app.trupeer.ai/view/HD6l3UQdG/oculus-iq-user-manual

Documentation- https://drive.google.com/file/d/1e8O-rKWullYc3_UhWpmVtrHTpS8ro08j/view?usp=sharing

OculusIQ hands a freight forwarder managing 150 SME clients a single command screen. It ingests shipment data, runs a 6-agent AI pipeline, scores every cargo item on a live Disruption Risk Index, simulates what a Suez Canal closure does to each client's SLA, and generates a WhatsApp-ready alert — all before the manager finishes their morning coffee.

What makes it different from every supply chain dashboard:

  • 🧠 A genuine multi-agent memory architecture. Six specialized agents share context through structured recall — the Cost Agent never re-reads the raw data; it reads what the Risk Agent already found.
  • 📦 Built for freight forwarders, not Fortune 500. Every existing tool is designed for one company. OculusIQ is designed for someone managing 150 companies simultaneously.
  • 💰 Tariff-adjusted landed cost in real time. With US-China tariffs at 145% in 2026, routing decisions are now tariff decisions. OculusIQ calculates the full landed cost of every alternative route before recommending it.
  • 🌊 Live disaster data on the map. GDACS cyclones, floods, and earthquakes appear as pulsing risk zones over active shipping corridors — no paid API, no key required.
  • 📱 WhatsApp-native alerts. Because in India and Southeast Asia, business runs on WhatsApp — not Salesforce.

💡 Inspiration

It started with a single observation that wouldn't leave us alone.

FourKites charges $300,000 a year. Their smallest customer is a Fortune 500 company. Their implementation takes six months and requires integrating with an ERP system most mid-market companies don't even have.

Meanwhile, India has 63 million MSMEs contributing 45.7% of the country's total exports. Most of them manage their entire supply chain through WhatsApp groups, Excel files, and three different carrier portals that don't talk to each other.

When the Red Sea crisis hit in late 2024, rerouting 30% of global container traffic via the Cape of Good Hope, these companies found out about it the same way their clients did: the shipment just didn't arrive.

We asked a simple question: why does enterprise-grade supply chain intelligence have to cost enterprise money? Gemini 1.5 Flash is free. Open-Meteo is free. GDACS is free. OpenStreetMap is free. The intelligence layer — the part that actually matters — costs nothing to run.

So we built OculusIQ: the freight intelligence platform that Ravi, a logistics operations head in Mumbai managing 120 SME clients, can set up in under an hour and use without a single technical integration.

The supply chain doesn't fail loudly. It fails quietly, over hours, across thousands of interdependent decisions. OculusIQ is the system that hears it before it falls.

🚢 What it does (the story)

You are a freight forwarder. It is 6:47 AM. You open OculusIQ.

The Operations Command Map loads — 500 shipment markers spread across global corridors, color-coded by Disruption Risk Index. Three are pulsing red. A GDACS alert has flagged a Category 3 cyclone entering the South China Sea. Eleven of your clients have cargo in the impact corridor.

You click the first critical marker. The Risk Agent's assessment loads instantly: risk score 91/100, three contributing factors — cyclone proximity, Port of Shanghai at 94% berth saturation, carrier MSC Elara flagged for mechanical inspection. The cascade analysis shows four additional shipments that will be affected when these delays compound at Rotterdam.

You open the Cost Intelligence Agent's route alternatives. Three options appear, each with full tariff-adjusted landed cost: freight + applicable tariff rate under the current trade regime + EU CBAM surcharge + insurance + port handling. Not just "go this way" — the total bill, itemized, before you commit.

The SLA Agent has already calculated that two of your clients — MediCare Pharma (99.5% SLA target) and BrightTech Electronics — are at breach risk if these shipments don't reroute within 18 hours. Their urgency scores are at the top of your action queue.

You open the Communication Agent's output. A WhatsApp message is pre-composed, client-specific, referencing the actual shipment ID and realistic new ETA, formatted for instant forwarding. You copy it. You send it. The client knows before anyone else does.

Twelve seconds. That's what used to take three hours of portal-checking, email drafting, and carrier hold music.

The 6-Agent Intelligence Pipeline

Open-Meteo + GDACS + Port Data + Carrier History
                         │
                         ▼
┌─────────────────────────────────────────────────────────────────┐
│  1 · RISK AGENT                                                 │
│  Scores 0–100 DRI per shipment  │  Cascade propagation          │
│  Z-score anomaly detection      │  Writes to shared context     │
└──────────────────────┬──────────────────────────────────────────┘
                       │
                       ▼
┌─────────────────────────────────────────────────────────────────┐
│  2 · SLA AGENT                                                  │
│  Recalls risk records (no raw reread)                           │
│  Maps to client SLA contracts  │  Breach probability per client │
└──────────────────────┬──────────────────────────────────────────┘
                       │
                       ▼
┌─────────────────────────────────────────────────────────────────┐
│  3 · COST INTELLIGENCE AGENT                                    │
│  Recalls affected routes       │  Tariff-adjusted landed cost   │
│  Dijkstra across 27-node port graph                             │
└──────────────────────┬──────────────────────────────────────────┘
                       │
                       ▼
┌─────────────────────────────────────────────────────────────────┐
│  4 · DOCUMENT INTELLIGENCE AGENT                                │
│  B/L text → 18 structured fields  │  Gemini 1.5 Flash          │
│  CSV import → geocoded shipments                                │
└──────────────────────┬──────────────────────────────────────────┘
                       │
                       ▼
┌─────────────────────────────────────────────────────────────────┐
│  5 · OPERATIONS AGENT                                           │
│  Combines all upstream context  │  6-scenario what-if           │
│  Action plans per client/operator                               │
└──────────────────────┬──────────────────────────────────────────┘
                       │
                       ▼
┌─────────────────────────────────────────────────────────────────┐
│  6 · COMMUNICATION AGENT                                        │
│  Recalls all findings — no access to original datasets          │
│  WhatsApp + email + weekly report                               │
└─────────────────────────────────────────────────────────────────┘

The key architectural principle: Agent N+1 reads Agent N's structured output — not the raw data. If upstream fields are missing, downstream agents raise explicitly. This is not a vibe — it is a provable data dependency enforced in the pipeline.

What each screen shows

Operations Command Map — One Leaflet map containing everything: live shipment positions, 27 port nodes sized by capacity and colored by congestion score, major shipping corridor overlays, chokepoint status (Suez · Malacca · Hormuz), active disruption zones, and GDACS disaster events as animated pulsing risk circles. Layer toggles let operators show exactly what they need. + Add Cargo, + Add Port, + Add Route directly from the map interface.

Cargo Portfolio — 500 shipments filterable by client, carrier, lane, mode, and risk level. Each row shows Disruption Risk Index, tariff-adjusted landed cost, HS code, incoterm, and SLA impact. Row-level edit for status and ETA. Bulk import via CSV with 19-column validation and Nominatim geocoding.

Client Intelligence Hub — The view that doesn't exist anywhere else at this price point. Every client: SLA gauge, active cargo value, at-risk shipment count, breach probability. Click any client → see their full risk-ranked shipment list, WhatsApp alert generator, and weekly performance report. The freight forwarder has never had this before.

Intelligence Center — On-demand scans powered by the Risk, SLA, and Operations Agents simultaneously. Anomaly detection flags: risk spikes (Z > 2.5σ), silent delays (ETA passed, status not updated), and carrier cluster failures (>40% of a carrier's fleet delayed simultaneously). Cascade graph shows interdependencies.

Risk Scenario Studio — Six real-world disruption scenarios with full cascade simulation: Suez Canal closure, South China Sea typhoon, Shanghai port lockdown, Rotterdam dock strike, global bunker fuel shortage, carrier ransomware attack. Target by specific client, shipment, or operator. Financial impact in dollars, itemized: delay cost + rerouting premium + insurance spike + SLA penalty clauses.

🔧 How we built it

Backend: FastAPI + SQLAlchemy Async + SQLite (WAL mode) + APScheduler + Uvicorn. The WAL-mode SQLite handles concurrent reads during live demo without locking — a critical detail when the background scheduler is refreshing risk scores every 5 minutes while the map is live.

AI Layer: Google Gemini 1.5 Flash via google-generativeai SDK. Every Gemini call runs in asyncio.run_in_executor because the SDK is synchronous but FastAPI is async. Every call has a deterministic fallback template — the app never crashes or shows empty states regardless of API key status.

Intelligence: The Risk Engine is pure Python weighted scoring — weather severity (35 pts), route type risk (20 pts), carrier historical delay rate (20 pts), cargo sensitivity (15 pts), seasonal risk (10 pts). The Cascade Propagation Engine identifies co-arriving shipments at the same destination port within a ±48h window and propagates risk upward when a triggering shipment crosses threshold 75. The Anomaly Detector runs Z-score analysis against the fleet's mean risk distribution on every scan.

Route Optimization: Dijkstra-style pathfinding across a 27-node graph of real global ports (Shanghai, Rotterdam, Singapore, Jebel Ali, Los Angeles, etc.) plus chokepoints. Yen's K-shortest paths returns 3 distinct alternatives with edge weights that factor in delay multipliers, port congestion scores, and cargo-type penalties. The Cost Intelligence Agent then adds the tariff layer from a static matrix that covers the most consequential 2026 trade regime combinations.

Live Data (zero paid APIs):

  • Open-Meteo → real wind speed, precipitation, visibility per route waypoint
  • GDACS API → live cyclones (TC), floods (FL), earthquakes (EQ), volcanic events (VO), filtered by Red and Orange alert level, mapped to shipping corridor proximity
  • Nominatim → coordinate geocoding for CSV-imported shipments at 1 req/sec (rate-limited properly with User-Agent header as required)
  • CartoDB Dark tiles → the map that makes everything look like a command center

Frontend: React 18 + Vite + Tailwind CSS + Leaflet + React-Leaflet + Recharts + Three.js + Framer Motion + Lucide React. The 3D ocean background in OceanCanvas3D.jsx uses Three.js with animated route arcs and vessel particles. Every number on every dashboard card comes from a DB-backed API endpoint — nothing is hardcoded.

Database: SQLite with 10 entity models: Shipment, Client, Disruption, Alert, PortNode, RouteEdge, ShipmentEvent, WeatherSnapshot, SimulationRun, SupplierProfile. The ShipmentEvent table is an event-sourcing audit log — every risk score change is recorded with before/after values and the triggering reason. This is the data that would feed a regulator's audit trail in production.

Scheduler: APScheduler runs four background jobs: risk score refresh every 5 minutes (in-transit shipments only), port congestion update every 15 minutes, GDACS ingestion every 30 minutes (deduplicated by URL, max 5 new events per cycle), and autonomous agent monitoring every 10 minutes when enabled.

✅ How we map to the judging rubric

Criterion How OculusIQ nails it
Agents that work Six agents process real seeded data (500 shipments, 15 clients, 27 ports). Risk Engine runs live Open-Meteo weather. GDACS pulls live disaster events. Ground truth is DB state, not hardcoded demo output.
Real agent collaboration Each agent reads structured output from upstream agents via shared context, not raw data. SLA Agent raises if risk records are missing. Cost Agent raises if route context is absent. Provable dependency chain.
End-user usability A freight forwarder with no technical background can: add a client in a wizard, import shipments by CSV, run a disruption simulation, read a WhatsApp alert, and understand every risk score in plain English.
Real-world problem $1.5T annual disruption losses. 63M+ Indian MSMEs exporting without visibility tools. US-China 145% tariffs making route decisions inseparable from cost decisions. This is the current moment.
Explainability Every risk score breaks down into weighted factors with plain-English descriptions. Every simulation shows cascade math: primary → secondary → tertiary impact with dollar amounts. No black box scores.

🧠 The architecture decision that made it real

The hardest problem wasn't building the agents. It was designing memory correctly.

Early builds passed data between agents in memory — one Python dict flowing through a function chain. It worked. It was also fake collaboration: one agent with multiple functions, not six agents with defined responsibilities.

We rebuilt around a structured context object that each agent reads from and writes to through explicit, typed fields. The downstream agent knows it is using the upstream agent's output because if that output is missing, it fails loudly with a message that says exactly which upstream field is absent and which agent was supposed to write it.

This is what makes the "real collaboration" criterion provable rather than narrated.

😤 Challenges we ran into

SQLite ALTER TABLE in production — SQLite cannot add NOT NULL columns to existing tables. Every new column in iteration 2 required a DEFAULT value in the ALTER statement or the migration helper would silently fail on existing databases. We wrote a startup schema guard that runs ADD COLUMN IF NOT EXISTS with safe defaults on every boot — non-destructive, idempotent, and never requires deleting the database.

Gemini as an async service — google-generativeai is a synchronous SDK inside an async FastAPI application. Running it directly blocks the event loop. The fix was asyncio.run_in_executor(None, lambda: model.generate_content(prompt)) — every Gemini call runs in a thread pool, keeping the rest of the application responsive.

GDACS event deduplication — GDACS updates continuously. Naive polling created duplicate disruption events every 30 minutes. We deduplicate by event URL as a stable identifier, cap new events at 5 per ingestion cycle, and update last_seen_at on existing events rather than inserting new rows.

Leaflet + Vite broken marker icons — The classic React-Leaflet bug: Vite's bundler breaks the default marker icon URL resolution. We caught this early after the first map test showed 500 invisible markers. Solution: switch entirely to L.circleMarker() for shipments and L.divIcon() with CSS for disaster pulse animations — no default icon dependency at all.

Cascade propagation scope — The first cascade implementation updated all shipments whenever any shipment's risk changed. This created a propagation storm on startup: 500 shipments, all updating each other, database locked for 45 seconds. We scoped propagation to co-arriving shipments within a ±48h ETA window at the same destination city — dramatically reducing the affected set while preserving the real-world logic.

🏆 Accomplishments we're proud of

Zero paid APIs, zero cents, full intelligence stack. Open-Meteo, GDACS, Nominatim, CartoDB, Gemini free tier — the entire live data layer costs nothing to run. This is not a limitation. It is the point. If OculusIQ requires expensive infrastructure, it cannot serve the users it was built for.

The WhatsApp alert generator actually works. It generates a wa.me/{phone}?text={message} link with a pre-formatted, client-specific, shipment-specific message. One click opens WhatsApp with the message ready to send. In regions where business runs on WhatsApp, this is not a feature — it is the entire value proposition.

A real tariff engine in 2026. The Cost Intelligence Agent calculates tariff-adjusted landed cost using a matrix that covers US-China (145%), India-UAE CEPA preferential rates, EU CBAM carbon surcharges for steel/aluminium, and GSP preferences for Indian textile exports. When you ask "which route is cheaper," OculusIQ tells you the total bill, not the freight cost.

The multi-client portfolio view. Fifteen clients, each with a live SLA gauge, cargo value, breach probability, and a detail panel with risk-ranked shipments. This view does not exist in any tool at this price point. We know because we looked.

The Scenario Studio financial model. When you simulate a Suez Canal closure, OculusIQ returns not just "47 shipments affected" but: delay cost ($X), rerouting premium ($Y), insurance spike ($Z), SLA penalty clauses ($W), total exposure ($total). Each component uses industry-standard rates: 0.2% of cargo value per day delay cost, expediting premium at 4x sea freight for air conversion, 30% SLA breach rate for penalty clause exposure.

📚 What we learned

Real supply chains are cascade systems, not linear ones. One delayed shipment at Port of Shanghai does not just affect that shipment. It takes a berth slot that another vessel was scheduled for, which pushes that vessel's cargo into a later window, which creates a ripple at Rotterdam three weeks later. Modeling this correctly required building a proper cascade propagation engine, not just flagging individual shipments.

The right abstraction for agents is shared state, not shared memory. Passing data between agents in memory works in demos. It falls apart in production when you need to debug why Agent 3 made a decision: you cannot replay what Agent 2 told it if Agent 2's output lived only in a Python variable that's now gone. Shared context objects with typed fields and explicit reads are the right pattern.

Free APIs are genuinely powerful if you design around their constraints. Open-Meteo has no rate limit for non-commercial use. GDACS updates every 30 minutes. Nominatim allows 1 request/second with a proper User-Agent. Gemini 1.5 Flash gives 1M tokens/day. These are not toy resources — they are enough to build a real intelligence layer if you cache intelligently and design your scheduler around the limits.

Freight forwarders are the right wedge into this market. A single freight forwarder adopting OculusIQ immediately covers 50–200 SME exporter clients. The network effect flows downward: as forwarders use it, their clients get access to the intelligence layer through the forwarder's WhatsApp alerts and weekly reports — without any direct onboarding.

🔮 What's next for OculusIQ

Real carrier API integration. Maersk, MSC, and CMA-CGM all have developer portals with container tracking APIs. Connecting these would replace synthetic current positions with live vessel AIS data. This is the single change that moves OculusIQ from "intelligence platform" to "live operations system."

WhatsApp Business API. The current implementation generates copy-ready WhatsApp messages. The next version sends them directly via Twilio or 360dialog when a risk threshold is crossed — no human in the loop for routine alerts.

PostgreSQL + cloud deployment. The SQLAlchemy async layer is already database-agnostic. One environment variable change switches from SQLite to a managed PostgreSQL instance. Deployment on Railway or Render with a proper DB gives the platform a permanent URL that freight forwarders can log into from anywhere.

Mobile-first view. Operations managers in India and Southeast Asia are primarily mobile users. A React Native port of the core dashboard — shipment list, risk alerts, WhatsApp forward — brings OculusIQ to where its users actually are.

Feedback loop from resolved disruptions. When an alert is acknowledged and a shipment is eventually delivered (on time or delayed), OculusIQ can record the outcome. Over time this builds a training signal: which risk factors actually predicted delays, which didn't, and how to calibrate the Disruption Risk Index against ground truth.

🚀 Closing line

Every other supply chain tool was built for the company that can afford a six-month implementation. OculusIQ was built for the freight forwarder who found out about the Suez closure from their client's angry WhatsApp message.

We fixed that.

Built With

  • carbon-analytics
  • document-intelligence
  • fastapi
  • gdacs-api
  • git
  • google-gemini-ai
  • javascript
  • multi-agent-systems
  • nominatim-api
  • open-meteo-api
  • predictive-analytics
  • python
  • react
  • recharts
  • rest-apis
  • risk-intelligence-engine
  • scenario-simulation
  • sla-prediction-models
  • sqlite
  • vite
Share this project:

Updates