🛢️ PetroMind: Enterprise Multi-Agent AI Platform for Petroleum & Natural Gas

---

🌟 Executive Overview

PetroMind is an enterprise-grade, autonomous multi-agent AI system designed specifically for the Oil and Natural Gas Corporation (ONGC) and upstream/downstream energy sectors. By combining specialized domain agents with local Parent-Child Retrieval-Augmented Generation (RAG), secure quantitative execution sandboxes, and Model Context Protocol (MCP) tool integrations, PetroMind delivers rigorous technical research, regulatory compliance audits, HSE risk matrices, and production/economic forecasting.

All inference is executed securely through ONGC ModelHub (google/gemma-4-26B-A4B-it) ensuring complete data sovereignty, high accuracy, and zero external data leakage.

---

🚀 Key Architectural Highlights

• 🧠 Multi-Agent LangGraph Orchestration (StateGraph): Uses stateful graph routing where a Supervisor Agent intelligently classifies user intent (research, regulation, risk, data, or mixed) and assigns tailored tasks to domain specialists in canonical or parallel execution order.
• 🛡️ Built-in Critic & Revision Loop: Every agent output is audited by an independent Critic Agent that verifies regulatory citations, numerical accuracy, and technical consistency. If gaps or hallucinations are detected, the system automatically triggers targeted revision loops (capped at LLM_MAX_ATTEMPTS).
• 🛑 Human-in-the-Loop (HITL) Governance: Before final report synthesis, execution pauses at an interactive approval checkpoint (human_approval_node), allowing engineers and regulatory experts to inspect confidence scores, compliance findings, and risk matrices on the web dashboard.
• 📂 Parent-Child RAG Architecture (Qdrant + Qwen3 / Jina): To solve the classic chunking trade-off, PetroMind implements two-level indexing:
  • Parent Chunks (~3,200 chars / ~800 tokens): Provide rich, complete surrounding context to the Gemma 4 26B model during synthesis.
  • Child Chunks (~800 chars / ~200 tokens): Indexed with high-dimensional embeddings (Qwen/Qwen3-Embedding-8B / jina-reranker-v3) in Qdrant (localhost:6444) for hyper-accurate semantic retrieval.
• 🔌 Tool-Equipped MCP (Model Context Protocol) Servers: Specialized tools are compartmentalized into dedicated MCP servers:
  • Vector RAG (vectordb_search.py): Searches over Indian petroleum codes (PNGRB, OISD, DGMS, MoPNG), US BSEE standards, SPE technical literature, and Volve field datasets.
  • Technical Web Search (tavily_search.py): Retrieves up-to-the-minute global market intelligence and academic literature.
  • Energy & Economic APIs (eia_api.py, worldbank_api.py): Queries official U.S. Energy Information Administration datasets and World Bank indicators with local filesystem caching (.eia_cache).
  • Secure Python REPL (python_repl.py): Executes complex petroleum engineering formulas, PVT calculations, and financial modeling in a sandboxed environment.
• ⚡ Rate-Limited & Fault-Tolerant Engine: Equipped with thread-safe global throttling (_throttle) and controlled backoff schedules (LLM_BACKOFF_SCHEDULE) to handle high-concurrency multi-agent bursts without triggering ModelHub HTTP 429 rate limits.

---

🏗️ System Architecture & Workflow

graph TD
    User([User / Web UI]) -->|Query & Parameters| API[FastAPI Async Backend]
    API -->|Initialize State| START((START))
    
    subgraph LangGraph Multi-Agent Orchestration
        START --> Supervisor[Supervisor Agent<br/>Intent Classification & Routing]
        
        Supervisor -->|Research Task| Research[Research Agent<br/>SPE & Literature RAG]
        Supervisor -->|Regulation Task| Regulation[Regulation Agent<br/>PNGRB / OISD / DGMS Compliance]
        Supervisor -->|Risk Task| Risk[Risk Agent<br/>5x5 Risk Matrix & HSE Hazards]
        Supervisor -->|Data Task| Data[Data Agent<br/>REPL Sandbox / EIA / Statistics]
        
        Research --> Critic[Critic Agent<br/>Hallucination & Citation Audit]
        Regulation --> Critic
        Risk --> Critic
        Data --> Critic
        
        Critic -->|NEEDS_REVISION<br/>(Up to 3x)| Supervisor
        Critic -->|PASS| HITL{Human-in-the-Loop<br/>Approval Checkpoint}
    end
    
    HITL -->|Operator Approved| Report[Report Agent<br/>Executive Markdown / JSON / PDF]
    Report -->|Final Deliverable| END((END))
    
    subgraph Local MCP & Data Layer
        Research -.->|Query| VectorDB[(Qdrant Vector DB<br/>Parent-Child Chunks)]
        Regulation -.->|Check Standards| VectorDB
        Risk -.->|Accident History| VectorDB
        Data -.->|Execute Code| REPL[Python REPL Sandbox]
        Data -.->|Fetch Data| APIs[EIA / World Bank Caches]
    end

---

🤖 Core Domain Agents

---

📥 RAG Ingestion Pipeline (step1 to step5)

The project includes an automated 5-step data preparation and embedding pipeline located in the root directory:

# 1. Initialize Qdrant collections with optimized vector dimensions and HNSW indices
python step1_setup_collections.py

# 2. Extract raw text from complex PDFs, Word documents, and reports inside source_data/
python step2_extract_text.py

# 3. Run Parent-Child quality-filtered chunking (~3,200 char parents / ~800 char children)
python step3_chunk.py

