Update README and deployment documentation

.gitignore

@@ -2,3 +2,7 @@
 .venv/
 __pycache__/
 *.pyc
+.playwright-mcp/
+hf-chatkit-domain-error.png
+workflow_agent builder.png
+pharma_complaints_agentic_en rev 4.drawio.png

README.md

@@ -1,6 +1,6 @@
 ---
 title: MIT Summer 2026 Pharma Agent
-emoji: 🧪
+emoji: 🧬
 colorFrom: blue
 colorTo: indigo
 sdk: docker
@@ -8,210 +8,200 @@ app_port: 7860
 pinned: false
 ---
 
-# MIT_AI_System_Architecture_LLMs_PharmaTeam
+# MIT AI System Architecture LLMs Pharma Team
 
-This guide explains how to run the local demo and what the updated website now shows.
+FastAPI website for a classroom pharmacovigilance and complaints demo. The site presents an 8-agent workflow, scenario lab, governance map, downloadable architecture diagrams, and a live OpenAI ChatKit conversation connected to a published Agent Builder workflow.
 
-Repository: `lmbarak01/MIT_AI_System_Architecture_LLMs_PharmaTeam`
+## Features
 
-## 1) Prerequisites
+- 8-agent pharmacovigilance, product-information, and claims/returns architecture.
+- Scenario lab with canonical use cases and prompt prefill into ChatKit.
+- Workflow state map for route and governance visualization.
+- Download buttons for the original architecture images:
+  - `static/agent-builder-multiagent-schema.png`
+  - `static/pharma_complaints_agentic_en_rev_4_sin_fondo.png`
+- Live ChatKit component backed by `POST /api/chatkit/session`.
+- Docker configuration for Hugging Face Spaces.
 
-- Python 3.11 or higher
-- Internet connection (the app uses OpenAI API and the ChatKit CDN)
-- Valid OpenAI credentials:
+## Requirements
+
+- Python 3.11 or higher for local development.
+- Internet access for the OpenAI API and ChatKit CDN.
+- Published OpenAI Agent Builder workflow.
+- OpenAI credentials:
   - `OPENAI_API_KEY`
   - `WORKFLOW_ID`
-  
-## 2) Go to the project folder
+- Git LFS for PNG assets when pushing to Hugging Face.
+
+## Local Setup
 
-Open PowerShell and run:
+Create and activate a virtual environment:
 
 ```powershell
-cd "C:\Users\leand\OneDrive\Documents\Pharma IA\MIT Agent Builder"
+python -m venv .venv
+.\.venv\Scripts\Activate.ps1
 ```
 
-## 3) Create and activate a virtual environment
-
-Create the virtual environment:
+Install dependencies:
 
 ```powershell
-python -m venv .venv
+pip install -r requirements.txt
 ```
 
-Activate it:
+Create `.env` from `.env.example`:
 
-```powershell
-.\.venv\Scripts\Activate.ps1
+```env
+OPENAI_API_KEY=sk-proj-...
+WORKFLOW_ID=wf_...
 ```
 
-If PowerShell blocks script execution:
+Run the app locally:
 
 ```powershell
-Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass
-.\.venv\Scripts\Activate.ps1
+uvicorn app:app --reload --port 8000
 ```
 
-## 4) Install dependencies
-
-With the environment activated:
+Open:
 
-```powershell
-pip install -r requirements.txt
+```text
+http://127.0.0.1:8000
 ```
 
-## 5) Configure environment variables
+Health check:
+
+```text
+http://127.0.0.1:8000/health
+```
 
-Create a `.env` file in the project root (you can copy `.env.example`) with:
+Expected response:
 
-```env
-OPENAI_API_KEY=sk-proj-...
-WORKFLOW_ID=wf_...
+```json
+{"status":"ok"}
 ```
 
-Notes:
-- `WORKFLOW_ID` must match a published workflow.
-- The backend always uses the latest published version for that workflow ID.
-- The API key is used only by the backend and is never exposed to the browser.
+## Hugging Face Space Deployment
 
-## 6) Run the application
+This repository is configured as a Docker Space through the README metadata and `Dockerfile`.
 
-From the same folder:
+### 1. Create or Use a Space
 
-```powershell
-uvicorn app:app --reload --port 8000
-```
+Create a public Hugging Face Space with:
 
-Open in your browser:
-
-`http://localhost:8000`
+- SDK: `Docker`
+- Visibility: `Public`
+- Repository name example: `pharma-IA/MIT_Summer_2026`
 
