# alfiinyang/personalityai architecture

> Architecture diagram of the GitHub repository alfiinyang/personalityai, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-09-26). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/alfiinyang/personalityai
- Repository: https://github.com/alfiinyang/personalityai

## Overview

##### Project Type and Purpose
- This is an open-source Python library (“PersonalityAI”) that provides a framework for building composite AI agents.
- It lets you define multiple “Persona” instances that each call out to an external LLM, then uses a “Referee” persona to mediate and produce a single coherent reply.
- The `experiments/` subpackage offers utilities to collect and analyze persona outputs for research or tuning.

##### File-Structure Analysis
- Top-level:
– `setup.py`, `requirements.txt` → packaging and dependency declarations.
– `README.md`, `LICENSE.txt` → documentation & licensing.
- Core package `personality/`:
– `create.py` → contains main classes `Person`, `Persona`, plus orchestration logic (parallel invocation, referee mediation, history management).
– `experiments/collectors.py` → utilities (`response_collector`, `ref_response_collector`) that interface with `Person` to extract per-persona or referee outputs.
- No separate “frontend” or “backend”—this is a library whose “frontend” API is the Python import surface, and whose “backend” is the orchestration of LLM calls.

##### README Insights
- **Core components**: `Person` (agent orchestrator), `Persona` (role-specific LLM wrapper), external LLM-client abstraction, conversation history.
- **Use cases**: defining personas, running parallel neural calls, synthesizing responses, experimental analysis.

1. User (invokes library API)
2. Person Orchestrator
3. Persona Instances (Angel, Devil, …)
4. Referee Persona
5. External LLM Client (OpenAI, Google, Anthropic, etc.)
6. Conversation History Store
7. Experimental Utilities Module
8. Packaging/Config (setup.py, requirements)
- User → Person
- Person → each Persona → LLM Client → Persona’s Thought Bubble → Person
- Person → Referee Persona → LLM Client → Referee’s Decision → Person
- Person → returns final response → User
- Person ↔ Conversation History (read/write)
- Experimental Utilities ← Person + History → analytics output
c. Architectural Patterns & Principles:
– Mediator Pattern: `Person` mediates between user, personas, and referee.
– Strategy Pattern: each `Persona` encapsulates a distinct prompting strategy/function.
– Pipeline (fan-out/fan-in): parallel persona calls then merge through referee.
– Dependency Injection: external LLM client passed into `Persona`/`Person`.
d. Key Technologies & Libraries:
– Python 3.x packaging (`setup.py`, `requirements.txt`)
– LLM clients (OpenAI SDK, Google Generative AI, Anthropic)
– Standard Python modules (`asyncio` if used for parallelism)
– Experiment-focused code under `personality/experiments`

##### Elements
- External systems (LLM service) in another
– **Configuration Layer**: represent packaging/config files (setup.py, requirements.txt) as annotations to show distribution and installation.

1. **User** on the far left.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Global entities
    User["User"]:::external

    %% Core Orchestration
    subgraph "Core Orchestration"
        Person["Person Orchestrator"]:::core
    end

    %% Personas and Referee
    subgraph "Personas & Referee"
        Personas["Persona Instances"]:::persona
        Referee["Referee Persona"]:::persona
    end

    %% External Systems
    subgraph "External Systems"
        LLM["LLM Client"]:::external
    end

    %% History Store
    subgraph "History"
        HistoryStore["Conversation History Store"]:::storage
    end

    %% Experimental Utilities
    subgraph "Experimental Utilities"
        ExpInit["__init__.py"]:::utility
        ExpCollectors["collectors.py"]:::utility
        AnalysisOutput["Analysis Output"]:::utility
    end

    %% Packaging & Documentation
    subgraph "Packaging & Config / Docs"
        Setup["setup.py"]:::config
        Requirements["requirements.txt"]:::config
        Readme["README.md"]:::config
        License["LICENSE.txt"]:::config
    end

    %% Connections
    User -->|"invokes API"| Person
    Person -->|"prompt+context"| Personas
    Personas -->|"calls"| LLM
    LLM -->|"thought bubble"| Personas
    Personas -->|"outputs"| Person

    Person -->|"prompt+context"| Referee
    Referee -->|"calls"| LLM
    LLM -->|"decision"| Referee
    Referee -->|"decision output"| Person

    Person -->|"final response"| User

    Person <-->|"read/write"| HistoryStore

    Person -->|"feeds"| ExpCollectors
    HistoryStore -->|"feeds"| ExpCollectors
    ExpCollectors -->|"produces"| AnalysisOutput

    %% Click Events
    click Person "https://github.com/alfiinyang/personalityai/blob/main/personality/create.py"
    click Personas "https://github.com/alfiinyang/personalityai/blob/main/personality/create.py"
    click Referee "https://github.com/alfiinyang/personalityai/blob/main/personality/create.py"
    click HistoryStore "https://github.com/alfiinyang/personalityai/blob/main/personality/create.py"
    click ExpCollectors "https://github.com/alfiinyang/personalityai/blob/main/personality/experiments/collectors.py"
    click ExpInit "https://github.com/alfiinyang/personalityai/blob/main/personality/experiments/__init__.py"
    click Setup "https://github.com/alfiinyang/personalityai/blob/main/setup.py"
    click Requirements "https://github.com/alfiinyang/personalityai/blob/main/requirements.txt"
    click Readme "https://github.com/alfiinyang/personalityai/blob/main/README.md"
    click License "https://github.com/alfiinyang/personalityai/blob/main/LICENSE.txt"

    %% Styles
    classDef core fill:#D0E8FF,stroke:#0366D6,stroke-width:2px
    classDef persona fill:#E8F0FE,stroke:#1A73E8,stroke-width:2px
    classDef external fill:#FFE8D0,stroke:#D97706,stroke-width:2px
    classDef storage fill:#E8FFE8,stroke:#15803D,stroke-width:2px
    classDef utility fill:#FFF8DC,stroke:#D4A017,stroke-width:2px
    classDef config fill:#F0F0F0,stroke:#6B7280,stroke-width:2px
```
