Document all app options and clarify the tool description

README.md

@@ -14,165 +14,80 @@ short_description: Interacting with LLMs
 
 # PRISE — Privacy Risk Inference System with Explainability
 
-**A chat interface that shows you, in real time, what a language model can infer about you.**
+PRISE is a browser-based chat interface that places a transparency layer between the user and a
+conversational LLM. Alongside the model's ordinary reply, each turn is annotated to show what the
+system has learned about the user. Identifying details in the message are highlighted and labelled
+by type. Phrases that match an external record about the user are marked and traced back to their
+source. A profile card lists the demographic attributes the model can now predict, each with its
+confidence and the evidence behind it. A single risk score summarises the turn.
 
-PRISE is a browser-based chatbot that sits a transparency layer between the user and a
-conversational LLM. Alongside the model's ordinary reply, every turn is annotated with what
-the system just learned: which spans of the message are personally identifying, which spans
-link to external data about the user, and which demographic attributes have become inferable
-as a result — each with the evidence that supports it.
+[Differential privacy](https://en.wikipedia.org/wiki/Differential_privacy) can be applied on the
+user's side: before a message is sent, its content words are perturbed so that the model receives
+a noised version of the text. The conversation panel still shows what the user actually wrote, and
+a badge on the message reports how many words were substituted and at which privacy budget (ε).
 
-It is the research instrument behind a between-subjects study (N = 565) of whether
-real-time inference explanations change what people choose to disclose.
+## Usage
 
----
-
-## What it does
-
-Each conversation turn passes through four mechanisms, all rendered back into the UI:
-
-| Mechanism | What the user sees |
-|---|---|
-| **PII detection** | Identifying spans highlighted in the message, coloured by category (Identity, Contact, Location, Sensitive), with a hover tooltip giving the type and the model's confidence. |
-| **External-data linkage** | Spans that match a retrieved document from an external corpus are underlined, with a tooltip showing the matched excerpt, its similarity score, and a link to the source where one exists. |
-| **Attribute inference** | A "How the AI sees you" card giving the most probable value for six attributes — age band, gender, marital status, education, financial situation, and country — each with a probability, the lift over the population base rate, and a *Why?* tooltip quoting the evidence. |
-| **Privacy risk score** | A 0–100 score combining the inference lift, the PII count and the linkage count, with a breakdown of which component drove it. |
-
-### Two differential privacy mechanisms
+### Dependencies
 
-Both share a single ε budget and can be switched on independently of the display settings.
+Python 3.10. Install with:
 
-- **Input DP** — a RANTEXT-style exponential mechanism over word embeddings perturbs content
-  words in the message *before the model sees it*, satisfying ε-local DP per token. The chat
-  panel still displays the original wording; a badge on the bubble reports how many words were
-  substituted and at what ε, so the protection is visible without showing the user noisy text.
-- **Retrieval DP** — an exponential mechanism over document scores during retrieval, with
-  sensitivity computed empirically from the candidate pool's utility range rather than a fixed
-  constant.
+```bash
+pip install -r requirements.txt
+```
 
-Retrieval itself is hybrid: dense FAISS similarity, BM25 lexical matching, and entity matching,
-fused with reciprocal rank fusion.
+The main dependencies are Gradio, OpenAI, LangChain, FAISS, sentence-transformers and rank-bm25.
 
----
+### API keys
 
-## Quick start
+Keys are read from the environment; only the provider you intend to use is required.
 
 ```bash
-# 1. Install
-pip install -r requirements.txt
-
-# 2. Provide credentials (only the provider you intend to use is required)
 export GEMINI_API_KEY="..."         # default provider
 export OPENAI_API_KEY="..."         # optional
 export TOGETHER_API_KEY="..."       # optional
-export VALID_ACCESS_TOKEN_1="..."   # optional: gate the app behind a token
-
-# 3. Run
-python app.py
+export VALID_ACCESS_TOKEN_1="..."   # optional, gates the app behind a token
 ```
 
-The app serves on `http://localhost:7860`. Nothing is hardcoded — every key is read from the
-environment, and the app degrades gracefully when an optional one is absent.
-
-To use the app without any API calls at all — useful for inspecting the interface — start it in
-demo mode, which produces deterministic placeholder annotations:
+### Running
 
 ```bash
-python app.py --demo 1
+python app.py
 ```
 
-### Optional: social media enrichment
+The app serves on `http://localhost:7860`.
 
-Setting `--enable_social_scraping 1` lets the external-data layer pull public posts through
-[Apify](https://apify.com) instead of, or in addition to, the local corpus. It needs
-`APIFY_TOKEN` plus the actor IDs (`APIFY_X_ACTOR_ID`, `APIFY_FB_POSTS_ACTOR`,
-`APIFY_FB_PAGES_ACTOR`, `APIFY_LI_POSTS_ACTOR`, `APIFY_WEB_SCRAPER_ACTOR`). This path is
-experimental and was **not** used in the reported study.
+### Options
 
----
-
-## Configuration
-
-Every option is available both as a command-line flag and as a URL query parameter, so a
-condition can be assigned by handing a participant a link.
+Every option below is available both as a command-line flag and as a URL query parameter, so a
+configuration can be assigned via a link:
 
 ```
-http://localhost:7860/?rag=1&epsilon=20&show_pii_highlights=1&token=YOUR_TOKEN
+http://localhost:7860/?rag=1&epsilon=20&show_pii_highlights=1
 ```
 
-| Parameter | Values | Meaning |
-|---|---|---|
-| `model` | model name | Which LLM to converse with |
-| `rag` | `0` / `1` | Enable external-data linkage |
-| `epsilon` | float or `inf` | DP budget, shared by both mechanisms; `inf` disables DP |
-| `show_risk` | `0` / `1` | Show the privacy risk panel |
-| `show_pii_highlights` | `0` / `1` | Highlight PII spans in the conversation |
-| `show_rag_highlights` | `0` / `1` | Highlight external-data linkages |
-| `show_tips` | `0` / `1` | Show hover tooltips |
-| `show_dp` | `0`–`3` | When to reveal the Privacy Settings panel: never / each turn / start only / on *End conversation* |
-| `show_infr_attr_card` | `0`–`2` | When to reveal the inference card: never / each turn / on *End conversation* |
-| `show_settings` | `0` / `1` | Expose the live settings panel |
-| `scenario_mode` | `real`, `persona2`, … | Free-style, or a scripted persona with known ground-truth attributes |
-| `demo` | `0` / `1` | Placeholder annotations, no API calls |
-| `token` | string | Session access token |
-
-### Study conditions
-
-The four experimental conditions differ only in these parameters:
-
-| Condition | External data | PII highlights | DP |
+| Option | Values | Default | Meaning |
 |---|---|---|---|
-| Baseline | `rag=0` | `show_pii_highlights=0` | `epsilon=inf` |
-| PII | `rag=0` | `show_pii_highlights=1` | `epsilon=inf` |
-| PII+3P | `rag=1` | `show_pii_highlights=1` | `epsilon=inf` |
-| PII+3P+DP | `rag=1` | `show_pii_highlights=1` | `epsilon=20` |
-
----
-
-## Repository layout
-
-```
-app.py                        Gradio application: UI, all four mechanisms, logging
-create_rag_retriever.py       HybridRetriever (FAISS + BM25 + entity, RRF) and DPRetriever
-social_scrape_via_apify.py    Optional public-post retrieval via Apify
-avatars/                      Illustrative persona images for the inference card
-external corpus/              External corpora used by the linkage layer
-  corpus_extended.csv           1,000 posts: 167 by the study persona, 833 by 30 other authors
-settings/                     Local runtime configuration (not published)
-```
-
-### The external corpus
-
-`external corpus/corpus_extended.csv` is the corpus the linkage and inference layers retrieve
-against. It holds 1,000 synthetic social media posts:
-
-- **167 posts by the study persona** (Sarah Chen), carrying the ground-truth attributes the
-  profiler is evaluated against.
-- **833 posts by 30 other synthetic authors**, spanning the same attribute space the profiler
-  infers over. Several are healthcare workers, and several live in the persona's cities, so
-  retrieval cannot succeed by keying on occupation or location alone. No distractor post names
-  the persona.
-
-Columns: `Unique ID`, `First Name`, `Last Name`, `text`, `platform`, `year_joined`, `Age bin`,
-`Finance Status`, `Education`, `Locale`, `Marital Status`, `Gender`, `source`, `content_type`,
-`is_persona`.
-
-Every post is synthetic. No real person's data is included.
-
----
-
-## Logging
-
-When an access token is supplied, each turn appends a row to a per-participant CSV: the message
-and the model's reply, the DP-perturbed text actually sent to the model, detected PII, external
-linkages, per-attribute inference probabilities and lifts, and the risk score with its
-breakdown. This is what the analysis pipeline consumes.
-
----
-
-## Notes
-
-- Retrieval indices are rebuilt from their component pickles at startup rather than unpickled
-  whole, so they stay portable across environments.
-- Every persona, corpus and conversation shipped here is synthetic.
-- License: CC BY-ND 4.0.
+| `model` | model name | `Gemini-2.5-Flash` | LLM used for the conversation |
+| `rag` | `0` / `1` | `1` | Link the conversation against the external corpus |
+| `epsilon` | float or `inf` | `inf` | Privacy budget for the perturbation; `inf` disables it |
+| `show_risk` | `0` / `1` | `1` | Show the privacy risk panel |
+| `show_tips` | `0` / `1` | `1` | Show hover tooltips |
+| `show_pii_highlights` | `0` / `1` | `1` | Highlight identifying details |
+| `show_rag_highlights` | `0` / `1` | `1` | Highlight matches against external data |
+| `show_settings` | `0` / `1` | `0` | Show the live settings panel |
+| `show_dp` | `0`–`3` | `1` | When to show the privacy settings panel: never, after each turn, at the start only, or when the conversation ends |
+| `show_infr_attr_card` | `0`–`2` | `1` | When to show the inferred-attributes card: never, after each turn, or when the conversation ends |
+| `enable_social_scraping` | `0` / `1` | `0` | Retrieve public social media posts as external data (experimental) |
+| `show_social_scraping` | `0` / `1` | `0` | Show the social media control in the interface |
+| `show_upload_data` | `0` / `1` | `0` | Show the control for uploading a custom corpus |
+| `scenario_mode` | `real`, `persona1`, `persona2` | `real` | Free-style conversation, or a scripted persona |
+| `demo` | `0` / `1` | `0` | Run the interface without making API calls |
+
+`token` is accepted as a URL parameter only, and carries the session access token.
+`--retriever_path` (an alternative retriever pickle) and `--port` (default `7860`) are
+command-line flags only.
+
+## License
+
+CC BY 4.0.