Persona Data Model

Persona Data Model

When you request a user's persona through the Onairos API, the response includes a structured personality profile generated from their connected platform data. This page documents the full response schema.

Response Structure

The response is wrapped in a DataAnalysis envelope containing the personality traits and metadata:

{
  "DataAnalysis": {
    "personality_traits": {
      "positive_traits": {
        "Creative Problem Solving": 92,
        "Science and Technology Enthusiasm": 88,
        "Community Engagement": 85,
        "Visual Storytelling": 78
      },
      "traits_to_improve": {
        "Structured Planning": 45,
        "Financial Awareness": 38,
        "Routine Consistency": 32
      },
      "user_summary": "You are a curious, creative individual...",
      "top_traits_explanation": "Your positive traits reflect a strong pattern...",
      "archetype": "Creative Explorer",
      "nudges": [
        { "text": "You're highly analytical — try journaling a decision you're mulling over." },
        { "text": "Consider dedicating time to purely enjoyable, less analytical activities — it can refresh your perspective." }
      ]
    }
  },
  "metadata": {
    "total_items_analyzed": 847,
    "items_sampled": 420,
    "total_liked": 295,
    "total_disliked": 125,
    "chunks_processed": 4,
    "total_chunks": 6,
    "coverage": "66.7%",
    "platform_breakdown": {
      "reddit": { "liked": 180, "disliked": 60 },
      "youtube": { "liked": 115, "disliked": 65 }
    }
  }
}

Fields Reference

personality_traits

Field	Type	Description
positive_traits	Record<string, number>	8-20 traits the user shows strength in, each scored 70-100
traits_to_improve	Record<string, number>	8-20 traits the user shows less engagement with, each scored 1-69
user_summary	string	2-3 paragraph natural language description written in second person ("you are...", "you tend to...") describing the user's personality and interests
top_traits_explanation	string	1-2 paragraph explanation written in second person of why these specific traits were identified
archetype	string	A 2-3 word label in "Adjective Role" format summarizing the user's personality type (e.g. "Creative Explorer", "Strategic Analyst", "Cultural Historian"). The noun is always a person role. Designed to be displayed as "The [archetype]".
nudges	Array<{ text: string }>	5-8 personalized, actionable suggestions based on the user's actual traits and interests. Each nudge is a short, friendly sentence written in second person. Includes strength-based tips, growth suggestions from traits_to_improve, and exploration prompts tied to their interests.

metadata

Field	Type	Description
total_items_analyzed	number	Total content items available from connected platforms
items_sampled	number	Number of items selected after platform-weighted sampling
total_liked	number	Count of positively engaged content items
total_disliked	number	Count of negatively engaged or rejected content items
chunks_processed	number	Number of data chunks processed during analysis (max 4)
total_chunks	number	Total chunks available from the dataset
coverage	string	Percentage of total data analyzed (e.g. "66.7%")
platform_breakdown	object	Per-platform counts of liked/disliked items included in analysis

Trait Scoring

Trait scores are integers that indicate the strength of each identified trait:

Category	Score Range	Meaning
Positive Traits	70 - 100	Traits the user consistently demonstrates through their content engagement
Traits to Improve	1 - 69	Behavioral tendencies revealed by data patterns (e.g. narrow focus, overthinking), not missing interests

Archetype

The archetype field provides a concise personality label in "Adjective Role" format:

• Always 2-3 words (e.g. "Creative Explorer", "Strategic Analyst", "Cultural Historian")
• The noun is always a person role (Thinker, Explorer, Analyst, Creator, etc.)
• Designed for display as "The [archetype]" — e.g. "The Creative Explorer"
• Derived from the dominant patterns across all positive traits

Nudges

The nudges array contains personalized, actionable suggestions tailored to the user's profile:

• 5-8 nudges per response, each as an object with a text field
• Written in second person with a warm, friendly tone
• Three categories of nudges:
  • Strength-based tips — leverage existing positive traits (e.g. "You're highly analytical — try journaling a decision you're mulling over")
  • Growth suggestions — based on traits_to_improve (e.g. "To combat analysis paralysis, set time limits for your research")
  • Exploration prompts — tied to specific interests from their data (e.g. "Explore the concept of systems thinking by reading about feedback loops")

// Display nudges in your UI
const nudges = persona.DataAnalysis.personality_traits.nudges;
nudges.forEach(nudge => {
  console.log(nudge.text);
});
// "You're highly analytical — try journaling a decision you're mulling over."
// "Consider dedicating time to purely enjoyable activities — it refreshes perspective."
// ...

User Summary & Traits Explanation

The user_summary field contains a natural language description of the user based on their engagement patterns. It covers:

• Primary interests and content preferences
• Cross-platform behavioral patterns
• How liked and disliked content shapes the overall profile

