How wissemkooli/m4_agentic_energy_planning works
M4 is a human-in-the-loop energy planning and operations decision-support system. A planner submits a natural-language goal or operating problem through the web UI; the backend investigates data, prepares a scenario, checks and solves an optimization or simulation, and returns alternatives for review. The agent explains and recommends, while users approve assumptions and administrators record decisions—nothing is executed automatically. The graph preserves documented data integration, authentication, history and administration capabilities. Some router and agent internals were not sampled, so uncertain wiring is omitted or shown as unverified.
Main entry points: services.py Application services · system.py System inputs · client.ts REST client · app.py FastAPI application
Components 22
Web experience
- Planning agent UI
frontend/src/pages/PlanningAgent.tsx - Scenario builder
frontend/src/pages/ScenarioBuilder.tsx - Runs and results
frontend/src/pages/StrategiesList.tsx - Admin review
frontend/src/pages/admin/ReviewQueue.tsx - REST client
frontend/src/api/client.ts
API and orchestration
- FastAPI application
M4-Mahdi/m4/api/app.py - Application services
M4-Mahdi/m4/services.py
Planning and operations
- Agent workflow
M4-Mahdi/m4/agent/graph.py - LLM integration
M4-Mahdi/m4/agent/llm.py - Scenario configuration
M4-Mahdi/m4/scenarios/schema.py - System inputs
M4-Mahdi/m4/modeling/system.py - Capacity optimization
M4-Mahdi/m4/optimization/engine.py - Operational optimization
M4-Mahdi/m4/operations/engine.py - Energy simulation
M4-Mahdi/m4/modeling/simulation.py - Strategy roadmap
M4-Mahdi/m4/strategy/roadmap.py
Energy data
- Input repository
M4-Mahdi/m4/data_integration/repository.py - Source adapters
M4-Mahdi/m4/data_integration/adapters.py - Demand pathways
M4-Mahdi/m4/modeling/demand.py
Identity and decisions
- Authentication
M4-Mahdi/m4/auth/security.py - Persistent records
M4-Mahdi/m4/db/models.py - Admin review API
M4-Mahdi/m4/api/routers/admin.py
Other components
- Planner
Connections 26
- Planner → Planning agent UI: submits goal
README.md - Planning agent UI → REST client: sends requests
frontend/src/pages/PlanningAgent.tsx - Scenario builder → REST client: sends requests
frontend/src/pages/ScenarioBuilder.tsx - Runs and results → REST client: fetches results
- Admin review → REST client: reviews decisions
- REST client → FastAPI application: calls REST API
README.md - FastAPI application → Application services: routes workflow
M4-Mahdi/m4/api/app.py - FastAPI application → Admin review API: mounts router
M4-Mahdi/m4/api/app.py - Application services → Agent workflow: invokes agent
M4-Mahdi/m4/services.py - Application services → Capacity optimization: runs planning
M4-Mahdi/m4/services.py - Application services → Operational optimization: runs operations
M4-Mahdi/m4/services.py - Application services → Energy simulation: runs simulation
M4-Mahdi/m4/services.py - Application services → Persistent records: persists runs
M4-Mahdi/m4/services.py - Agent workflow → LLM integration: uses optional LLM
README.md - Agent workflow → Scenario configuration: forms scenario
README.md - Capacity optimization → System inputs: builds from
M4-Mahdi/m4/optimization/engine.py - Operational optimization → System inputs: builds from
M4-Mahdi/m4/operations/engine.py - Energy simulation → System inputs: uses shared inputs
M4-Mahdi/m4/modeling/system.py - System inputs → Input repository: loads inputs
M4-Mahdi/m4/modeling/system.py - Input repository → Source adapters: loads source data
M4-Mahdi/m4/data_integration/repository.py - System inputs → Demand pathways: uses demand pathways
M4-Mahdi/m4/modeling/system.py - System inputs → Scenario configuration: applies scenario
M4-Mahdi/m4/modeling/system.py - Capacity optimization → Strategy roadmap: informs strategies
- Planner → Authentication: authenticates
README.md - Authentication → Persistent records: uses user records
M4-Mahdi/m4/auth/security.py - Admin review API → Persistent records: records decisions