# Persona Chat System Specification

**Status**: ✅ Complete **Version**: 1.0 **Last Updated**: December 2025
**Author**: Engineering Team

## 1. Overview

### 1.1 Summary

The Persona Chat System enables users to have text and voice conversations with
AI-powered teacher personas representing diverse wisdom traditions. Each persona
has unique teaching styles, knowledge domains, and personality characteristics.

### 1.2 Business Context

- **Goal**: Provide personalized spiritual guidance from authentic tradition
  perspectives
- **Users**: Seekers, students, practitioners across experience levels
- **Value**: Accessible wisdom teaching without barriers of geography or cost

### 1.3 Success Metrics

| Metric                 | Target      |
| ---------------------- | ----------- |
| Response latency (p50) | < 2 seconds |
| Response latency (p95) | < 4 seconds |
| User satisfaction      | > 4.2/5.0   |
| Session completion     | > 80%       |
| Return rate (7-day)    | > 40%       |

## 2. Requirements

### 2.1 Functional Requirements

| ID    | Requirement                              | Priority |
| ----- | ---------------------------------------- | -------- |
| FR-1  | Users can select from available personas | P0       |
| FR-2  | Users can send text messages             | P0       |
| FR-3  | Personas respond with streaming text     | P0       |
| FR-4  | Personas cite sources when relevant      | P0       |
| FR-5  | Users can adjust response depth          | P1       |
| FR-6  | Users can adjust response tone           | P1       |
| FR-7  | Conversation history is preserved        | P0       |
| FR-8  | Users can continue past conversations    | P1       |
| FR-9  | Users can request audio responses        | P1       |
| FR-10 | Personas maintain session context        | P0       |

### 2.2 Non-Functional Requirements

| ID    | Requirement       | Target             |
| ----- | ----------------- | ------------------ |
| NFR-1 | Availability      | 99.9% uptime       |
| NFR-2 | Response time     | p50 < 2s, p95 < 4s |
| NFR-3 | Concurrent users  | 10,000+            |
| NFR-4 | Context window    | 128k tokens        |
| NFR-5 | Citation accuracy | > 95%              |

## 3. User Stories

### 3.1 Core Stories

**US-1: Start Conversation**

> As a seeker, I want to start a conversation with a Zen Master persona so that
> I can receive guidance on meditation practice.

**Acceptance Criteria**:

- [ ] User can browse available personas
- [ ] User can view persona description and style
- [ ] User can start new conversation with selected persona
- [ ] First message from persona acknowledges user

**US-2: Continue Conversation**

> As a student, I want to continue a previous conversation so that I can build
> on our prior discussion.

**Acceptance Criteria**:

- [ ] User can view conversation history
- [ ] User can select past conversation
- [ ] Persona has context of previous messages
- [ ] Conversation picks up naturally

**US-3: Get Cited Response**

> As a researcher, I want responses to include source citations so that I can
> verify information and explore further.

**Acceptance Criteria**:

- [ ] Citations appear inline or as references
- [ ] Citations link to original sources
- [ ] Citation confidence scores are shown
- [ ] User can enable/disable citation mode

## 4. Technical Design

### 4.1 Architecture

```
┌─────────┐     ┌─────────┐     ┌──────────────┐     ┌─────────────┐
│ Client  │────>│   BFF   │────>│ Conversation │────>│     AI      │
│         │<────│         │<────│   Service    │<────│   Service   │
└─────────┘     └─────────┘     └──────────────┘     └─────────────┘
                                        │                   │
                                        ▼                   ▼
                                ┌──────────────┐     ┌─────────────┐
                                │  PostgreSQL  │     │     RAG     │
                                │  (Messages)  │     │  Pipeline   │
                                └──────────────┘     └─────────────┘
```

### 4.2 API Endpoints

**Create Chat Turn**

```http
POST /v1/chat
Authorization: Bearer <token>
Content-Type: application/json

{
  "conversation_id": "uuid",      // optional, creates new if omitted
  "persona": "zen_master",
  "input": {
    "text": "How do I quiet my mind during meditation?"
  },
  "options": {
    "cite": true,
    "depth": "practical",
    "stream": true
  }
}
```

**Response (SSE)**

```
event: token
data: {"text":"The"}

event: token
data: {"text":" mind"}

event: citation
data: {"source":"Shunryu Suzuki, Zen Mind Beginner's Mind","confidence":0.92}

event: done
data: {"message_id":"uuid","latency_ms":1834}
```

### 4.3 Data Model

**Conversations Table**

```sql
conversations (
    id UUID PRIMARY KEY,
    user_id UUID,
    persona_key VARCHAR(50),
    created_at TIMESTAMPTZ,
    updated_at TIMESTAMPTZ,
    metadata JSONB
)
```

**Messages Table**

```sql
messages (
    id UUID PRIMARY KEY,
    conversation_id UUID,
    role VARCHAR(20),
    text_ref TEXT,
    citations JSONB,
    metrics JSONB,
    created_at TIMESTAMPTZ
)
```

### 4.4 Persona Configuration

```json
{
  "key": "zen_master",
  "title": "Zen Master",
  "tradition": "Zen Buddhism",
  "style_config": {
    "teaching_style": "socratic",
    "uses_koans": true,
    "directness": 0.8,
    "humor": 0.3,
    "formality": 0.6
  },
  "system_prompt": "You are a Zen master...",
  "voice_id": "calm_male_1",
  "policy_tags": ["buddhist", "meditation"]
}
```

## 5. UX/UI Considerations

### 5.1 Chat Interface

- Message bubbles with clear user/assistant distinction
- Typing indicator during streaming
- Citation panel (expandable)
- Persona avatar and name visible
- Quick action buttons ("Explain more", "Simpler please")
- Depth/tone sliders

### 5.2 Persona Selection

- Grid/list view of personas
- Preview cards with tradition and style
- Search and filter by tradition
- "Try conversation" sample

## 6. Security Considerations

### 6.1 Content Safety

- All responses pass through moderation service
- Medical/mental health disclaimers injected when relevant
- Crisis guidance for distress signals
- Cultural sensitivity validation

### 6.2 Data Privacy

- Conversation data encrypted at rest
- User can delete conversation history
- PII not stored in logs
- Consent required for voice cloning

## 7. Testing Strategy

### 7.1 Test Types

| Type              | Coverage Target |
| ----------------- | --------------- |
| Unit tests        | 90%             |
| Integration tests | 80%             |
| E2E tests         | Critical paths  |
| Load tests        | 10k concurrent  |
| Security tests    | OWASP Top 10    |

### 7.2 Acceptance Criteria

- [ ] All personas respond within SLA
- [ ] Citations are accurate and verifiable
- [ ] Conversations persist across sessions
- [ ] Moderation catches unsafe content
- [ ] Voice responses sync with text

## 8. Rollout Plan

### 8.1 Feature Flags

| Flag                          | Description        |
| ----------------------------- | ------------------ |
| `persona_chat_enabled`        | Master enable      |
| `persona_chat_citations`      | Citation mode      |
| `persona_chat_voice`          | Voice responses    |
| `persona_chat_depth_controls` | Depth/tone sliders |

### 8.2 Phased Rollout

1. **Alpha**: Internal team only
2. **Beta**: 5% of users, Zen/Stoic personas only
3. **GA Phase 1**: 25% of users, all MVP personas
4. **GA Phase 2**: 100% of users

## Related Documents

- [Voice Chat Spec](./voice-chat-spec.md)
- [Lecture Generation Spec](./lecture-generation-spec.md)
- [Moderation Service](../architecture.md#moderation-service)
