OilGas Nanobot Swarm

Overview

OilGas Nanobot Swarm is an open-source hierarchical multi-agent AI system for oil and gas engineering. It uses a 3-tier Queen → L1 Domain Leads → L2 Sub-Agents architecture to decompose complex engineering problems and deliver expert-level analysis.

Key Features

• 7 built-in petroleum engineering calculators (drilling, reservoir, production, pipeline, well control, petrophysics, regulatory)
• 9 pre-configured O&G agent teams with specialized workflows
• AI Agent Builder and Team Builder — generate custom agents from natural language
• OpenAI-compatible API — works with any OpenAI SDK client
• NeuralQuantum.ai branded web dashboard with mobile support
• Deployable to Vercel, Render, Railway, or Docker Compose

Quick Start

Option 1 — Use the live demo (no setup)

curl -X POST https://oilgas-nanobot-swarm.vibecaas.app/swarm/run \
  -H "Content-Type: application/json" \
  -d '{"goal": "Calculate ECD at 10,000 ft TVD, 10.5 ppg mud, 320 psi APL"}'

Option 2 — Deploy to Vercel

npm i -g vercel
git clone https://github.com/ttracx/oilgas-nanobot-swarm.git
cd oilgas-nanobot-swarm
vercel --prod
# Set OLLAMA_API_KEY in Vercel dashboard

Option 3 — Docker Compose (local)

git clone https://github.com/ttracx/oilgas-nanobot-swarm.git
cd oilgas-nanobot-swarm
cp .env.example .env   # add OLLAMA_API_KEY
docker compose up -d
curl http://localhost:8100/health

Architecture

The swarm uses a 3-tier hierarchy:

The Vercel deployment uses a streamlined single-call API against Ollama Cloud or NVIDIA NIM. The full-stack deployment (Docker/Render/Railway) includes Redis state, knowledge vault, and background scheduler.

API Endpoints

Base URL: https://oilgas-nanobot-swarm.vibecaas.app

Request Format

POST /swarm/run

{
  "goal": "Your engineering question (required, max 10,000 chars)",
  "mode": "hierarchical",   // or "flat" (optional)
  "team": "well-engineering-review",  // optional named team
  "metadata": {}            // optional context
}

POST /agent/build & /team/build

{
  "description": "Describe what you want (10–2000 chars)"
}

Response Format

POST /swarm/run response

{
  "success": true,
  "session_id": "nq-1772088336060",
  "goal": "...",
  "final_answer": "Step-by-step engineering analysis...",
  "subtask_count": 1,
  "duration_seconds": 7.6,
  "powered_by": "NeuralQuantum.ai"
}

POST /agent/build response

{
  "success": true,
  "type": "agent",
  "config": {
    "name": "production-decline-monitor",
    "mode": "hierarchical",
    "tools": ["production_engineering_calc", ...],
    "system_prompt": "You are...",
    "python_code": "from nanobot.scheduler...",
    "use_cases": [...],
    "example_goal": "..."
  },
  "duration_seconds": 6.1
}

Code Examples

Python (requests)

import requests

r = requests.post(
    "https://oilgas-nanobot-swarm.vibecaas.app/swarm/run",
    json={
        "goal": "Calculate kill mud weight. SIDPP=380 psi, MW=10.5 ppg, TVD=9800 ft",
        "team": "well-engineering-review"
    }
)
print(r.json()["final_answer"])

Python (OpenAI SDK)

from openai import OpenAI

client = OpenAI(
    base_url="https://oilgas-nanobot-swarm.vibecaas.app/v1",
    api_key="demo",
)
response = client.chat.completions.create(
    model="nanobot-swarm",
    messages=[{"role": "user", "content": "Explain Archie's equation with an example"}],
)
print(response.choices[0].message.content)

JavaScript (fetch)

const res = await fetch(
  "https://oilgas-nanobot-swarm.vibecaas.app/swarm/run",
  {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      goal: "Design frac program for Wolfcamp A: 8,500 ft lateral, target 2000 BOPD IP",
      team: "completions-design"
    })
  }
);
const data = await res.json();
console.log(data.final_answer);

cURL

curl -X POST https://oilgas-nanobot-swarm.vibecaas.app/swarm/run \
  -H "Content-Type: application/json" \
  -d '{"goal": "Run HSE PSM 14-element compliance audit for offshore platform"}'

Engineering Tools

All agents have access to these 7 built-in calculators. Reference them in goals or let the AI invoke them automatically.

Agent Teams

Use "team": "team-name" in your /swarm/run request to activate a pre-configured workflow.

curl -X POST https://oilgas-nanobot-swarm.vibecaas.app/team/build \
  -H "Content-Type: application/json" \
  -d '{"description": "Weekly waterflood performance review team that tracks injection rates, voidage replacement ratio, and pattern efficiency across all injectors"}'

Deployment — Vercel

Critical: vercel.json must use functions config

{
  "version": 2,
  "functions": { "api/index.py": { "maxDuration": 60 } },
  "rewrites": [
    { "source": "/", "destination": "/nanobot/static/index.html" },
    { "source": "/health", "destination": "/api/index.py" },
    { "source": "/swarm/:path*", "destination": "/api/index.py" },
    ...
  ]
}

Required environment variables

render deploy --config render.yaml
# or
railway up

cp .env.example .env
# Edit .env — add OLLAMA_API_KEY
docker compose up -d
curl http://localhost:8100/health

Adding a Custom Tool

Implement the BaseTool ABC in nanobot/tools/:

from nanobot.tools.base import BaseTool, ToolResult
import time

class MyTool(BaseTool):
    name = "my_calc"
    description = "Calculate [something]. Used for [when]."
    parameters_schema = {
        "type": "object",
        "properties": {
            "value": {"type": "number", "description": "Input in ppg"},
        },
        "required": ["value"],
    }

    async def run(self, value: float, **kwargs) -> ToolResult:
        start = time.time()
        result = value * 0.052
        return ToolResult(
            tool_name=self.name,
            success=True,
            output=f"Result: {result:.4f} psi/ft",
            raw={"result": result},
            duration_seconds=time.time() - start,
        )

Register it in nanobot/tools/oilgas_tools.py → get_oilgas_tools().

from nanobot.scheduler.agent_teams import AgentTeam, register_team

register_team(AgentTeam(
    name="my-team",
    description="One-line dashboard description",
    mode="hierarchical",  # or "flat"
    system_prompt="""You are the [Role] Team.

Workflow:
1. Use [tool_name] to [action]
2. Analyze results and synthesize

Output Format:
## Summary
## Findings
## Recommendations""",
    inject_knowledge=True,
    update_knowledge_after=True,
    max_tokens=4096,
    temperature=0.1,
))