AI Virtual Focus Group System

An AI-driven multi-agent market research system designed to help founders, brand strategists, and marketers test new product concepts, messaging, and pricing strategies on autonomous consumer personas before committing capital to real-world campaigns.

---

Task & Core Architecture: Why Multi-Agent?

What the System Solves

Traditional market research (focus groups, surveys, A/B testing) is slow and expensive. Standard single-prompt LLM evaluations often suffer from severe sycophancy (the LLM being overly polite and praising every idea) or groupthink.

This system orchestrates specialized, autonomous AI agents through structured test execution pipelines to simulate realistic consumer feedback, moderate bias, and distill raw chat logs into actionable executive strategy.

Test Execution Matrix

The framework supports 6 specialized testing methodologies, enforcing execution isolation to guarantee valid results:

Test Type	Execution Pattern	Goal	Key Edge Cases & Mitigations
Direct Concept Validation	Phase 1: 1-on-1 Phase 2: Group Debate (Opt)	Baseline interest, clarity, red flags.	Sycophancy → Sycophancy Index & Friction Prompts
Head-to-Head (A/B/N)	Parallel Isolated Panels	Win-rate without prompt leakage.	Contamination → Clean Slate Pattern (Isolated memory)
Competitive Displacement	Phase 1: 1-on-1 vs Incumbent Phase 2: Group Debate	Test switching power against leaders.	Hallucinated specs → Grounded market context
Price Elasticity (van Westendorp)	Parallel 1-on-1s per price	Optimal price floor, ceiling, and WTP.	Virtue signaling → Pure 1-on-1 isolated execution
Sequential Feature Rollout	Multi-stage 1-on-1s	Feature addition value delta.	Context bloat → Intermediate summarization
In-Depth Interview (IDI)	Single Dedicated Persona	Deep emotional drivers.	Conversational drift → 2-Tier Orchestrator state machine

---

Agent Roles, Inputs, Outputs & Tools

1. Persona Agent (app/agents/persona_agent.py)

• Role: Simulates specific target consumers with custom demographic profiles, pain points, and buying behaviors.
• Inputs: Persona metadata dictionary, current conversation state, active test context.
• Outputs: Human-like feedback, objections, rating scales, or price willingness responses.
• Tools: None (pure roleplay execution).

2. Moderator Agent (app/agents/moderator_agent.py)

• Role: Facilitates group debates, asks follow-up probing questions, enforces discussion guides, and performs Step 2 Data Reduction.
• Inputs: Raw conversation transcripts, active test parameters, friction thresholds.
• Outputs: Discussion probes, targeted follow-up questions, and compact structured JSON test summaries (schemas/summary.py).
• Tools: sycophancy_detector.py (evaluates persona output for unearned praise and injects friction prompts).

3. Meta-Analyst Agent (app/agents/meta_analyst_agent.py)

• Role: Synthesizes isolated test results into an executive decision matrix.
• Inputs: Lightweight JSON summaries from Test 1 and Test 2 (strict 2-test pipeline limit).
• Outputs: Executive Strategic Summary, Go/No-Go Recommendation, Risk/Objection Matrix, Actionable Next Steps.
• Tools: pricing_calculator.py (aggregates van Westendorp price points to output optimal price range).

---

Inter-Agent Communication & Data Flow

Communication follows a strict 3-Tier Pipeline to keep latency low (<30 seconds) and prevent context bloat: [ Input Payload ] │ ▼ ┌────────────────────────────────────────────────────────┐ │ 1. Execution Phase (Orchestrator) │ │ • Persona Agents & Moderator execute tests │ │ • Generates: Raw Chat Transcripts / Event Logs │ └──────────────────────────┬─────────────────────────────┘ │ ▼ ┌────────────────────────────────────────────────────────┐ │ 2. Data Reduction Phase (Test Moderator) │ │ • Condenses raw transcripts into JSON Summaries │ │ • Output Format: JSON (Metrics, Objections, Quotes)│ └──────────────────────────┬─────────────────────────────┘ │ ▼ ┌────────────────────────────────────────────────────────┐ │ 3. Meta-Analysis Phase (Meta-Analyst Agent) │ │ • Ingests max 2 JSON Summaries │ │ • Output Format: Final Executive Strategy Report │ └────────────────────────────────────────────────────────┘

Communication Rules & Guardrails

• The 2-Test Limit Rule: Pipelines are constrained to a maximum of 2 chained tests per run to limit API costs and run durations.
• Isolated Memory State: Tests executing in parallel or across price points utilize the Clean Slate Pattern—persona execution memory resets between test variations to eliminate cross-contamination and anchoring bias.
• Structured JSON Transfer: Inter-agent communication between reduction and synthesis stages passes strictly through validated Pydantic models (schemas/summary.py), preventing context window bloat.

---

Tech Stack & Frameworks

• Language & Runtime: Python 3.10+
• API Framework: FastAPI (endpoints in app/api/v1/endpoints/)
• LLM Integration: openRouter API via OpenAI SDK (app/core/llm_factory.py)
• Data Validation: Pydantic v2 (app/schemas/)
• State & Orchestration: Custom Async Pipeline Engine (app/orchestrator/)
• Environment Configuration: python-dotenv

---

How to Run the System

1. Prerequisites & Installation

Ensure you have Python installed and clone/setup your environment:

git clone <your-repo-url>
cd ai-focus-group
python -m venv venv
  # On Windows: venv\Scripts\activate
pip install -r requirements.txt

2.Environment Setup

Create a .env file in the root directory:

PROJECT_NAME="AI Virtual Focus Group Engine"
OPENROUTER_API_KEY="XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXxx"
DEFAULT_MODEL="gpt-4o"
FAST_MODEL="gpt-4o-mini"
ANALYST_MODEL="gpt-4o"
MAX_PIPELINE_TIMEOUT=30

3. Running the Demo Pipeline

python demo.py

4. Running the Web API

uvicorn main:app --reload --port 8000