Provider Intelligence

The platform distinguishes between provider-detected resources (e.g., YouTube, Vimeo) and direct media (e.g., .mp4, .jpg files). Provider detection enables richer intelligence without downloading the actual media binary.

Intelligence Provenance

Every piece of data in the response has a provenance — where and how it was produced:

Provenance	Meaning	Example
Provider-native	Sourced directly from the content provider	YouTube thumbnail URL, oEmbed title
Generated	Computed by the platform's enrichment pipeline	Blurhash placeholder
Computed	Derived from analysis of the media data	Dominant color palette
Extracted	Read from the media binary metadata	Codec via ffprobe, image dimensions

Core Semantic

The distinction between provider-native and generated intelligence is fundamental. A YouTube thumbnail at i.ytimg.com is provider-native — it exists regardless of whether the platform processes the video. A blurhash placeholder is generated — it exists only because the platform computed it.

Provider Detection

When a URL matches a known provider pattern, the platform activates provider-specific intelligence:

// Provider detection result
{
  "provider": {
    "name": "youtube",
    "confidence": 1,                    // 1 = known provider, deterministic
    "detectionMethod": "url-parser"     // URL pattern matching
  }
}

Detection Rules

Rule	Behavior
Known provider URL	confidence: 1, detectionMethod: "url-parser"
Direct media URL	provider block is omitted entirely
Unknown webpage	Provider block absent — treated as generic webpage

WARNING

The provider block only exists for provider-detected URLs. Direct media (video files, images, audio files) must never have a provider block. This is enforced by contract tests.

Provider-Native Preview Persistence

Provider-native intelligence is canonicalized during initial discovery and persists immutably across all subsequent profile projections and cache retrievals.

FAST discovery        → provider-native thumbnail stored in canonical state
STANDARD from cache   → same thumbnail preserved
FULL from cache       → same thumbnail preserved

YouTube Thumbnail Lifecycle

// Canonical raw state (internal)
{
  "providerNative": {
    "provider": "youtube",
    "id": "GLTTI1NFHus",
    "title": "Provider Native Title",
    "thumbnail": {
      "url": "https://i.ytimg.com/vi/GLTTI1NFHus/hqdefault.jpg"
    }
  }
}

This provider-native data is projected consistently:

// FAST projection — provider-native preview is visible, NOT hidden
{
  "preview": {
    "thumbnail": {
      "url": "https://i.ytimg.com/vi/GLTTI1NFHus/hqdefault.jpg"
    }
    // placeholder: omitted (not provider-native, FAST hides generated)
    // palette: omitted (not provider-native, FAST hides generated)
  },
  "projection": {
    "hiddenFields": []    // provider-native preview is NOT projection-hidden
  }
}

// STANDARD and FULL projections — same thumbnail, always
{
  "preview": {
    "thumbnail": {
      "url": "https://i.ytimg.com/vi/GLTTI1NFHus/hqdefault.jpg"
    }
  }
}

Provider-Native vs Generated Preview

The FAST profile distinguishes between provider-native and generated preview data:

Preview Type	FAST Behavior	Source
YouTube thumbnail URL	✅ Visible	Provider CDN (provider-native)
Generated thumbnail	❌ Projection-hidden	Platform worker
Blurhash placeholder	❌ Projection-hidden	Platform computation
Color palette	❌ Projection-hidden	Platform computation

This means a FAST YouTube response includes the thumbnail, but a FAST direct-video response hides the preview entirely and declares it in hiddenFields.

Canonical URL Normalization

Provider detection also normalizes URLs to their canonical form:

{
  "identity": {
    "url": "https://youtu.be/GLTTI1NFHus?si=okdNMy6_p0VSqZJG",
    "finalUrl": "https://youtu.be/GLTTI1NFHus?si=okdNMy6_p0VSqZJG",
    "canonicalUrl": "https://www.youtube.com/watch?v=GLTTI1NFHus"
  }
}

The canonicalUrl is the normalized, deterministic form. Short URLs (youtu.be), share URLs (with ?si= parameters), and embed URLs are all resolved to the same canonical representation.

Embed URL Generation

For provider resources, the platform generates embeddable URLs:

{
  "playback": {
    "strategy": "iframe",
    "component": "iframe",
    "embedUrl": "https://www.youtube.com/embed/GLTTI1NFHus",
    "streamable": false,
    "downloadable": false
  }
}

Provider resources use iframe playback strategy, while direct media uses native strategy with <video> or <audio> components.

Enrichment Source Semantics

The enrichmentSources record preserves the provenance of each enrichment stage:

{
  "enrichmentSources": {
    "semantic": "fresh",       // detected in this request
    "mediaFormat": "fresh",    // detected in this request
    "oembed": "fresh"          // fetched from provider in this request
  }
}

Valid provenance values:

Value	Meaning
fresh	Produced during the current request lifecycle
cache	Retrieved from canonical cache (but provenance stays fresh — see below)
worker	Produced by background worker
provider	Sourced from content provider
inflight	Attached to an active enrichment lifecycle

Immutable Provenance

enrichmentSources records are immutable. When a cached response is served, responseSource changes to "cache", but enrichmentSources stays as originally recorded (e.g., "fresh"). This preserves the true provenance of when data was produced.