UX session analysis

# ux-session-analysis: one manifest spins up the namespace.
# Platform manifest schema (GET /v1/discovery/schema). Validate with POST /v1/manifest/validate,
# apply with POST /v1/manifest/apply or the Deploy button. Wiring comes from the flow diagram:
# edges are bucket -> collection sources, collection -> retriever scope, retriever -> view.
# Applying a SECOND time, over a namespace this template already created: use
# POST /v1/manifest/apply?mode=create_missing, which creates what is missing and leaves
# what exists alone. The default, create_only, fails the WHOLE apply and rolls it back if
# any resource already exists, so an upgrade looks like a dead end without this. Use
# mode=upsert to also patch resources that exist but have drifted from this file.
version: '1.0'
metadata:
  name: ux-session-analysis
  description: "Namespace template ux-session-analysis. Generated from the flow diagram on mixpeek.com/templates/ux-session-analysis."
namespaces:
  - name: ux-session-analysis
    description: "Everything below lives in this namespace."
    feature_extractors:
      - name: multimodal_extractor
        version: v1
      - name: text_extractor
        version: v1
    # Daily spend budget, in dollars of what you are charged (1,000 credits a dollar).
    # New batches pause once the namespace has spent this much today; queries are not capped.
    # Raise it later on the namespace: PATCH /v1/namespaces/<id> {"spend_budget": {"daily_usd": N}}.
    budget:
      daily_usd: 0.1

# Data sources. A storage connection carries credentials, so it is created in Studio
# (or POST /v1/organizations/storage-connections) and synced into the bucket named here.
#   clinic-recordings: s3, continuous, moderated session recordings from your rig, in your account -> bucket sessions
buckets:
  - name: sessions
    namespace: ux-session-analysis
    description: "Meant to be fed by clinic-recordings (s3, continuous). No source is connected yet: applying this manifest creates the bucket only. Connect the source to this bucket in Studio (Syncs) to start the feed."
    schema:
      properties:
        content:
          type: video
          required: true
        study_id:
          type: string
          required: true
        participant_id:
          type: string
          required: true
        study_task_id:
          type: string
        rig_id:
          type: string

# Connect your own storage. Create the two secrets, uncomment, and apply again;
# apply live-tests the connection, so it must have real credentials to succeed.
# Until then the buckets above accept direct uploads.
# storage_connections:
#   - name: clinic-recordings-connection
#     provider: s3
#     description: "Read-only access to the s3 location holding moderated session recordings from your rig, in your account."
#     config:
#       region: us-east-1
#       credentials:
#         type: access_key
#         access_key_id: ${{ secrets.AWS_ACCESS_KEY_ID }}
#         secret_access_key: ${{ secrets.AWS_SECRET_ACCESS_KEY }}

# bucket_syncs:
#   - name: clinic-recordings-sync
#     bucket: sessions
#     connection: clinic-recordings-connection
#     source_path: "sessions/"
#     sync_mode: continuous
#     polling_interval_seconds: 300
#     skip_duplicates: true
#     file_filters:
#       include_patterns: ["*.mp4", "*.mov"]
#     schema_mapping:
#       mappings:
#         content:
#           target_type: blob
#           source: {type: file}
#           blob_type: video

collections:
  - name: session-scenes
    namespace: ux-session-analysis
    description: "multimodal_extractor@v1 over bucket sessions. Feeds session-transcripts, find-the-moment, task-roll-up."
    source:
      type: bucket
      bucket: sessions
    feature_extractor:
      name: multimodal_extractor
      version: v1
      parameters:
        run_transcription: true
        run_ocr: true
      input_mappings:
        video: content
      field_passthrough:
        - source_path: study_id
        - source_path: participant_id
        - source_path: rig_id
        - source_path: study_task_id
        - source_path: file_location
        - source_path: segment_id
        - source_path: start_time
        - source_path: end_time
    enabled: true
  - name: session-transcripts
    namespace: ux-session-analysis
    description: "text_extractor@v1 over collection session-scenes. Feeds frustration-monitor, participant-frustration, find-the-moment, task-roll-up."
    source:
      type: collection
      collection: session-scenes
    feature_extractor:
      name: text_extractor
      version: v1
      input_mappings:
        text: transcription
      field_passthrough:
        - source_path: study_id
        - source_path: participant_id
        - source_path: study_task_id
        - source_path: segment_id
        - source_path: video_segment_url
        - source_path: start_time
        - source_path: end_time
    alert_applications:
      - alert: participant-frustration
        input_mappings:
          - input_key: query
            source: {source_type: constant, value: "user expresses frustration or gives up"}
          - input_key: document_id
            source: {source_type: document_field, path: _internal.document_id}
    enabled: true
