---
name: "Semblance — Synthetic Society"
client: Oliver Internal
status: active
tech: [Python, Quart, Socket.IO, MongoDB, React, TypeScript, Tailwind, shadcn/ui, Docker, Gemini, OpenAI]
local_path: /Volumes/SSD/Projects/Oliver/semblance
deploy: docker compose up --build
url: 
server: GCP (same issue as Mod Comms — 30s LB timeout)
tags: [oliver, ai, synthetic-personas, focus-group, insights, gcp, socketio]
created: 2026-04-14
last_commit: 2026-03-30
commits: 109
---

## Overview
AI platform for creating synthetic consumer personas and running autonomous focus group sessions. Real-time multi-persona AI conversations.

**Key capabilities:**
- AI persona generation from audience briefs (Gemini 3 Pro Preview, GPT-4.1, GPT-5.2)
- Live focus group sessions (manual or fully autonomous AI moderation)
- Document uploads (PDF, DOCX, TXT) as focus group assets
- Analytics + theme extraction
- Bulk export (PDF)

Backup: `semblance_backup/`

## Tech Stack
- **Frontend:** React + TypeScript + Vite + Tailwind + shadcn/ui (port 5137 or build)
- **Backend:** Python + Quart (async Flask) + Hypercorn ASGI (port 5137)
- **Database:** MongoDB (PyMongo)
- **Real-time:** python-socketio + AsyncServer (ASGI wrapped)
- **AI:** Gemini 3 Pro Preview (default), GPT-4.1, GPT-5.2
- **Auth:** Custom JWT (Quart-compatible, NOT Flask-JWT-Extended)
- **Infrastructure:** Docker + docker-compose

## Architecture
```
React SPA (TypeScript + shadcn/ui)
    ↓ Socket.IO (WebSocketContext)
Quart backend (python-socketio AsyncServer)
    ├── ai_runner_service.py (background task execution)
    ├── autonomous_conversation_controller.py (multi-persona orchestration)
    ├── conversation_decision_service.py (next speaker logic)
    ├── conversation_context_service.py (state + history)
    └── llm_service.py (multi-model: Gemini/GPT)
    ↓
MongoDB (personas, sessions, messages)
```

### Known Issue — GCP 30s Load Balancer Timeout
All async LLM routes were fixed to bypass GCP 30s LB timeout (same issue as Mod Comms).
Tasks migrated from WebSocket delivery → HTTP polling.

## Dev Commands
```bash
# Frontend
npm run build          # Production build (use for testing)
npm run build:dev      # Dev build
npm run lint
npm run preview

# Backend
cd backend && python run.py   # Starts on port 5137
```

## Deployment
- **Run:** `docker compose up --build`
- **Local path:** `/Volumes/SSD/Projects/Oliver/semblance`
- **Backend port:** 5137 (Hypercorn)

## Timeline / Git History
| Date | Change |
|------|--------|
| 2026-03-30 | Fix: task result not stored in useTaskPolling (false 'no personas' error) |
| 2026-03-23 | Fix AI autonomous mode: cross-loop WebSocket emit + polling fallback |
| 2026-03-23 | Allow document uploads (PDF, DOCX, TXT) as focus group assets |
| 2026-03-23 | **Critical:** Migrate task delivery WebSocket → HTTP polling (GCP 30s timeout) |
| 2026-03-23 | Fix all async LLM routes: bypass GCP 30s LB timeout |
| 2026-03-23 | Fix naive vs aware datetime crash + stuck AI mode |

## Sessions
### 2026-04-14 – Project catalogued
**Done:** Added to Obsidian second brain with full details.

---
## Change Log
| Date | Requested | Changed | Files |
|------|-----------|---------|-------|
| 2026-03-23 | Fix AI mode hanging on GCP | WebSocket → HTTP polling for all LLM routes | backend |
| 2026-03-23 | Add document upload support | PDF/DOCX/TXT as focus group assets | backend, frontend |

## Related
- [[modcomms/Mod Comms]] (same GCP timeout issue)
- [[olivas/OliVAS]]
- [[build-a-squad/Build A Squad]]