Self-Model API: From Zero to Personalized in 30 Minutes

TL;DR

• The Clarity Self-Model API lets you create, observe, and query user models with three API calls,no ML infrastructure required
• This guide walks through a working integration in 30 minutes: create a model, feed observations, and get personalized inferences
• By the end, you will have a self-model that improves with every user interaction and persists across sessions

The Self-Model API enables per-user personalization with three API calls: create a model, observe interactions, and query beliefs. No historical data, ML infrastructure, or data science team is required to start seeing personalized responses. This guide walks through the full integration from zero to personalized output in 30 minutes, including observation design patterns and next-level strategies for cross-context models.

Step 1: Create a Self-Model

Every user in your system gets a self-model. Think of it as a structured profile that evolves,not a static preferences object, but a living representation of what the user believes, knows, and prefers.

1import Clarity from '@heyclarity/sdk';← Install: npm i @heyclarity/sdk
2
3const clarity = new Clarity({ apiKey: process.env.CLARITY_API_KEY });← Your API key from dashboard
4
5// Create a self-model for a new user← One model per user
6const model = await clarity.createSelfModel({← Returns model object
7  externalUserId: 'user_abc123',← Your user ID
8  context: 'product-analytics-app',← Your app context
9});
10
11console.log(model.id); // 'sm_7f3a...'← Self-model ID for future calls
12console.log(model.alignmentScore); // 0.5 (neutral start)← Score evolves with observations

The self-model starts with a neutral alignment score of 0.5. It has no beliefs yet,it knows nothing about the user. That is about to change.

What is the alignment score? It is a 0-1 score that measures how well the model understands the user. A score of 0.5 means “no understanding yet.” As you feed observations, the score increases as the model builds coherent beliefs about the user. A score above 0.8 typically means the model can reliably predict user preferences across contexts.

Step 2: Observe Interactions

Observations are how the self-model learns. Every meaningful interaction the user has with your product is an observation. You do not need to send every click,focus on interactions that reveal intent, preferences, or expertise.

1// User chose a specific dashboard layout← Preference signal
2await clarity.observe(model.id, {← Feed observation
3  type: 'preference',← Observation type
4  content: 'User selected compact table view over chart view',← What happened
5  context: 'dashboard-layout',← Where it happened
6});
7
8// User asked a question revealing expertise level← Expertise signal
9await clarity.observe(model.id, {← Another observation
10  type: 'interaction',← Conversation signal
11  content: 'User asked about p95 latency percentiles',← Reveals domain knowledge
12  context: 'support-chat',← Context matters
13});
14
15// User edited an AI-generated summary← Correction signal (high value)
16await clarity.observe(model.id, {← Edits are gold
17  type: 'correction',← User corrected the system
18  content: 'Changed verbose summary to 3 bullet points',← Strong preference signal
19  context: 'report-generation',
20});

Three observations and the self-model already has material to work with. It can now infer: this user prefers data density over visualization, has technical expertise in performance monitoring, and wants concise output formats.

Which interactions should you observe? Focus on high-signal moments:

You do not need to instrument everything on day one. Start with 3-5 high-signal interaction points and expand as you validate the model’s accuracy.

Step 3: Query for Personalization

Now the payoff. When you need to personalize something,a response, a default setting, a content recommendation,query the self-model.

1// Get the current self-model state← Fetch model with beliefs
2const model = await clarity.getSelfModel('user_abc123');← By your user ID
3
4// Access structured beliefs← What the model learned
5const beliefs = model.beliefs;← Array of belief objects
6// => [
7//   { statement: 'Prefers data tables over charts', confidence: 0.82 },← From layout choice
8//   { statement: 'Has technical performance monitoring expertise', confidence: 0.75 },← From question
9//   { statement: 'Values concise output', confidence: 0.88 },← From correction
10// ]
11
12// Use beliefs to personalize your LLM prompt← The integration point
13const systemPrompt = `User preferences: ${beliefs.map(← Inject into context
14  b => b.statement).join('; ')}`;← Simple string concat

That is the core loop: create, observe, query. Three API calls. The self-model handles all the complexity of belief inference, confidence scoring, and temporal evolution.

The Full Integration Pattern

Let us put it all together in a realistic scenario. You have an AI-powered analytics product. Users ask questions about their data, and you use an LLM to generate insights. Here is how self-models make those insights personalized.

The integration adds roughly 10 lines of code to your existing LLM pipeline. You are already constructing a system prompt. Now you include the user’s self-model beliefs in that prompt. The LLM does the rest,it naturally adapts its response style based on the context you provide.

Observation Design Patterns

After the initial integration, the most impactful thing you can do is improve the quality of your observations. Here are patterns that work well.

The Correction Pattern: When a user edits an AI-generated output, capture both the original and the edit. The diff between them is the highest-value signal in your entire product. It tells you exactly how the user’s expectations differ from your defaults.

The A/B Choice Pattern: When you show users options (layout choices, feature toggles, format selectors), observe the choice and the alternatives they rejected. A user who picks “CSV” when “PDF” and “JSON” are also available is telling you something specific about their workflow.

The Question Pattern: Natural language questions from users reveal their mental model. “How do I filter by p95 latency?” tells you they think in percentile terms. “Why is my app slow?” tells you they are outcome-oriented and may not know performance metrics vocabulary.

The Absence Pattern: Track features that are available but never used. If a user has had access to the advanced query builder for 60 days and has never opened it, that is a belief signal,either they do not know about it, do not need it, or find it intimidating.

Beyond the Quickstart

Once the basic loop is working, here are the next integration levels.

Trade-offs and Limitations

Cold start is real but short. A brand-new self-model knows nothing. The first 5-10 observations are the most critical. Design your observation points to capture high-signal interactions early in the user journey.

Observation quality matters more than quantity. Sending every mouse move as an observation will not produce better models. It will produce noise. Focus on the 5-10 interaction types that reveal genuine preferences and expertise.

Latency adds up. Each API call adds 50-100ms of latency. For real-time applications, consider caching the self-model locally and refreshing periodically rather than querying on every request.

Models can be wrong. A user who exported CSVs three times might prefer CSVs, or they might have been following a tutorial. Confidence scores reflect this uncertainty, but surfacing a “Your Preferences” page where users can correct their model significantly improves accuracy.

What to Do Next

1. Get your API key: Sign up at the Clarity dashboard and create your first project. It takes under 2 minutes.
2. Instrument your highest-value interaction: Pick the single interaction in your product where personalization would have the most impact. Add the three-call integration loop (create, observe, query) to that interaction.
3. Measure the difference: Run an A/B test,same feature, with and without self-model personalization. Start in the API playground to prototype before integrating into production.

References

Related

• Three Layers of AI Personalization Architecture
• The Product Manager Guide to Self-Models
• Minimum Viable Evals: Start Here