Upload 10 files

README.md

@@ -1,19 +1,86 @@
+
+# Persona Feedback Simulation App
+
+A **Streamlit-based app** for generating realistic persona feedback using the OpenAI API.  
+This version includes production-ready improvements such as modular design, authentication support, cloud storage, and monitoring hooks.
+
 ---
-title: Feedback Simulator
-emoji: 🚀
-colorFrom: red
-colorTo: red
-sdk: docker
-app_port: 8501
-tags:
-- streamlit
-pinned: false
-short_description: AI-powered persona feedback simulator
+
+## Features
+
+- **Persona management**: Create, edit, and simulate personas.
+- **OpenAI API integration**: Generate realistic feedback automatically.
+- **Database support**: Optional Supabase or SQLite backend.
+- **Secure API key handling**: Avoid exposing secrets.
+- **Modular codebase**: Separate app, utilities, and database logic.
+- **Deployment ready**: Works on Streamlit Cloud or GitHub Codespaces.
+- **Monitoring hooks**: Metrics and logging for production use.
+
+
 ---
 
-# Welcome to Streamlit!
+## Setup & Installation
+
+1. **Clone the repository**
+
+```bash
+git clone https://github.com/yourusername/persona-feedback-app.git
+cd persona-feedback-app
+```
+
+2. **Create a virtual environment**
+
+```bash
+python -m venv venv
+source venv/bin/activate   # macOS/Linux
+venv\Scripts\activate     # Windows
+```
+
+3. **Install dependencies**
+
+```bash
+pip install -r requirements.txt
+```
+
+4. **Set your OpenAI API key**
+
+```bash
+export OPENAI_API_KEY="your_api_key_here"   # macOS/Linux
+setx OPENAI_API_KEY "your_api_key_here"     # Windows
+```
+
+---
+
+## Running the App
+
+```bash
+streamlit run app.py
+```
+
+- Open the browser link provided by Streamlit.
+- Create or select personas, input features, and generate feedback.
+
+---
+
+## Testing
+
+Unit tests use **pytest** and can be run with:
+
+```bash
+pytest
+```
+
+- Tests cover:
+  - Response generation (small, empty, large input)
+  - Persona management
+  - Concurrency handling
+
+**Tip:** You can mock OpenAI responses for offline testing.
+
+---
 
-Edit `/src/streamlit_app.py` to customize this app to your heart's desire. :heart:
+## Deployment
 
