Skip to content

spec.md

Latest commit

 

History

History
321 lines (217 loc) · 14.1 KB

spec.md

File metadata and controls

321 lines (217 loc) · 14.1 KB

ARES-E Technical Specification — DE-FOA-0003612

Agentic Resilience & Evaluation System for Essential-Infrastructure (ARES-E) DOE Genesis Mission — Phase I Prototype Version 0.2.0 | April 2026

1. Executive Summary

ARES-E is a deterministic, physics-constrained evaluation harness purpose-built for the American Science Cloud (AmSC). It provides a unified platform for scoring, validating, and auditing scientific AI agent actions across three DOE Genesis Mission topic areas:

Topic Codename Capability
16 — Scaling the Grid EWIS Physics-Informed Neural Networks for grid dispatch under Dynamic Line Rating
21 — Fluid Flow for Energy WOIK Closed-loop thermal-hydraulic conservation via directed-graph topology
20 — Cybersecurity for AI PHIAK ε-Differential privacy, adversarial/injection detection, data-provenance fingerprinting

The platform enforces Verification, Validation, and Uncertainty Quantification (VVUQ) at every evaluation step, produces a cryptographically-chained (SHA-256) audit trail exportable as STIX/TAXII 2.1 bundles, and delivers a plug-and-play interoperability registry enabling zero-downtime integration of additional agency engines (NNSA, NIST, NRC, Navy, ISO).

2. Scope and Alignment with DE-FOA-0003612

2.1 Genesis Mission Objectives Addressed

This system directly advances the Genesis Mission's core objectives as stated in the FOA:

  • Accelerate breakthroughs in energy dominance — The EWIS engine validates AI-proposed grid dispatch strategies against Kirchhoff-law physics constraints, ensuring agent recommendations improve upon classical baselines before deployment.
  • Discovery science — The WOIK engine enforces first-law thermodynamic conservation (Q = ṁ · cₚ · ΔT) on closed-loop cooling systems, enabling safe exploration of novel thermal configurations for HPC and reactor cooling.
  • National security capabilities — The PHIAK engine provides ε-differential privacy guarantees on infrastructure telemetry and detects adversarial injection, poisoning, and prompt-manipulation attacks targeting scientific AI agents.

2.2 American Science Cloud Integration

ARES-E is designed for seamless deployment on the AmSC:

  • Air-gapped operation — Zero external API calls; all computation is local.
  • FAIR data compliance — Every payload requires structured metadata (Source, Modality, Timestamp, Uncertainty_Margin) per DOE FAIR principles.
  • STIX/TAXII 2.1 audit export — Immutable ledger exportable for DOE threat-intelligence sharing and DFIR forensics.
  • Containerized deployment — Docker Compose manifest provides Uvicorn + Ray head for immediate AmSC cluster integration.

2.3 OT Agreement Alignment

OT Section ARES-E Compliance Mechanism
Section I — Scope of Work Three-topic coverage (16, 21, 20) with deterministic VVUQ scoring
Section III — Intellectual Property All code MIT-licensed; no third-party IP encumbrances; IP Certification-ready
Section IV — IP Warranty Open-source dependencies only (PyTorch, NetworkX, NumPy, FastAPI)
Section V — RTES No foreign entity dependencies; 100% U.S. development; no FCOC components
Section VI — Reporting Milestone-aligned deliverables with deterministic acceptance criteria
Appendix II — Patent Rights No Subject Inventions claimed; Government retains non-exclusive license
Appendix III — Data Rights Open data rights; Government has Unlimited Rights in all delivered Data

3. System Architecture

3.1 Component Hierarchy

┌─────────────────────────────────────────────────────────┐
│                   FastAPI Application                    │
│                      app/main.py                        │
├─────────────────────────────────────────────────────────┤
│                 API Layer (endpoints.py)                 │
│    POST /submit_workflow  GET /status  GET /ledger      │
│    GET /domains           GET /health                   │
├─────────────────────────────────────────────────────────┤
│             GenesisHarness (amsc_harness.py)            │
│  ┌──────────────────────────────────────────────────┐   │
│  │       InteroperabilityManager (registry)          │   │
│  │   register_engine / unregister_engine / execute    │   │
│  └──────────────────────────────────────────────────┘   │
├────────────┬─────────────┬──────────────────────────────┤
│  EWIS      │  WOIK       │  PHIAK                       │
│  GridPINN  │  FluidEngine│  DPMechanism                 │
│  Dispatch  │  NetworkX   │  AdversarialDetector          │
│  Baseline  │  1st Law    │  SHA-256 Fingerprint          │
│  AI-Adv.   │  ΔT Check   │  ε-Laplace                   │
├────────────┴─────────────┴──────────────────────────────┤
│          ZeroTrustLedger (cyber_ledger.py)              │
│   SHA-256 Hash Chain → STIX/TAXII 2.1 Bundle Export     │
└─────────────────────────────────────────────────────────┘

