doc: Added info about files, prototypes and LLMs platforms in README.md

Author: geoffroy-noel-ddh

README.md

@@ -2,24 +2,45 @@
 
 KDL components for the Algorithmic Justice research project.
 
-[Experimental interface](https://kingsdigitallab.github.io/algorithmic-justice/nlpui.html).
+[Experimental interfaces](https://kingsdigitallab.github.io/algorithmic-justice/nlpui.html).
 
-# Requirements
+# Interfaces
 
-The interface requires an API Key to interact with large language models (LLM) hosted by KCL e-Research (ER).
+The web application has three prototypes, each one on a separate screen.
 
-If you are a KDL member of staff you can generate your own API Key like this:
-1. Go to [the LLM platform hosted by ER](https://ai.create.kcl.ac.uk/)
-2. Click the account icon in the top right corner of the screen: a drop down menu appears
-3. Click 'Settings' in the menu; a Setting model appears
-4. Click Account on the left hand side
-5. click "Generate New API Key" near the bottom of the modal
-6. copy the key and paste it in a private place for future referrence. Do not share it with anyone
-7. Now you can paste that API Key in the Settings Tab of [the natural language processing application](https://kingsdigitallab.github.io/algorithmic-justice/nlpui.html) developped by KDL
+1. A **questionnaire** about a driver's statement that can be answered by a magistrate or a large language model (LLM).
+2. A **highlighter** to ask a LLM to highlight passages in the driver statement which are relevant to the users query.
+3. An **integrated prototype** that lets a magistrate select cases to consult the automated answers to predefined questions from a LLM and the resulting fine calculated with an algorithm from the answers and the driver's weekly wage.
 
-If everything goes well, you can return to the 'Highlighter' tab and ask a question to the language model.
+# Interacting with LLMs
 
-# Local set up
+By default the application use **cached** responses from LLMs. 
+
+If you want to prompt live LLMs, 
+you'll need to select the URL of an LLM inference platform in the setting screen 
+and paste your API token.
+
+If your machine has a GPU, 
+you can install and use a [local Ollama platform](https://ollama.com/), 
+usually at `http://localhost:11434/v1`. After installation, type 
+`ollama pull qwen3.5:4b` to download that particular LLM. 
+Check the [Ollama models list on their site](https://ollama.com/search) 
+to see what else you can download.
+
+You can use [KCL e-Research (ER) AI Hub](https://ai.create.kcl.ac.uk/) 
+if you are a KCL staff member.
+That platform URL is `https://api.ai.create.kcl.ac.uk/v1`.
+Note that you will need to access it through ER VPN and 
+[create your own API Key](https://ai.create.kcl.ac.uk/dashboard/api-keys/create):
+
+Another simple option is to use the [OpenRouter platform](https://openrouter.ai/) 
+which is a third-party service that offers a large number of paid-for and free models.
+All you need is to create an account and an API key.
+
+If everything goes well, you can return to the 'Highlighter' or 'Highlighter'
+tab and ask a question to the language model.
+
+# Running the application on your local machine
 
 First clone this repository.
 
@@ -37,3 +58,14 @@ cd app
 npm start
 ```
 
+Then visit the index page at `http://localhost:3000` to access the prototypes.
+
+# Data and tools
+
+* [`settings.mjs`](app/settings.mjs): application-wide settings, such as API URLs and prompt templates for the LLM. `SETTINGS` is a special structure which values can be temporarily edited in the browser on the settings tab of the first prototype before prompting the LLMs.
+
+* [`app-data.json`](app/data/app-data.json): contains the questionnaire, with algorithmic effect of each yes answer, the sample cases, and buckets indexed by the sum of effects from questionnaire and the the ratio applied to the monthly wage to calcualte the fine.
+
+* [`responses.json`](app/data/responses.json): contains all the cached responses from the LLM for every combination of question and case in the questionnaire. 
+
+* [`cache.mjs`](tools/cache.mjs): a command line tool to get live responses from the LLM for every combination of question and case in the questionnaire and save them in `responses.json`.

app/index.html

@@ -11,7 +11,10 @@
     <h1>App Index</h1>
   </main>
   <p>
-    <a href="nlpui.html">NPL Interface</a>
+    <a href="nlpui.html">Questionnaire and Highlighter</a>
+  </p>
+  <p>
+    <a href="poc3.html">Integrated prototype</a>
   </p>
 </body>
-</html>   
+</html>

app/poc3.js

@@ -10,16 +10,14 @@ S explaination
 C highlights
 C summary 
 W highlights snippets
-W algorithm
+W show algorithm
 W polish interface
 
+S dedupe code (with nlpui.js)
 */
 const { createApp, nextTick } = window.Vue;
 import CachedInferenceEngine from './cached-inference-engine.mjs'
 
-const TAB_HIGHLIGHTER = 'highlighter'
-const DELAY_IN_SECONDS_FOR_CACHED_RESPONSES = 2
-
 function camelToSpaceCase(str) {
   return str.replace(/([a-z])([A-Z])/g, '$1 $2')
       .replace(/^./, (match) => match.toUpperCase());
@@ -64,7 +62,7 @@ createApp({
       isServiceWorking: false,
       questionnaire: {},
       modelsList: [],
-      areDetailsShown: true,
+      areDetailsShown: false,
     }
   },
   async mounted() {