The top_traits_explanation provides the reasoning behind trait selection, explaining which content patterns led to each trait.

Both fields are written in second person ("you are...", "you tend to...") and are useful for displaying a human-readable persona overview to end users or for feeding into recommendation engines and LLMs as context.

Evidence Mode

When evidence mode is enabled, traits include additional detail with emoji identifiers and evidence citations from the user's actual content:

{
  "positive_traits": {
    "Space Exploration Interest": {
      "score": 95,
      "emoji": "🚀",
      "evidence": "You consistently engage with NASA and SpaceX content on YouTube"
    },
    "Coding Enthusiasm": {
      "score": 88,
      "emoji": "💻",
      "evidence": "Your Reddit activity shows frequent visits to programming subreddits"
    }
  },
  "traits_to_improve": {
    "Narrow Focus": {
      "score": 35,
      "emoji": "🔍",
      "evidence": "Your content is almost entirely strategy and tech with little variety"
    }
  }
}

Evidence Mode Fields (per trait)

Field	Type	Description
score	number	Same scoring as standard mode (70-100 for positive, 1-69 for improve)
emoji	string	A single emoji representing the trait (e.g. 🚀 for space, 🍳 for cooking, 🎵 for music)
evidence	string	A brief phrase (8-15 words) citing specific content from the user's data, written in second person. References the platform source when available.

Using the Data

const response = await onairos.personas.get('user_123');
const traits = response.DataAnalysis.personality_traits;

// Sort positive traits by score for prioritized personalization
const topTraits = Object.entries(traits.positive_traits)
  .sort(([, a], [, b]) => b - a)
  .slice(0, 5);

console.log('Top 5 traits:', topTraits);
// [["Creative Problem Solving", 92], ["Science Enthusiasm", 88], ...]

// Display the user's archetype
console.log(`The ${traits.archetype}`);
// "The Creative Explorer"

// Show personalized nudges
traits.nudges.forEach(nudge => console.log(nudge.text));

// Use user_summary for display or LLM context
console.log(traits.user_summary);

// Avoid content matching traits_to_improve
const avoidTopics = Object.keys(traits.traits_to_improve)
  .filter(trait => traits.traits_to_improve[trait] < 30);

// For evidence mode responses, access detailed trait info
// const traitDetail = traits.positive_traits["Space Exploration Interest"];
// console.log(traitDetail.emoji, traitDetail.score, traitDetail.evidence);

Best Practices

• Use the top 3-5 positive traits for content recommendations — these have the strongest signal
• Respect traits_to_improve as behavioral tendencies, not missing interests — they describe patterns like narrow focus or overthinking, not absent hobbies
• Display the archetype as a quick personality label — prefix with "The" for display (e.g. "The Creative Explorer")
• Surface nudges to users as personalized tips — they are specific to the user's actual data and interests
• Display user_summary to give users transparency into how their persona is understood
• Check metadata.coverage to understand data completeness — higher coverage means more reliable traits
• Consider platform_breakdown to understand which platforms contributed most to the profile
• Traits update over time as users connect more platforms or engage with new content
• Handle both trait formats — check if trait values are numbers (standard) or objects (evidence mode) when building dynamic UIs

TypeScript Types

// Standard mode: trait values are plain scores
interface PersonalityTraitsStandard {
  positive_traits: Record<string, number>;
  traits_to_improve: Record<string, number>;
  user_summary: string;
  top_traits_explanation: string;
  archetype: string;
  nudges: Nudge[];
}

// Evidence mode: trait values include emoji and evidence
interface TraitDetail {
  score: number;
  emoji: string;
  evidence: string;
}

interface PersonalityTraitsEvidence {
  positive_traits: Record<string, TraitDetail>;
  traits_to_improve: Record<string, TraitDetail>;
  user_summary: string;
  top_traits_explanation: string;
  archetype: string;
  nudges: Nudge[];
}

interface Nudge {
  text: string;
}

type PersonalityTraits = PersonalityTraitsStandard | PersonalityTraitsEvidence;

interface PlatformBreakdown {
  [platform: string]: {
    liked: number;
    disliked: number;
  };
}

interface PersonaMetadata {
  total_items_analyzed: number;
  items_sampled: number;
  total_liked: number;
  total_disliked: number;
  chunks_processed: number;
  total_chunks: number;
  coverage: string;
  platform_breakdown: PlatformBreakdown;
}

interface PersonaResponse {
  DataAnalysis: {
    personality_traits: PersonalityTraits;
  };
  metadata: PersonaMetadata;
}

Full Example Response (Standard Mode)