-If you have any questions, checkout our [documentation](https://docs.streamlit.io) and [community
-forums](https://discuss.streamlit.io).
+- **Streamlit Cloud**: Push your repo and configure the secrets (API keys) in the app settings.
+- **GitHub Codespaces**: Works in the dev container with all dependencies installed.
+- **Optional database**: Use SQLite for local testing or Supabase for cloud storage.

ai_helpers.py

@@ -0,0 +1,96 @@
+import openai
+import logging
+import time
+from typing import List, Dict, Optional
+from config import OPENAI_DEFAULTS, REPORT_DEFAULTS
+from utils import build_sentiment_summary, extract_persona_response  # utils in same package
+
+log = logging.getLogger(__name__)
+
+def build_prompt(personas: List[Dict], feature_inputs: Dict, conversation_history: str = "") -> str:
+    """Construct a compact prompt for the chat model."""
+    persona_block = "\n".join(
+        f"- {p['name']} ({p['occupation']}, {p.get('location','')}, Tech: {p.get('tech_proficiency','')})"
+        for p in personas
+    )
+    feature_block = ""
+    for k, v in feature_inputs.items():
+        vtxt = ", ".join(v) if isinstance(v, list) else (v or "")
+        feature_block += f"{k}:\n{vtxt}\n\n"
+
+    prompt = f"""
+Personas:
+{persona_block}
+
+Features:
+{feature_block}
+
+Simulate a realistic persona conversation. Each persona should reply in 2-3 sentences.
+Use this template for each persona:
+
+[Persona Name]:
+- Response: <what they say>
+- Reasoning: <why>
+- Confidence: <High|Medium|Low>
+- Suggested follow-up: <question>
+
+"""
+    if conversation_history:
+        prompt += f"\nPrevious conversation:\n{conversation_history}\nContinue naturally."
+    return prompt.strip()
+
+def generate_response(feature_inputs: Dict, personas: List[Dict], history: str, model: str) -> str:
+    """Single-shot OpenAI call (may raise exceptions)."""
+    prompt = build_prompt(personas, feature_inputs, history)
+    resp = openai.chat.completions.create(
+        model=model,
+        messages=[
+            {"role": "system", "content": "You are an AI facilitator for a virtual focus group."},
+            {"role": "user", "content": prompt}
+        ],
+        temperature=OPENAI_DEFAULTS.get("temperature", 0.8),
+        max_tokens=OPENAI_DEFAULTS.get("max_tokens", 1500)
+    )
+    return resp.choices[0].message.content.strip()
+
+def generate_response_with_retry(feature_inputs: Dict, personas: List[Dict], history: str, model: str, retries: int = 3, backoff: float = 1.0) -> str:
+    """Call OpenAI with retries and exponential backoff."""
+    for attempt in range(retries):
+        try:
+            return generate_response(feature_inputs, personas, history, model)
+        except Exception as e:
+            log.exception("OpenAI call failed (attempt %s): %s", attempt + 1, e)
+            if attempt + 1 < retries:
+                time.sleep(backoff * (2 ** attempt))
+            else:
+                # final failure
+                raise
+
+def generate_feedback_report(conversation: str, model: str) -> str:
+    """Generate a structured feedback report using OpenAI."""
+    prompt = f"""
+Analyze the following conversation and create a structured feedback report.
+
+Conversation:
+{conversation}
+
+Sections:
+- Executive Summary
+- Patterns & Themes
+- Consensus Points
+- Disagreements & Concerns
+- Persona Insights
+- Actionable Recommendations
+- Quantitative Metrics (acceptance %, likelihood per persona, priority)
+- Risk Assessment
+"""
+    resp = openai.chat.completions.create(
+        model=model,
+        messages=[
+            {"role": "system", "content": "You are an expert product analyst and UX researcher."},
+            {"role": "user", "content": prompt}
+        ],
+        temperature=REPORT_DEFAULTS.get("temperature", 0.7),
+        max_tokens=REPORT_DEFAULTS.get("max_tokens", 1500)
+    )
+    return resp.choices[0].message.content

app.py

@@ -0,0 +1,187 @@
+import streamlit as st
+import json
+from typing import List, Dict
+
+from config import MODEL_CHOICES, DEFAULT_MODEL, DEFAULT_PERSONA_PATH
+from utils import (
+    get_personas,
+    format_response_line,
+    detect_insight_or_concern,
+    extract_persona_response,
+    build_sentiment_summary,
+    build_heatmap_chart,
+    save_personas,
+)
+from ai_helpers import generate_response_with_retry, generate_feedback_report
+
+# -------------------------
+# Page config & state
+# -------------------------
+st.set_page_config(page_title="Persona Feedback Simulator", page_icon="💬", layout="wide")
+
+if "conversation_history" not in st.session_state:
+    st.session_state.conversation_history = ""
+if "api_key" not in st.session_state:
+    st.session_state.api_key = ""
+
+# -------------------------
+# Sidebar: API key, model, personas upload
+# -------------------------
+st.sidebar.header("🔑 API Configuration")
+api_key_input = st.sidebar.text_input("OpenAI API Key", type="password", value=st.session_state.api_key)
+if api_key_input:
+    st.session_state.api_key = api_key_input
+    import openai
+    openai.api_key = api_key_input
+else:
+    st.sidebar.info("Enter OpenAI API key to enable generation.")
+
+model_choice = st.sidebar.selectbox("Model", MODEL_CHOICES, index=MODEL_CHOICES.index(DEFAULT_MODEL))
+
+st.sidebar.markdown("---")
+st.sidebar.header("👥 Personas")
+uploaded = st.sidebar.file_uploader("Upload personas.json", type=["json"])
+personas = get_personas(uploaded, path=DEFAULT_PERSONA_PATH)
+st.sidebar.metric("Total Personas", len(personas))
+
+# -------------------------
+# Main UI - Feature input
+# -------------------------
+st.title("💬 Persona Feedback Simulator")
+st.header("📝 Feature Description")
+tabs = st.tabs(["Text", "Files"])
+with tabs[0]:
+    text_desc = st.text_area("Describe your feature", height=160)
+with tabs[1]:
+    uploaded_files = st.file_uploader("Upload wireframes / mockups", accept_multiple_files=True, type=["png", "jpg", "jpeg", "pdf"])
+
+feature_inputs = {
+    "Text": text_desc or "",
+    "Files": [f.name for f in (uploaded_files or [])]
+}
+
+st.markdown("---")
+
+# -------------------------
+# Persona selection
+# -------------------------
+st.header("👥 Choose Personas")
+if not personas:
+    st.warning("No personas available.")
+    selected_personas: List[Dict] = []
+else:
+    labels = [f"{p['name']} ({p.get('occupation','')})" for p in personas]
+    defaults = labels[:3]
+    selected_labels = st.multiselect("Select personas:", labels, default=defaults)
+    selected_personas = [p for p in personas if f"{p['name']} ({p.get('occupation','')})" in selected_labels]
+
+# -------------------------
+# Ask / Report / Clear controls
+# -------------------------
+st.header("💭 Ask Your Question")
+question = st.text_input("Question to personas")
+c1, c2, c3 = st.columns([2, 2, 1])
+ask_btn = c1.button("🎯 Ask")
+report_btn = c2.button("📊 Generate Report")
+clear_btn = c3.button("🗑️ Clear")
+
+if ask_btn:
+    if not st.session_state.api_key:
+        st.warning("Please set your OpenAI API key in the sidebar.")
+    elif not selected_personas:
+        st.warning("Please select at least one persona.")
+    elif not (question or feature_inputs["Text"]):
+        st.warning("Enter a question or feature description.")
+    else:
+        if question:
+            st.session_state.conversation_history += f"\n**User:** {question}\n"
+        with st.spinner("Generating persona responses..."):
+            try:
+                resp = generate_response_with_retry(feature_inputs, selected_personas, st.session_state.conversation_history, model_choice)
+                st.session_state.conversation_history += resp + "\n"
+                st.rerun()
+            except Exception as e:
+                st.error(f"Failed to generate response: {e}")
+
+if report_btn:
+    if not st.session_state.conversation_history.strip():
+        st.warning("Nothing to analyze yet.")
+    else:
+        with st.spinner("Generating feedback report..."):
+            try:
+                report = generate_feedback_report(st.session_state.conversation_history, model_choice)
+                st.markdown("## 📊 Feedback Report")
+                st.markdown(report)
+                st.download_button("⬇️ Download Report", report, "persona_report.md")
+            except Exception as e:
+                st.error(f"Failed to generate report: {e}")
+
+if clear_btn:
+    st.session_state.conversation_history = ""
+    st.rerun()
+
+st.markdown("---")
+
+# -------------------------
+# Conversation display + heatmap
+# -------------------------
+st.header("💬 Conversation History")
+if st.session_state.conversation_history.strip() and selected_personas:
+    lines = [ln for ln in st.session_state.conversation_history.split("\n") if ln.strip()]
+
+    # Display conversation lines with persona formatting
+    for line in lines:
+        matched = False
+        for p in selected_personas:
+            if line.startswith(p["name"]):
+                response_text = extract_persona_response(line)
+                hl = detect_insight_or_concern(response_text)
+                st.markdown(format_response_line(line, p["name"], hl), unsafe_allow_html=True)
+                matched = True
+                break
+        if not matched:
+            # user or neutral lines
+            st.markdown(line)
+
+    st.info("💡 Continue the discussion using the **question field above** to ask a follow-up question.")
+
+    # Build & show heatmap
+    df_summary = build_sentiment_summary(lines, selected_personas)
+    chart = build_heatmap_chart(df_summary)
+    st.markdown("## 🔥 Persona Sentiment Heatmap")
+    st.altair_chart(chart, use_container_width=True)
+else:
+    st.info("No conversation yet. Ask your personas a question to get started!")
+
+# -------------------------
+# Sidebar persona creation (persist)
+# -------------------------
+st.sidebar.markdown("---")
+st.sidebar.header("➕ Create Persona")
+with st.sidebar.form("new_persona_form"):
+    name = st.text_input("Name*")
+    occupation = st.text_input("Occupation*")
+    location = st.text_input("Location")
+    tech = st.selectbox("Tech Proficiency", ["Low", "Medium", "High"])
+    traits = st.text_area("Behavioral traits (comma-separated)")
+    submit = st.form_submit_button("Add Persona")
+    if submit:
+        if not name or not occupation:
+            st.sidebar.error("Name and Occupation required.")
+        else:
+            new_p = {
+                "id": f"p{len(personas)+1}",
+                "name": name.strip(),
+                "occupation": occupation.strip(),
+                "location": location.strip() or "Unknown",
+                "tech_proficiency": tech,
+                "behavioral_traits": [t.strip() for t in traits.split(",") if t.strip()]
+            }
+            personas.append(new_p)
+            if save_personas(personas, path=DEFAULT_PERSONA_PATH):
+                st.sidebar.success("✅ Persona added and saved.")
+            else:
+                st.sidebar.error("❌ Persona added but failed to save.")
+            st.rerun()
+
+st.sidebar.metric("Total Personas", len(personas))

config.py

@@ -0,0 +1,40 @@
+import os
+
+# -------------------------
+# Model and API Config
+# -------------------------
+
+MODEL_CHOICES = ["gpt-4o-mini", "gpt-4o", "gpt-4-turbo"]
+DEFAULT_MODEL = "gpt-4o-mini"
+
+OPENAI_DEFAULTS = {
+    "temperature": 0.8,
+    "max_tokens": 2000
+}
+
+REPORT_DEFAULTS = {
+    "temperature": 0.7,
+    "max_tokens": 2500
+}
+
+# -------------------------
+# Persona Colors
+# -------------------------
+PERSONA_COLORS = {
+    "Sophia Martinez": "#E6194B",
+    "Jamal Robinson": "#3CB44B",
+    "Eleanor Chen": "#FFE119",
+    "Diego Alvarez": "#4363D8",
+    "Anita Patel": "#F58231",
+    "Robert Klein": "#911EB4",
+    "Nia Thompson": "#46F0F0",
+    "Marcus Green": "#F032E6",
+    "Aisha Mbatha": "#BCF60C",
+    "Owen Gallagher": "#FABEBE",
+}
+
+# -------------------------
+# File Paths
+# -------------------------
+BASE_DIR = os.path.dirname(os.path.abspath(__file__))
+DEFAULT_PERSONA_PATH = os.path.join(BASE_DIR, "personas.json")

integration_deployment.md

@@ -0,0 +1,249 @@
+# Persona Feedback Simulator – Integration & Deployment
+
+## Table of Contents
+1. [Overview](#overview)  
+2. [System Architecture](#system-architecture)  
+3. [Prerequisites](#prerequisites)  
+4. [Installation and Setup](#installation-and-setup)  
+5. [Configuration](#configuration)  
+6. [Database / Data Storage](#database--data-storage)  
+7. [API Specifications](#api-specifications)  
+8. [Deployment Procedures](#deployment-procedures)  
+9. [Monitoring and Metrics](#monitoring-and-metrics)  
+10. [Maintenance and Update Procedures](#maintenance-and-update-procedures)  
+11. [Troubleshooting](#troubleshooting)  
+12. [Backup and Recovery](#backup-and-recovery)  
+
+---
+
+## 1. Overview
+The **Persona Feedback Simulator** is a Streamlit-based application that allows users to simulate conversations among virtual personas regarding product features. The system is designed to support:
+
+- Multiple personas stored in `personas.json`
+- AI-driven responses via OpenAI models (`gpt-4o-mini` recommended)
+- Automatic backup and recovery of persona data
+- Monitoring and observability via Prometheus metrics
+- Scalable deployment with load balancing
+
+---
+
+## 2. System Architecture
+**Components:**
+1. **Streamlit App** (`app.py`)  
+   - Handles UI, persona selection, question submission, AI integration, and persona responses.
+2. **Prometheus Metrics** (`Counter`, `Histogram`)  
+   - Exposes metrics on `/metrics` for request counts, response times, and errors.
+3. **Load Balancer** (NGINX)  
+   - Balances traffic between multiple containerized app instances.
+4. **Persistent Storage** (`personas.json` + backup `personas_backup.json`)  
+   - Stores persona definitions and allows safe recovery.
+5. **Optional Cloud Integration**  
+   - Can use S3, GCS, or a database backend for production durability.
+
+**Diagram:**
+
+```
+[User Browser] --> [NGINX Load Balancer] --> [Streamlit App Containers]
+                                         \--> [Prometheus Metrics]
+                                         \--> [Persistent Storage / Backup]
+```
+
+---
+
+## 3. Prerequisites
+- **Python 3.11+** (tested with 3.13)  
+- **Docker & Docker Compose** for containerized deployment  
+- **OpenAI API key** for AI responses  
+- **Prometheus** for metrics collection (optional, but recommended)  
+
+**Python packages** (in `requirements.txt`):
+```
+streamlit
+openai
+prometheus_client
+```
+
+---
+
+## 4. Installation and Setup
+
+1. **Clone the repository:**
+```bash
+git clone https://github.com/<your-username>/persona-feedback-simulator.git
+cd persona-feedback-simulator
+```
+
+2. **Set OpenAI API Key:**
+```bash
+export OPENAI_API_KEY="sk-..."
+```
+
+3. **Install dependencies locally (optional):**
+```bash
+python -m venv venv
+source venv/bin/activate
+pip install -r requirements.txt
+```
+
+4. **Run the app locally:**
+```bash
+streamlit run app.py
+```
+
+---
+
+## 5. Configuration
+
+### Environment Variables
+- `OPENAI_API_KEY` – OpenAI authentication
+- `PROMETHEUS_PORT` – Optional, defaults to 8000
+- `STREAMLIT_PORT` – Optional, defaults to 8501
+
+### Configuration Files
+- `personas.json` – Primary persona definitions
+- `personas_backup.json` – Auto-backup file
+- `prometheus.yml` – Prometheus scrape configuration
+- `nginx.conf` – Load balancer configuration
+
+---
+
+## 6. Database / Data Storage
+Currently uses **JSON files**:
+
+### `personas.json`
+| Field | Type | Description |
+|-------|------|-------------|
+| id | integer | Unique persona ID |
+| name | string | Persona full name |
+| occupation | string | Job title |
+| location | string | Geographical location |
+| tech_proficiency | string | "Low", "Medium", or "High" |
+| behavioral_traits | array[string] | List of persona traits |
+
+### Backup Strategy
+- Automatic backup to `personas_backup.json` whenever personas are added or modified.
+- Restore automatically if `personas.json` is missing or corrupted.
+
+---
+
+## 7. API Specifications
+
+### 7.1 Internal App Functions
+| Function | Endpoint/Usage | Description |
+|----------|----------------|-------------|
+| `generate_response` | Internal | Sends feature input + persona data to OpenAI and returns conversation |
+| `generate_feedback_report` | Internal | Summarizes conversation with actionable insights |
+| `instrumented` | Decorator | Wraps functions for Prometheus metrics (`REQUEST_COUNTER`, `RESPONSE_TIME`) |
+
+### 7.2 Prometheus Metrics
+Exposed at `/metrics` (default port 8000):
+
+| Metric | Type | Labels | Description |
+|--------|------|--------|-------------|
+| `app_requests_total` | Counter | `endpoint`, `status` | Counts total requests and success/error outcomes |
+| `app_response_time_seconds` | Histogram | `endpoint` | Measures response duration per endpoint |
+| `app_heartbeat` | Gauge | – | Optional: timestamp for health checks |
+
+### 7.3 Health Endpoint
+Optional `/healthz` endpoint for load balancer or Kubernetes:
+
+```python
+@app.route("/healthz")
+def health():
+    return "OK", 200
+```
+
+---
+
+## 8. Deployment Procedures
+
+### 8.1 Docker Deployment
+**Dockerfile**
+```dockerfile
+WORKDIR /app
+COPY . /app
+RUN pip install --no-cache-dir -r requirements.txt
+EXPOSE 8501 8000
+CMD ["streamlit", "run", "app.py", "--server.port=8501"]
+```
+
+**Docker Compose**
+```yaml
+version: '3'
+services:
+  app1:
+    build: .
+    ports:
+      - "8501:8501"
+    environment:
+      - OPENAI_API_KEY=${OPENAI_API_KEY}
+  nginx:
+    image: nginx:latest
+    ports:
+      - "80:80"
+    volumes:
+      - ./nginx.conf:/etc/nginx/nginx.conf:ro
+```
+
+---
+
+## 9. Monitoring and Metrics
+
+1. **Prometheus Scraping**
+```yaml
+scrape_configs:
+  - job_name: 'persona_app'
+    static_configs:
+      - targets: ['app1:8000', 'app2:8000', 'app3:8000']
+```
+
+2. **Metrics to Watch**
+- Request counts per endpoint
+- Error rate
+- Response latency
+- Heartbeat (optional)
+
+3. **Optional Visualization**
+- Connect Prometheus to Grafana dashboards
+- Create alerts for:
+  - High error rate
+  - Service unavailability
+  - Slow response times
+
+---
+
+## 10. Maintenance and Update Procedures
+
+- **Update Python packages:** `pip install -r requirements.txt --upgrade`
+- **Update app code:** Pull latest from GitHub and rebuild Docker containers
+- **Persona updates:** Add through UI, then backup occurs automatically
+- **Rolling restart:** Use Docker Compose `up -d --force-recreate` or Kubernetes Deployment rolling update
+- **Configuration changes:** Update `nginx.conf`, `prometheus.yml`, or `.env` variables and reload respective services
+
+---
+
+## 11. Troubleshooting
+
+| Issue | Solution |
+|-------|---------|
+| `personas.json` not found | Ensure it exists next to `app.py` or restore from backup |
+| Duplicated Prometheus metrics | Use custom registry or `st.cache_resource` (see metrics setup) |
+| OpenAI errors | Verify `OPENAI_API_KEY` and network connectivity |
+| Streamlit reload issues | Clear browser cache or restart app container |
+
+---
+
+## 12. Backup and Recovery
+
+1. **Automatic Backup:** Occurs whenever personas are added or modified → saved to `personas_backup.json`.
+2. **Restore Backup:** If `personas.json` missing or corrupted, app restores from backup on startup.
+3. **Manual Backup Trigger:** Call `backup_personas()` in code after persona updates.
+4. **Optional Cloud Backup:** Sync `personas_backup.json` to S3/GCS for off-site durability.
+
+---
+
+### Notes for Developers
+- Always maintain a **clean `personas.json`** in version control for initial deployments.
+- Use the **backup/restore helpers** to prevent accidental persona data loss.
+- Keep **metrics endpoints open** only for internal monitoring (don’t expose publicly without authentication).
+

personas.json

@@ -0,0 +1 @@
+[{"id":1,"name":"Sophia Martinez","age":34,"gender":"Female","occupation":"Marketing Manager","location":"Austin, Texas","tech_proficiency":"High","income_level":"Upper-Middle","interests":["data analytics","digital campaigns","branding","travel"],"personality":"Analytical, persuasive, pragmatic","communication_style":"Professional but approachable, uses marketing jargon","behavioral_traits":["Goal-oriented","Metrics-driven","Team collaborator"],"product_preferences":"Loves features that provide measurable ROI or improve productivity"},{"id":2,"name":"Jamal Robinson","age":22,"gender":"Male","occupation":"College Student (Computer Science)","location":"Chicago, Illinois","tech_proficiency":"Expert","income_level":"Low","interests":["gaming","AI","social media","open-source projects"],"personality":"Curious, outspoken, experimental","communication_style":"Casual and meme-friendly, uses tech slang","behavioral_traits":["Early adopter","Enjoys tinkering","Socially engaged online"],"product_preferences":"Values innovation, customization, and gamification"},{"id":3,"name":"Eleanor Chen","age":46,"gender":"Female","occupation":"High School Teacher","location":"San Francisco, California","tech_proficiency":"Moderate","income_level":"Middle","interests":["education","reading","community work","family time"],"personality":"Patient, empathetic, articulate","communication_style":"Clear and thoughtful, educational tone","behavioral_traits":["Cautious adopter","Prefers reliability","Community-minded"],"product_preferences":"Values simplicity, clarity, and ethical design"},{"id":4,"name":"Diego Alvarez","age":29,"gender":"Male","occupation":"UX Designer","location":"Barcelona, Spain","tech_proficiency":"High","income_level":"Upper-Middle","interests":["design thinking","photography","user research","cycling"],"personality":"Creative, detail-oriented, empathetic","communication_style":"Reflective, uses design terminology","behavioral_traits":["Empathy-driven","Iterative thinker","User advocate"],"product_preferences":"Values aesthetics, usability, and accessibility"},{"id":5,"name":"Anita Patel","age":39,"gender":"Female","occupation":"Small Business Owner (Online Boutique)","location":"Toronto, Canada","tech_proficiency":"Moderate","income_level":"Middle","interests":["fashion","entrepreneurship","social media marketing","family"],"personality":"Driven, pragmatic, social","communication_style":"Friendly and informal, with business undertones","behavioral_traits":["Risk-taker","Customer-focused","Budget-conscious"],"product_preferences":"Loves tools that automate tasks and boost sales"},{"id":6,"name":"Robert Klein","age":61,"gender":"Male","occupation":"Retired Engineer","location":"Munich, Germany","tech_proficiency":"Intermediate","income_level":"Upper-Middle","interests":["gardening","woodworking","technology trends","cycling"],"personality":"Logical, patient, skeptical","communication_style":"Methodical and concise","behavioral_traits":["Fact-driven","Early-morning routine","Skeptical of marketing hype"],"product_preferences":"Prefers durability, data transparency, and reliability"},{"id":7,"name":"Nia Thompson","age":27,"gender":"Female","occupation":"Social Media Influencer","location":"Los Angeles, California","tech_proficiency":"Expert","income_level":"High","interests":["photography","fashion","travel","wellness"],"personality":"Charismatic, spontaneous, expressive","communication_style":"Conversational, emotional, uses emojis","behavioral_traits":["Trend-sensitive","Highly visual","Collaborative"],"product_preferences":"Values aesthetics, social shareability, and novelty"},{"id":8,"name":"Marcus Green","age":51,"gender":"Male","occupation":"Construction Site Manager","location":"Birmingham, UK","tech_proficiency":"Low","income_level":"Middle","interests":["sports","DIY projects","family outings","local pubs"],"personality":"Down-to-earth, straightforward, humorous","communication_style":"Direct and practical","behavioral_traits":["Skeptical of new tech","Hands-on learner","Prefers face-to-face"],"product_preferences":"Wants clear value, reliability, and low maintenance"},{"id":9,"name":"Aisha Mbatha","age":31,"gender":"Female","occupation":"Public Health Researcher","location":"Nairobi, Kenya","tech_proficiency":"High","income_level":"Middle","interests":["data science","policy analysis","volunteering","fitness"],"personality":"Curious, data-driven, empathetic","communication_style":"Balanced between analytical and conversational","behavioral_traits":["Research-oriented","Socially conscious","Detail-focused"],"product_preferences":"Values privacy, inclusivity, and evidence-based features"},{"id":10,"name":"Owen Gallagher","age":42,"gender":"Male","occupation":"Truck Driver","location":"Dublin, Ireland","tech_proficiency":"Low","income_level":"Working Class","interests":["road trips","radio shows","sports","family"],"personality":"Friendly, patient, no-nonsense","communication_style":"Informal, storytelling tone","behavioral_traits":["Routine-oriented","Practical","Prefers stability"],"product_preferences":"Wants ease of use, low cost, and safety features"}]

requirements.txt

@@ -1,3 +1,3 @@
-altair
-pandas
-streamlit
+streamlit>=1.20
+openai>=0.27.0
+prometheus-client>=0.16.0

simulation_algorithm_design.md

@@ -0,0 +1,195 @@
+# Simulation Algorithm Design
+
+This is a detailed overview of the simulation
+algorithm that powers the persona-based feedback system. It explains
+how personas are modeled, how user feature descriptions are processed,
+how conversations are generated, and how the system synthesizes feedback
+into structured insights. It also outlines the underlying AI
+architecture and decision-making processes.
+
+------------------------------------------------------------------------
+
+## Persona Modeling
+
+Personas represent simulated users with distinct
+characteristics, demographics, and communication styles. Each persona is
+defined as a structured JSON object with the following schema:
+
+``` json
+{
+    "id":1,
+    "name":"Sophia Martinez"
+    "age":34
+    "gender":"Female"
+    "occupation":"Marketing Manager"
+    "location":"Austin, Texas"
+    "tech_proficiency":"High"
+    "income_level":"Upper-Middle"
+    "interests":["data analytics","digital campaigns","branding","travel"]
+    "personality":"Analytical, persuasive, pragmatic"
+    "communication_style":"Professional but approachable, uses marketing jargon"
+    "behavioral_traits":["Goal-oriented","Metrics-driven","Team collaborator"]
+    "product_preferences":"Loves features that provide measurable ROI or improve productivity"
+}
+```
+
+### Key Persona Attributes
+
+-   **Occupation:** Defines the professional role and informs domain-specific vocabulary or reasoning.
+-   **Tech Proficiency:** A categorical indicator (“Low”, “Medium”, “High”) determining familiarity with digital tools or technical language.
+-   **Personality:** Descriptive traits that guide tone and emotional expression (e.g., analytical, creative, empathetic).
+-   **Behavioral Traits:** A list of tendencies shaping decision-making and feedback approach (e.g., goal-oriented, cautious).
+-   **Product Preferences:** Describes what the persona values in products or features — such as measurable ROI, innovation, or usability.
+
+### Behavioral Logic
+
+Each persona follows a set of rule-based and probabilistic logic for
+generating feedback. The simulation ensures diverse, realistic outputs
+by adjusting response tone and focus based on both persona attributes
+and conversation history.
+
+------------------------------------------------------------------------
+
+## Feature Description Processing
+
+Feature descriptions --- e.g., project summaries, data reports, or
+design specifications --- are preprocessed before being fed into
+personas.
+
+### Steps:
+
+1.  **Text Cleaning:** Remove formatting artifacts, redundant
+    whitespace, and HTML tags.
+2.  **Semantic Parsing:** Break down input into feature units (e.g.,
+    "target users," "goals," "methodology").
+3.  **Embedding Generation:** Convert text into dense vector embeddings
+    via an OpenAI text embedding model.
+4.  **Contextual Weighting:** Assign higher weights to sections
+    containing keywords like *impact*, *risk*, or *improvement
+    opportunity*.
+5.  **Persona-Specific Filtering:** Each persona receives a subset of
+    features relevant to their domain.
+
+This ensures that feedback remains context-aware and targeted to
+persona expertise.
+
+------------------------------------------------------------------------
+
+## Conversation Generation
+
+Conversations simulate an interactive critique between the user and
+multiple personas. The process follows a turn-based design:
+
+### Workflow
+
+1.  **User Prompt Ingestion:** The user provides a question or
+    description.
+2.  **Persona Response Loop:**
+    -   Each persona analyzes the prompt through its embedding and
+        memory context.
+    -   The persona's decision engine generates a structured response
+        using an OpenAI language model (e.g., GPT-5).
+    -   Responses are tagged with persona metadata and colorized for
+        display.
+3.  **History Integration:** Previous interactions are appended to the
+    persona's memory for continuity.
+4.  **Adaptive Tone Adjustment:** The persona adjusts its verbosity or
+    formality based on conversation depth and user sentiment.
+
+### Pseudo-code Example
+
+``` python
+for persona in personas:
+    context = build_context(user_input, persona.memory)
+    response = generate_response(model="gpt-5", role=persona.role, tone=persona.tone, context=context)
+    update_history(persona, response)
+```
+
+------------------------------------------------------------------------
+
+## Feedback Synthesis
+
+After generating individual persona responses, the system produces a
+summary report highlighting key insights and concerns.
+
+### Steps:
+
+1.  **Response Extraction:** Parse persona outputs into structured units
+    (feedback statements).
+2.  **Topic Clustering:** Group feedback by themes (clarity, engagement,
+    usability, etc.).
+3.  **Sentiment Weighting:** Use semantic analysis to determine whether
+    comments are positive, neutral, or critical.
+4.  **Insight-Concern Classification:** Mark feedback as *insight*
+    (constructive) or *concern* (problematic).
+5.  **Visualization Layer:** Generate bar charts, sentiment histograms,
+    and keyword clouds for report display.
+
+The synthesized report provides **multi-perspective feedback** combining
+all personas' evaluations.
+
+------------------------------------------------------------------------
+
+## Underlying AI Architecture
+
+The simulation architecture combines symbolic reasoning (rules,
+goals, and persona metadata) with neural generation (GPT-5
+responses).
+
+### Core Components
+
+-   **Persona Memory:** Tracks each persona's previous statements and
+    context.
+-   **Embedding Engine:** Converts text into vectorized meaning for
+    cross-referencing and relevance scoring.
+-   **Response Generator:** A large language model (LLM) that interprets
+    both persona context and user input.
+-   **Feedback Synthesizer:** Aggregates persona responses into
+    structured insights.
+
+### Decision-Making Flow
+
+``` mermaid
+flowchart TD
+A[User Input] --> B[Feature Preprocessing]
+B --> C[Persona Loop]
+C -->|Contextual Prompt| D[GPT-5 Response Generator]
+D --> E[Persona Response Memory]
+E --> F[Feedback Synthesis Module]
+F --> G[Visualization + Summary Report]
+```
+
+This hybrid architecture ensures responses are contextually
+consistent, behaviorally diverse, and analytically useful.
+
+------------------------------------------------------------------------
+
+## Decision-Making Processes
+
+Each persona's decision-making combines deterministic and probabilistic
+components:
+
+  **Goal Alignment:** Checks how closely input aligns with persona's goals.
+
+  **Contextual Memory Recall:** Retrieves relevant parts of previous interactions.
+
+  **Response Scoring:** Evaluates multiple candidate responses using an internal reward model (clarity, tone, novelty).
+
+  **Tone Calibration:** Adjusts phrasing style (formal, critical, supportive).
+  
+  **Adaptive Weighting:** Balances between deterministic persona behavior and stochastic creativity from GPT generation.
+
+  -----------------------------------------------------------------------
+
+------------------------------------------------------------------------
+
+## Summary
+
+This simulation framework enables multi-persona feedback generation
+by integrating structured persona modeling, semantic text
+processing, LLM-driven dialogue generation, Automated feedback
+synthesis and visualization
+
+Together, these elements create a robust, flexible system for
+simulated evaluation and insight generation across creative,
+technical, and analytical domains.

use_cases.md

@@ -0,0 +1,55 @@
+# Use Cases
+
+---
+
+## 1. Early Concept Validation
+**Industry:** Healthcare Technology  
+**Use:** Simulate patients, clinicians, and compliance officers to evaluate early UI sketches for a self-reporting app.  
+**Value:** Detects accessibility, workflow, and privacy concerns before prototyping.
+
+---
+
+## 2. UI & UX Refinement
+**Industry:** Fintech  
+**Feature:** Interactive dashboards or visual elements.  
+**Use:** Personas with varying financial literacy assess clarity and customization.  
+**Value:** Reveals gaps between novice and expert users, guiding data simplification.
+
+---
+
+## 3. Workflow Optimization
+**Industry:** Manufacturing / Industrial IoT  
+**Feature:** Alert systems and automation workflows.  
+**Use:** Simulated technicians and managers review alert logic and workload balance.  
+**Value:** Improves efficiency and reduces false alerts.
+
+---
+
+## 4. Content & Messaging Feedback
+**Industry:** Consumer Marketing  
+**Feature:** Campaign tone and message framing.  
+**Use:** Personas test reactions to sustainability or brand claims.  
+**Value:** Refines balance between emotional appeal and factual credibility.
+
+---
+
+## 5. Detailed Design Feedback
+**Industry:** SaaS / Productivity Tools  
+**Feature:** UI controls, filter logic, and data views.  
+**Use:** Simulated roles (manager, developer, executive) evaluate usability.  
+**Value:** Supports adaptive design for multiple user roles.
+
+---
+
+## 6. Pre-Launch Validation
+**Industry:** eCommerce  
+**Feature:** Recommendation systems and personalization logic.  
+**Use:** Personas emulate shoppers with diverse goals and budgets.  
+**Value:** Identifies algorithm bias and improves relevance before release.
+
+---
+
+## 7. Cross-Functional Alignment
+**Industry:** Enterprise Software  
+**Use:** Personas representing legal, technical, and user teams simulate feedback sessions.  
+**Value:** Accelerates stakeholder consensus through synthetic dialogue.

utils.py

@@ -0,0 +1,180 @@
+import json
+import re
+import streamlit as st
+import pandas as pd
+import altair as alt
+import logging
+from typing import List, Dict, Optional
+from config import DEFAULT_PERSONA_PATH, PERSONA_COLORS as CONFIG_PERSONA_COLORS
+
+log = logging.getLogger(__name__)
+
+# Local color cache that starts from config's colors (if provided)
+PERSONA_COLORS = dict(CONFIG_PERSONA_COLORS) if isinstance(CONFIG_PERSONA_COLORS, dict) else {}
+
+# -------------------------
+# Personas I/O & validation
+# -------------------------
+def load_personas_from_file(path: str = DEFAULT_PERSONA_PATH) -> List[Dict]:
+    """Load personas from JSON file. Returns [] on errors."""
+    try:
+        with open(path, "r", encoding="utf-8") as f:
+            data = json.load(f)
+            if not isinstance(data, list):
+                st.warning(f"⚠️ {path} does not contain a list. Returning empty personas.")
+                return []
+            return data
+    except FileNotFoundError:
+        log.info("personas file not found: %s", path)
+        return []
+    except json.JSONDecodeError as e:
+        st.error(f"❌ Malformed JSON in {path}: {e}")
+        return []
+    except Exception as e:
+        st.error(f"❌ Unexpected error loading {path}: {e}")
+        return []
+
+def get_personas(uploaded_file=None, path: str = DEFAULT_PERSONA_PATH) -> List[Dict]:
+    """
+    Return personas. If uploaded_file is provided (streamlit UploadedFile),
+    attempt to load and replace saved personas.
+    """
+    personas = load_personas_from_file(path)
+
+    if uploaded_file:
+        try:
+            imported = json.load(uploaded_file)
+            if not isinstance(imported, list):
+                st.error("Uploaded persona file must be a JSON list.")
+            else:
+                personas = imported
+                # try to persist
+                try:
+                    with open(path, "w", encoding="utf-8") as f:
+                        json.dump(personas, f, indent=2)
+                    st.success("✅ Personas imported and saved successfully!")
+                except Exception as e:
+                    st.error(f"❌ Could not save uploaded personas to disk: {e}")
+        except json.JSONDecodeError:
+            st.error("❌ Uploaded file contains invalid JSON.")
+        except Exception as e:
+            st.error(f"❌ Error reading uploaded file: {e}")
+
+    return personas
+
+def validate_persona(persona: Dict) -> bool:
+    """Basic validation for persona structure."""
+    required = ["name", "occupation", "tech_proficiency", "behavioral_traits"]
+    for r in required:
+        if r not in persona or persona[r] in (None, "", []):
+            return False
+    if not isinstance(persona.get("behavioral_traits", []), list):
+        return False
+    return True
+
+def save_personas(personas: List[Dict], path: str = DEFAULT_PERSONA_PATH) -> bool:
+    """Persist personas to disk. Returns True on success."""
+    try:
+        with open(path, "w", encoding="utf-8") as f:
+            json.dump(personas, f, indent=2)
+        return True
+    except Exception as e:
+        st.error(f"❌ Could not save personas: {e}")
+        log.exception("save_personas failed")
+        return False
+
+# -------------------------
+# Display & formatting
+# -------------------------
+def get_color_for_persona(name: str) -> str:
+    """Return or generate a stable hex color for a persona name."""
+    if name not in PERSONA_COLORS:
+        PERSONA_COLORS[name] = f"#{(hash(name) & 0xFFFFFF):06x}"
+    return PERSONA_COLORS[name]
+
+def format_response_line(text: str, persona_name: str, highlight: Optional[str] = None) -> str:
+    """Return HTML string for styled persona line."""
+    color = get_color_for_persona(persona_name)
+    background = ""
+    if highlight == "insight":
+        background = "background-color: #d4edda;"
+    elif highlight == "concern":
+        background = "background-color: #f8d7da;"
+    return (
+        f"<div style='color:{color}; {background} padding:8px; margin:6px 0; "
+        f"border-left:4px solid {color}; border-radius:4px; white-space:pre-wrap;'>{text}</div>"
+    )
+
+# -------------------------
+# Text parsing & sentiment
+# -------------------------
+_INSIGHT_PATTERN = re.compile(r'\b(think|improve|great|helpful|excellent|love|benefit|useful|like)\b', re.I)
+_CONCERN_PATTERN = re.compile(r'\b(worry|concern|problem|issue|difficult|hard|confused|frustrat|dislike)\b', re.I)
+
+def detect_insight_or_concern(text: str) -> Optional[str]:
+    """Return 'insight' / 'concern' / None based on simple keyword matching."""
+    if not text:
+        return None
+    if _INSIGHT_PATTERN.search(text):
+        return "insight"
+    if _CONCERN_PATTERN.search(text):
+        return "concern"
+    return None
+
+def extract_persona_response(line):
+    """
+    Remove persona name and metadata, return only the response text.
+    Example:
+    "John: - Response: I think this is great" -> "I think this is great"
+    """
+    parts = re.split(r":\s*-?\s*Response:?", line, maxsplit=1)
+    if len(parts) == 2:
+        return parts[1].strip()
+    else:
+        return line
+
+def score_sentiment(text: str) -> int:
+    """Simple numeric score: insight=1, concern=-1, neutral=0"""
+    cat = detect_insight_or_concern(text)
+    return 1 if cat == "insight" else -1 if cat == "concern" else 0
+
+# -------------------------
+# Heatmap / Chart builder
+# -------------------------
+def build_sentiment_summary(lines: List[str], selected_personas: List[Dict]) -> pd.DataFrame:
+    """
+    Return a DataFrame with average sentiment score per persona.
+    Ensures each selected persona appears in the result.
+    """
+    rows = []
+    for line in lines:
+        for p in selected_personas:
+            if line.startswith(p["name"]):
+                text = extract_persona_response(line)
+                rows.append({"Persona": p["name"], "Sentiment": score_sentiment(text)})
+    df = pd.DataFrame(rows) if rows else pd.DataFrame(columns=["Persona", "Sentiment"])
+    # ensure order & include personas with no rows
+    names = [p["name"] for p in selected_personas]
+    if df.empty:
+        return pd.DataFrame({"Persona": names, "Sentiment": [0]*len(names)})
+    summary = df.groupby("Persona")["Sentiment"].mean().reindex(names, fill_value=0).reset_index()
+    return summary
+
+def build_heatmap_chart(df_summary: pd.DataFrame, height: int = 220) -> alt.Chart:
+    """Return an Altair bar chart representing sentiment summary."""
+    chart = (
+        alt.Chart(df_summary)
+        .mark_bar()
+        .encode(
+            x=alt.X("Persona", sort="-y"),
+            y=alt.Y("Sentiment", title="Average Sentiment Score", scale=alt.Scale(domain=[-1, 1])),
+            color=alt.Color(
+                "Sentiment",
+                scale=alt.Scale(domain=[-1, 0, 1], range=["#F94144", "#FFC300", "#3CB44B"]),
+                legend=None
+            ),
+            tooltip=["Persona", "Sentiment"]
+        )
+        .properties(height=height)
+    )
+    return chart