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

{
  "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": "This person is a curious, creative individual...",
    "top_traits_explanation": "The positive traits reflect a strong pattern..."
  },
  "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 of the user's personality and interests
top_traits_explanation	string	1-2 paragraph explanation of why these specific traits were identified

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	Areas where the user shows less engagement or actively avoids

User Summary

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

This field is useful for displaying a human-readable persona overview to end users or for feeding into recommendation engines as context.

Using the Data

const persona = await onairos.personas.get('user_123');
const traits = persona.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], ...]

// 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);

Best Practices

• Use the top 3-5 positive traits for content recommendations — these have the strongest signal
• Respect traits_to_improve as exclusion filters rather than negative labels
• 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

TypeScript Types

interface PersonalityTraits {
  positive_traits: Record<string, number>;
  traits_to_improve: Record<string, number>;
  user_summary: string;
  top_traits_explanation: string;
}

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 {
  personality_traits: PersonalityTraits;
  metadata: PersonaMetadata;
}

Full Example Response

{
  "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": "This person is a curious, creative individual with a strong affinity for science, technology, and problem-solving. They actively seek out content about AI research, open-source projects, and innovative applications of technology. Their engagement spans multiple platforms, showing consistent interest in community-driven discussions and collaborative projects.\n\nBeyond technology, they have a clear appreciation for visual arts, music, and environmental topics. They prefer hands-on, practical content over theoretical discussions and are drawn to communities that value sharing knowledge and building together.",
    "top_traits_explanation": "The 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 consistent upvoting of engineering challenges, coding tutorials, and design thinking content.\n\nTraits to improve are derived from content the user actively avoids or downvotes, particularly reality TV, celebrity gossip, and highly structured planning content, suggesting a preference for organic, curiosity-driven exploration over rigid frameworks."
  },
  "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 }
    }
  }
}