Docs

README.md

@@ -89,7 +89,7 @@ export VITE_ATM_SIMU=http://[Service url]:[Service port]
 cd config/dev/cab-standalone
 ./docker-compose.sh
 ```
-> **_NOTE:_** You will see the word cab (Cockpit Assistant Bidirectionnel) on most files in the project. Note that it was the initial project name of InteractiveAI. Might be updated later. 
+> **_NOTE:_** You will see the word cab on most files in the project. Note that it was the initial project name of InteractiveAI. Might be updated later. 
 
 3. **Setting up Keycloak `Frontend URL`**  
     * Access Keycloak Interface: 
@@ -99,13 +99,13 @@ cd config/dev/cab-standalone
       - Log in to the Keycloak admin console using your administrator credentials (`admin:admin` by default)
     * Configure frontendUrl:
       - On the Keycloak admin console, locate and click on the "Realm Settings" section.
-      - In the Frontend URL setting, add the URL of your Assistant Platform frontend as a valid redirect URI. This URL is typically where your frontend application is hosted. For example, if your frontend is hosted locally for development purposes, you might add `http://localhost:3200/*`.
-      - After adding the frontend URL, save the changes to update the client settings.
+      - In the Frontend URL field, add the URL of InteractiveAI frontend. If your frontend is hosted locally for development purposes, you might add `http://localhost:3200/`.
+      - After adding the frontend URL, save the changes.
     * Configure Valid Redirect URIs:
       - On the Keycloak admin console, locate and click on the "Clients" section.
