🌐 ForgeCAT Connector (UTC Module)

Partner Integration API for Climate & Hazard Models

Version: v1.0Status: Official Integration Layer Category: Scientific / Climate / Hazard Modeling

ForgeCAT Connector is a lightweight Go-based microservice that exposes a clean and uniform partner API for executing tropical cyclone ensemble simulations (UTC model) on the Forge Pool planetary compute network.

It provides:

• Input normalization for external hazard formats
• Validation of storm metadata and climate parameters
• Mapping to ForgeCAT UTC adapter shape
• Execution on Forge Pool Web Core
• Enriched scientific statistics
• Billing transparency
• Deterministic reproducible results

---

🚀 1. Purpose

The Connector simplifies partner adoption:

Partner → Connector → Forge Pool → Hub → Agents → Results

Instead of sending raw ForgeCAT payloads, partners use a consistent, clean structure, while the Connector handles:

• model mapping
• parameter validation
• error semantics
• enriched output (percentiles, extremes, metadata)
• simplified endpoint design

---

📡 2. Endpoint Overview

POST /v1/utc/run

Executes a full UTC cyclone ensemble run.

Example request:

{
  "model": "UTC-1.0",
  "ensemble": 5000000,
  "storm": {
    "id": "sample-001",
    "basin": "atlantic",
    "year": 2024
  },
  "scenario": {
    "rcp": "rcp4.5",
    "delta_intensity": 3.5
  },
  "parameters": {
    "major_threshold": 50
  },
  "seed": 987654321
}

---

🔧 3. Internal Mapping (Partner → ForgeCAT)

Partner parameters are mapped into ForgeCAT UTC’s expected structure:

{
  "ensemble_size": 5000000,
  "model": "UTC-1.0",
  "initial_conditions": { ... },
  "climate_factors": { ... },
  "utc_parameters": { ... },
  "seed": 987654321,
  "job_id": "<ulid>"
}

This payload is forwarded to:

POST /api/v0/compute/montecarlo/forgecat-utc

on the Web Core.

---

🧮 4. Example Enriched Response

Real production output:

{
  "request_id": "01KBG4C9W80765K7CRXS4PCGJ5",
  "status": "success",
  "connector_id": "forgecat-connector-v1",
  "timestamp": "2025-12-03T00:46:51Z",

  "ensembles": {
    "iterations": 5000000,
    "agents": 4,
    "mean_intensity": 53.50,
    "extreme_probability": 0.6148,
    "distribution": {
      "min": 0,
      "max": 114.95,
      "p90": 68.88,
      "p99": 81.41,
      "p999": 90.58
    }
  },

  "billing": {
    "customer_eur": 0.15,
    "customer_credits": 15,
    "provider_total_eur": 0.105,
    "forge_eur": 0.045
  },

  "raw": { ...full Forge Pool response... }
}

---

🧪 5. Performance Examples

5,000,000 ensembles

• 4 agents
• 0.16 seconds
• €0.15

100,000,000 ensembles

• 9 agents
• 0.66 seconds
• €3.00

These results were obtained on real Forge Pool deployments.

---

🛠 6. Architecture Diagram

[ Partner System ]
        |
        v
[ ForgeCAT Connector ]
  Validation + Mapping
        |
        v
[ Forge Pool Web Core API ]
        |
        v
[ Forge Hub ]
        |
        v
[ Global Agents ] ← parallel shards
        |
        v
[ Results → Web Core → Connector ]

---

📦 7. Deployment

The Connector ships as:

• Go binary
• Docker image
• Kubernetes-ready service

Env vars:

FORGE_API_KEY=<key>
FORGE_BASE_URL=https://api.forgepool.io/v0
SERVER_PORT=8080
CONNECTOR_VERSION=forgecat-connector-v1

---

🔐 8. Authentication

All Forge Pool calls are done using:

X-Forge-Api-Key: fpak_*****

The connector itself does not require authentication by default, but supports:

• API tokens
• mTLS (optional)
• IP whitelisting
• Rate limits

---

🧭 9. Future Extensions

The architecture supports additional hazard adapters:

• Windfield intensity
• Rainfall ensembles
• Hailstorm models
• Flood Monte Carlo
• Wildfire spread (MC/ABM)
• Track models (TC track physics)
• Global hazard index scoring

Adding a new module only requires:

• new mapper
• new validator
• new handler
• new adapter call

Everything else remains identical.

---

🏁 10. Summary

The ForgeCAT Connector provides:

• A clean integration surface for climate & hazard models
• A stable API for partners and enterprise users
• Automatic mapping & validation
• Planetary-scale execution via Forge Pool
• Enriched scientific outputs
• Deterministic reproducibility

It is the recommended entry point for any organization wanting to use ForgeCAT in production.