🚢 chAIn: Autonomous Resilience Oracle

nexHacks 2026 | Track: DevTools & Infrastructure / General

chAIn is a physics-aware supply chain control plane. It moves global logistics from reactive (fixing things after they break) to resilient (simulating and acting before they break).

By leveraging NVIDIA Cosmos World Models (deployed on AWS SageMaker) and a Multi-Agent Council, chAIn reduces "Time to Action" for supply chain disruptions from 48 hours to 300 seconds.

---

� Quick Start

Prerequisites

• Python 3.10+
• AWS Account with SageMaker endpoint hosting NVIDIA Cosmos model
• Google AI API Key (for Gemini)

Setup

1. Clone the repository

   git clone https://github.com/your-team/chain.git
   cd chain

2. Create a virtual environment

   python -m venv venv
   
   # Windows
   venv\Scripts\activate
   
   # macOS/Linux
   source venv/bin/activate

3. Install dependencies

   pip install -r requirements.txt

4. Configure environment variables

   Create a .env file in the project root:

   AWS_ACCESS_KEY_ID=your_aws_access_key_id
   AWS_SECRET_ACCESS_KEY=your_aws_secret_access_key
   AWS_COSMOS_ENDPOINT=your_sagemaker_endpoint_name
   GOOGLE_API_KEY=your_google_api_key
   SHIPPING_API_KEY=your_shipping_api_key

5. Run the application

   # Start the main agent
   python main.py
   
   # Or run the Streamlit dashboard
   streamlit run frontend/dashboard.py

🐳 Docker

1. Build the image

   docker build -t chain .

2. Run the container

   docker run -p 8000:8000 --env-file .env chain

3. Access the API

   • Health check: http://localhost:8000/health
   • API docs: http://localhost:8000/docs

---

�👥 1. The Team (Pod-Based Coordination)

Role	Primary Owner	Key Responsibility
Lead Architect	[Name]	The Brain: LangGraph orchestration and Council State.
The Sensor	[Name]	The Senses: NVIDIA Cosmos model on AWS SageMaker and live MCP data ingestion.
The Executor	[Name]	The Hands: Enterprise action tools and MCP server hosting.
The Designer	[Name]	The UI: Streamlit Command Center and Agent Trace visualization.

---

📂 2. Project Structure

/chain
│── main.py                # Entry point: Streams agent updates to the UI
│── requirements.txt       # AI Stack (LangGraph, MCP SDK, boto3)
│── .env                   # SHARED: AWS_COSMOS_ENDPOINT, AWS credentials, SHIPPING_API_KEY
│
├── /core                  # THE BRAIN (Architect)
│   ├── state.py           # The JSON Contract (CouncilState)
│   ├── graph.py           # LangGraph nodes and conditional edges
│   └── prompts.py         # Detailed Agent System Prompts
│
├── /senses                # THE SENSES (Sensor)
│   ├── cosmos.py          # AWS SageMaker LLM for scenario prediction
│   └── mcp_clients.py     # Weather, Maritime, and Traffic MCP data
│
├── /actions               # THE HANDS (Executor)
│   ├── erp_tools.py       # Enterprise PO, Reroute, and Hedge logic
│   └── mcp_server.py      # Local MCP server for our internal tools
│
└── /frontend              # THE UI (Designer)
    └── dashboard.py       # Streamlit Dashboard (Live Trace & Map)

---

📜 3. The Technical Contract (core/state.py)

To prevent integration errors, all agents must adhere to this shared state schema:

from typing import Annotated, List, TypedDict
from langchain_core.messages import BaseMessage
from langgraph.graph.message import add_messages

class CouncilState(TypedDict):
    # 1. Memory: The trace of all agent debates
    messages: Annotated[List[BaseMessage], add_messages]
    
    # 2. Perception: Real-time world data (Weather, Traffic, Stocks)
    world_context: dict 
    
    # 3. Simulation: Physics-aware predictions from Cosmos model (AWS SageMaker)
    simulated_future: dict
    
    # 4. Strategy: The final approved rerouting/mitigation plan
    intervention_plan: str
    
    # 5. Flags for Graph Control
    is_verified: bool  # Skeptic Agent must set this to True
    is_executed: bool  # Strategist Agent sets this after action

---

🛠️ 4. Tech Stack & Prerequisites

• Python 3.11+
• LangGraph: For cyclical multi-agent workflows.
• NVIDIA Cosmos Model (AWS SageMaker): For world state prediction and physical reasoning.
• MCP (Model Context Protocol): For universal tool/data connectivity.
• Streamlit: For the real-time agent monitoring dashboard.

---

📅 5. The 36-Hour Battle Plan

Phase 1: The Contract

• Goal: Architect defines the JSON schema; Designer builds the Figma/Streamlit mockups.
• Sync: All 4 agree on the CouncilState fields.

Phase 2: Parallel Deep-Dive

• Architect: Scaffolds the graph nodes with "Dummy" agents.
• Sensor: Connects live maritime APIs and integrates Cosmos model via AWS SageMaker for "future frames."
• Executor: Builds the trigger_reroute tool inside a local MCP server.
• Designer: Connects the UI to the Shared Database to watch "Mock" updates.

Phase 3: The Integration

• Merge: All components using live Cosmos predictions from AWS SageMaker endpoint.
• Stream: Enable stream_mode="updates" so the UI shows live agent debate.

Phase 4: Polish & Pitch

• Visuals: Add "Agent Reasoning" logs to the dashboard.
• Story: Finalize the deck focusing on the ROI of Reduced Latency.

---

🚀 6. Git Coordination Protocol

1. Branch by Role: dev-architect, dev-sensor, dev-executor, dev-ui.
2. File Isolation: Never edit files outside your role's directory.
3. Commit often: Push to your branch every 2 hours to avoid "Massive Merge" disasters.