7251967b64
- 35 project notes (PARA structure, 1:1 disk mapping) - CLAUDE.md session protocol - Projects Index MOC - Templates: Daily, Meeting, Project - 03 Resources, 02 Areas structure - .gitignore excludes credentials, workspace files, smart-env Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
96 lines
3.5 KiB
Markdown
96 lines
3.5 KiB
Markdown
---
|
||
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]]
|