Imported from urgabonselmullervg/FintechMVP (gridflex-mvp/AGENTS.md). Install upstream with npx skills add urgabonselmullervg/FintechMVP --skill gridflex-mvp. Copyright stays with the author.

AGENTS.md — Contributor & Agent Guide

This file defines how any contributor (human or AI agent) should work in this repository. It is the canonical source of project rules.

What we are building

GridFlex Local Settlement Simulator — a Streamlit web application that simulates how local energy flexibility on a Dutch business park can be priced, matched, settled, and turned into bankable cashflow data.

GridFlex Exchange is a B2B software, pricing, matching, reporting and financial settlement layer on top of existing energy contracts.

The goal is a convincing, working, investor-oriented prototype — not a real regulated energy exchange.

What GridFlex is NOT (keep the scope honest)

• Not an energy supplier — does not sell or deliver electricity.
• Not a Balance Responsible Party (BRP).
• Not a grid operator (DSO/TSO).
• Not a peer-to-peer electricity trading platform.

Tech stack

• Python + Streamlit for the app.
• pandas, numpy for data and computation.
• plotly for visualisation.
• pytest for tests.

Architecture & pipelines

Code lives in a clear src/ package. The simulation is organised as a linear, loosely-coupled pipeline so each stage can be built and tested on its own:

step_1_simulation → step_1b_forecast → step_2_pricing_engine → step_3_matching_engine → step_4_settlement → step_5_finance → step_6_reporting

Build new functionality as separate pipeline steps; do not entangle stages.

Hard constraints (do NOT do these)

• ❌ No real EDSN / smart-meter integration.
• ❌ No real supplier or BRP APIs.
• ❌ No real payment processing.
• ❌ No blockchain / smart contracts.
• ❌ No authentication or login system unless explicitly requested.
• ✅ All energy data must be simulated.

Design principles

• Don't be "too clever." Favour a strong, legible demo over a half-finished enterprise app. No unnecessary cloud infra, frameworks, or abstractions.
• Keep code modular, readable, and well-documented.
• Prioritise demo clarity, clean architecture, and investor-readiness.
• Every pipeline stage should be unit-testable in isolation.

Workflow (milestone-based)

Build the project step by step — never in one uncontrolled pass. After each milestone:

1. Explain what changed.
2. Explain how to run / test it.
3. Suggest a git commit message.
4. Stop and wait for the next instruction.

Keep the git history logical: small, scoped commits with clear messages.

Running locally

pip install -r requirements.txt
streamlit run app.py     # run the app
pytest                   # run the tests