-## 7) Quick verification
+The deployed direct app URL will follow this pattern:
 
-- Backend health:
-  - `http://localhost:8000/health`
-  - Expected response: `{"status":"ok"}`
-- ChatKit session:
-  - The frontend automatically calls `POST /api/chatkit/session`.
+```text
+https://<owner>-<space-name>.hf.space
+```
 
-## 8) Website features
+For this project:
 
-The updated website now includes:
+```text
+https://pharma-ia-mit-summer-2026.hf.space
+```
 
-1. Hero and scope overview
-- Frames the demo as an 8-agent pharmacovigilance and complaints workflow.
-- Highlights the three routing paths and the 15-day EU BfArM PV deadline.
+### 2. Configure Secrets
 
-2. Updated agent architecture
-- Shows the latest 8 agents now represented on the site:
-  - Agent 1: Intake and Normalization
-  - Agent 2: Classifier and Router
-  - Agent 3: Economic Flow
-  - Agent 4: Product Information Flow
-  - Agent 5: PV Triage
-  - Agent 6: Interview and Follow-up
-  - Agent 7: HITL Gatekeeper
-  - Agent 8: Q&A User
-  - Agent 8 is the loop that keeps asking for missing PV follow-up data, especially a contact email, until follow-up can continue.
+In the Hugging Face Space settings, add these as **Secrets**:
 
-3. Three routing paths
-- Economic claims and returns
-- Product information
-- Pharmacovigilance
+```text
+OPENAI_API_KEY
+WORKFLOW_ID
+```
 
-4. Governance layer
-- Security guardrails at intake
-- Grounding expectations for product-information answers
-- Output moderation before closure
-- Mandatory HITL handling for serious safety cases
+Do not commit `.env`. Hugging Face reads secrets from runtime environment variables.
 
-5. Scenario Lab
-- Replaced the old mixed examples with the canonical `Use Case Guide` scenarios:
-  - `UC-1` crushed shipment economic claim
-  - `UC-2` renal dosing product-information question
-  - `UC-3` serious adverse-event pharmacovigilance case
-  - `UC-4` serious adverse-event case where the patient already provides `pv_test@gmail.com`, so Agent 8 does not activate
-- Each scenario shows:
-  - expected route
-  - expected decision
-  - workflow evidence
-  - operational actions
-- The prompt can still be prefilled into ChatKit.
+### 3. Allowlist the Space Domain in OpenAI
 
-6. Workflow State Map
-- Educational state view of:
-  - input guardrail
-  - intake
-  - triage
-  - specialist handling
-  - follow-up / Q&A
-  - output guardrail / HITL
-  - outcome
+ChatKit production domains must be allowlisted in OpenAI Platform.
 
-7. Live Chat (Managed Workflow)
-- Embedded ChatKit component
-- Real conversation connected to the OpenAI workflow via `WORKFLOW_ID` (latest published version).
-- Backend creates a secure session and returns `client_secret`
+Add the exact direct Space domain:
 
-## 9) Workflow version behavior
+```text
+https://pharma-ia-mit-summer-2026.hf.space
+```
 
-The backend always creates ChatKit sessions with:
-- `WORKFLOW_ID` only
+OpenAI settings:
 
-OpenAI resolves that to the latest published workflow version.
+```text
+https://platform.openai.com/settings/organization/security/domain-allowlist
+```
 
-## 10) Important implementation note
+Use the direct `.hf.space` URL for testing the app. The `huggingface.co/spaces/...` page embeds the app in an iframe and may behave differently for external widgets.
 
-The website update does not change the OpenAI workflow invocation logic.
+### 4. Push to Hugging Face
 
