Greeting System — Overview¶

Audience: Business stakeholders, product owners, analysts, new team members. This document answers "what does this module do and why does it matter?" in plain language. No unexplained technical jargon.

This content was migrated from Documentation/GREETING_SYSTEM.md and restructured into audience sections. Review for accuracy against the current codebase.

What This Module Does¶

The Greeting System creates a personalized welcome message every time a user opens Swisper. Instead of a generic "How can I help you?", the assistant greets the user by name, references things it remembers about their life — an upcoming trip, a meeting tomorrow, a child's birthday last weekend — and offers proactive suggestions tailored to what's happening.

This transforms the first moment of interaction from a blank screen into a warm, context-aware experience. The system intelligently selects the most relevant and timely facts from the user's stored information, avoids repeating the same topics, and adapts its language and tone to the user's preferences. If the user has no stored facts yet (new account or facts disabled), the system still produces a friendly, localized greeting with helpful suggestions.

A frequency gate ensures the personalized greeting only appears when appropriate — at least 4 hours apart or on a new day — so users aren't bombarded with elaborate welcomes every time they switch tabs.

Who It Serves¶

• End users who benefit from feeling recognized and remembered when they open the app, with proactive suggestions that save them from having to think of what to ask.
• Product owners tracking engagement metrics — personalized greetings are a key driver of session engagement and perceived trust.
• New team members who need to understand how Swisper creates its "personal companion" feel from the very first interaction.

Key Capabilities¶

• Generates personalized greetings referencing the user's most relevant stored facts, selected by an intelligent priority scoring system.
• Applies a recency rotation system that penalizes recently-mentioned facts, ensuring variety across sessions.
• Includes warmth facts — stable personal details like pets, hobbies, and family relationships — to build emotional connection.
• Provides three proactive suggestions (practical, useful, creative) as clickable quick-reply options.
• Supports multiple languages (English, German, French, Italian) based on user or avatar preferences.
• Operates in three prompt variants: full personalized, simple (no facts), and voice mode.
• Enforces a frequency gate (configurable, default 4 hours) to avoid over-greeting.

How Fact Selection Works¶

The heart of the Greeting System is its fact preloading brain — the logic that decides which facts Swisper mentions in your greeting. Every stored fact is scored on a 0–100 scale using four components:

The Scoring Formula¶

PRIORITY SCORE = Time Urgency + Fact Type Priority + Confidence Score + Recency Penalty
                  (0–50 pts)      (0–30 pts)          (0–20 pts)        (-60 to 0 pts)

The facts with the highest total scores are selected for the greeting.

1. Time Urgency (0–50 points)¶

Facts tied to dates are scored by how close that date is to today. Events happening tomorrow score the highest; events from last week still score well; stable facts with no date get a baseline score.

2. Fact Type Priority (0–30 points)¶

Different types of facts have different value for greetings. Time-sensitive, actionable facts rank highest; static profile information ranks lowest.

3. Confidence Score (0–20 points)¶

Facts the system is more confident about score higher. A fact explicitly stated by the user ("I'm flying to Tokyo tomorrow") scores 20. A weaker inference scores less. Facts below 0.7 confidence are excluded entirely.

4. Recency Penalty — The Rotation System (-60 to 0 points)¶

Without rotation, Swisper would mention the same facts every greeting. The recency penalty suppresses recently-used facts so the greeting stays fresh:

Example: A fact about an upcoming Tokyo trip scores 96 points normally (50 urgency + 28 travel + 18 confidence). If it was mentioned today, the -60 penalty drops it to 36 — so other facts get a turn. After 6 days, the penalty clears and it's back to full priority.

Warmth Facts — Building Empathy¶

On top of the priority-scored facts, the system adds up to one warmth fact — a stable, personal detail that humanizes the greeting:

• Pet facts — "User has a golden retriever named Max"
• Hobby facts — "User plays tennis on Saturdays"
• Relationship facts — "User's wife is Cindy"

Warmth facts are woven in only when they connect naturally to the other facts in the greeting. "Hope Max is keeping you company while you recover" (connecting a pet to a health fact) feels natural. "You've been married 12 years" out of nowhere feels forced — so the system skips it.

All of This is Configurable¶

Every number in the scoring system — the time windows, the type priorities, the recency penalties, the confidence threshold, the number of facts, the warmth types — is stored in a database configuration table and can be adjusted at runtime via the Admin API. No code changes needed. See the Developer Guide for the complete configuration reference.

How It Fits in the Platform¶

The Greeting System operates independently from the main chat pipeline. While normal messages go through Intent Classification, Entity Resolution, and the full Global Supervisor graph, greetings bypass all of that for speed — they call the greeting node directly via a dedicated API endpoint (POST /api/v1/chats/greeting). The greeting node uses the Fact Preloading Service to load prioritized facts from the database, caches them in Redis (so the main chat pipeline has them warm when the user replies), and streams the response via Server-Sent Events. Configuration is managed through the fact_preloading_config database table, adjustable at runtime via the Admin Settings module.

Limits and Edge Cases¶

• No conversation context: The greeting has no awareness of what the user was doing in their last session. It references stored facts but cannot say "continuing from where we left off" or reference previous chat topics.
• Fact rotation can exhaust options: If a user has very few facts and logs in frequently, the recency penalty can suppress all facts, resulting in a generic greeting even though facts exist. The penalty decays over 6 days.
• Language detection is coarse: Language is determined from the avatar preference or browser locale, not from the user's actual language use. A multilingual user who switches between German and English will always get greetings in whichever language is set as their preference.
• No event-based triggers: Greetings only fire when the user opens the app. The system doesn't proactively send greetings based on calendar events, time of day, or life changes (planned for future phases).

FAQ¶

Q: Why does Swisper sometimes give a simple greeting instead of a personalized one? A: This happens when the frequency gate is active (you opened the app less than 4 hours ago), when you have no stored facts yet, or when all your facts have been mentioned recently and are temporarily suppressed by the rotation system.

Q: How does the system decide which facts to mention? A: Each fact is scored on a 0–100 scale combining four factors: how time-urgent it is (upcoming trip > stable hobby), what type of fact it is (schedule and travel rank highest), how confident the system is in the fact, and how recently it was mentioned (recently used facts are penalized). The top-scoring facts are selected. See the "How Fact Selection Works" section above for the full breakdown.

Q: What are warmth facts and why does the system include them? A: Warmth facts are stable personal details — pets, hobbies, family relationships — that humanize the greeting. They're not time-sensitive, but they build emotional connection. The system adds up to one warmth fact per greeting, and only when it connects naturally to the other facts being mentioned.

Q: Can I control how often the personalized greeting appears? A: Yes. The minimum gap between personalized greetings is configurable (default: 4 hours). The fact_preloading_config table also lets you adjust how many facts are included, which fact types are prioritized, how aggressively the recency rotation works, and more. All changes take effect within 60 seconds without restarting the service.

Q: Does the greeting work in languages other than English? A: Yes. The system supports English, German, French, and Italian. The language is determined from your avatar's stored preference or your browser locale. The LLM generates the greeting natively in the detected language.