Glossary of Terms¶

This glossary defines key terms, concepts, and terminology used throughout the Archety system.

Core Concepts¶

Archety¶

The AI-powered personal assistant system that helps users manage their daily tasks, schedule, and communications through intelligent automation and natural conversation.

Conversation State Manager¶

The unified system for managing conversation state in Archety. Combines explicit awaiting states (for structured miniapp flows) with query enrichment (for general conversation) into a single source of truth with clear priority: Explicit Awaiting > Soft Context > Query Enrichment.

Awaiting Type¶

A state indicating the system is waiting for specific user input. Types include: - SELECTION: User must pick from options (e.g., "Which venue?") - METADATA: User can add info about an item (e.g., "Any tips?") - CONFIRMATION: User must confirm yes/no - INPUT: User must provide freeform text

Soft Context¶

Lower-priority state (5 min TTL) that provides context for follow-up messages without forcing a specific resolution. Used after actions like adding a venue to enable natural follow-ups.

Resolution¶

The process of matching a user's message to an active awaiting state. Resolution types include selection, metadata, confirmation, input, and cancel.

Sage¶

The conversational AI personality that users interact with. Sage is built on large language models and provides natural, context-aware responses.

Superpower¶

A user-created custom app built via natural conversation with Sage. Users describe what they want ("create a superpower that tracks my workouts"), and Sage generates a config-driven app without requiring code. Superpowers can access Gmail, Calendar, and Vision API via OAuth grants. See also: Workflow (automated background tasks).

Creation flow: User describes → SmartRouter routes to create_superpower → AppCreationHandler manages conversation → GPT-5 generates definition → Saved to database

Location: app/miniapps/generator/

Workflow¶

An automated background task that runs proactively on behalf of the user (formerly called "superpowers" in code). Examples include: - Travel Brain: Flight tracking, departure reminders - Calendar Management: Automatically scheduling meetings - Email Triage: Identifying urgent emails - Weather Updates: Proactive weather alerts - Evening Prep: End-of-day summaries and tomorrow's agenda

Location: app/workflows/

Terminology Note: The folder was renamed from app/superpowers/ to app/workflows/ in January 2026. "Superpowers" now refers to user-created apps.

Intent Classification¶

The process of analyzing user input to determine what action or response is appropriate. The intent classifier categorizes messages into types like: - Casual conversation - Task request - Question - Feedback

Smart Router¶

The system component that decides which handler should process a user message based on the classified intent and context. See SmartMessageRouter.

SmartMessageRouter¶

The unified routing system that uses GPT-5-mini to make intelligent routing decisions with full context visibility. Replaces the fragmented approach of MiniAppDetector + IntentRouter + UnifiedClassifier with a single decision point. Located in app/orchestrator/smart_message_router.py.

RoutingContext¶

A dataclass that aggregates ALL relevant context before a routing decision is made. Includes: active MiniApp session, conversation history, calendar context, memories, awaiting states, and available routing targets. Located in app/orchestrator/routing_context.py.

RoutingDecision¶

The structured output from SmartMessageRouter containing: route type (miniapp/workflow/conversation), target_id, action, pre-parsed entities, confidence, and reasoning. Enables handlers to skip re-parsing when entities are already extracted.

Pre-Parsed Entities¶

Entity data extracted by SmartMessageRouter and passed to handlers via MiniAppContext.routing_entities. Allows handlers to skip LLM parsing when the router has already identified venues, schedules, dates, etc.

EntityExtractor¶

A dedicated LLM component (gpt-5-nano, 4000 tokens) that extracts structured entities from user messages during MiniApp routing. Returns typed entities like VenueEntity, QueryEntity, and TripEntity via MiniAppContext.extracted_entities. Replaces fragmented regex patterns across handlers. Located in app/orchestrator/entity_extractor.py.

ExtractedEntities¶

The structured output from EntityExtractor containing: - venues: List[VenueEntity] - Extracted venue data with actions (add, update, delete, rate, mark_visited) - query: QueryEntity - Query parameters (filters, search terms) - trip: TripEntity - Trip-level actions (set_destination, recall, end_session) - primary_action: str - The main action detected in the message

VenueEntity¶

A dataclass representing extracted venue information including: name, action, district, category, must_try items, vibe descriptors, best_for tags, rating, review, and references_last flag for pronoun resolution ("delete that", "rate it").

UnifiedExtractedEntities¶

The complete extraction result from EntityExtractor supporting ALL MiniApps (trip_planner, bill_split, poll, todo_list, transport_solver). Contains app_type, primary_action, confidence, session control flags (is_cancel, is_done, is_help), and app-specific entities.

Correlation ID¶

An 8-character UUID generated at the start of each routing request. Flows through SmartMessageRouter → EntityExtractor → handlers via request_id_var ContextVar. Enables request tracing across components and appears in Keywords.ai observability dashboard.

ExtractionError¶

A structured error class for entity extraction failures with error codes (VALIDATION_ERROR, LLM_TIMEOUT, RATE_LIMITED, PARSE_ERROR) and a retryable flag for smart fallback strategies.