-The following remain unchanged:
-- `POST /api/chatkit/session` in `app.py`
-- the session payload shape sent to `/v1/chatkit/sessions`
-- workflow latest-version behavior
-- the ChatKit initialization flow in `static/app.js`
+Add the Space remote:
 
-## 11) Common issues
+```powershell
+git remote add hfspace https://user:<HF_TOKEN>@huggingface.co/spaces/pharma-IA/MIT_Summer_2026
+```
 
-- Error: Missing required environment variable(s)
-  - Check that `.env` exists and contains both required values.
+Install and initialize Git LFS if needed:
 
-- Error 404 workflow not found
-  - Confirm `WORKFLOW_ID` in OpenAI Agent Builder.
-  - Verify it belongs to the same project as the API key.
+```powershell
+git lfs install
+git lfs track "*.png"
+git add .gitattributes
+```
 
-- Chat does not load in frontend
-  - Check internet access (ChatKit CDN and OpenAI API).
-  - Check browser console and Uvicorn logs.
-
-## 12) Stop the application
-
-- In terminal: `Ctrl + C`
-- To exit the virtual environment:
+Push:
 
 ```powershell
-deactivate
+git push hfspace main
+```
+
+Hugging Face will rebuild the Docker Space automatically.
+
+## Runtime Behavior
+
+The backend creates ChatKit sessions with:
+
+```json
+{
+  "workflow": {"id": "WORKFLOW_ID"},
+  "user": "stable_user_id"
+}
 ```
 
-## 13) Project file tree and description
+OpenAI resolves the workflow ID to the latest published workflow version. No workflow version is hardcoded in this repository.
+
+## Troubleshooting
+
+- `Missing required environment variable(s)`: set `OPENAI_API_KEY` and `WORKFLOW_ID` locally or in HF Space Secrets.
+- `workflow not found`: confirm the workflow is published and belongs to the same OpenAI project as the API key.
+- Chat area is blank in HF: open the direct `.hf.space` URL and confirm that domain is in the OpenAI domain allowlist.
+- PNG push rejected by Hugging Face: use Git LFS for image assets.
+- Local CSS looks stale: hard refresh the browser with `Ctrl+F5`.
+
+## Project Tree
 
 ```text
 MIT Agent Builder/
 |-- app.py
+|-- Dockerfile
 |-- requirements.txt
 |-- .env.example
-|-- .gitignore
+|-- .gitattributes
 |-- README.md
 `-- static/
     |-- index.html
     |-- styles.css
-    `-- app.js
+    |-- app.js
+    |-- agent-builder-multiagent-schema.png
+    `-- pharma_complaints_agentic_en_rev_4_sin_fondo.png
 ```
 
-- `app.py`: FastAPI backend. Serves the site, exposes `/health`, and creates ChatKit sessions via OpenAI.
-- `requirements.txt`: Python dependencies required to run the app.
-- `.env.example`: Template for required environment variables.
-- `.gitignore`: Ignores local environment and cache files.
-- `README.md`: Setup, run, troubleshooting, and updated site description.
-- `static/index.html`: Main web page structure and content sections.
-- `static/styles.css`: Visual styling, layout, and responsive behavior.
-- `static/app.js`: Scenario selector, workflow-state rendering, and ChatKit initialization.
+## File Roles
 
+- `app.py`: FastAPI backend. Serves the site, health check, static assets, and ChatKit session endpoint.
+- `Dockerfile`: Runtime image for Hugging Face Docker Spaces.
+- `requirements.txt`: Python dependencies.
+- `.env.example`: Local environment template.
+- `.gitattributes`: Git LFS tracking for PNG assets.
+- `static/index.html`: Website content and layout.
+- `static/styles.css`: Visual styling and responsive behavior.
+- `static/app.js`: Scenario logic, ChatKit initialization, and error handling.

static/app.js

@@ -108,7 +108,7 @@ const scenarios = [
     actions: [
       "Run ICSR minimum-criteria and seriousness screening.",
       "Ask patient follow-up questions and capture missing safety fields.",
-      "Escalate through the HITL gatekeeper and flag the 15-day BfArM timeline.",
+      "Escalate through the HITL gatekeeper and flag the applicable regulatory timeline.",
     ],
     stepStates: {
       input: "active",