Smart Search Platform - Context Pack and Adapter Contracts

Purpose

• Chuẩn hóa dữ liệu context và giao thức adapter để mở rộng Smart Search sang nhiều module mà không sửa core liên tục.

Context Pack (Shared Input)

interface SmartSearchContextPack {
  userId?: string;
  role?: 'student' | 'teacher' | 'admin';
  visitorState?: 'anonymous' | 'authenticated';
  pageContext: 'home' | 'course' | 'learning' | 'practice' | 'vocabulary';
  pageContextId?:
    | 'home.main'
    | 'home.prelogin_main'
    | 'home.program_landing_prelogin'
    | 'home.program_compare_prelogin'
    | 'course.dashboard'
    | 'course.guest_overview'
    | 'course.guest_courses_preview'
    | 'course.guest_course_detail_gate'
    | 'learning.dashboard'
    | 'practice.entry'
    | 'vocabulary.dashboard';
  locale: 'vi' | 'en';
  timezone: string;
  activeProgram?: string;
  activeCourseId?: string;
  activeBankId?: string;
  sourceContext?: 'self_study' | 'course';
  returnTo?: string;
  urgencySignals?: {
    dueIn72h?: number;
    nextClassAt?: string;
    vocabDueToday?: number;
  };
  momentumSignals?: {
    inProgressItemId?: string;
    streakDays?: number;
    lastActionAt?: string;
  };
  goalSignals?: {
    targetScore?: string;
    impactTier?: 'high' | 'medium' | 'low';
  };
  learningSignals?: {
    weakUnitId?: string;
    confidenceTier?: 'low' | 'medium' | 'high';
    highAttention?: boolean;
    goalComparisonMode?: 'direct' | 'normalized' | 'not_comparable';
  };
  courseSignals?: {
    overdueCount?: number;
    dueTodayCount?: number;
    inProgressCount?: number;
    nextSessionAt?: string;
    debtTaskCount?: number;
    absenceEligible?: boolean;
  };
  entitlement?: {
    hasPro?: boolean;
    hasCourseAccess?: boolean;
  };
  discoverySignals?: {
    preferredProgram?: 'IELTS' | 'SAT' | 'TOEIC' | 'COMMUNICATION';
    preferredLane?: 'course' | 'self_study';
    timePreference?: 'weekday_evening' | 'weekend' | 'flexible';
    goalHint?: string;
  };
  conversionSignals?: {
    canDirectAuth?: boolean;
    consultationEligible?: boolean;
    entrySource?: string;
  };
  facetSignals?: {
    preferredFeatureFamilies?: Array<'ai' | 'practice' | 'schedule' | 'result' | 'vocabulary' | 'course_ops' | 'discovery'>;
    preferredContentTypes?: Array<'insight' | 'task' | 'plan' | 'material' | 'review' | 'catalog' | 'guide'>;
    preferredFormats?: Array<'widget' | 'list' | 'card' | 'popup' | 'tab' | 'report' | 'checklist'>;
  };
}

Adapter Interface (Shared)

interface SmartSearchAdapter {
  getName(): string;
  getSupportedIntents(): string[];
  execute(intentId: string, query: string, context: SmartSearchContextPack): Promise<SmartSearchResult[]>;
}

Domain Adapter Responsibilities

• Home Adapter:
  • map intent vào Continue Learning, Quick Access, Recommendation.
  • pre-login mode phải hỗ trợ discovery actions:
    • mở program landing,
    • mở compare view,
    • auth-first với returnTo.
  • phải support facet filter để query theo loại nội dung (báo cáo, widget, checklist) vẫn trả đúng feature.
• Course Adapter:
  • trả kết quả action-rich (PAGE/STEP/EXEC/AI) theo course context.
  • ưu tiên worklist actionable (required, overdue, in_progress).
  • map query thao tác sang flow EXEC có confirm (absence, booking).
  • guest mode phải hỗ trợ:
    • course preview list,
    • course detail guest gate,
    • consultation/auth conversion actions.
  • facet-aware result mapping:
    • phân biệt task vs insight vs ops khi query tổng quát theo loại.
• Learning Adapter:
  • ưu tiên weak-unit và impact window 30 ngày.
  • tôn trọng confidence gate + goal comparison mode.
  • khi highAttention=true, boost recovery actions.
  • facet-aware:
    • query báo cáo ưu tiên stats/report cards,
    • query task ưu tiên exercise actions.
• Practice Adapter:
  • validate route contract PRA (source_context/program/exercise_id/returnTo).
  • hỗ trợ facet task, checklist, guide.