retrievers:
  - name: find-the-moment
    namespace: ux-session-analysis
    description: "Searches session-scenes, session-transcripts across 2 feature indexes with rrf fusion."
    collections:
      - session-scenes
      - session-transcripts
    input_schema:
      query:
        type: text
        required: true
        description: "What to look for; searched across every index below"
    stages:
      - stage_name: search
        stage_id: feature_search
        parameters:
          searches:
            - feature_uri: "mixpeek://text_extractor@v1"
              query:
                input_mode: text
                value: "{{INPUT.query}}"
              top_k: 25
            - feature_uri: "mixpeek://multimodal_extractor@v1/vertex_multimodal_embedding"
              query:
                input_mode: text
                value: "{{INPUT.query}}"
              top_k: 25
          fusion: rrf
          final_top_k: 25
    tags:
      - template:ux-session-analysis
  - name: task-roll-up
    namespace: ux-session-analysis
    description: "Searches session-transcripts, session-scenes across 1 feature index. Groups documents by participant_id."
    collections:
      - session-transcripts
      - session-scenes
    input_schema:
      query:
        type: text
        required: true
        description: "What to look for; searched across every index below"
    stages:
      - stage_name: search
        stage_id: feature_search
        parameters:
          searches:
            - feature_uri: "mixpeek://text_extractor@v1"
              query:
                input_mode: text
                value: "{{INPUT.query}}"
              top_k: 200
          fusion: rrf
          final_top_k: 200
      - stage_name: group
        stage_id: group_by
        parameters:
          group_by_field: participant_id
    tags:
      - template:ux-session-analysis
  - name: frustration-monitor
    namespace: ux-session-analysis
    description: "The alert's check: does the transcript just written show a participant frustrated or giving up. Scoped to that one transcript. Materialises into participant-frustration."
    collections:
      - session-transcripts
    input_schema:
      query:
        type: text
        required: true
        description: "What to look for; searched across every index below"
      document_id:
        type: text
        required: true
        description: "The written document this run is scoped to, supplied by the alert attachment"
    stages:
      - stage_name: search
        stage_id: feature_search
        pre_filters:
          AND:
            - field: _internal.document_id
              operator: eq
              value: "{{INPUT.document_id}}"
        parameters:
          searches:
            - feature_uri: "mixpeek://text_extractor@v1"
              query:
                input_mode: text
                value: "{{INPUT.query}}"
              top_k: 5
              min_score: 0.82
          fusion: rrf
          final_top_k: 5
    tags:
      - template:ux-session-analysis
alerts:
  - name: participant-frustration
    namespace: ux-session-analysis
    description: "Emails the org notifications address (Settings -> Notifications; unset means opted out) when a new session transcript shows a participant frustrated or giving up on a task."
    source: retriever
    retriever: frustration-monitor
    trigger_on: results
    notification_config:
      channels:
        - channel_type: email
      include_matches: true
      include_scores: true
    enabled: false

# What a run of this template must show (plan 11.14). One realtime step only:
# the sessions bucket requires metadata fields on every object, and a seed
# object carries blobs alone, so no document can be seeded and the document,
# query and alert steps the other templates run have nothing to read here.
acceptance:
  max_cost_usd: 0.1
  steps:
    - name: query-embedding-served
      kind: realtime
      feature_uri: mixpeek://text_extractor@v1
      inputs: {text: "the participant could not find the checkout button"}
      # No dims: the step checks the length the index declares where it runs
      # (1024 under e5, 384 under the standalone's MiniLM).
      expect: {}