Footage Intelligence at Archive Scale

# footage-intelligence: 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: footage-intelligence
  description: "Namespace template footage-intelligence. Generated from the flow diagram on mixpeek.com/templates/footage-intelligence."
namespaces:
  - name: footage-intelligence
    description: "Everything below lives in this namespace."
    feature_extractors:
      - name: passthrough_extractor
        version: v1
      - name: multimodal_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: 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.
#   active-sync: s3, continuous -> bucket footage-active
#   static-archive: s3, one-time -> bucket footage-archive
#   legacy-load: s3, one-time -> bucket footage-legacy
#   ad-library: s3, continuous -> bucket ads
#   editor-output: manual, on upload -> bucket editor-assets
buckets:
  - name: footage-active
    namespace: footage-intelligence
    description: "Meant to be fed by active-sync (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
        source_label:
          type: string
        filename:
          type: string
        production_id:
          type: string
        job_id:
          type: string
  - name: footage-archive
    namespace: footage-intelligence
    description: "Meant to be fed by static-archive (s3, one-time). 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
        source_label:
          type: string
        filename:
          type: string
        production_id:
          type: string
        job_id:
          type: string
  - name: footage-legacy
    namespace: footage-intelligence
    description: "Meant to be fed by legacy-load (s3, one-time). 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
        source_label:
          type: string
        filename:
          type: string
        production_id:
          type: string
        job_id:
          type: string
  - name: ads
    namespace: footage-intelligence
    description: "Meant to be fed by ad-library (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
        ad_id:
          type: string
        brand:
          type: string
        source_label:
          type: string
  - name: editor-assets
    namespace: footage-intelligence
    description: "Meant to be fed by editor-output (manual, on upload): upload files here or write them through the API. Nothing arrives until you do."
    schema:
      properties:
        content:
          type: video
        asset_type:
          type: string
        source_label:
          type: string
collections:
  - name: raw-footage
    namespace: footage-intelligence
    description: "passthrough_extractor@v1 over bucket footage-active (the manifest wires one source bucket; footage-archive, footage-legacy are added after apply)."
    source:
      type: bucket
      bucket: footage-active
    feature_extractor:
      name: passthrough_extractor
      version: v1
      field_passthrough:
        - source_path: source_label
        - source_path: filename
        - source_path: production_id
        - source_path: job_id
    enabled: true
  - name: footage-scenes
    namespace: footage-intelligence
    description: "multimodal_extractor@v1 over bucket footage-active (the manifest wires one source bucket; footage-archive, footage-legacy are added after apply). Feeds logo-on-screen-monitor, logo-on-screen, scene-search, scene-themes."
    source:
      type: bucket
      bucket: footage-active
    feature_extractor:
      name: multimodal_extractor
      version: v1
      input_mappings:
        video: content
      field_passthrough:
        - source_path: production_id
        - source_path: job_id
        - source_path: source_label
    alert_applications:
      - alert: logo-on-screen
        input_mappings:
          - input_key: query
            source: {source_type: constant, value: "a brand logo on screen"}
          - input_key: document_id
            source: {source_type: document_field, path: _internal.document_id}
    enabled: true
  - name: ad-creatives
    namespace: footage-intelligence
    description: "multimodal_extractor@v1 over bucket ads. Feeds ad-search."
    source:
      type: bucket
      bucket: ads
    feature_extractor:
      name: multimodal_extractor
      version: v1
      field_passthrough:
        - source_path: ad_id
          required: true
        - source_path: brand
          required: true
        - source_path: source_label
    enabled: true
  - name: editor-assets
    namespace: footage-intelligence
    description: "passthrough_extractor@v1 over bucket editor-assets."
    source:
      type: bucket
      bucket: editor-assets
    feature_extractor:
      name: passthrough_extractor
      version: v1
      field_passthrough:
        - source_path: asset_type
          required: true
        - source_path: source_label
    enabled: true
