# AGENTS: GridForge Architecture & Guidelines

Overview
- GridForge is a production-ready, low-code platform for composing cross-domain energy optimization apps using a visual DSL concept (Objects, Morphisms, Functors, Limits/Colimits, Time Monoid).
- This repository implements a robust Python-based core with a FastAPI server to prototype end-to-end workflows, including DSL modelling, adapter generation, a toy distributed solver (ADMM-lite), simulation sandbox, and governance scaffolding.

Tech Stack (Current)
- Language: Python 3.11+
- Server: FastAPI (uvicorn for dev server)
- Persistence: SQLite via SQLAlchemy (lightweight local storage)
- DSL & Validation: Pydantic models
- Solver: Simple ADMM-lite placeholder for distributed optimization
- Adapters: Auto-generated skeletons in adapters/ for plug-and-play deployment
- Simulation: Sandbox module to validate end-to-end flows
- Governance: RBAC scaffold and audit-friendly event logging

How to Run (dev)
- Install: python -m pip install -e .
- Run server: uvicorn gridforge.server:app --reload
- Tests: pytest

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)
 AGENTS.md is the canonical place to document architectural decisions and contribution rules. If you introduce major architectural changes, update this file accordingly.

Contributing
- Keep changes small and well-scoped. Prefer incremental improvements that can be validated with tests.
- Add tests for any new behavior. Ensure test.sh passes locally.
- Document any public API changes in AGENTS.md and README.md.