3.2 Data Flow

  1. Ingestion — AI agent submits a JSON payload via POST /api/v1/genesis/submit_workflow conforming to the GenesisWorkflowPayload Pydantic V2 schema.
  2. Validation — Pydantic strict-mode validators enforce FAIR metadata presence, domain-literal typing (EWIS | WOIK | PHIAK), and parameter-schema conformance.
  3. Dispatch — InteroperabilityManager.execute() routes the payload to the registered domain engine.
  4. Evaluation — The domain engine produces a result dict containing physics_violations (int) and vvuq_score (float in [0, 1]).
  5. Audit — ZeroTrustLedger.add_record() appends a SHA-256-chained block referencing the evaluation result.
  6. Response — The harness stores the workflow status and returns the job_id for subsequent status queries.

3.3 Technology Stack

Layer Technology Version Purpose
API Framework FastAPI 0.111+ Async REST API with OpenAPI 3.1 auto-docs
Schema Validation Pydantic V2 2.7+ Strict-mode FAIR-compliant data validation
Physics ML PyTorch 2.1+ GridPINN training with composite physics loss
Graph Modeling NetworkX 3.4+ Directed-graph thermal-loop topology
Numerical NumPy 2.2+ Laplace mechanism for differential privacy
Cryptographic hashlib (stdlib) — SHA-256 hash chaining for zero-trust audit
Orchestration Ray 2.5+ Distributed compute for AmSC HPC clusters
Containerization Docker Compose 3.9 — Uvicorn + Ray head for local simulation

4. Topic 16 — EWIS: Physics-Informed Grid Modeling

4.1 GridPINN Architecture

Three-layer fully-connected neural network with sigmoid output activation:

Input(3) → Linear(64) → ReLU → Linear(64) → ReLU → Linear(1) → Sigmoid

Composite Loss Function:

$$L = L_{\text{data}} + \lambda \cdot L_{\text{physics}}$$

Where $L_{\text{data}} = \text{MSE}(\hat{y}, y)$ and $L_{\text{physics}}$ penalizes deviation from Kirchhoff branch-flow conservation (sum of currents at a node ≈ 0).

4.2 Dynamic Line Rating (DLR)

The deterministic dispatch layer computes effective capacity under weather-driven DLR:

$$C_{\text{eff}} = C_{\text{rated}} \cdot \max(0.1,\ 1.0 - 0.2 \cdot w)$$

Where $w \in [0, 1]$ is the weather anomaly severity. A physics violation is flagged when reserve margin falls below 5%.

4.3 AI-Advantage Metric

$$A = \begin{cases} 0 & \text{if } V > 0 \ \max\bigl(0,\ \min(1,\ 1 - |r_{\text{PINN}} - r_{\text{baseline}}|)\bigr) & \text{otherwise} \end{cases}$$

This metric quantifies the PINN's improvement over classical static dispatch, penalizing any physics violation to zero.

5. Topic 21 — WOIK: Water-Energy Nexus Thermal Hydraulics

5.1 Loop Topology

A NetworkX directed graph models the closed cooling loop:

Chiller → Pump → Heat_Load → Return → Chiller

5.2 Governing Equation

First-law energy conservation:

$$Q = \dot{m} \cdot c_p \cdot \Delta T$$

Where:

  • $Q$ = heat load (kW)
  • $\dot{m} = \rho \cdot V_{\text{flow}}$ = mass flow rate (kg/s)
  • $c_p = 4.186$ kJ/(kg·K) for liquid water at ~25°C
  • $\Delta T_{\text{critical}} = 15$ K — violation threshold

5.3 Flow Balance Validation

The engine rejects flow allocations where the maximum deviation from mean flow exceeds 20%, preventing physically unrealizable configurations from reaching the conservation check.

6. Topic 20 — PHIAK: Cybersecurity for AI

6.1 Differential Privacy

Laplace mechanism with configurable privacy budget:

$$\tilde{x} = x + \text{Laplace}\left(0,\ \frac{\Delta f}{\varepsilon}\right)$$