Tiered Fallback Extraction¶

A 3-tier extraction strategy in EntityExtractor: Tier 1 uses fast patterns (no LLM), Tier 2 uses LLM extraction, Tier 3 falls back to Tier 1 results if LLM fails. Improves resilience for common patterns like "cancel", "done", and numbered lists.

Field Mirroring¶

A prompt engineering technique where LLM prompts explicitly use the same field names as the expected JSON output schema. Improves extraction accuracy by reducing LLM interpretation errors.

Keywords.ai¶

The LLM observability platform integrated via keywordsai-tracing package. Provides tracing, cost tracking, and debugging for OpenAI API calls. Uses keywordsai_span_attributes context manager for correlation ID and metadata attachment.

CommandParser¶

DEPRECATED - Legacy LLM-based command parser used as a fallback when EntityExtractor doesn't produce actionable results. Being phased out in favor of EntityExtractor. Located in app/miniapps/routing/command_parser.py.

BillSplitState¶

An enum defining the states in the Bill Split state machine flow: IDLE, RECEIPT_RECEIVED, AWAITING_SPLIT_MODE, EVEN_SPLIT, ITEMIZED_CLAIMING, AWAITING_TIP, CALCULATED, ANNOUNCED, VENMO_SENT, TRACKING, SETTLED. Drives the conversational flow in BillSplitHandler.

Even Split¶

A bill split mode where the total is divided equally among all participants. The payer absorbs any rounding remainder (extra penny).

Itemized Split¶

A bill split mode where each participant claims their items from the receipt. Tax and tip are distributed proportionally based on each person's subtotal share. Unclaimed items are split evenly among all participants.

Venmo Charge Link¶