• Vocabulary Adapter:
  • debt-aware ranking (due review, mistake queue, start session).
  • hỗ trợ facet review, list, report, popup.

Cross-module Handoff Rules

1. Mọi STEP dẫn sang PRA phải mang đủ params route contract.
2. Mọi kết quả PRA có vocab_suggestion_payload hợp lệ phải được ghi vào suggestion lane của Vocabulary.
3. Handoff từ Search Level-1 AI sang Level-2 AI Tutor phải giữ packet tối thiểu:
   • inlineFeatureKey + intentId + query + inlineSummary + sourceModule + returnTo.
4. Handoff discovery pre-login -> auth bắt buộc giữ returnTo + entrySource + targetEntity.
5. Khi có đủ evidence nguồn platform, adapter nên gửi kèm provenance hint để AI Tutor khởi tạo grounding rõ ngay lượt đầu.

AI Inline -> AI Tutor Packet Contract

interface AIInlineTutorHandoffPayload {
  inlineFeatureKey: string;
  intentId: string;
  query: string;
  inlineSummary: string;
  evidence?: string[];
  provenanceHints?: Array<{
    sourceClass: 'practice' | 'course' | 'blog' | 'history';
    sourceId?: string;
  }>;
  recommendedActions?: string[];
  sourceModule: 'home' | 'course' | 'learning' | 'practice' | 'vocabulary';
  pageContextId?: string;
  freshnessAt?: string;
  confidence?: 'low' | 'medium' | 'high';
  payloadTier?: 'full' | 'balanced' | 'lite';
  returnTo: string;
}

Validation rules:

• required fields thiếu -> xem là degraded packet.
• degraded packet không được chặn open-chat:
  • vẫn mở AI Tutor,
  • seed tối thiểu = intentId + query + sourceModule,
  • hiển thị notice nhẹ,
  • log search_ai_tutor_handoff_fallback_open.

Compression rules:

• payloadTier selection:
  • full: desktop/mobile high-capability.
  • balanced: mobile default.
  • lite: low-end or poor-network fallback.
• Caps baseline:
  • evidence[]: 3/2/0-1.
  • recommendedActions[]: 3/2/1.
  • inlineSummary: tier-capped length.
• Compression không được loại bỏ packet required minimum.

AI Tutor Grounding Metadata Contract (DEC-0083)

interface AITutorGroundingMetadata {
  sourcePriority: ['session_context', 'platform_kb', 'learner_history', 'general_fallback'];
  provenanceClasses: Array<'practice' | 'course' | 'blog' | 'history' | 'general_fallback'>;
  requiresFallbackDisclosure?: boolean;
}

Adapter requirements:

• Nếu có evidence từ platform:
  • map evidence sang provenanceHints theo source class (practice|course|blog|history).
• Nếu không có evidence đủ mạnh:
  • vẫn mở AI Tutor (không block),
  • đánh dấu requiresFallbackDisclosure = true ở handoff metadata layer để AI Tutor render disclaimer phù hợp.
• Handoff packet không cần chứa toàn bộ citation chi tiết; chỉ cần đủ seed để AI Tutor runtime truy xuất nguồn đầy đủ ở bước sau.

AI Full Test Intent-variant Mapping (DEC-0089)

• Query cluster thi thu|full test|mock test:
  • map canonical intent = ACT_TEST.
  • map variant = AIF_MOCK_FULL_TEST.
• Nếu thiếu context program/assessment-form:
  • fallback về test flow chuẩn với disambiguation ngắn (không fail cứng).

Error and Fallback

• Thiếu context quan trọng: fallback PAGE an toàn thay vì fail cứng.
• Adapter timeout: trả partial results + nguồn fallback.
• Không có kết quả: hiển thị AI fallback với context tối thiểu.

References

• SSP_00_Overview.md
• contracts/SSP_Intent_Taxonomy_Result_Contract.md
• area-bundles/SSP_Program_Course_Discovery_Search_Bundles.md
• ../Practice Flow/PRA_Entry_Routing_Contracts.md
• ../Practice Flow/PRA_Result_Impact_Contracts.md
• ../Course Management/CM_TECH_Smart_Search_Architecture.md
• ../Home & Discovery/HOME_ENG_Home_Pre_Login.md

Change log

• 2026-02-28: title: “Smart Search Platform - Context Pack and Adapter Contracts”
• 2026-03-01: Add AI Inline to AI Tutor packet schema, validation rule, and degraded fallback behavior.
• 2026-03-01: Add grounding metadata contract (provenanceHints, fallback disclosure requirement) to align AI Tutor provenance transparency.
• 2026-03-01: Add mobile payload tier compression policy and full-test intent-variant mapping contract.