{
  "DataAnalysis": {
    "personality_traits": {
      "positive_traits": {
        "Creative Problem Solving": 92,
        "Science and Technology Enthusiasm": 88,
        "Community Engagement": 85,
        "Visual Storytelling": 78,
        "Music Discovery": 76,
        "Open Source Contribution": 74,
        "Environmental Awareness": 73,
        "Collaborative Learning": 71
      },
      "traits_to_improve": {
        "Structured Planning": 45,
        "Financial Awareness": 38,
        "Routine Consistency": 32,
        "Formal Communication": 28,
        "Competitive Sports Interest": 22,
        "Political Engagement": 18,
        "Celebrity Culture Interest": 12,
        "Reality TV Engagement": 8
      },
      "user_summary": "You are a curious, creative individual with a strong affinity for science, technology, and problem-solving. You actively seek out content about AI research, open-source projects, and innovative applications of technology. Your engagement spans multiple platforms, showing consistent interest in community-driven discussions and collaborative projects.\n\nBeyond technology, you have a clear appreciation for visual arts, music, and environmental topics. You prefer hands-on, practical content over theoretical discussions and are drawn to communities that value sharing knowledge and building together.",
      "top_traits_explanation": "Your positive traits reflect a strong pattern of engagement with creative, technology-focused, and community-oriented content across Reddit and YouTube. The high score for Creative Problem Solving comes from your consistent upvoting of engineering challenges, coding tutorials, and design thinking content.\n\nTraits to improve are derived from content you actively avoid or downvote, particularly reality TV, celebrity gossip, and highly structured planning content, suggesting a preference for organic, curiosity-driven exploration over rigid frameworks.",
      "archetype": "Creative Explorer",
      "nudges": [
        { "text": "You're highly creative and love problem-solving — try building a small side project that combines two of your interests." },
        { "text": "Consider dedicating time to structured planning exercises — even a simple weekly to-do list can channel your curiosity more effectively." },
        { "text": "Your love of open source is a strength — explore contributing to a project outside your usual tech stack to broaden your skills." },
        { "text": "To balance your deep-dive tendencies, try setting time limits for research sessions — it can help prevent analysis paralysis." },
        { "text": "Your environmental awareness is notable — explore how technology intersects with sustainability for a natural fit with your interests." },
        { "text": "Seek out communities that blend your interests in visual storytelling and technology — creative coding communities might be a great fit." }
      ]
    }
  },
  "metadata": {
    "total_items_analyzed": 847,
    "items_sampled": 420,
    "total_liked": 295,
    "total_disliked": 125,
    "chunks_processed": 4,
    "total_chunks": 6,
    "coverage": "66.7%",
    "platform_breakdown": {
      "reddit": { "liked": 180, "disliked": 60 },
      "youtube": { "liked": 115, "disliked": 65 }
    }
  }
}

Full Example Response (Evidence Mode)

{
  "DataAnalysis": {
    "personality_traits": {
      "positive_traits": {
        "Creative Problem Solving": {
          "score": 92,
          "emoji": "🧩",
          "evidence": "You consistently upvote engineering challenges and design thinking on Reddit"
        },
        "Science and Technology Enthusiasm": {
          "score": 88,
          "emoji": "🔬",
          "evidence": "Your YouTube history is heavily focused on AI research and tech explainers"
        },
        "Community Engagement": {
          "score": 85,
          "emoji": "🤝",
          "evidence": "You actively participate in collaborative open-source discussions on Reddit"
        }
      },
      "traits_to_improve": {
        "Narrow Focus": {
          "score": 42,
          "emoji": "🔍",
          "evidence": "Your content is almost entirely tech and science with little variety"
        },
        "Structured Planning": {
          "score": 35,
          "emoji": "📋",
          "evidence": "You tend to avoid productivity and planning content across platforms"
        }
      },
      "user_summary": "You are a curious, tech-driven individual who thrives on creative problem-solving and community collaboration. Your engagement shows a deep passion for science, open-source projects, and innovative technology.",
      "top_traits_explanation": "Your top traits reflect consistent engagement with engineering, AI research, and collaborative communities across Reddit and YouTube.",
      "archetype": "Creative Explorer",
      "nudges": [
        { "text": "You're a natural problem-solver — try applying that skill to a non-tech challenge this week." },
        { "text": "Your community involvement is a strength — consider mentoring someone new to open source." },
        { "text": "To broaden your perspective, explore content outside your usual tech focus." }
      ]
    }
  },
  "metadata": {
    "total_items_analyzed": 847,
    "items_sampled": 420,
    "total_liked": 295,
    "total_disliked": 125,
    "chunks_processed": 4,
    "total_chunks": 6,
    "coverage": "66.7%",
    "platform_breakdown": {
      "reddit": { "liked": 180, "disliked": 60 },
      "youtube": { "liked": 115, "disliked": 65 }
    }
  }
}