OpenPersona

Advanced Multi-Agent Personality Intelligence System

A comprehensive, production-ready toolkit for developing, evaluating, and managing AI personalities using OpenAI's Agents SDK, GPT-4o, and advanced AI engineering patterns.

Key Features

Advanced Evaluation System

• Multi-dimensional Analysis: Personality consistency, coherence, and authenticity scoring
• Real-time Monitoring: Live personality drift detection and behavioral analysis
• Comparative Metrics: Cross-personality evaluation and benchmarking capabilities
• Custom Evaluation Frameworks: Extensible evaluation criteria and scoring systems

Intelligent Agent Architecture

• OpenAI Agents SDK Integration: Native support for structured agent interactions
• Multi-Agent Coordination: Sophisticated inter-agent communication and collaboration
• Dynamic Personality Injection: Runtime personality trait modification and adaptation
• Context-Aware Responses: Personality-driven contextual response generation

Comprehensive Analytics

• Real-time Dashboards: Live personality metrics and performance monitoring
• Advanced Visualizations: Multi-dimensional personality trait mapping and evolution tracking
• Predictive Analysis: Personality consistency forecasting and drift prediction
• Export Capabilities: Comprehensive reporting and data export functionality

Production-Ready Architecture

• Scalable FastAPI Backend: High-performance, async API with automatic documentation
• SQLite/PostgreSQL Support: Flexible database backend with migration support
• Docker Containerization: Complete containerized deployment with orchestration
• Comprehensive Testing: Unit, integration, and performance test suites
• CI/CD Pipeline: Automated testing, building, and deployment workflows

Quick Start

# Clone the repository
git clone https://github.com/llamasearchai/OpenPersona.git
cd OpenPersona

# Set up Python environment
cd python
poetry install

# Configure environment
cp env.example .env
# Edit .env with your OpenAI API key and other settings

# Run the application
poetry run python run_enhanced.py

# Visit http://localhost:8001/docs for API documentation

Installation

Prerequisites

• Python 3.11+ with Poetry
• Node.js 18+ with npm/yarn (for UI components)
• Rust 1.70+ (for performance-critical components)
• Docker & Docker Compose (for containerized deployment)
• OpenAI API Key (for AI-powered features)

Development Setup

1. Clone and Setup

   git clone https://github.com/llamasearchai/OpenPersona.git
   cd OpenPersona

2. Backend Setup

   cd python
   poetry install
   cp env.example .env
   # Configure your .env file

3. Frontend Setup

   cd ui
   npm install

4. Database Setup

   cd python
   poetry run python -c "from persona_agent_backend.utils.database import create_tables; create_tables()"

Configuration

Environment Variables

# OpenAI Configuration
OPENAI_API_KEY=your_openai_api_key_here
OPENAI_MODEL=gpt-4o
OPENAI_MAX_TOKENS=4000

# Database Configuration
DATABASE_URL=sqlite:///./openpersona.db
# or for PostgreSQL:
# DATABASE_URL=postgresql://user:password@localhost/openpersona

# API Configuration
API_HOST=0.0.0.0
API_PORT=8001
DEBUG=true
LOG_LEVEL=INFO

# Security
SECRET_KEY=your-secret-key-here
ACCESS_TOKEN_EXPIRE_MINUTES=30

# Features
ENABLE_ANALYTICS=true
ENABLE_CACHING=true
CACHE_TTL=3600

Advanced Configuration

The system supports extensive configuration through:

• Environment Variables: Runtime configuration
• Configuration Files: Structured YAML/JSON configuration
• Database Settings: Advanced database tuning
• Logging Configuration: Detailed logging setup

API Documentation

Core Endpoints

Personality Management

# Create a personality profile
POST /api/personalities
{
  "name": "Analytical Assistant",
  "description": "Logical, data-driven personality",
  "traits": {
    "openness": 0.8,
    "conscientiousness": 0.9,
    "extraversion": 0.4,
    "agreeableness": 0.7,
    "neuroticism": 0.2
  }
}