-      - Select the client representing your Assistant Platform application.  
-      - Within the client settings, look for the "Valid Redirect URIs" or similar configuration field.
-      - Add the URL of your Assistant Platform frontend, it should match the one used in the frontendUrl setting.
+      - Select the client (opfab-client).  
+      - Within the client settings, look for the "Valid Redirect URIs" field.
+      - Add the URL of the frontend with /*, if it's local deployment: `http://localhost:3200/*`.
       - After adding the Valid Redirect URIs, save the changes to update the client settings.
 
 
@@ -121,7 +121,7 @@ cd resources
 ./loadTestConf.sh
 ```
 
-5. If you encounter CORS errors (which can happen if you start tha platform in a non-HTTPS environment), you can start your browser with security mode disabled.
+5. If you encounter CORS errors (which can happen if you start the platform in a non-HTTPS environment), you can start your browser with security mode disabled.
 
 ```sh
 your-chromium-browser --disable-web-security --user-data-dir="[some directory here]" # replace your-chromium-browser with your browser
@@ -131,7 +131,7 @@ your-chromium-browser --disable-web-security --user-data-dir="[some directory he
 
 ### Default ports
 
-This project is based on a microservice architecture. Every service run on a specific port. Some of th default ports are as fellow:
+This project is based on a microservice architecture. Every service run on a specific port. Some of the default ports are as fellow:
 * Frontend: 3200
 * Context Service: 5100
 * Event Service: 5000

docs/AIAgent_integration.md

@@ -0,0 +1,180 @@
+# AI Agent Integration
+
+## Overview
+
+InteractiveAI is a platform that bridges AI agents with digital environments (simulators) through a web interface. It provides operators with real-time event monitoring, contextual recommendations, and the ability to apply AI-generated actions directly to their environment.
+
+This documentation uses the PowerGrid domain as an example to illustrate how to integrate an AI agent (ExpertRL Agent) with InteractiveAI.
+
+In our enviroment diagram, we are refering to steps 3 and 4.
+
+![Architecture diagram](img/InteractiveAI_AIAgent.png)
+*Figure 1: InteractiveAI general workflow*
+
+---
+
+## AI Agent Repository Structure
+
+The agent repository should include an `app` folder and a `Dockerfile` at the root. The following structure is used by ExpertAgent ([reference implementation](https://github.com/ainetus/T2.1_deep_expert/tree/docker)):
+
+```
+agent-repo/
+├── Dockerfile
+├── requirements_docker.txt
+├── setup.py
+└── app/
+    ├── __init__.py       # Runs the API
+    └── main.py           # FastAPI app definition
+```
+
+### `Dockerfile` (minimal illustration)
+
+```dockerfile
+FROM python:3.12-slim
+
+WORKDIR /app
+
+# Install git
+# Create a directory for environment
+
+# Install Agent package dependencies
+COPY requirements_docker.txt .
+RUN pip install --no-cache-dir -r requirements_docker.txt
+
+# Copy API + agent package
+COPY app ./app/
+
+# Install the project using setup.py at the root
+RUN pip install .
+
+# Expose port
+EXPOSE 8000
+
+# Run server
+CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000"]
+```
+
+### `app/main.py`
+
+```python
+from fastapi import FastAPI
+
+agent = ExpertAgentRL(kwargs)
+app = FastAPI()
+
+@app.post("/api/v1/recommendation")
+def get_recommendation(request: RecommendationRequest):
+    # Convert incoming data to the observation format your agent expects
+    observation = {
+        "event": request.event,
+        "context": request.context,
+    }
+    # Get recommendation from RL agent
+    obs.from_json(observation.get("context", {}).get("observation"))
+    action = agent.act(obs, reward=None, done=False)
+    result = get_parade_info(action, obs)
+    if result is not list:
+        result = [result]
+    return result
+```
+
+For a complete implementation of `main.py`, see [here](https://github.com/ainetus/T2.1_deep_expert/blob/docker/app/main.py).  
+The transformation of an action to the required format is handled by `get_parade_info(act, obs)`, available [here](https://github.com/ainetus/T2.1_deep_expert/blob/docker/app/main.py#L100).
+
+---
+
+## Running and Testing the Agent Locally
+
+### 1. Build the Docker image
+
+```bash
+docker build -t expert-agent-api .
+```
+
+### 2. Run the container
+
+```bash
+docker run -p 8000:8000 expert-agent-api
+```
+
+### 3. Test the recommendation endpoint
+
+Send a POST request using a context JSON file:
+
+```bash
+curl -X POST http://localhost:8000/api/v1/recommendation \
+  -H "Content-Type: application/json" \
+  --data @rte_recommendation.json
+```
+
+The `rte_recommendation.json` context example is available [here](https://github.com/ainetus/T2.1_deep_expert/blob/docker/app/rte_recommendation.json). The expected output is a list of recommendations in dictionary format:
+
+```json
+[
+  {
+    "title": "Topological recommendation: Schematic acquisition at substation 11",
+    "description": "Assign bus 1 to line (extremity) id 11, Assign bus 1 to line (origin) id 13, Assign bus 1 to load id 12",
+    "use_case": "PowerGrid",
+    "agent_type": 2,
+    "actions": [
+      {
+        "_set_line_status": [0, 0, 0, "..."],
+        "_switch_line_status": [false, false, "..."],
+        "_set_topo_vect": [0, 0, 1, 1, 1, "..."],
+        "_change_bus_vect": [false, false, "..."],
+        "_redispatch": [0.0, 0.0, "..."],
+        "_storage_power": [],
+        "_curtail": [-1.0, -1.0, "..."],
+        "_raise_alarm": [false, false, false],
+        "_raise_alert": []
+      }
+    ],
+    "kpis": {
+      "type_of_the_reco": "Topological",
+      "efficiency_of_the_reco": 0.8976841568946838
+    }
+  }
+]
+```
+
+> A helper function `get_parade_info(act, obs)` is provided — it takes an action and the corresponding observation and outputs this dictionary format per action.
+
+---
+
+## Complete Dockerfile
+
+```dockerfile
+FROM python:3.12-slim
+
+WORKDIR /app
+
+# Install git
+RUN apt-get update && apt-get install -y git && apt-get clean
+
+# Create a directory for environment
+RUN mkdir -p /home/root/data_grid2op/
+RUN git clone https://github.com/AI4REALNET/grid2op-scenario.git /tmp/grid2op-scenario
+RUN mkdir -p /root/data_grid2op
+RUN cp -r /tmp/grid2op-scenario/ai4realnet_small /root/data_grid2op/ai4realnet_small
+RUN rm -rf /tmp/grid2op-scenario
+
+# Python dependencies
+COPY requirements_docker.txt .
+RUN pip install --no-cache-dir -r requirements_docker.txt
+
+# Copy API + agent package
+COPY app ./app/
+COPY ExpertAgent ./ExpertAgent/
+COPY setup.py .
+
+# Install the project using setup.py at the root
+RUN pip install .
+
+# Expose port
+EXPOSE 8000
+
+# Run server
+CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000"]
+```
+
+For the full Dockerfile example, see [here](https://github.com/ainetus/T2.1_deep_expert/blob/docker/Dockerfile).

docs/README.md

@@ -0,0 +1,36 @@
+# InteractiveAI
+
+InteractiveAI is an open-source platform for monitoring and managing complex industrial networks. It integrates human-machine interaction and human expertise to optimize AI performance in demanding operational environments.
+
+## Documentation
+
+- [Platform Overview](./overview.md) — Architecture, services, and integration model
+- [Getting Started](./getting-started.md) — How to connect your system to the platform
+
+### API Reference
+
+| Service | Description |
+|---|---|
+| [Event Service](./api/event-service.md) | Push events into the platform |
+| [Context Service](./api/context-service.md) | Push context updates to the platform |
+| [Historic Service](./api/historic-service.md) | Event and action log; report generation |
+| [Recommendation Service](./api/recommendation-service.md) | AI and ontology-based recommendations |
+| [Capitalization Service](./api/capitalization-service.md) | Operator feedback storage |
+
+## Quick start
+
+External systems only need to call two APIs:
+
+```http
+# 1. Send an event
+POST http://{Platform_Server}/cab_event/api/v1/events
+
+# 2. Send a context update
+POST http://{Platform_Server}/cab_context/api/v1/contexts
+```
+
+See [Getting Started](./getting-started.md) for full details, including the simulator callback endpoint you need to implement.
+
+## Source
+
+Based on the [IRT-SystemX/InteractiveAI](https://github.com/ainetus/InteractiveAI) platform.

docs/api/authentication.md

@@ -0,0 +1,103 @@
+# Authentication
+
+All InteractiveAI APIs require a bearer token. You must obtain a token before calling any endpoint, and include it in every request.
+
+## Get a token
+
+```http
+POST http://{Platform_Server}:3200/auth/token
+Content-Type: application/x-www-form-urlencoded
+```
+
+### Request body
+
+| Field | Value |
+|---|---|
+| `username` | `publisher_test`
+| `password` |`test` |
+| `grant_type` | `password` |
+| `clientId` | `opfab-client` |
+
+### Example (curl)
+
+```bash
+curl -X POST http://{Platform_Server}:3200/auth/token \
+  -H "Content-Type: application/x-www-form-urlencoded" \
+  -d "username=publisher_test&password=test&grant_type=password&clientId=opfab-client"
+```
+
+### Response
+
+```json
+{
+  "access_token": "<token>",
+  "token_type": "Bearer",
+  ...
+}
+```
+
+The token to use in subsequent requests is: `{token_type} {access_token}` (e.g. `Bearer eyJ...`).
+
+---
+
+## Use the token
+
+Include the token in the `Authorization` header of every API call:
+
+```http
+POST http://{Platform_Server}:3200/cab_event/api/v1/events
+Authorization: Bearer eyJ...
+Content-Type: application/json
+```
+
+---
+
+## Python example
+
+```python
+import requests
+import json
+
+server_url = "{Platform_Server}"
+username = "publisher_test"
+password = "test"
+client_id = "opfab-client"
+
+token_url = f"http://{server_url}:3200/auth/token"
+
+# Request token
+response = requests.post(
+    token_url,
+    headers={"Content-Type": "application/x-www-form-urlencoded"},
+    data=f"username={username}&password={password}&grant_type=password&clientId={client_id}"
+)
+
+if response.status_code >= 500:
+    raise ValueError(f"Token request failed with status code {response.status_code}")
+
+data = response.json()
+token = data["token_type"] + " " + data["access_token"]
+
+# Use the token in subsequent requests
+headers = {
+    "Authorization": token,
+    "Content-Type": "application/json"
+}
+
+# Example: send an event
+requests.post(
+    f"http://{server_url}:3200/cab_event/api/v1/events",
+    headers=headers,
+    json={ ... }
+)
+```
+
+---
+
+## API base URLs
+
+| Service | URL |
+|---|---|
+| Auth | `http://{Platform_Server}:3200/auth/token` |
+| Event | `http://{Platform_Server}:3200/cab_event/api/v1/events` |
+| Context | `http://{Platform_Server}:3200/cabcontext/api/v1/contexts` |