A URL (https://venmo.com/?txn=charge&...) that opens the Venmo app pre-filled with a charge request. Generated by app/miniapps/apps/bill_split/venmo_links.py and sent to the payer's 1:1 DM.

Payment Tracker¶

A 48-hour deferred job that checks the payer's Gmail inbox for Venmo "paid you" notifications. Matches payments by amount (within $0.50 tolerance) and recipient name. Located in app/miniapps/apps/bill_split/payment_tracker.py.

Receipt Analyzer¶

A GPT-5 Vision component that extracts structured data (items, prices, tax, tip, total, confidence) from receipt photos. Returns is_receipt classification and confidence score. Located in app/miniapps/apps/bill_split/receipt_analyzer.py.

Webhook Trigger¶

An HTTP endpoint that allows external services (Stripe, GitHub, Zapier, etc.) to invoke miniapp actions via POST requests. Secured with HMAC-SHA256 signatures, rate-limited per webhook. Each webhook is scoped to a specific miniapp action and uses routing_action to bypass trigger matching. Located in app/services/webhook_service.py, app/api/webhook_ingestion_routes.py.

Webhook Secret¶

A 64-character hex string (32 bytes) used by external services to sign payloads via HMAC-SHA256. Shown once on creation or rotation, never returned in list endpoints. Stored plaintext in database (required for HMAC verification).

Payload Mapping¶

An optional dot-notation mapping that extracts values from incoming webhook JSON payloads into template context variables. Example: {"amount": "event.data.amount"} resolves payload["event"]["data"]["amount"] and makes it available as amount in the action's session data.

Completion Criteria¶

A natural-language string on a superpower definition that describes when an action chain is considered successful. After all operations execute, a CompletionChecker evaluates the criteria against the results using GPT-5-nano. Behind enable_completion_criteria_evaluation feature flag.

Escalation Rules¶

A dictionary on a superpower definition mapping failure types (e.g., on_oauth_failure, on_empty_result, on_rate_limit) to recovery messages or halt instructions. When an operation fails, the EscalationHandler classifies the failure and routes to the matching rule.

Billing Telemetry¶

Structured log events (BILLING_EVENT: *) emitted at key points in the billing funnel: upgrade prompted, upgrade clicked, subscription started/canceled, limit hit, payment failed, winback sent. Located in app/services/billing_telemetry.py.

Grandfathering¶

The policy that equipped superpowers remain usable after a user downgrades from paid to free. The loadout slot check in can_use_superpower() allows equipped items regardless of subscription status. New equips above the free slot cap are blocked.

Slot Allocation¶

The number of superpower loadout slots available to a user, determined by subscription tier and companion level. Free users get 1 slot; paid users get 3-6 (scaling with companion level). Configured via get_slot_allocation() in app/services/companion_level_service.py.

Upgrade Nag Frequency¶

The rate-limiting rule for upgrade suggestions: max 1 per week, never during emotional conversations, never after same-conversation decline. Tracked via users.last_upgrade_prompt_at.

Technical Terms¶

Context Window¶

The amount of conversation history and relevant information provided to the LLM when generating a response. Includes: - Recent messages - User preferences - Relevant memories - System state

Memory System¶

Powered by Supermemory (primary) with mem0 as legacy fallback. This system stores and retrieves user preferences, facts, and contextual information to make conversations more personalized and coherent over time.

Supermemory¶

The primary memory service provider for Archety. Features: - User Profiles: Automatic static/dynamic fact extraction for cross-session context - Knowledge Graph: Automatic entity relationship tracking - <300ms latency: 25x faster than mem0 - Container Tags: Multi-dimensional namespace filtering

mem0¶

Legacy memory service, retained as a fallback when Supermemory is unavailable. Slower (2-8s latency) but still functional.

User Profile¶

A Supermemory feature that maintains persistent context about users across sessions. Includes static facts (name, preferences) and dynamic facts (current trips, activities).

WebSocket Connection¶

A persistent, bidirectional communication channel between the user's client and the Archety backend, enabling real-time message exchange.

Reflex Response¶

A fast-path response mechanism that provides immediate acknowledgment to user messages before full processing completes.

Multi-Bubble Response¶

A response pattern where Sage sends multiple sequential messages to better mimic natural conversation flow.

Training Data¶

Conversation logs and interactions used to improve Sage's responses and the system's behavior through fine-tuning or few-shot learning.

API Terms¶

Endpoint¶

A specific URL path that accepts HTTP requests and returns responses. Example: /api/v1/chat

WebSocket Event¶

A message type sent over the WebSocket connection. Examples: - user_message: User sent a message - sage_response: Sage is responding - workflow_triggered: A workflow executed (e.g., Travel Brain, Calendar alerts) - typing_indicator: Sage is thinking

Rate Limit¶

A restriction on how many requests a user can make within a time window to prevent abuse and ensure fair resource usage.

User-Facing Terms¶

Onboarding¶

The process of setting up a new user's account. Onboarding V2 (PRD 6) uses a survey-based frictionless funnel with three entry paths: web survey, cold text, and group chat recognition. No OTP or payment gate — free tier activates on signup.

Onboarding Session¶

A database record (onboarding_sessions table) tracking a user's progress through the web survey funnel. Stores survey answers, compatibility scores, and pre-generated first response. Status flow: survey_incomplete → survey_complete → assistant_selected → activated.

Companion Picker¶

The UI step where users choose between three AI companions (Sage, Vex, Echo) based on compatibility scores computed from personality survey answers. Shows live speech bubbles and a "Best Match" badge.

Compatibility Scores¶

Deterministic scores (0-100) computed per assistant based on personality Q1 and Q2 survey answers. No LLM calls. Each persona has weighted scoring profiles. Located in app/services/compatibility_service.py.

Stranger Mode¶

First-message warm-up behavior for unregistered users who text the assistant directly (cold text entry path). Messages 1-3: guarded/short. Messages 4-10: warming up. Messages 10-15: almost normal. Messages 15+: auto-activate account. Located in app/services/stranger_mode_service.py.

Entry Path¶

How a user first encounters the platform. Values: web_survey (primary), cold_text (word-of-mouth), group_chat (viral). Stored on both onboarding_sessions and users tables.

Pre-generated Response¶

A cached first response generated via GPT-5 + persona template + survey data when the user selects their companion. Delivered instantly (<1s) when the user sends their first iMessage. Located in app/services/pregenerated_response_service.py.

Trait¶

A personality characteristic or preference that defines how Sage interacts with the user. Examples: - Communication style (casual, formal, humorous) - Verbosity (concise, detailed) - Proactivity level (reactive, moderately proactive, highly proactive)

Integration¶

A connection to an external service like Google Calendar, Gmail, or weather APIs that enables Archety to access and act on user data.

Database Terms¶

User Record¶

A database entry containing user account information, settings, and metadata.

Session¶

A period of continuous interaction between a user and Sage, tracked for context and analytics.

Message History¶

The complete log of messages exchanged between a user and Sage, stored for context and training purposes.

Workflow Log¶

A record of when and how workflows were executed, including user feedback and outcomes. (Formerly "Superpower Log")

Architecture Terms¶

Middleware¶

Software components that intercept and process requests before they reach the main application logic. Examples: - Authentication middleware - Rate limiting middleware - Logging middleware

Handler¶

A function or class responsible for processing a specific type of user request or system event.

Service Layer¶

The layer of the application containing business logic and interacting with external services and the database.

Repository Pattern¶

A design pattern that abstracts database operations behind a clean interface, making code more maintainable and testable.

Deployment Terms¶

Environment Variables¶

Configuration values (like API keys, database URLs) that are set outside the code and can differ between environments.

CI/CD Pipeline¶

Continuous Integration/Continuous Deployment - automated processes that test, build, and deploy code changes.

Health Check¶

An endpoint or mechanism that reports whether the service is running correctly, used by monitoring systems and load balancers.

Rollback¶

The process of reverting to a previous version of the code when a deployment causes issues.

Monitoring Terms¶

Latency¶

The time it takes for the system to respond to a request, measured at various percentiles (p50, p95, p99).

Error Rate¶

The percentage of requests that result in errors, tracked to identify system issues.

Active Users¶

The number of users actively using the system within a specific time period.

Uptime¶

The percentage of time the system is available and functioning correctly.