# 4. Generate embeddings via Qwen3-Embedding-8B / Jina and ingest into local Qdrant
python step4_embed_and_store.py

# 5. Execute RAG validation benchmarks and quality checks (Ragas metrics)
python step5_validate.py

---

🛠️ Getting Started & Setup

1. Prerequisites

• Python: 3.10 or higher (3.11 recommended)
• Node.js: 18.x or higher (with npm or pnpm)
• Qdrant: Local Qdrant server running on localhost:6444 (or Docker: docker run -p 6444:6333 qdrant/qdrant)

2. Environment Configuration

Clone the repository and copy the example environment file:

cp .env.example .env

Edit .env and configure your credentials:

ONGC_API_BASE_URL=https://modelhub.ongc.co.in/v1
ONGC_API_KEY=your_ongc_modelhub_api_key
EMBEDDING_MODEL=Qwen/Qwen3-Embedding-8B
QDRANT_HOST=localhost
QDRANT_PORT=6444
TAVILY_API_KEY=your_tavily_key
EIA_API_KEY=your_eia_key
LANGSMITH_TRACING=true
LANGSMITH_PROJECT=PetroMind

3. Backend & Python Setup

Activate your virtual environment and install dependencies:

# Create and activate virtual environment (if not already created)
python -m venv petromind_env
# On Windows:
petromind_env\Scripts\activate
# On Linux/Mac:
source petromind_env/bin/activate

# Install Python requirements
pip install -r backend/requirements.txt

4. Frontend Studio Setup

Install dependencies for the Vite web interface:

cd frontend
npm install
# or: pnpm install
cd ..

---

🏃 Running the Application

1. Start the FastAPI Async Backend

Run the backend server from the project root directory:

python -m uvicorn backend.main:app --host 0.0.0.0 --port 8000 --reload

• API Documentation (Swagger UI): http://localhost:8000/docs
• Health & State Endpoints: http://localhost:8000/api/reports

2. Start the Vite Frontend Studio

In a separate terminal window, launch the interactive web studio:

cd frontend
npm run dev

• Web Studio Dashboard: http://localhost:5173

---

📁 Project Directory Structure

ongc/
├── agents/                      # 🤖 Core LangGraph Multi-Agent Implementation
│   ├── config.py                # Centralized ModelHub & LLM configuration
│   ├── graph.py                 # LangGraph StateGraph, routing & HITL interrupt
│   ├── state.py                 # PetroMindState schema & logging events
│   ├── supervisor.py            # Supervisor routing agent
│   ├── research_agent.py        # Technical literature & SPE RAG agent
│   ├── regulation_agent.py      # Indian (PNGRB/OISD/DGMS) & global compliance agent
│   ├── risk_agent.py            # HSE hazard identification & 5x5 Risk Matrix agent
│   ├── data_agent.py            # Quantitative analyst, REPL & EIA statistics agent
│   ├── critic_agent.py          # Quality audit & hallucination verification agent
│   └── report_agent.py          # Executive markdown, JSON & PDF report generator
├── backend/                     # ⚙️ FastAPI Async Server & Job Orchestration
│   ├── main.py                  # API routes (/api/reports, PDF downloads)
│   ├── runner.py                # JobManager, asynchronous runners & SSE updates
│   └── schemas.py               # Pydantic request/response models
├── frontend/                    # 🎨 Modern Vite Studio Web Interface
│   ├── index.html               # Main application layout
│   ├── app.js                   # State synchronization, graphs & UI rendering
│   ├── styles.css               # Rich dark-mode design system & animations
│   └── package.json             # Frontend dependencies & scripts
├── mcp_servers/                 # 🔌 Model Context Protocol Tools
│   ├── vectordb_search.py       # Local Qdrant semantic search engine
│   ├── tavily_search.py         # Live web technical intelligence search
│   ├── eia_api.py               # U.S. EIA energy statistics client + cache
│   ├── worldbank_api.py         # World Bank global economic data client
│   ├── pdf_reader.py            # PDF text & layout extractor
│   └── python_repl.py           # Sandboxed Python mathematical calculation engine
├── utils/                       # 🛠️ Shared Utilities & Logging
│   ├── logger.py                # Token consumption & execution latency logger
│   └── reranker.py              # Jina Reranker v3 late-interaction integration
├── step1_setup_collections.py   # RAG Step 1: Qdrant schema setup
├── step2_extract_text.py        # RAG Step 2: Multi-format text extraction
├── step3_chunk.py               # RAG Step 3: Parent-Child hierarchical chunking
├── step4_embed_and_store.py     # RAG Step 4: Batch embedding & vector storage
├── step5_validate.py            # RAG Step 5: Automated benchmark validation
├── try.py                       # Standalone pipeline/chunking experiment script
├── .env.example                 # Example environment variables template
├── .gitignore                   # Comprehensive rules ignoring large data & secrets
└── README.md                    # Project documentation

---

🔒 Security & Data Governance

• Zero External Network Leakage: All internal petroleum data, field reports, and regulatory scans remain inside ONGC's secure network periphery via ONGC ModelHub.
• Secret Protection: API keys and sensitive tokens (ONGC_API_KEY, etc.) are strictly isolated via .env / Kubernetes secrets and excluded from version control.
• Sandbox Execution: Mathematical evaluation (python_repl) operates inside a controlled, read-only calculation scope preventing arbitrary system calls or unauthorized filesystem writes.

---

📜 License

Internal Proprietary Software developed for Oil and Natural Gas Corporation (ONGC) & PetroMind Initiatives. All rights reserved.