doc: update README.md

README.md

@@ -1,21 +1,27 @@
-# Agent Explanation
+# A Multi-Level Explainability Framework for BDI Multi Agent Systems - Narrative Generator Component
 
-Explanation component for _a multi-level framework for BDI Multi-Agent Systems_.
+This repository contains a prototype implementation of the **Narrative Generator** for our research project _A Multi-Level Explainability Framework for BDI Multi Agent Systems_. You access directly the deployed web application **[here](https://yan-elena.github.io/agent-explanation/)** without installing anything.
 
-Agent-Explanation is a repository that provides the explanation component for inspecting and explaining the behaviour of a BDI multi-agent system. The framework's objective is to provide a multi-level vision of explainability that encompasses both low-level aspects for debugging purposes for developers and high-level aspects for exploring and understanding the system's behaviour for end-users.
+## The Multi-Level Explainability Framework
+<img src="https://github.com/yan-elena/agent-explanation/assets/78790594/d77f7f57-79fc-4a60-86f8-1410f2c0e7c7" width=50%>
 
-You can find the deployed web application **[here](https://yan-elena.github.io/agent-explanation/)** so you can use it without installing anything.
+This framework aims to address the problem of AI-systems explainability at multiple levels: implementation, design, and domain levels. In particular, the idea is to use the logs of the JaCaMo BDI Multi-Agent System produced by the **[Logger Component](https://github.com/yan-elena/agent-logging)** and automatically extract narratives at multiple levels.
 
-For generating explanations concerning your agent system, you must use the **[logging component](https://github.com/yan-elena/agent-logging)** of the framework and generate log files.
-Once the log files have been obtained, they can be loaded into the web application.
+The primary levels of abstraction identified in this study are as follows:
+- The **Implementation Level**: a detailed narrative closely related to the Agent and Multi-Agent Systems useful for debugging and testing.
+- The **Design Level**: a level that describes the agent behavior regardless of its implementation useful for analysis and verification.
+- The **Domain Level**: a high-level narrative that explains the behavior with reference to the domain and requirements of the system. (work in progress)
 
-You can also use the example files in the `/examples` folder to visualise the result and try the multi-level explanation.
+## Usage
 
-## Multi-level Explainability
-<img src="https://github.com/yan-elena/agent-explanation/assets/78790594/d77f7f57-79fc-4a60-86f8-1410f2c0e7c7" width=50%>
+Following the instructions presented in the **[Logger Component](https://github.com/yan-elena/agent-logging)** to generate the `log files` of your JaCaMo project.
+Once the log files have been obtained, they can be loaded in the Home Page:
 
-The primary levels of abstraction identified in this study are as follows:
-- The **Implementation Level**: a detailed narrative closely related to the Agent and Multi-Agent Systems for debugging and testing - for developers.
-- The **Design Level**: a level that describes the agent behaviour regardless of its implementation for analysis and verification - for designers.
-- The **Domain Level**: a high-level narrative that explains the behaviour with reference to the domain and requirements of the system - for users and domain experts.
+<img src="https://github.com/yan-elena/agent-explanation/assets/78790594/2f3ba3c4-bd31-41ea-bd5f-ff588ee9824f" width=50%>
+
+At this point, you can navigate through the generated narratives at multiple levels for each agent in the system.
+
+<img src="https://github.com/yan-elena/agent-explanation/assets/78790594/ddfd0ca2-1475-4119-8c1a-c7ce318e5ed4" width=50%>
 
+## Examples
+You can also use the example log files in the `/examples` folder to visualize the result and try the multi-level explanation.