PersonaMap

PersonaMap is designed to augment the functionality of conversational AI systems.

It classifies user interests — which we call personas — using vector embeddings.

Instead of raw text, the system represents conversations as vectors to capture patterns in user behavior. PersonaMap then decomposes conversation history into multiple personas and visualizes them through an interactive interface.

Overall, PersonaMap turns raw conversations into interpretable persona representations, enabling better personalization and user control.

Why PersonaMap?

Modern conversational AI tools use persistent memory for personalization, but they still have limitations:

• AI models can over-eagerly reference memories and use unrelated context.
• Memory is often limited to chat content and misses meta-behavior like response preferences.
• Users have limited visibility and control over how memories are formed and used.

PersonaMap addresses these issues by transforming conversations into vector embeddings and generating multiple personas representing different aspects of the user. These personas improve contextual awareness by allowing the system to focus on the most relevant persona during a conversation, while also supporting applications such as content recommendation.

A key goal is transparency and control: users can view how they are modeled and interact with their personas through a user interface.

System overview

• Raw data comes from conversations and is treated as prompt-response pairs (PR pairs).
• Each PR pair is converted into structured JSON and then transformed with an embedding model into a vector representation.
• The system operates in latent vector space to cluster and extract persona structures from conversation history.
• At runtime, the Chatbot loads previous conversation messages as context, generates a response via the OpenAI gpt-5.4-nano API, appends it to the database, and updates embeddings.
• Conversation embeddings, PR-pair embeddings, and persona embeddings are refreshed using OpenAI's text-embedding-small model and a K-means algorithm.
• The GUI interacts directly with the database to show conversations, messages, and extracted personas.

Project structure

• PersonaMap_GUI.py — main Qt GUI implementation for the interactive interface.
• src/app.py — application entry point that initializes the Chatbot, database, and UI.
• src/chatbot/chatbot.py — Chatbot logic, response generation, and integration with LLMs.
• src/database/manager.py — data loading, conversation history, persona management, and embedding handling.
• src/utils/kmeans.py — clustering utilities used for persona extraction.
• data/ — runtime CSV files for conversations, messages, pair embeddings, and personas.
• generate_sample_data.py — helper script to generate placeholder data for testing.
• requirements.txt — Python dependency list.
• .env — local environment configuration for OpenAI API keys.

Requirements

• Python 3.11+ recommended
• numpy
• pandas
• openai
• python-dotenv
• tqdm
• PySide6

Install dependencies with:

pip install -r requirements.txt

Running the GUI

1. Create a .env file in the repository root with your OpenAI API key:

OPENAI_API_KEY=your_api_key_here

2. Prepare the ./data/ directory with sample data files.

3. Start the GUI from the repository root:

python -m src.app

The app loads data from ./data/ and displays conversations, messages, personas, and persona selection.

Data files

The project expects these CSV files in ./data/:

• conversations.csv
• messages.csv
• pair_embeddings.csv
• personas.csv

Expected columns

conversations.csv

• id
• title
• last_modified_at
• summary
• embedding

messages.csv

• id
• conversation_id
• author
• timestamp
• content

pair_embeddings.csv

• id
• user_message_id
• ai_message_id
• embedding
• augmented_embedding

personas.csv

• id
• name
• desc
• source_pair_ids
• centroid_embedding
• weight

Currently the directory has AI generated sample data.