PETAL

Planification Énergétique Territoriale Assistée par LLM (PETAL), a solution for assisted territorial energy planning using large language models.

Overview

This project deals with the implementation of a solution that is designed to assist an informed user into energy planning for a municipality, in Switzerland. This solution leverages the AI orchestration and agentic AI concepts.

This work is done in the context of my bachelor thesis which is named "Optimisation de la planification énergétique urbaine par l'orchestration de l'IA" which translates into "Optimization of urban energy planning through AI orchestration" in English.

This section offers an overview of the codebase, its main components, and provides instructions on how to run the project. For a comprehensive and detailed description of the project, including the rationale behind architectural and implementation choices as well as the key takeaways, please refer to the separate thesis report file.

Author & Acknowledgments

Osmani Dion, Author, HES-SO Valais-Wallis Student, Informatique et systèmes de communication

Page Jessen, Supervisor, HES-SO Valais-Wallis Lecturer, Énergie et techniques environnementales

Desmons Florian, Co-supervisor, HES-SO Valais-Wallis Lecturer, Informatique et systèmes de communication

Cédric Travelletti, Assisted the technical aspects, HES-SO Valais-Wallis Lecturer, Informatique et systèmes de communication

Objectives

This work is organized into several objectives:

• Define the key information needed to assist the user in decision-making.
• Identify and assess available and usable data sources for this decision support.
• Structure the decision support system using an orchestrator AI and several specialized AIs.
• Train specialized AIs on specialized data.
• Simplify user interfacing by managing communication between the orchestrator AI and the specialized AIs.

Techincal Overview

The following sections provided an overview of the codebase, its main components, and provides instructions on how to run the project.

Project Structure

Considering the project's structure, the codebase is organized as follows:

├── backend/                        # Backend services and APIs (main logic)
│   ├── benchmarking/               # Benchmarking data
│   ├── marimo/                     # Marimo notebooks for data preparation
│   ├── src/                        # Backend source code and scripts
│   ├── tests/                      # Backend test suite
│   ├── pyproject.toml              # Backend project configuration file
│   └── uv.lock                     # Lock file generated by uv
├── frontend/                       # Frontend application
│   ├── server/                     # Frontend server code and script
│   ├── src/                        # Frontend source code
│   ├── bun.lock                    # Lock file for Bun package manager
│   ├── package.json                # Node.js project configuration
│   └── vite.config.ts              # Vite build tool configuration
├── docker-compose.yaml             # Docker Compose orchestration file
└── run.sh                          # Project run script

Please note that only the most important files and directories are presented above.

Energy planning solution

The backend directory forms the backbone of the project, managing interactions between the orchestrator AI and the specialized AIs.

It is organized around multiple agents, each responsible for a specific task or function:

• Router Agent: This agent acts as the initial point of contact for user requests. It analyzes the incoming query, referencing previous interactions to understand the user's intent and maintain conversational continuity. By storing additional context from the ongoing dialogue, the router agent enables a more natural, conversation-like interaction with the system.

• Clarification Agent: This agent intervenes when the user's query lacks sufficient detail or when additional information is required to proceed. It prompts the user for the necessary clarifications, ensuring that all essential data is collected before moving forward with the decision support process.

• Geographic Context Agent: Responsible for sourcing relevant information, this agent selects and retrieves the most pertinent data points in response to the user's question. This can include specific datasets, geographic information, or applicable guidelines and legislation from municipal, cantonal, or federal sources. Its goal is to ensure that all necessary and probative information is available for informed decision-making.

• Answer Generation Agent: Once the relevant context and data have been gathered, this agent synthesizes the information into a coherent response. It ensures that the answer not only addresses the user's query but also adheres to the established principles and rules of energy planning, providing guidance that is both accurate and compliant with key regulations.

• Answer Critic Agent: After the answer is streamed to the user, it is evaluated against a set of predefined criteria focused on common interpretation errors. If the answer isn't correct, complete or free from significant interpretation errors, the whole pipeline is restarted.

Running the project

The project leverages a modern, modular technology stack for both backend and frontend components:

• Backend:

  • Python 3.11 is used as the primary programming language.
  • LangGraph (see LangChain LangGraph) is employed to orchestrate and manage the agentic AI workflows, enabling the creation of complex, multi-agent conversational flows using graph-based workflows.
  • Ollama is used to run and manage local large language models, providing an efficient and flexible way to serve LLMs for the backend agents.
  • Redis is used as a fast, in-memory data store to persist guidelines, legislation, and user memories, enabling efficient retrieval of regulatory information and maintaining conversational context across sessions.
  • uv is used for Python package installation and dependency resolution, providing fast and reliable environment management.

• Frontend:

  • Built with React using TypeScript for type safety and maintainability.
  • Bun serves as both the JavaScript runtime and package manager, offering fast installs and efficient script execution.
  • Vite is used as the build tool, enabling rapid development and optimized production builds.

This combination ensures a robust and scalable environment for both AI-driven backend logic and an interactive user interface.

All services are packaged into separate Docker containers for streamlined deployment, with Docker Compose used to orchestrate and manage them collectively.

---

Before running the project, ensure that Docker and Docker Compose are installed on your system. For installation instructions, refer to the official Docker Compose documentation: https://docs.docker.com/compose/install/

Install the NVIDIA Container Toolkit on the host machine that will run the Ollama Docker service, as Ollama is a GPU-intensive service. This enables GPU passthrough for optimal performance. Follow the official NVIDIA Container Toolkit installation guide: https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/latest/install-guide.html

Before getting started, create an environment configuration file by duplicating .env.example as either .env.dev or .env.prod, according to your deployment requirements. Specify the models you intend to use in this file and modify any other settings as needed.

To launch the various services, use the run.sh script:

./run.sh <env> docker compose up
# where <env> is either 'dev' or 'prod'

This script automatically loads the correct environment variables from either .env.dev or .env.prod, depending on the mode you specify, before running the chosen command.

If you wish to start only a specific service let's say on a particular host, you can do so with:

./run.sh <env> docker compose up <service>
# where <env> is either 'dev' or 'prod', and <service> is one of 'ollama','redis', 'backend', or 'frontend'

The web interface can be accessed at http://localhost:5000, by default.

References

All references can be found in the thesis report, located at ./thesis/bachelor_thesis.pdf.

Note

For any additional questions not addressed in this document or the thesis report, please feel free to reach out to me at you can also contact me at dion(dot)08osmani(at)gmail(dot)com.