O&G Agentic AI Field Operations Copilot

A production-grade prototype demonstrating ReAct + Safety-Critical Human-in-the-Loop (HITL) architecture for Oil & Gas operations. Built for a Data & Digital Executive to showcase on LinkedIn.

What This Demonstrates

This prototype showcases five architectural capabilities that boards and operators care about in 2025:

1. Agentic Reasoning - Not a chatbot; a state machine that plans, executes, and reflects
2. Symbolic Wrapping - The LLM never executes directly; it selects from pre-verified read-only tools
3. Safety by Design - Deterministic risk classification with human sovereignty over recommendations
4. Observability First - Every decision is logged in an immutable audit trail
5. Graceful Degradation - Works offline without API keys (heuristic mode), upgrades with LLM

Architecture Overview

User Query -> Perception (Intent/Entity Extraction) -> Planner (Tool Selection)
    -> Executor (Read-Only Tools) -> Synthesis (Evidence Correlation)
    -> Safety Critic (Risk Classification) -> [HITL Gate if Orange/Red] -> Response

LangGraph State Machine

Node	Purpose	Key Feature
perception	Parse intent, extract entities (asset tag, metric, timeframe)	Keyword + LLM fallback
planner	Generate step-by-step tool calling plan	Max 3 steps, tool schemas enforced
executor	Call read-only tools deterministically	Never executes raw SQL/Python
synthesis	Correlate findings into coherent response	Offline heuristic mode + LLM mode
safety_critic	Classify risk: Green/Yellow/Orange/Red	Keyword + alert-based heuristics
hitl_gate	Pause for human approval on Orange/Red	Checkpoint ID, pause/resume via MemorySaver
final_response	Format with risk badge, citations, audit stamp	Immutable audit trail

Risk Classification

Level	Trigger	HITL Required
Green	Factual retrieval only	No
Yellow	General guidance, warnings	No
Orange	Operational recommendations, sensor anomalies	Yes - Synchronous approval
Red	Safety-critical, emergency, "do not operate"	Yes + Secondary review

Tools (Read-Only)

Tool	Function	Safety
search_manuals	Search O&M manuals, API standards, troubleshooting guides	Read-only document retrieval
query_sensor	Query time-series sensor data with anomaly detection	Read-only, synthetic data for demo

Project Structure

og_copilot/
├── app.py                          # Streamlit UI (chat + approval card + audit log)
├── requirements.txt
├── README.md
├── app/
│   ├── __init__.py
│   ├── config.py                   # Safety thresholds, asset registry, LLM config
│   ├── agent/
│   │   ├── __init__.py
│   │   ├── state.py                # TypedDict AgentState definition
│   │   ├── tools.py                # 2 read-only tools + in-memory knowledge base
│   │   ├── nodes.py                # 7 node functions for the ReAct + Safety loop
│   │   └── graph.py                # LangGraph state machine compilation
│   └── data/
│       ├── __init__.py
│       └── init_knowledge_base.py  # ChromaDB initialization script

Quick Start

Option A: With LLM (Enhanced Responses)

Set your API key (supports OpenAI or OpenRouter):

export OPENAI_API_KEY="your-key-here"
# OR for OpenRouter
export OPEN_ROUTER_API_KEY="your-key-here"
export OPENAI_BASE_URL="https://openrouter.ai/api/v1"
export LLM_MODEL="openai/gpt-4o-mini"

Option B: Without API Key (Offline Mode - Works Immediately)

The prototype works fully without any API key. The agent uses deterministic heuristics for:

• Intent classification (keyword-based)
• Tool plan generation (rule-based fallback)
• Risk classification (keyword + sensor alert analysis)
• Response synthesis (structured formatting of tool outputs)

Run the Application

cd og_copilot
pip install -r requirements.txt
python -m streamlit run app.py

Then open http://localhost:8501 in your browser.

Demo Scenarios

The sidebar includes one-click demo queries:

1. "Why did Compressor A trip last night?" -> Triggers document search for trip investigation procedures (Yellow risk)
2. "What's the current bearing temperature for COMP-A-001?" -> Triggers sensor query with CRITICAL alert (Orange risk -> HITL approval card)
3. "Draft a shift handover note for Compressor A" -> Combines document search + sensor data (Orange risk -> HITL approval card)

Key Features Demonstrated

1. HITL Approval Card Widget

When the safety critic classifies a response as Orange or Red:

• Agent status changes from ACTIVE to PAUSED
• An approval card appears with evidence summary, proposed action, and risk rationale
• Chat input is disabled until operator approves or rejects
• Full audit trail captures the decision

2. Audit Trail

Every event is logged:

• User queries
• HITL triggers (with checkpoint ID)
• Operator approvals/rejections
• Agent completions with risk classification

3. Asset Registry

Three synthetic assets with realistic baselines:

• COMP-A-001: Main Process Compressor (72C baseline, 3.2 mm/s vibration)
• COMP-B-002: Refrigeration Compressor (65C baseline, 4.5 mm/s vibration)
• PUMP-X-101: Injection Pump (55C baseline, 2.8 mm/s vibration)

4. Safety Thresholds

Based on API 570 and industry standards:

• Bearing temperature max: 85C (warning), 95C (critical), 100C (emergency shutdown)
• Vibration max: 7 mm/s (warning), 11 mm/s (critical)
• Baseline deviation: 15% triggers investigation

LinkedIn Article Talking Points

When writing your article, emphasize these architectural decisions:

1. "It's not RAG, it's a state machine" - The ReAct loop shows planning, not just prompting
2. "Symbolic wrapping, not prompt engineering" - LLM selects tools; deterministic code executes them
3. "Safety is the architecture, not a feature" - HITL is wired into the graph, not bolted on
4. "Works offline, scales with API" - Heuristic mode proves functionality without vendor lock-in
5. "Every decision is auditable" - Immutable logs for regulatory compliance (OGMP 2.0, EPA)

Extending the Prototype

To add more tools:

1. Define a new StructuredTool in app/agent/tools.py
2. Add it to the TOOLS registry
3. Update the planner system prompt in app/agent/nodes.py
4. Add safety guardrails in the critic if needed

To connect to real SCADA:

1. Replace query_sensor implementation with actual Historian/PI System queries
2. Keep the same interface; the agent doesn't need changes

Tech Stack

Layer	Technology
Orchestration	LangGraph (StateGraph + MemorySaver)
LLM	GPT-4o Mini via OpenRouter (optional, lazy init)
Embeddings	sentence-transformers/all-MiniLM-L6-v2 (fallback: keyword scoring)
Vector Store	In-memory (ChromaDB-ready for scale)
UI	Streamlit with custom CSS
Data	Synthetic time-series with deterministic anomaly injection

---

Built for demonstration purposes. The architecture is designed to scale to production with ChromaDB + SCADA historian integration + enterprise auth.