# GridForge

GridForge is a production-ready, low-code platform for composing cross-domain energy optimization applications. Utilities, SMEs, and communities can rapidly assemble multi-agent workflows that span electricity, water, heating, and edge devices. The platform exposes a visual DSL inspired by Object/Morphism/Functor/Limits/Colimits and a monoidal time model, enabling local problem definitions, data exchange channels, and global constraints.

Key capabilities:
- Visual DSL constructs: Objects (local optimization problems), Morphisms (data channels with schemas), Functors (problem transformers to a canonical representation), Limits/Colimits (global constraints and composition points), and TimeMonoid (rounds and async updates).
- Auto-generated adapters and contract registry with versioning and conformance tests for plug-and-play deployment on DERs, meters, pumps, and controllable loads.
- Integrated solver stack: optional ADMM-lite engine for distributed optimization with delta-sync and audit-ready reconciliation.
- Simulation sandbox and hardware-in-the-loop templates to validate end-to-end workflows before field deployment.
- Governance scaffold: RBAC, multi-tenant isolation, audit trails, and policy-driven exposure of shared signals.
- Metrics: deployment time, adapter coverage, convergence speed, cross-domain performance, and governance/traceability KPIs.

Getting started
- Install: python -m pip install -e .
- Run API server: uvicorn gridforge.server:app --reload
- Run tests: pytest
- Run packaging checks: bash test.sh (will build and run tests)

Project structure (high level)
- gridforge/
  - __init__.py: Package initialization
  - dsl.py: Core DSL data models (Object, Morphism, Functor, Limits, TimeMonoid)
  - core.py: Canonicalization and transformations of DSL into a canonical representation
  - adapters.py: Skeleton adapter generation and registry logic
  - contract.py: Versioned adapter contracts, conformance testing stubs
  - solver.py: ADMM-lite solver implementation for toy problems
  - simulation.py: Sandbox environment for end-to-end validation
  - governance.py: RBAC and policy scaffolding
  - server.py: FastAPI app exposing a basic API for prototyping
tests/
  - test_basic.py: Basic DSL and adapter generation tests
  - test_solver.py: Simple solver behavior tests (toy problem)

Roadmap
- Expand DSL with richer validation, transformations, and cross-domain semantics.
- Implement delta-sync runtime with robust reconciliation and audit logging.
- Integrate with real-world backbones (Open-EnergyMesh, CatOpt) via adapters.
- Harden the governance layer with policy engines and multi-tenant isolation.
- Provide end-to-end demos and hardware-in-the-loop templates.