semblance/backend/README.md

Semblance Synthetic Society Backend

This is the Python backend for the Semblance Synthetic Society project. It provides API endpoints for authentication, personas, and focus groups.

Setup

1. Make sure you have Python 3.8+ installed
2. Create a virtual environment:

   cd backend
   python -m venv venv
   

3. Activate the virtual environment:
   • On macOS/Linux:

     source venv/bin/activate
     

   • On Windows:

     venv\Scripts\activate
     

4. Install dependencies:

   pip install -r requirements.txt
   

Running the Backend

python run.py

The server will start on http://localhost:5000

API Endpoints

Authentication

• POST /api/auth/login - Login with username and password
• POST /api/auth/register - Register a new user
• GET /api/auth/me - Get current user profile

Personas

• GET /api/personas - Get personas for current user
• GET /api/personas/all - Get all personas
• GET /api/personas/:id - Get persona by ID
• POST /api/personas - Create a new persona
• PUT /api/personas/:id - Update a persona
• DELETE /api/personas/:id - Delete a persona
• POST /api/personas/batch - Create multiple personas

Focus Groups

• GET /api/focus-groups - Get focus groups for current user
• GET /api/focus-groups/all - Get all focus groups
• GET /api/focus-groups/:id - Get focus group by ID
• POST /api/focus-groups - Create a new focus group
• PUT /api/focus-groups/:id - Update a focus group
• DELETE /api/focus-groups/:id - Delete a focus group
• POST /api/focus-groups/:id/participants - Add participant to focus group
• DELETE /api/focus-groups/:id/participants/:personaId - Remove participant from focus group
• GET /api/focus-groups/:id/messages - Get messages for a focus group
• POST /api/focus-groups/:id/messages - Add a message to a focus group

AI Personas

• POST /api/ai-personas/generate - Generate a synthetic persona using AI
• POST /api/ai-personas/generate-and-save - Generate and save a synthetic persona
• POST /api/ai-personas/batch-generate - Generate multiple synthetic personas
• POST /api/ai-personas/batch-generate-and-save - Generate and save multiple synthetic personas

Focus Group AI

• POST /api/focus-group-ai/generate-response - Generate an AI response from a persona in a focus group discussion

AI Response Generation Example

Request Body:

{
  "focus_group_id": "focus_group_id",
  "persona_id": "persona_id",
  "current_topic": "What do you think about this product?",
  "temperature": 0.7  // Optional, controls randomness (0.0 to 1.0)
}

Response:

{
  "message": "Response generated successfully",
  "response": "I find the product quite interesting. As someone who values efficiency, I appreciate the intuitive interface and how it streamlines my workflow. However, I'm concerned about the price point, which seems high compared to similar options on the market.",
  "message_id": "message_id"
}

How AI Response Generation Works

The system generates realistic persona responses by:

1. Using the persona's demographic details, personality traits, goals, and frustrations
2. Including the full discussion guide text
3. Taking up to 50 most recent conversation messages for context
4. Processing the current topic/question
5. Generating a response in the persona's authentic voice

The current_topic parameter can be any text: a moderator question, a specific prompt, or a summary of discussion points. The AI will respond as if the persona is directly addressing this topic.

Default User

A default user with the following credentials is automatically created:

• Username: user
• Password: pass
• Role: admin