# Psyche Persona Service

Persona management service for the Psyche AI Virtual Assistant Platform.

## Overview

The Persona Service provides comprehensive AI agent persona management
capabilities:

- **Identity Management**: CRUD operations, versioning, templates
- **Personality Configuration**: Big Five model, communication styles
- **Expertise Configuration**: Domains, knowledge boundaries, scope limits
- **Memory Systems**: Facts, opinions, story memory, user interactions
- **Behavioral Constraints**: Response validation, drift prevention
- **Asset Management**: Avatar and voice profile creation, training

## Architecture

The service consists of two packages:

```
src/
├── persona_service/      # FastAPI REST API
│   ├── __init__.py
│   └── main.py           # API endpoints
└── persona_system/       # Core business logic
    ├── __init__.py       # PersonaSystem unified interface
    ├── identity/         # Identity management
    ├── personality/      # Personality configuration
    ├── expertise/        # Expertise configuration
    ├── memory/           # Memory systems
    ├── constraints/      # Behavioral constraints
    ├── drift/            # Drift detection
    └── assets/           # Avatar and voice assets
```

## API Endpoints

### Health & Status

```
GET /health              # Service health
GET /ready               # Readiness check
```

### Templates

```
GET /templates/personas      # List persona templates
GET /templates/personalities # List personality presets
GET /templates/domains       # List expertise domain templates
GET /templates/constraints   # List constraint presets
```

### Persona CRUD

```
POST /personas                           # Create persona
GET /personas/{id}                       # Get persona
PUT /personas/{id}                       # Update persona
DELETE /personas/{id}                    # Delete persona
GET /personas                            # List personas
POST /personas/{id}/clone                # Clone persona
POST /personas/from-template/{template}  # Create from template
```

### Personality

```
GET /personas/{id}/personality           # Get personality config
POST /personas/{id}/personality          # Configure personality
```

### Expertise

```
GET /personas/{id}/expertise             # Get expertise config
POST /personas/{id}/expertise            # Configure expertise
POST /personas/{id}/expertise/domains    # Add domain
POST /personas/{id}/expertise/evaluate   # Evaluate query expertise
```

### Memory

```
POST /personas/{id}/memories/facts       # Add fact
POST /personas/{id}/memories/opinions    # Add opinion
POST /personas/{id}/memories/interactions  # Record interaction
POST /personas/{id}/memories/retrieve    # Retrieve memories
```

### Constraints

```
GET /personas/{id}/constraints           # Get constraints
POST /personas/{id}/constraints          # Configure constraints
POST /personas/{id}/constraints/check-response  # Validate response
POST /personas/{id}/constraints/check-drift     # Check drift
```

### Assets

```
POST /personas/{id}/avatars              # Create avatar
POST /personas/{id}/voices               # Create voice
POST /avatars/{id}/train                 # Train avatar
POST /voices/{id}/train                  # Train voice
POST /personas/{id}/assets/link          # Link assets
GET /personas/{id}/assets                # Get asset bundle
```

### System Prompt

```
POST /personas/{id}/system-prompt        # Generate system prompt
```

## Persona System

### PersonaSystem Class

The unified interface for persona management:

```python
from persona_system import PersonaSystem

# Create system
system = PersonaSystem()

# Create a persona
persona = system.create_persona(
    name="Alex",
    role="assistant",
    personality_preset="warm_professional",
    expertise_domains=[{"template_id": "customer_support"}],
)

# Configure personality
system.configure_personality(
    persona.id,
    big_five={"openness": 0.7, "agreeableness": 0.9},
)

# Add memory
system.add_fact(
    persona.id,
    key="company",
    value="Acme Corp",
)

# Generate system prompt
prompt = system.generate_system_prompt(persona.id)
```

### Personality Presets

| Preset                  | Description               |
| ----------------------- | ------------------------- |
| `warm_professional`     | Friendly and professional |
| `technical_expert`      | Precise, detail-oriented  |
| `empathetic_counselor`  | Supportive, understanding |
| `creative_collaborator` | Imaginative, enthusiastic |
| `efficient_executor`    | Direct, task-focused      |

### Expertise Domain Templates

| Template            | Description                      |
| ------------------- | -------------------------------- |
| `customer_support`  | Customer service and support     |
| `technical_support` | Technical troubleshooting        |
| `healthcare`        | Health information (non-medical) |
| `education`         | Learning and instruction         |
| `finance`           | Financial information            |

### Constraint Presets

| Preset         | Description                      |
| -------------- | -------------------------------- |
| `professional` | Professional workplace standards |
| `transparent`  | Open about AI nature             |
| `creative`     | More flexible expression         |
| `strict`       | Highly constrained responses     |

## Configuration

### Environment Variables

| Variable       | Description           | Default                |
| -------------- | --------------------- | ---------------------- |
| `SERVICE_PORT` | API port              | 8009                   |
| `DATABASE_URL` | PostgreSQL connection | postgresql://...       |
| `REDIS_URL`    | Redis connection      | redis://localhost:6379 |
| `QDRANT_URL`   | Vector DB connection  | http://localhost:6333  |
| `LOG_LEVEL`    | Log level             | INFO                   |

## Development

### Using Nx

```bash
# Install dependencies
nx install psyche-persona-service

# Run development server
nx serve psyche-persona-service

# Run production server
nx serve-prod psyche-persona-service

# Run tests
nx test psyche-persona-service
nx test-unit psyche-persona-service
nx test-integration psyche-persona-service

# Run tests with coverage
nx test-cov psyche-persona-service

# Lint and format
nx lint psyche-persona-service
nx format psyche-persona-service

# Docker
nx docker-build psyche-persona-service
nx docker-run psyche-persona-service
```

### Direct Poetry Commands

```bash
cd apps/psyche/persona-service
poetry install
poetry run pytest
poetry run uvicorn persona_service.main:app --reload --host 0.0.0.0 --port 8009
```

## Performance Targets

| Operation             | Target Latency |
| --------------------- | -------------- |
| Create persona        | < 50ms         |
| Get persona           | < 10ms         |
| Configure personality | < 20ms         |
| Add memory            | < 15ms         |
| Retrieve memories     | < 100ms        |
| Generate prompt       | < 200ms        |
| Check drift           | < 50ms         |

## License

Proprietary - Oshun Platform