What does a composite run actually do?

It clusters the centroids of runs you name, rather than the documents. So instead of a second flat clustering over everything, you get a layer above the partitions: groups of groups. That is what makes the result navigable rather than just large.

How does an agent use this?

The same way a person does. The composite groups sit above the per-partition clusters, which sit above the scenes, and the cluster endpoints let a tool call walk down that tree. Nothing about the hierarchy is agent-specific; it is navigable because it has levels.

Do I have to re-cluster to add new footage?

No. An assign run folds new documents into the existing centroids without re-clustering. You re-cut a partition with a full run when its shape has actually drifted, which is a judgement rather than a schedule.

What is the partition key here?

The template uses production_id because it is a natural grouping in the reference pipeline. The right key is whatever splits your corpus into pieces that fit under the cap and mean something to the people reading the clusters. Check the field is indexed on your documents before relying on it; a filter path that matches nothing returns an empty result rather than an error.

Media

Template v1.0 · updated 2026-09-12

Footage Intelligence at Archive Scale

Millions of scenes you can move through instead of search. Footage, ads and editor assets land in three clean collections, get clustered one partition at a time, and roll up into a navigable hierarchy an agent can walk.

A corpus you navigate by structure rather than by query, with every partition clustered under the limit that makes clustering possible at all.

Deploy starter pipeline

Performance-video teams whose archive outgrew search. Once a corpus passes a million scenes, the question stops being 'find me this clip' and becomes 'show me what is in here', and a result list cannot answer that.

1.27M

scenes in the reference corpus

The scale the partitioning recipe was written against, from the blessed clustering runbook.

5 → 3

sources into clean collections

Three footage sources merge into one collection; ads and editor assets keep their own.

100k

documents per HDBSCAN run

The hard cap on the quadratic methods. The pairwise distance matrix costs sample_size squared times 8 bytes, about 80 GB at that ceiling.

documents per k-means run

The hard cap on the linear methods. Above it, a partition is split again rather than the cap being raised.

What it looks like

Frame in, decisions fire, a verdict lands, a reviewer's call feeds back.

Simulated walkthrough · illustrative frames, scripted decisions

A camera operator silhouetted against a lit set

IngestStill: Pexels / Wolrider YURTSEVENframe 1 of 3

Decision path

Ingest
scene
route: cleared

Landed by a passthrough extractor with its source label intact.

Running tally

cleared

review

excluded

Reviewer feedback

When the frames are done, a reviewer's call on the borderline case feeds back into the thresholds.

What goes in

Footage
Three sources: an active sync, a large static archive, and a frozen legacy load. One shared schema so the merge is homogeneous.
Ads
Approved creatives, carrying their own ad and brand identifiers.
Editor assets
Graphics, text capsules and generated assets from the edit bay.

Where the decisions fire

Illustrative frames; boxes show the decision path, not live model output

A phone on a gimbal recording against a green screen — Ingest · Ads keep their own identifiers, so a cluster can be read back to the creative it came from.Still: Pexels / Javier Gonzalez

Two editors reviewing a timeline on a studio monitor — Ingest · Editor assets land in their own collection rather than being mixed into footage, because they are a different kind of thing.Still: Pexels / Ron Lach

What comes out

Clean collections
Raw footage, ads and editor assets, landed by a passthrough extractor so downstream teams build on stable inputs.
Per-partition clusters
One clustering execution per partition key, with the algorithm chosen by the partition's size.
A composite roll-up
Cluster centroids from those executions grouped into a layer above them.
Filtered retrievers
Scene and ad search that can be narrowed to one partition.

How the namespace is wired

5 buckets, 3 collections, 0 clean views, 2 retrievers. The diagram generates the manifest below; they cannot drift apart.

SourceBucketCollectionClean viewRetrieverClusterClick a node to inspect it

Reward signals

How reviewer decisions move the thresholds

Thresholds at ingest drift as the corpus changes. The reviewers working the queue are the ones who see where a threshold is wrong first, so this template routes their decisions back into the model that set it.

DocsInteractions API

Clusters are re-cut as the corpus grows, and the mode decides what that costs.

Explicit signals

Labels written back onto the source documents, so a retriever can filter on a cluster a person named.

Implicit signals

Which clusters get opened and searched from, which is the signal for whether the grouping is useful.

Where they land

raw-footage

System collections in your namespace, on the same vector store as the rest of the template. They are yours to query.

How the loop closes

An assign run folds each day's new scenes into existing centroids without paying for a re-cluster; a full run re-cuts a partition when its shape has drifted.

DocsManifest schema

One file spins up the namespace. Generated from the diagram above. Also served at /templates/footage-intelligence.namespace.yaml.

# 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.
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

# 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: "Fed by active-sync (s3, continuous)."
    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: "Fed by static-archive (s3, one-time)."
    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: "Fed by legacy-load (s3, one-time)."
    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: "Fed by ad-library (s3, continuous)."
    schema:
      properties:
        content:
          type: video
        ad_id:
          type: string
        brand:
          type: string
        source_label:
          type: string
  - name: editor-assets
    namespace: footage-intelligence
    description: "Fed by editor-output (manual, on upload)."
    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). Feeds scene-search, scene-themes."
    source:
      type: bucket
      bucket: footage-active
    feature_extractor:
      name: passthrough_extractor
      version: v1
      field_passthrough:
        - source_path: source_label
          required: true
        - source_path: filename
        - source_path: production_id
        - source_path: job_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 raw-footage across 1 feature index."
    collections:
      - raw-footage
    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/multilingual_e5_large_instruct_v1"
              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/multilingual_e5_large_instruct_v1"
              query:
                input_mode: text
                value: "{{INPUT.query}}"
              top_k: 50
          fusion: rrf
          final_top_k: 50
    tags:
      - template:footage-intelligence
clusters:
  - name: scene-themes
    namespace: footage-intelligence
    description: "Groups raw-footage by embedding similarity, one run per production_id."
    source_collections:
      - raw-footage
    cluster_type: vector
    # one execution per production_id; the value is supplied at execute time
    filters:
      field: production_id
      operator: eq
      value: null
    vector_config:
      feature_uris:
        - mixpeek://multimodal_extractor@v1/multilingual_e5_large_instruct_v1
      clustering_method: hdbscan
      algorithm_params:
        min_cluster_size: 50
        min_samples: 10
    llm_labeling:
      provider: google
      model_name: gemini-2.5-flash
    enrich_source_collection: true
    tags:
      - template:footage-intelligence
  - name: cross-partition-themes
    namespace: footage-intelligence
    description: "Rolls up the centroids of scene-themes into groups above them."
    source_collections:
      []  # a composite run reads centroids from the executions named below
    cluster_type: vector
    vector_config:
      clustering_method: kmeans
      algorithm_params:
        n_clusters: 24
    mode: composite
    source_cluster_names:
      - scene-themes
    tags:
      - template:footage-intelligence