Adds Interactive Mode to Matlab agent (#24)

- Introduces interactive mode for bidirectional data exchange. The interactive mode
  requires stream_source for sending inputs from client to the Matlab agent.
  The API payloads and configuration gets  updated.
- Updates the Matlab Wrapper codes for stream and interactive simulation modes.
- Adds new examples and expands documentation to describe all simulation modes.

Author: marcomelloni

.github/workflows/matlab-agent-ci.yml

@@ -58,20 +58,22 @@ jobs:
         run: poetry run pylint matlab_agent --fail-under=9
 
       # ───── 6. Tests ─────
-      # - name: Run pytest with coverage
-      #   run: poetry run pytest
-
-      # - name: Upload coverage to Codecov
-      #   if: matrix.os == 'ubuntu-latest'
-      #   uses: codecov/codecov-action@v5
-      #   with:
-      #     files: coverage.xml
-      #     fail_ci_if_error: true
-      #     token: ${{ secrets.CODECOV_TOKEN }}
-
-      # - name: Run pytest (no coverage)
-      #   if: matrix.os != 'ubuntu-latest'
-      #   run: poetry run pytest -q
+      - name: Run pytest (with coverage)
+        if: matrix.os == 'ubuntu-latest'
+        run: poetry run pytest --cov=matlab_agent --cov-report=xml
+
+      - name: Upload coverage to Codecov
+        if: matrix.os == 'ubuntu-latest'
+        uses: codecov/codecov-action@v5
+        with:
+          files: coverage.xml
+          fail_ci_if_error: true
+          token: ${{ secrets.CODECOV_TOKEN }}
+
+      # Windows/macOS → test without coverage
+      - name: Run pytest (no coverage)
+        if: matrix.os != 'ubuntu-latest'
+        run: poetry run pytest -q
 
       # ───── 7. Build + dist artefacts ─────
       - name: Install runtime dependencies

.gitignore

@@ -198,19 +198,20 @@ agents/matlab/dist/
 config*.yaml
 simulation*.yaml
 *.csv
-interactive.py
-*_interactive.py
-**/examples/interactive-simulation/*
 #SIMULATION BRIDGE 
 /logs
 /certs
 *.pem
 *_use.yaml
 client/
+dist/
+/certs
+*.pem
+*_use.yaml
+client/
 client_ripetitive/
 dist/
 .venv*
 certs
 performance_log/
 performance_old/
-MagicMock/

README.md

@@ -19,9 +19,9 @@ _sim-bridge_ exposes a unified interface that enables seamless data exchange and
 - [Simulation Bridge](#simulation-bridge)
   - [Table of Contents](#table-of-contents)
   - [Key Features](#key-features)
-    - [Agents](#agents)
-    - [Modes of Simulation](#modes-of-simulation)
-    - [Plug-in Protocol Adapters](#plug-in-protocol-adapters)
+      - [Agents](#agents)
+      - [Modes of Simulation](#modes-of-simulation)
+      - [Plug-in Protocol Adapters](#plug-in-protocol-adapters)
   - [Documentation](#documentation)
     - [Simulation Bridge](#simulation-bridge-1)
     - [Matlab Agent](#matlab-agent)

agents/matlab/.pylintrc

@@ -577,12 +577,4 @@ max-returns=6
 max-statements=50
 
 # Minimum number of public methods for a class (see R0903).
-min-public-methods=1
-
-
-[EXCEPTIONS]
-
-# Exceptions that will emit a warning when being caught. Defaults to
-# "BaseException, Exception".
-overgeneral-exceptions=BaseException,
-                       Exception
+min-public-methods=1

agents/matlab/README.md

@@ -3,9 +3,10 @@
 The MATLAB Agent is a Python-based connector designed to interface with MATLAB simulations through various methods. It provides the following functionalities:
 
 - **Batch Simulation**: Executes predefined MATLAB routines with specified input parameters, collecting the final results upon completion.
-- **Streaming Simulation (Agent-Based)**: Allows sending input once, with the output being received in real-time during the simulation.
+- **Streaming Simulation**: Executes MATLAB simulations where input parameters are sent once at the beginning, and results are transmitted continuously in real-time as the simulation progresses.
+- **Interactive Simulation**: Enables bidirectional communication with MATLAB during simulation execution, allowing continuous exchange of data, both input parameters and output results flow in real-time throughout the simulation process.
 
-The MATLAB Agent is primarily built to integrate with the Simulation Bridge but can also be utilized by external systems via RabbitMQ exchange methods. Communication parameters and other settings must be defined in the YAML-based configuration file.
+The MATLAB Agent is primarily built to integrate with the Simulation Bridge [_sim_bridge_](../../README.md) but can also be utilized by external systems via RabbitMQ exchange methods. Communication parameters and other settings must be defined in the YAML-based configuration file.
 
 <div align="center">
   <img src="matlab_agent/images/structure.png" alt="MATLAB Agent Structure" width="600" style="border: 1px solid #ddd; border-radius: 4px; padding: 5px;">
@@ -183,8 +184,9 @@ logging:
   file: logs/matlab_agent.log # The file path where logs will be stored.
 
 tcp:
-  host: localhost # The hostname or IP address for TCP communication.
-  port: 5678 # The port number for TCP communication.
+  host: localhost # Host for receiving input stream
+  input_port: 5679 # Port for receiving input stream
+  output_port: 5678 # Port for output stream
 
 response_templates:
   success:
@@ -246,7 +248,8 @@ This command creates the following structure in your current directory (existing
 ├── config.yaml                 # Agent configuration settings
 ├── SimulationBatch.m           # Template for batch simulations
 ├── SimulationStreaming.m       # Template for streaming simulations
-├── SimulationWrapper.m         # MATLAB class for easy communication with the MATLAB Agent during streaming simulations
+├── SimulationWrapperStreaming.m  # MATLAB class for streaming simulations
+├── SimulationWrapperInteractive.m  # MATLAB class for interactive simulations
 └── client/
   ├── simulation.yaml         # Example simulation request payload
   ├── use.yaml                # Client configuration file
@@ -292,16 +295,16 @@ Example output:
 
 ```bash
 dist/
-├── matlab_agent-0.2.0-py3-none-any.whl
-└── matlab_agent-0.2.0.tar.gz
+├── matlab_agent-0.3.0-py3-none-any.whl
+└── matlab_agent-0.3.0.tar.gz
 ```
 
 ### Verifying the Package (Optional but Recommended)
 
 You can verify that the package works by installing it locally:
 
 ```bash
-pip install dist/matlab_agent-0.2.0-py3-none-any.whl
+pip install dist/matlab_agent-0.3.0-py3-none-any.whl
 ```
 
 Then, run the command defined in the script:
@@ -315,7 +318,7 @@ matlab-agent
 When you modify the code and want to release a new version, increment the version number in `pyproject.toml`:
 
 ```toml
-version = "0.3.0"
+version = "0.4.0"
 ```
 
 Then rebuild the package:
@@ -349,6 +352,7 @@ Inside this folder, you'll find:
 - `use.yaml` — Configuration file for the communication protocol (e.g., RabbitMQ settings)
 - `simulation.yaml` — The simulation request payload that will be sent to the MATLAB Agent
 - `use_matlab_agent.py` — Python script to send the request and receive the results
+- `use_matlab_agent_interactive.py` — Python script to interact with the MATLAB Agent in real-time
 
 For detailed instructions on how to configure and use the client, refer to the [Use Matlab Agent](./matlab_agent/resources/README.md) in the `agents/matlab/matlab_agent/resources/` folder.
 

agents/matlab/matlab_agent/__version__.py

@@ -1 +1 @@
-__version__ = "0.2.0"
+__version__ = "1.0.0"

agents/matlab/matlab_agent/api/simulation.yaml.template

@@ -14,13 +14,18 @@ simulation:
   # Options:
   #   - 'batch': runs the simulation in batch mode, where results are returned only after the entire computation is complete.
   #   - 'streaming': runs the simulation in streaming mode, providing real-time updates at each computation step.
+  #   - 'interactive': same as 'streaming', where you need to provide a continuous stream of inputs and outputs.
 
   file: SimulationStreaming.m
   # The name of the MATLAB script or function file to execute for this simulation.
 
   inputs:
     # Input variables to be passed to the simulation.
-    # Customize these key-value pairs as needed for your specific simulation.
+    # If the simulation type is 'interactive', it is mandatory to specify 'stream_source' to indicate the source of the input stream.
+    # stream_source: The source of the input stream, e.g., RabbitMQ, which streams real-time input data to the simulation.
+    # This is required for interactive simulations.
+    stream_source: # Source of the input stream, typically RabbitMQ for streaming mode.
+
     i1: ..
     i2: ..
     i3: ..

agents/matlab/matlab_agent/config/config.yaml.template

@@ -33,7 +33,8 @@ performance:
 
 tcp:
   host: localhost
-  port: 5678
+  input_port: 5679
+  output_port: 5678
 
 response_templates:
   success:

agents/matlab/matlab_agent/docs/README.md

@@ -58,14 +58,14 @@ An Streaming simulation is designed to receive a predefined input configuration
 
 ### Streaming Requirements
 
-For this type of simulation, you must use the `SimulationWrapper` class, which should be placed in the same folder as the `Simulation.m` file. The `SimulationWrapper.m` handles the TCP/IP connection and communication with the MATLAB agent script.
+For this type of simulation, you must use the `SimulationWrapperStreaming` class, which should be placed in the same folder as the `SimulationStreaming.m` file. The `SimulationWrapperStreaming.m` handles the TCP/IP connection and communication with the MATLAB agent script.
 
 The simulation logic must be entirely contained within the main function, defined at the top level as `Simulation()`. This function is responsible for managing both inputs and outputs in the following format:
 
 ```matlab
 function Simulation()
   % 🔌 Initialize the wrapper
-  wrapper = SimulationWrapper();
+  wrapper = SimulationWrapperStreaming();
 
   % Receive input from the MATLAB agent (via JSON)
   inputs = wrapper.get_inputs();
@@ -94,3 +94,54 @@ These files provide reference implementations to help you structure your simulat
 #### Notes
 
 No additional files are handled. All data is transmitted exclusively through the TCP socket.
+
+---
+
+## Interactive Simulation
+
+An interactive simulation continuously exchanges data with the MATLAB Agent. The MATLAB code reacts to new input frames and can send updated outputs at any time during execution. Unlike batch or streaming modes, the simulation remains active while new frames arrive asynchronously.
+
+Use the `SimulationWrapperInteractive` class located alongside your `InteractiveSimulation.m` file. This wrapper manages two TCP connections:
+
+1. **Output stream** – sends simulation results to the MATLAB Agent.
+2. **Input stream** – receives new frames coming from the message broker.
+
+### Interactive Flow
+
+1. **Instantiate the wrapper**
+
+   ```matlab
+   wrapper = SimulationWrapperInteractive();
+   ```
+
+2. **Retrieve initial parameters**
+   Before entering the main loop the simulation can pull a first packet of inputs provided during the handshake.
+
+   ```matlab
+   init_data = wrapper.get_initial_inputs();
+   % ... initialise simulation state using init_data ...
+   ```
+
+3. **Main loop**
+   Continuously poll for new frames, update the state and emit outputs.
+
+   ```matlab
+   while true
+      data_in = wrapper.get_input();
+      if ~isempty(data_in)
+          % ... update simulation state ...
+          wrapper.send_output(struct('inputs', data_in));
+      end
+      pause(0.01); % small delay to avoid busy waiting
+   end
+   ```
+
+4. **Finalisation**
+   When the simulation ends, optionally call wrapper.send_completed() and clean up any resources.
+   ```matlab
+    wrapper.send_completed();
+   ```
+
+The corresponding API payload must specify `inputs.stream_source` with a RabbitMQ URL pointing to the topic where input frames will be published.
+
+Refer to `examples/interactive-simulation` for a full example.

agents/matlab/matlab_agent/docs/examples/interactive-simulation/InteractiveSimulation.m

@@ -0,0 +1,82 @@
+function InteractiveSimulation()
+    % INTERACTIVESIMULATION  Interactive demo with frame validation.
+    %   It processes valid telemetry (t, x, y, vx, vy) and sends an error packet
+
+    wrapper = SimulationWrapperInteractive();
+    init = wrapper.get_initial_inputs();  % handshake parameters
+
+    REQUIRED = init.REQUIRED; % required fields in the input frame
+    PAUSE_IO = init.PAUSE_IO; % pause to avoid spin-lock (s)
+    MAX_STEPS = init.MAX_STEPS; % number of iterations before termination
+
+    last_input = struct();  % cache of the last valid frame
+    last_time  = [];        % timestamp of the last valid frame
+
+    step = 0;               % iteration counter
+
+    %% ───── main loop
+    while step < MAX_STEPS
+        data_in = wrapper.get_input();  % receive data from the Python client
+
+        % 1️⃣ Frame validation
+        disp('📥 Received frame:');
+        disp(data_in);  % log the incoming frame
+
+        invalid_reason = "";
+        if isempty(data_in)
+            invalid_reason = "empty frame";
+        elseif ~isstruct(data_in)
+            invalid_reason = "not a struct";
+        elseif ~all(isfield(data_in, REQUIRED))
+            missing = REQUIRED(~isfield(data_in, REQUIRED));
+            invalid_reason = "missing fields: " + strjoin(missing, ",");
+        end
+
+        % 2️⃣ Always generate an output
+        if invalid_reason ~= ""
+            disp(['❌ Invalid frame: ', invalid_reason]);
+            err_out = struct( ...
+                "status", "invalid", ...
+                "reason", invalid_reason, ...
+                "timestamp", posixtime(datetime("now")) ...
+            );
+            wrapper.send_output(err_out);
+        else
+            % 3️⃣ If the frame is valid and new, process it
+            if isempty(last_input) || ~isequal(data_in, last_input)
+                t  = data_in.t;   x  = data_in.x;   y  = data_in.y;
+                vx = data_in.vx;  vy = data_in.vy;
+
+                if isempty(last_time)
+                    dt = 0;
+                else
+                    dt = t - last_time;
+                end
+
+                x_next = x + vx * dt;
+                y_next = y + vy * dt;
+
+                ok_out = struct( ...
+                    "status", "ok", ...
+                    "predicted", struct("x_next", x_next, "y_next", y_next), ...
+                    "misc", struct( ...
+                        "distance_from_origin", hypot(x, y), ...
+                        "timestamp", posixtime(datetime("now")) ...
+                    ) ...
+                );
+
+                disp('📤 Output sent:');
+                disp(ok_out);
+                wrapper.send_output(ok_out);
+
+                last_input = data_in;
+                last_time  = t;
+            end
+        end
+
+        step = step + 1;
+        pause(PAUSE_IO);
+    end
+
+    wrapper.send_completed();
+end