Where $\varepsilon$ is the privacy budget and $\Delta f$ is the global sensitivity. Smaller $\varepsilon$ provides stronger privacy guarantees at the cost of higher noise.

6.2 Adversarial Detection

Eight compiled regex patterns detect injection attacks:

  • SQL injection (DROP TABLE, UNION SELECT, ; --)
  • Prompt injection (ignore previous instructions)
  • XSS (<script>)
  • Command injection (EXEC, SHUTDOWN, DELETE)

Seven keyword detectors identify data-poisoning vocabulary: malicious, backdoor, trigger, poison, adversarial, trojan, evasion.

6.3 SHA-256 Fingerprinting

Content-addressable fingerprinting enables data provenance tracking across the AmSC:

$$h = \text{SHA-256}(\text{UTF-8}(d))$$

7. VVUQ Framework

7.1 Score Computation

Each domain engine returns a vvuq_score in [0, 1]:

Domain VVUQ Computation
EWIS $1 -
WOIK 1.0 if energy is conserved AND $\Delta T &lt; 15$ K; else 0.0
PHIAK $\max(0,\ \min(1,\ 1 - 0.1 \cdot N_{\text{detections}}))$

7.2 Deterministic Validation Path

The physics validation layer operates independently of the AI prediction layer:

  1. Deterministic dispatch computes ground-truth metrics from first principles.
  2. PINN prediction is compared against the deterministic result.
  3. VVUQ score quantifies agreement; violations are absolute disqualifiers.

This separation ensures that no AI prediction can bypass physics constraints.

8. Zero-Trust Audit Ledger

8.1 Chain Structure

Each evaluation produces a block:

{
  "index": N,
  "timestamp": "ISO-8601",
  "data": { ... evaluation payload ... },
  "stix_type": "indicator",
  "taxii_collection": "DOE-ARES-E",
  "previous_hash": "SHA-256 of block N-1",
  "hash": "SHA-256 of this block (excluding hash field)"
}

8.2 Integrity Verification

verify_chain() walks the full chain and confirms:

  • Each block's previous_hash matches the prior block's hash.
  • Each block's hash is consistent with its content.

8.3 STIX/TAXII 2.1 Export

The ledger exports as a STIX bundle with spec_version: "2.1", where each block becomes an indicator object with labels ["DOE", "ARES-E", "STIX", "zero-trust"] and confidence 100.

9. Interoperability

9.1 Registry Pattern

The InteroperabilityManager provides a plug-and-play engine registry:

harness.interop.register_engine("NNSA", nnsa_engine_callable)
harness.interop.register_engine("NIST", nist_engine_callable)
harness.interop.get_registered_domains()  # ['EWIS', 'NNSA', 'NIST', 'PHIAK', 'WOIK']

9.2 Engine Interface Contract

Any callable conforming to the following signature can be registered:

def engine(payload: Dict[str, Any]) -> Dict[str, Any]:
    """Must return dict with 'physics_violations' (int) and 'vvuq_score' (float)."""

9.3 Multi-Agency Dispatch

The harness routes payloads by the domain field in the workflow payload, enabling seamless integration of DOE Lab, NNSA, Navy, NIST, NRC, and ISO evaluation engines without modifying the orchestration core.

10. Test Suite

Module Tests Coverage
test_physics_engines.py 25 EWIS dispatch, PINN, baseline, AI-advantage; WOIK conservation, violations, flow balance; PHIAK privacy, adversarial detection, fingerprint
test_amsc_harness.py 11 All 3 domains via harness, failures, ledger growth, chain verification, interoperability register/unregister
test_api_endpoints.py 9 All 5 REST endpoints, Pydantic validation errors, 404 handling
Total 45 Zero warnings, zero deprecations

11. Deployment

11.1 Local Development

git clone https://github.com/DaScient/Genesis.git && cd Genesis
pip install -e .
PYTHONPATH=. pytest -v
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

11.2 Containerized (AmSC Simulation)

docker-compose up --build

11.3 AmSC / LCF Production

  • Deploy behind Science DMZ network perimeter.
  • Set CORS_ORIGINS environment variable to restrict allowed origins.
  • Enable torch.use_deterministic_algorithms(True) for reproducibility on LCF GPU nodes.
  • Mount Ray cluster head for distributed PINN training across HPC nodes.

12. Revision History

Version Date Author Description
0.1.0 2026-04-02 ARES-E Team Initial scaffold and engine implementations
0.2.0 2026-04-02 ARES-E Team Production-grade rewrite: Pydantic V2, 45 tests, interoperability, enhanced notebooks