42 lines
2.2 KiB
Markdown
42 lines
2.2 KiB
Markdown
# 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.
|