# Get all personalities
GET /api/personalities

# Update personality
PUT /api/personalities/{personality_id}

Agent Operations

# Create an agent
POST /api/agents
{
  "name": "DataBot",
  "personality_id": "personality-abc123",
  "system_prompt": "You are a data analysis assistant..."
}

# Send message to agent
POST /api/agents/{agent_id}/message
{
  "content": "Analyze this dataset",
  "context": "Previous conversation context"
}

Evaluation System

# Run personality evaluation
POST /api/evaluations
{
  "conversation_id": "conv-123",
  "evaluation_type": "consistency",
  "criteria": ["personality_adherence", "response_quality"]
}

# Get evaluation results
GET /api/evaluations/{evaluation_id}

Interactive Documentation

Visit /docs when running the server for complete interactive API documentation with:

• Live API Testing: Test endpoints directly from the browser
• Schema Documentation: Complete request/response schemas
• Authentication Examples: Authentication flow examples
• Error Handling: Comprehensive error response documentation

Testing

Running Tests

# Run all tests
cd python
poetry run pytest

# Run with coverage
poetry run pytest --cov=persona_agent_backend

# Run specific test categories
poetry run pytest tests/test_evaluations.py
poetry run pytest -m integration

Test Categories

• Unit Tests: Individual component testing
• Integration Tests: End-to-end workflow testing
• Performance Tests: Load and stress testing
• API Tests: Comprehensive API endpoint testing

Deployment

Docker Deployment

# Build and run with Docker Compose
docker-compose up --build

# Production deployment
docker-compose -f docker-compose.prod.yml up -d

Cloud Deployment

The system supports deployment on:

• AWS: ECS, EKS, Lambda
• Google Cloud: GKE, Cloud Run
• Azure: AKS, Container Instances
• DigitalOcean: App Platform, Kubernetes

Configuration Management

• Environment-based: Different configs for dev/staging/prod
• Secret Management: Secure handling of API keys and credentials
• Health Checks: Comprehensive health monitoring
• Logging: Structured logging with log aggregation

Monitoring

Metrics and Analytics

The system provides comprehensive monitoring through:

• Application Metrics: Response times, error rates, throughput
• Business Metrics: Personality evaluation scores, agent performance
• Infrastructure Metrics: Resource usage, database performance
• Custom Dashboards: Tailored monitoring views

Health Checks

# System health
GET /health

# Detailed system status
GET /api/system/stats

# Database health
GET /api/system/db-health

Architecture

System Components

1. FastAPI Backend: High-performance async API server
2. SQLite/PostgreSQL: Flexible data persistence layer
3. OpenAI Integration: Native Agents SDK integration
4. Evaluation Engine: Multi-dimensional personality analysis
5. Analytics Dashboard: Real-time monitoring and insights
6. Docker Environment: Containerized deployment system

Design Patterns

• Repository Pattern: Clean data access layer
• Factory Pattern: Dynamic personality and agent creation
• Observer Pattern: Real-time event monitoring
• Strategy Pattern: Pluggable evaluation algorithms

Performance Optimization

• Async Operations: Non-blocking I/O for high concurrency
• Database Optimization: Efficient queries and indexing
• Caching Layer: Redis-based response caching
• Connection Pooling: Optimized database connections

Contributing

We welcome contributions! Please see our Contributing Guide for details.

Development Workflow

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests for new functionality
5. Ensure all tests pass
6. Submit a pull request

Code Standards

• Python: Follow PEP 8 with Black formatting
• TypeScript: ESLint + Prettier configuration
• Rust: Standard Rust formatting with Clippy
• Documentation: Comprehensive docstrings and comments

License

This project is licensed under the MIT License - see the LICENSE file for details.

Support

• Documentation: Comprehensive guides and API docs
• Community: GitHub Discussions and Issues
• Email: NikJois@llamasearch.ai

---

Built with care for the AI personality evaluation community