Eve library

Persona Chat System Specification

Guide

Revision 1

On this page

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#

text
┌─────────┐     ┌─────────┐     ┌──────────────┐     ┌─────────────┐
│ 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)

text
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