Python FastAPI LangGraph LangSmith vLLM XGBoost SHAP pgvector TimescaleDB PostGIS Redis Next.js Docker
The architecture of ARIA is a direct response to the April 2023 rider retention crisis at Loadshare, documented in the research publicly published in January 2025 by Arun Ravichandran (Ex Senior Program Manager).
Beyond the Extra Mile: A Tale of Riders, Routes and Retention
Documentation CHATBOT : https://gauraansh.tech/aria/docs-chat
Live App : https://gauraansh.tech/aria/login
ARIA is a multi-agent inference pipeline built over a fully dynamic discrete-event simulation engine. No static data, no hardcoded thresholds — every order is generated by a Poisson-inspired arrival model, delivery zone selected via live density-weighted scoring across 180 zones, fare computed from distance + zone-type interaction features, and dead-run risk scored by a two-stage CalibratedXGBoost model before dispatch. Rider EPH trajectory is computed per-cycle using momentum features (eph_slope, eph_acceleration derived from lag snapshots). Zone pressure, churn risk, and restaurant delay signals emerge entirely from algorithmic scoring — no rule-based triggers.
The system runs a 5-agent LangGraph pipeline every 15 simulation-minutes, operating across 500 riders and 200 restaurants in 180 zones across 12 Indian cities. Agents synthesise pre-computed scores at inference and never compute directly — all computation is delegated to XGBoost models and deterministic algorithmic modules. The LLM is called 4–6 times per cycle, only for explanation and synthesis.
Client Next.js 14 · React Flow · Leaflet.js · WebSocket · Claude Desktop via MCP
Intelligence 5 LangGraph agents · Qwen2.5-32B-Instruct-GPTQ-Int4 · vLLM · LangSmith
MCP Server FastAPI (port 8001) · 14 tools · APScheduler · fastapi-mcp
ML + Algo 4 XGBoost models · 3 algorithmic modules · FastAPI internal (port 8002)
Data PostgreSQL 16 · TimescaleDB · PostGIS · pgvector · Redis 7
Infrastructure Docker Compose · Dual RTX 3090 (48GB VRAM)
All agents run on Qwen2.5-32B-Instruct-GPTQ-Int4 served via vLLM across dual RTX 3090s, with per-node LangSmith observability throughout.
| Agent | Role |
|---|---|
| Zone Intelligence | Classifies 180 zones per cycle; density-aware relocation recommendations weighted by live stress_ratio and order_delta |
| Restaurant Intelligence | Scores delay risk per restaurant from rolling delay_rate and avg_delay_mins; fires rider + operator alerts above configurable thresholds |
| Dead Run Prevention | Scores each pending order against a two-stage XGBoost model before dispatch; flags orders destined for statistically dead zones |
| Earnings Guardian | Computes EPH trajectory per rider using momentum features; escalates churn signals for consecutive below-threshold sessions |
| Supervisor | Orchestrates all sub-agents; runs deterministic KPI analysis; writes cycle_briefings; queries pgvector episode memory for analogous past cycles |
The Supervisor implements a 6-node LangGraph state machine: ground_past_outcomes → validate_inputs → analyze_patterns → retrieve_context → call_llm → write_and_publish. Pattern detection and financial KPI computation (earnings shortfall, dead zone pressure, churn surge) are fully deterministic — the LLM only writes the natural language synthesis after all signals are resolved.
All models trained with RandomizedSearchCV hyperparameter tuning, 70/15/15 train/val/test splits, SHAP importances pre-computed at training time and served at inference (never recomputed at runtime).
| Model | Type | Data | Key Design |
|---|---|---|---|
| Rider Persona Classifier | Binary classifier | Synthetic (grounded in Loadshare research statistics) | Classifies supplementary vs. dedicated; drives EPH threshold assignment |
| Delivery Duration Scorer | Regressor | Real Kaggle dataset — Food Delivery Time Prediction (41,953 rows, 22 Indian cities) | Fixed target encoding leakage from original dataset (replaced MEstimateEncoder with label encoding) |
| Dead Zone Risk Predictor | Two-stage: CalibratedClassifierCV (isotonic) + regressor |
Synthetic | Interaction features peripheral_ld_risk and dist_x_dead_rate computed at inference; calibrated probabilities prevent overconfident dispatch blocking |
| Earnings Trajectory Forecaster | Two-stage: EPH regressor → churn classifier | Synthetic | eph_target injected into regressor features but deliberately excluded from classifier features — prevents shortcut learning / label leakage |
Models 1, 3, and 4 are trained on synthetic data generated with algorithmic and statistical logic — rider persona distributions, zone density curves, dead-run probabilities, and EPH thresholds are all grounded in Loadshare's published research.
The discrete-event simulation runs at configurable time acceleration (default 10×, max 300×). Every tick:
- Order Factory generates orders via a Poisson-inspired arrival rate modulated by zone density and time-of-day
- Dispatcher selects the nearest idle rider, scores the order for dead-run risk via the ML model before assignment, computes fare from
BASE_FARE_RS + distance × rate + zone_type_premium - Zone Engine writes density snapshots to TimescaleDB every simulated hour; snapshots feed both the Zone agent and the Dead Run agent's risk scoring
- Session Manager tracks per-rider shift windows, EPH accumulation, and triggers warm-start hydration on service restart
The Supervisor queries pgvector episode memory for analogous past cycles before calling the LLM. Retrieval is hybrid:
- Recency filter — episodes within a configurable lookback window
- Severity adjacency — episodes within one severity level of the current classification
- City/zone overlap — GIN-indexed
TEXT[]intersection - Cosine similarity — HNSW index over 768-dim Ollama nomic-embed-text embeddings
Candidates below similarity < 0.65 are dropped. Top-3 episodes (capped at 1200 chars total) are injected as RAG context into the LLM prompt. Embed input is a canonical string over severity + detected patterns + financial KPIs — not the LLM summary — ensuring embedding stability across cycles.
ARIA ships a documentation chatbot exposing full technical depth, with two retrieval modes switchable from the UI:
Vector mode — pgvector cosine similarity over Ollama qwen3-embedding (4096-dim) chunks stored with HNSW index.
PageIndex mode (experimental) — Structure-aware retrieval over a 140-node document tree. No embeddings, no arbitrary chunking. Two-file architecture: ARIA_NAV.md (routing layer with per-section keywords and summaries) and ARIA_DOCS.md (content layer), fully decoupled. Three-level tree search: LLM selects chapters at L0, sections at L1 using 120-char keyword previews, full structured content retrieved at L2. A keyword correction layer (_kw_score_chapter_max with word-boundary regex and MAX-per-chapter scoring) forces chapter override when the LLM misroutes on technical queries. SSE token streaming end-to-end — vLLM → FastAPI → Next.js proxy → client.
Full technical documentation: ARIA_DOCS.md
| Source | Used For | Notes |
|---|---|---|
| Kaggle — Food Delivery Time Prediction (gauravmalik26) | Model 2 training | 41,953 rows, 22 Indian cities; fixed MEstimateEncoder target leakage |
Synthetic generator (synthetic_generator_v2.py) |
Models 1, 3, 4 + simulation seed | Rider personas, zone density curves, EPH distributions grounded in Loadshare research |
| TimescaleDB continuous aggregates | Zone density, restaurant delay | zone_density_hourly, restaurant_delay_hourly — pre-aggregated for agent queries |
docker-compose.yml 8 services: postgres, redis, vllm, ollama,
fastapi-mcp, fastapi-ml, event-stream, frontend
Hardware Dual RTX 3090 (48GB VRAM total), i7, 128GB RAM
LLM Qwen2.5-32B-Instruct-GPTQ-Int4 (dev: 7B-Instruct)
Embeddings Ollama — nomic-embed-text (768-dim), qwen3-embedding (4096-dim)
Database PostgreSQL 16 + TimescaleDB + PostGIS + pgvector
Frontend Next.js 14, deployed on Vercel (basePath: /aria)
Backend — Python 3.11 · FastAPI · LangGraph · LangChain · LangSmith · APScheduler · asyncpg · structlog
ML — XGBoost · scikit-learn · SHAP · joblib · CalibratedClassifierCV
LLM / Inference — vLLM · Ollama · Qwen2.5-32B-Instruct-GPTQ-Int4
Data — PostgreSQL 16 · TimescaleDB · PostGIS · pgvector · Redis 7
Frontend — Next.js 14 · TypeScript · Tailwind CSS · React Flow · Leaflet.js · Zustand
Infrastructure — Docker Compose · Vercel · Dual RTX 3090