Inspiration Feed v2 — Runtime Pipeline

Proposed flow for POST /inspiration/v2/refresh. Overview: inspiration-feed-v2-overview.md.

v2 scope: caption embeddings only — no video or image analysis.

Pipeline at a glance

Async — CaptionEmbedWorker (shared, not per user)

Runs outside the refresh hot path. Fires after any post upsert into InspirationCreatorPost or InspirationHashtagPost.

Rules:

Embed every cached post with a non-empty caption — once per (platform, externalId).
Skip if embedding already exists (idempotent).
Empty captions: skip embed; post can still appear via Tier 1/3 on other signals.

Async — ThumbnailMirrorWorker (shared, not per user)

Runs outside the refresh hot path. Fires after any post upsert into InspirationCreatorPost or InspirationHashtagPost that has a thumbnailUrl but no thumbnailS3Url.

S3 key: inspiration/thumbnails/{platform}/{externalId}.jpg — one object per post, shared across all users.

Rules:

Mirror every cached post with a non-empty thumbnailUrl — once per (platform, externalId).
Skip if thumbnailS3Url already set (idempotent).
If CDN fetch fails (URL already expired): log warning, leave thumbnailS3Url null — post still appears in feed, client shows placeholder.
Default dimensions: 80×80 JPEG quality 40 (~1–3 KB). Configurable via env (see overview).

Step 0 — Regions & profile

Same as v1: getContentRegionsForUser(userId).

Load UserInspirationProfile, InspirationSavedPost, and recent InspirationInteraction docs.

Step 0.5 — Resolve saved URL posts

Same as v1 (resolveStaleInspirationPosts). Queue caption embed for newly scraped posts.

Saved posts get weight 1.0 in Step 2 automatically (strongest similarity seed).

Step 1 — Creator posts (Tier 1)

Function: resolveStaleCreatorPosts(profileCreators, { regions })

Upsert into InspirationCreatorPost. Enqueue caption embed for each new/changed caption. Enqueue thumbnail mirror for each post with a thumbnailUrl and no thumbnailS3Url.

Scoring (freshness-first):

relevanceScore = creatorBaseWeight × 0.3 + freshnessScore × 0.7

Step 2 — Collect signals & interaction weights

Hashtag signals (Tier 3): same as v1 — buzz, profile, creator tags, saved-post tags.

Caption similarity seeds (Tier 2):

const seeds = []

// Saved posts — weight 1.0
for (const saved of savedPosts) {
  seeds.push({ platform, externalId, weight: WEIGHT_SAVE })  // 1.0
}

// Visits — weight 0.6 if dwell >= VISIT_DWELL_MS
for (const visit of qualifiedVisits) {
  seeds.push({ platform, externalId, weight: WEIGHT_VISIT })  // 0.6
}

// Likes — weight 0.8
for (const like of likes) {
  seeds.push({ platform, externalId, weight: WEIGHT_LIKE })  // 0.8
}

// Merge duplicate posts: use max weight

Load InspirationCaptionEmbedding for each seed. If embedding missing (backlog), skip seed until worker completes.

Weighted taste vector:

tasteVector = normalize( sum(seed.embedding × seed.weight) )

If no seeds exist, Tier 2 is skipped for this user (budget flows to Tier 3/4).

Step 3 — Weights, purge & budget

Tier 3: computeHashtagWeights() + interaction hashtag boosts (hide → negative).
Purge stale InspirationItem docs (same as v1, extended for creator_direct).
Budget split: 40% / 25% / 25% / 10% (creator / caption-similar / hashtag / genre).

Step 4 — Hashtag cache (Tier 3)

Same as v1 resolveStaleHashtags. Enqueue caption embed and thumbnail mirror for each newly stored InspirationHashtagPost.

Step 5 — Caption-similar posts (Tier 2)

Function: fetchCaptionSimilarPosts(userId, tasteVector, limit)

No OpenAI on this step — reads pre-computed shared embeddings only.

Seed attribution: For each candidate, record the highest-weight seed post with highest pairwise caption similarity (for sourceMeta.seedPosts).

Optional Apify top-up: If results < tier2Max, derive caption keywords from top seeds and run hashtag/keyword scrape — only as fallback.

Step 6 — Assemble tiers

Tier	Source	Sort	Budget
1	`InspirationCreatorPost`	freshness-first	tier1Max
2	Caption similarity pool	similarity × freshness	tier2Max
3	`InspirationHashtagPost`	v1 relevanceScore	tier3Max
4	Genre hashtags	v1 relevanceScore	tier4Max

Dedupe by platform:externalId — lower tier number wins.

Categories:

Tier	`category`
1	`creator_direct`
2	`caption_similar`
3	`user_hashtag` / `creator_hashtag` / …
4	`genre`

Step 7 — Bulk upsert

Same $setOnInsert / $set pattern as v1. Add fields:

tier: 1 | 2 | 3 | 4
captionSimilarity: number (Tier 2 only, mutable)
sourceMeta.seedPosts: [{ platform, externalId, weight }]
thumbnailS3Url: string | null — copied from source post; updated by ThumbnailMirrorWorker once available ($set on every refresh so it fills in as the worker catches up)

Visit / save flow (weight only, no embed)

Caption was already embedded when the post entered cache. Interaction only changes which embeddings seed Tier 2 and by how much.

GET /feed/v2 — Sort order

sort: { tier: 1, relevanceScore: -1, postedAt: -1, seen: 1 }

Within Tier 2, secondary sort by captionSimilarity DESC.

Cost summary

Step	OpenAI?	S3?
Scrape + cache upsert	No	No
CaptionEmbedWorker	Yes — once per post, shared	No
ThumbnailMirrorWorker	No	Yes — once per post, shared (~1–3 KB)
Build taste vector	No	No
Tier 2 similarity search	No	No
Save / visit API	No	No

v1 → v2 mapping

v1	v2
Creator hashtags only	Creator posts + caption embed
Hashtag overlap	Hashtag Tier 3 + caption similarity Tier 2
seen	seen + visit/save weights
No embeddings	Shared caption embedding per post