SSE Event Type — Prompt Suggestion

SSE Event Type — Prompt Suggestion

Purpose

Define the prompt_suggestion event type for streaming contextual prompt suggestions to clients. Each suggestion is sent as a separate event, allowing clients to render suggestions incrementally as they arrive.

---

Event Type: prompt_suggestion

Event Structure

Each suggestion is sent as an individual event:

{
  "event_type": "prompt_suggestion",
  "version": "0.1",
  "timestamp": "2025-10-06T19:37:23.367966Z",
  "response_id": "<unique id for the request>",
  "content": "Which store near me has the highest total points I can earn this week?"
}

Field Definitions

• event_type (string, required) — Always prompt_suggestion.
• version (string, required) — Schema version (0.1).
• timestamp (string, required) — ISO-8601 timestamp when emitted.
• response_id (string, required) — Unique identifier for the request/session.
• content (string, required) — The suggestion text (personality-driven, natural language).

---

Client Behavior

Receiving Suggestions

• Incremental Rendering: Render each suggestion as its event arrives
• Event Ordering: Suggestions arrive in priority order from the server
• Collection: Collect all prompt_suggestion events until completed event

Rendering Suggestions

• Display Format: Render as tappable cards/buttons
• Layout: Grid or list layout depending on screen size
• Touch Targets: Minimum 44x44pt tap areas for accessibility
• Visual Feedback: Immediate feedback on tap (ripple, highlight, scale)

Interaction Pattern

1. User taps a suggestion card
2. Suggestion content is submitted as user query to chat API
3. Transition to chat view with query pre-filled or submitted
4. Optionally track suggestion usage for analytics

Accessibility

• Screen Readers: Read full text aloud
• High Contrast: Ensure sufficient contrast ratios (WCAG AA minimum)
• Keyboard Navigation: Support keyboard focus and activation
• Reduced Motion: Respect prefers-reduced-motion settings

---

UI Guidelines

Personality & Tone

Suggestions use natural, conversational language with personality:

✅ Good Examples:

• “I drink a lot of coffee, how can I turn this into an earning habit?”
• “Compare my shopping list across Aldi, Target, and Walmart for total points earned”
• “Curate a post breakup ‘treat yourself’ shopping trip; consider self care, wines, and ice creams”
• “Help me prep for a snowstorm — stockpile essentials with the best offers”

❌ Avoid:

• “Find coffee offers” (too generic)
• “Compare stores” (lacks personality)
• “Search for ice cream” (not conversational)
• “Get pantry items” (too transactional)

Visual Design

• Card Layout: Text-focused with optional icon or decoration
• Typography: Clear, readable font size (minimum 16px for body text)
• Spacing: Adequate padding for comfortable reading and tapping
• Color: Use brand colors consistently

Animation

• Entry: Staggered fade-in (50-100ms delay between items)
• Tap: Scale animation (0.95) with haptic feedback
• Loading: Shimmer skeleton matching final card size
• Transition: Smooth animation when submitting suggestion

---

Usage Contexts

The prompt_suggestions data type can be used in multiple contexts:

1. Landing Page (Initial Load)

Hard-coded suggestions shown when chat is first opened to help users get started.

Characteristics:

• Fixed set of curated suggestions
• No personalization required
• Same for all users
• Optimized for discoverability

2. Inline Contextual (After Response)

Dynamic suggestions generated based on conversation context, tool usage, and user interests.

Characteristics:

• Context-aware based on previous queries
• Considers tool calls made (e.g., offers searched)
• Adapts to user’s apparent interests
• Helps users discover next steps

3. Error Recovery

Suggestions shown when a query fails or returns no results.

Characteristics:

• Related to failed query topic
• Alternative approaches to same goal
• Helps users rephrase or broaden search

---

Technical Notes

Event Streaming

• Event Count: Typically 3-5 suggestions per stream
• Order: Suggestions arrive in priority/relevance order
• Completion: Always followed by a completed event
• Clients should collect all events until completed

Content Length

• Typical: 40-80 characters
• Maximum: 150 characters (for display constraints)
• Clients should handle text wrapping or truncation

Response ID

• The response_id is consistent across all events in a stream
• Format varies by endpoint (e.g., req_landing_{userId}_{timestamp} or OpenAI chatcmpl-xxx)
• Used for correlation and analytics

---

Compatibility

• Fields unknown to the client must be ignored
• New optional fields (e.g., subtitle, deeplink) may be added without version bump
• New categories may be added without version bump
• Changes to required fields require a version increment
• Breaking changes require a version increment

---

Example Event Sequences

Landing Page Suggestions

event: prompt_suggestion
data: {"event_type":"prompt_suggestion","version":"0.1","timestamp":"2025-10-06T19:37:23.367966Z","response_id":"req_landing_123","content":"Which store near me has the highest total points I can earn this week?"}

event: prompt_suggestion
data: {"event_type":"prompt_suggestion","version":"0.1","timestamp":"2025-10-06T19:37:23.368123Z","response_id":"req_landing_123","content":"I drink a lot of coffee, how can I turn this into an earning habit?"}

event: prompt_suggestion
data: {"event_type":"prompt_suggestion","version":"0.1","timestamp":"2025-10-06T19:37:23.368234Z","response_id":"req_landing_123","content":"Compare my shopping list across Aldi, Target, and Walmart for total points earned"}

event: completed
data: {"event_type":"completed","type":"final"}

Contextual Suggestions (After Offer Search)

event: prompt_suggestion
data: {"event_type":"prompt_suggestion","version":"0.1","timestamp":"2025-10-06T19:37:25.123456Z","response_id":"chatcmpl-abc123","content":"Compare these offers to what's available at Target and Walmart"}

event: prompt_suggestion
data: {"event_type":"prompt_suggestion","version":"0.1","timestamp":"2025-10-06T19:37:25.123567Z","response_id":"chatcmpl-abc123","content":"Show me more offers for breakfast items like these"}

event: prompt_suggestion
data: {"event_type":"prompt_suggestion","version":"0.1","timestamp":"2025-10-06T19:37:25.123678Z","response_id":"chatcmpl-abc123","content":"Find stores near me that carry these products"}

event: completed
data: {"event_type":"completed","type":"final"}

---

Future Enhancements

Potential additions to the event schema (would be optional fields):

• id (string) — Unique identifier for tracking/analytics
• category (string) — Semantic category for filtering/organization
• icon (string) — Icon identifier for visual representation
• deeplink (string) — Direct navigation URL when tapped
• subtitle (string) — Additional context or description
• badge (string) — Badge text (e.g., “Popular”, “New”)
• metadata (object) — Arbitrary metadata for analytics
• priority (number) — Display priority/ranking hint (if order needs override)