Developer quickstart, API walkthrough, engine extension tutorial, and notebook demonstrations. Target audience: new team members, evaluators, and integrators joining the ARES-E program.
| Requirement | Minimum Version | Verification Command |
|---|---|---|
| Python | 3.11+ | python --version |
| pip | 23.0+ | pip --version |
| Poetry | 1.7+ | poetry --version |
| Docker (optional) | 24.0+ | docker --version |
| Git | 2.40+ | git --version |
git clone https://github.com/DaScient/Genesis.git
cd Genesispoetry installOr with pip:
pip install -e .PYTHONPATH=. pytest -q --tb=lineExpected output: 45 passed with zero warnings.
Genesis/
├── app/
│ ├── main.py # FastAPI entry point (v0.2.0)
│ ├── api/
│ │ └── endpoints.py # REST endpoints under /api/v1/genesis/
│ ├── core/
│ │ ├── amsc_harness.py # Master orchestrator (GenesisHarness)
│ │ ├── cyber_ledger.py # SHA-256 audit ledger (ZeroTrustLedger)
│ │ └── interoperability.py # Plugin registry (InteroperabilityManager)
│ ├── engines/
│ │ ├── ewis_grid.py # Topic 16 — GridPINN + dispatch
│ │ ├── woik_fluid.py # Topic 21 — Thermal hydraulics
│ │ └── phiak_cyber.py # Topic 20 — Cyber + DP + adversarial
│ └── schemas/
│ └── genesis_payloads.py # Pydantic V2 FAIR schemas
├── tests/
│ ├── test_physics_engines.py # 25 tests
│ ├── test_amsc_harness.py # 11 tests
│ └── test_api_endpoints.py # 9 tests
├── notebooks/ # Jupyter demonstrations
├── docs/ # Enterprise documentation
├── docker-compose.yml # Container orchestration
├── pyproject.toml # Poetry configuration
└── README.md # Project overview
PYTHONPATH=. uvicorn app.main:app --reload --host 0.0.0.0 --port 8000docker compose up --buildcurl http://localhost:8000/Expected: {"message": "ARES-E Genesis API", "version": "0.2.0"}
curl -X POST http://localhost:8000/api/v1/genesis/submit_workflow \
-H "Content-Type: application/json" \
-d '{
"metadata": {
"domain": "EWIS",
"version": "0.2.0",
"tags": ["grid", "dispatch"],
"fair_pid": "doi:10.ares/ewis-001"
},
"parameters": {
"grid_nodes": 10,
"epochs": 20
}
}'Response:
{
"job_id": "uuid-string",
"domain": "EWIS",
"status": "COMPLETED",
"physics_violations": 0,
"vvuq_score": 0.85,
"timestamp": "2025-01-01T00:00:00+00:00"
}curl http://localhost:8000/api/v1/genesis/status/{job_id}curl http://localhost:8000/api/v1/genesis/ledgerReturns STIX/TAXII 2.1 bundle with all evaluation records.
curl http://localhost:8000/api/v1/genesis/domainsReturns: {"domains": ["EWIS", "PHIAK", "WOIK"]}
curl http://localhost:8000/api/v1/genesis/healthReturns system health including ledger integrity status.
Purpose: Physics-informed neural network for autonomous grid dispatch optimization.
Key Classes:
GridPINN— 3-layer MLP with physics residual loss.evaluate_agent_grid_dispatch()— Main dispatch evaluation.compute_classical_baseline()— Deterministic reference.compute_ai_advantage()— Ratio of PINN to classical performance.
Workflow Parameters:
{"grid_nodes": 10, "epochs": 20}Purpose: Closed-loop thermal hydraulic analysis for water-energy nexus systems.
Key Classes:
WoikFluidEngine— NetworkX-based directed graph thermal loop.evaluate_thermal_hydraulics()— Main thermal evaluation.
Workflow Parameters:
{"target_flow_rate": 5.0}Purpose: Differential privacy, adversarial detection, and data fingerprinting.
Key Classes:
DifferentialPrivacyMechanism— Laplace noise injection (configurable ε).AdversarialDetector— 8 injection + 7 poisoning pattern detectors.PhiakCyberEngine— Orchestrates DP, detection, and fingerprinting.
Workflow Parameters:
{"epsilon": 1.0, "sensitivity": 1.0, "test_payload": "SELECT * FROM grid"}# app/engines/my_engine.py
from typing import Any
def evaluate_my_domain(parameters: dict[str, Any]) -> dict[str, Any]:
"""Evaluate custom domain logic."""
physics_violations = 0
vvuq_score = 0.90
return {
"domain": "MY_DOMAIN",
"physics_violations": physics_violations,
"vvuq_score": vvuq_score,
"results": {"custom_metric": 42.0},
}from app.core.interoperability import InteroperabilityManager
from app.engines.my_engine import evaluate_my_domain
mgr = InteroperabilityManager()
mgr.register_engine("MY_DOMAIN", evaluate_my_domain)In app/schemas/genesis_payloads.py, extend the domain Literal:
domain: Literal["EWIS", "WOIK", "PHIAK", "MY_DOMAIN"]In app/core/amsc_harness.py, add:
def _run_my_domain(self, params: dict[str, Any]) -> dict[str, Any]:
return self._interop.execute("MY_DOMAIN", params)And register in __init__:
self._interop.register_engine("MY_DOMAIN", self._run_my_domain)# tests/test_my_engine.py
from app.engines.my_engine import evaluate_my_domain
def test_evaluate_my_domain():
result = evaluate_my_domain({"param": "value"})
assert result["physics_violations"] == 0
assert 0.0 <= result["vvuq_score"] <= 1.0PYTHONPATH=. pytest -q --tb=lineThe notebooks/ directory contains Jupyter notebooks demonstrating each engine:
| Notebook | Purpose |
|---|---|
ewis_grid_demo.ipynb |
GridPINN training, dispatch, baseline comparison |
woik_fluid_demo.ipynb |
Thermal loop construction, flow balance, violation detection |
phiak_cyber_demo.ipynb |
Differential privacy calibration, adversarial detection |
genesis_harness_demo.ipynb |
Full orchestrator workflow with STIX export |
Launch notebooks:
jupyter notebook notebooks/| Task | Command |
|---|---|
| Run all tests | PYTHONPATH=. pytest -q --tb=line |
| Run tests with coverage | PYTHONPATH=. pytest --cov=app --cov-report=term-missing |
| Start API server | PYTHONPATH=. uvicorn app.main:app --reload |
| Build Docker images | docker compose build |
| Start all services | docker compose up -d |
| View API docs | Open http://localhost:8000/docs (Swagger UI) |
| View OpenAPI spec | Open http://localhost:8000/openapi.json |
| Check dependency security | pip audit |
| Format code | black app/ tests/ |
| Lint code | ruff check app/ tests/ |
- Technical Specification:
docs/submission/spec.md - Security Posture:
docs/governance/security_compliance.md - Data Rights:
docs/governance/data_rights_ip_guide.md - Responsible AI:
docs/governance/responsible_ai_plan.md - Deployment Operations:
docs/training/deployment_runbook.md - Documentation Index:
docs/INDEX.md