This project implements a multi-agent LLM framework for explaining AC Optimal Power Flow (AC-OPF) results in a form that is useful and accessible to the system operator. It is designed to translate complex OPF outputs into clear, structured, and operationally relevant explanations that support decision-making in power system analysis.

The framework uses a multi-agent architecture in which different LLM roles collaborate to generate, critique, refine, and evaluate explanations of AC-OPF snapshots.
This design enables iterative improvement of explanation quality and helps produce more consistent, informative, and operator-oriented outputs.

The pipeline is compatible with OpenAI GPT-5.4 through the API wrapper defined in llm_utils.py.
All LLM-based explanation, critique, distillation, and refinement steps are executed using GPT-5.4 as the underlying language model.

This repository is intended for building an LLM-ready explanation pipeline for AC-OPF results, with a focus on interpretability, human-in-the-loop refinement, and practical support for power system operators.

LLM-Based OPF Explanation Pipeline

Overview

This project generates OPF snapshot datasets, runs an LLM-based training pipeline to improve explanation quality, tests the resulting prompt, and evaluates the outputs.

---

Execution Order

1. Replace your organization API key in llm_utils.py
2. Run run_poa.py to generate warm-start, training, and test data
3. Run mainppeline.py to run the training/refinement pipeline
4. Run testing.py to generate test explanations
5. Run evaluator.py to evaluate and score the results

---

Step 1: Configure API Key

Before running anything, open:

llm_utils.py

Replace the existing placeholder or API key value with your own organization API key.

---

Step 2: Generate Data

Run:

python run_poa.py

This script generates warm-start, training, and test snapshots for the selected case.

Generated files

• warm_snapshots_case39_cf.json
• train_snapshots_case39_cf.json
• test_snapshots_case39_cf.json
• test_snapshots_case39_cf2.json

---

Step 3: Run the Main Pipeline

Run:

python mainppeline.py

This script runs the Actor / Critic / Refiner pipeline.

Available designs

When prompted, choose one of the following:

• 1 = No human intervention
• 2 = Human in the loop
• 3 = Human feedback visible to AI Critic

Prompt files used

• actor_prompt_base.txt
• critic1_prompt.txt
• refiner_prompt.txt
• distiller_prompt.txt

Expected input files

• warmstart_examples.json
• train_snapshots_case39_cf2.json

Output files

• actor_prompt_1.txt
• actor_prompt_2.txt
• actor_prompt_3.txt
• all_distilled_rules_1.json
• all_distilled_rules_2.json
• all_distilled_rules_3.json
• actor_explanations_1.json
• actor_explanations_2.json
• actor_explanations_3.json

---

Step 4: Run Testing

Run:

python testing.py

Current test execution uses:

• input prompt: actor_prompt_base.txt
• output file: test_actor_explanations_base.json

---

Step 5: Run Evaluation

Run:

python evaluator.py

This script performs evaluation and scoring of the generated test explanations.

---

Full Run Commands

python run_poa.py
python mainppeline.py
python testing.py
python evaluator.py

---

Notes

• Make sure the API key in llm_utils.py is valid before running any script.
• mainppeline.py expects:
  • warmstart_examples.json
  • train_snapshots_case39_cf2.json
• If your generated filenames are different, rename them or update the paths inside the script.
• The pipeline expects input entries with an opf_summary field.

---

Project Files

Core scripts

• llm_utils.py
• run_poa.py
• mainppeline.py
• testing.py
• evaluator.py

Prompt files

• actor_prompt_base.txt
• critic1_prompt.txt
• refiner_prompt.txt
• distiller_prompt.txt

Generated dataset files

• warm_snapshots_case39_cf.json
• train_snapshots_case39_cf.json
• test_snapshots_case39_cf.json
• test_snapshots_case39_cf2.json

Training outputs

• actor_prompt_1.txt
• actor_prompt_2.txt
• actor_prompt_3.txt
• all_distilled_rules_1.json
• all_distilled_rules_2.json
• all_distilled_rules_3.json
• actor_explanations_1.json
• actor_explanations_2.json
• actor_explanations_3.json

Testing outputs

• test_actor_explanations_base.json

---

Requirements

pip install -r requirements.txt

## Citation

This repository contains the code accompanying the accepted paper:

F. Moaidi and R. J. Bessa, "Understanding OPF Redispatch Actions through LLM-Assisted
Counterfactual Analysis," 26th International Conference on Environment
and Electrical Engineering & 10th Industrial and Commercial Power Systems Europe,
Lisbon, Portugal, 29 June – 02 July, 2026.



## License

This code is released under the Mozilla Public License 2.0 (MPL-2.0).

You may use, modify, and redistribute this software under the terms of
the MPL 2.0. See the LICENSE file for details.