retrievers:
  - name: scene-search
    namespace: footage-intelligence
    description: "Searches footage-scenes across 1 feature index."
    collections:
      - footage-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://multimodal_extractor@v1/vertex_multimodal_embedding"
              query:
                input_mode: text
                value: "{{INPUT.query}}"
              top_k: 50
          fusion: rrf
          final_top_k: 50
    tags:
      - template:footage-intelligence
  - name: ad-search
    namespace: footage-intelligence
    description: "Searches ad-creatives across 1 feature index."
    collections:
      - ad-creatives
    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://multimodal_extractor@v1/vertex_multimodal_embedding"
              query:
                input_mode: text
                value: "{{INPUT.query}}"
              top_k: 50
          fusion: rrf
          final_top_k: 50
    tags:
      - template:footage-intelligence
  - name: logo-on-screen-monitor
    namespace: footage-intelligence
    description: "The alert's check: does the scene just written show a brand logo on screen. The search is scoped to that one scene, and an llm_filter watches it and keeps it only when a logo is visible. Materialises into logo-on-screen."
    collections:
      - footage-scenes
    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://multimodal_extractor@v1/vertex_multimodal_embedding"
              query:
                input_mode: text
                value: "{{INPUT.query}}"
              top_k: 5
          fusion: rrf
          final_top_k: 5
      - stage_name: judge
        stage_id: llm_filter
        parameters:
          criteria: "Keep this footage scene only if it shows {{INPUT.query}}: a company logo or brand name mark clearly visible in the frame. Discard it otherwise."
          include_media: true
    tags:
      - template:footage-intelligence
# Composite cluster run(s) are not emitted below, because the manifest schema cannot express them:
#   cross-partition-themes: rolls up the centroids of scene-themes
# The manifest cluster spec requires source_collections to have at least one
# item, and a composite run has no source COLLECTION: it reads the centroids of prior
# EXECUTIONS. Naming it here fails validation for the entire manifest. Run it once the
# partitioned runs have completed: POST /v1/clusters/{id}/execute on the partitioned cluster
# with mode composite and source_execution_ids naming at least two of those runs.
clusters:
  - name: scene-themes
    namespace: footage-intelligence
    description: "Groups footage-scenes by embedding similarity, one run per production_id."
    source_collections:
      - footage-scenes
    cluster_type: vector
    # Partitioned on production_id: execute once per value, passing
    #   filters: {AND: [{field: production_id, operator: eq, value: <one production_id>}]}
    # with each execution. The manifest cannot hold that value.
    # kmeans needs at least 24 documents in a production_id, since it has to
    # put each one in a group. Raise or lower n_clusters to the number of groups you
    # want to browse per production_id.
    vector_config:
      feature_uris:
        - mixpeek://multimodal_extractor@v1/vertex_multimodal_embedding
      clustering_method: kmeans
      algorithm_params:
        n_clusters: 24
    llm_labeling:
      enabled: true
      provider: google
      model_name: gemini-2.5-flash
alerts:
  - name: logo-on-screen
    namespace: footage-intelligence
    description: "Emails the org notifications address (Settings -> Notifications; unset means opted out) when a newly indexed footage scene shows a brand logo on screen."
    source: retriever
    retriever: logo-on-screen-monitor
    trigger_on: results
    notification_config:
      channels:
        - channel_type: email
      include_matches: true
      include_scores: true
    enabled: false

# Plan 11.14: two public-domain films from the starter sample set, ingested by
# one bounded batch after apply, and the use case they must satisfy.
seed:
  - bucket: footage-active
    max_objects: 2
    objects:
      - blobs: {content: samples/starter/videos/norelco-speed.mp4}
      - blobs: {content: samples/starter/videos/mexican-hat-dance.mp4}
acceptance:
  max_cost_usd: 0.5
  steps:
    - name: footage-listed
      kind: documents
      collection: raw-footage
      expect: {min_documents: 2}
    - name: footage-scenes-indexed
      kind: documents
      collection: footage-scenes
      expect: {min_documents: 2}
    - name: scene-search-answers
      kind: query
      retriever: scene-search
      inputs: {query: people dancing}
      expect: {min_results: 1}