Research Workflows

Fabric’s research workflows discover problems, validate opportunities, and generate execution-ready business playbooks. Three core workflows compose into a pipeline that transforms raw platform content into actionable startup plans.

Pipeline Overview

research/problem-intelligence     Discover problems across platforms
         │
         │ ideas.0, ideas.1, ...
         │
    ┌────┴────┐
    │         │
research/  research/
playbook   idea-deep-dive

Workflow	Purpose	Output
`research/problem-intelligence`	Cross-platform problem discovery	Ranked clusters, ideas, specs
`research/trend-analyst`	Cross-platform trend scoring	Scored trends with velocity/relevance/opportunity
`research/optimal-schedule`	Optimal posting times from trend data	10-15 prioritized time slots per platform
`global/post-performance-analyst`	Analyze why a published post performed	Scored analysis with recommendations
`research/playbook`	Execution-ready business playbook	Single opinionated playbook
`research/idea-deep-dive`	Broad market analysis	Market validation, pricing, GTM, revenue
`research/reference-format-analysis`	Extract format DNA from a reference reel	Format DNA, recreation blueprint, summary

Problem Intelligence

Workflow: research/problem-intelligence

Ingests content from 8 platforms: Reddit, Hacker News, YouTube, YouTube Shorts, TikTok, Instagram, Twitter, and forums. Extracts problems, normalizes and deduplicates, clusters by semantic similarity, detects existing solutions, scores opportunities deterministically, generates startup ideas, and produces SaaS specs.

# Discover problems in a niche
fab-workflow research/problem-intelligence \
  --input niche="developer tools" \
  -o output/devtools.json

# Reddit discovery mode (auto-discover and crawl subreddits)
fab-workflow research/problem-intelligence \
  --input niche="project management" \
  --input reddit_discovery=true \
  --input depth=25 \
  -o output/pm-deep.json

# Monitor specific subreddits (no search query needed)
fab-workflow research/problem-intelligence \
  --input 'subreddits=["SaaS","startups","Entrepreneur"]' \
  -o output/saas-reddit.json

# Re-run with Reddit discovery on previous output
fab-workflow research/problem-intelligence \
  --input-file output/devtools.json \
  --input reddit_discovery=true \
  --input depth=25 \
  --input 'platforms=["reddit"]' \
  -o output/devtools-deep.json

curl -X POST "$FABRIC_URL/v1/workflows/run?name=research/problem-intelligence" \
  -H "Authorization: Bearer $FABRIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "input": {
      "niche": "developer tools"
    }
  }'

Pipeline

plan_ingestion
       │
  ┌────┼──────────────────────────────────────┐
reddit  hackernews  youtube  shorts  tiktok  instagram  twitter  forums
  └────┼──────────────────────────────────────┘
       │
  merge_sources
       │
  extract_problems          (parallelized LLM batches)
       │
  normalize_problems        (text cleanup + embedding dedup)
       │
  cluster_problems          (cosine similarity > 0.88)
       │
  aggregate_solutions       (detect existing solutions)
       │
  compute_scores            (deterministic, no LLM)
       │
  generate_ideas            (1-3 per top cluster)
       │
  score_ideas → generate_specs → format_output

Input

Parameter	Type	Default	Description
`query`	`string`	—	Search query (optional if `niche` or `subreddits` provided)
`niche`	`string`	—	Domain to focus on (auto-derives query)
`subreddits`	`list[str]`	`[]`	Specific subreddits to monitor
`forum_urls`	`list[str]`	`[]`	Forum URLs to ingest
`platforms`	`list[str]`	all 8	Platforms to query: `reddit`, `hackernews`, `youtube`, `youtube_shorts`, `tiktok`, `instagram`, `twitter`, `forums`
`depth`	`int`	`10`	Results per platform/subreddit
`reddit_discovery`	`bool`	`false`	Auto-discover relevant subreddits
`max_subreddits`	`int`	`15`	Max subreddits to discover
`reddit_concurrency`	`int`	`3`	Concurrent subreddit crawls
`extract_concurrency`	`int`	`3`	Concurrent LLM extraction batches
`top_clusters`	`int`	`10`	Clusters to generate ideas for
`top_ideas`	`int`	`5`	Ideas to generate specs for

At least one of query, niche, subreddits, or forum_urls is required.

Reddit Discovery Mode

When reddit_discovery=true, the adapter auto-discovers relevant subreddits, crawls each in parallel across hot/top/new sort orders, and fetches full comment threads. Uses rotating browser user agents.

CLI
REST

fab-workflow research/problem-intelligence \
  --input niche="developer tools" \
  --input reddit_discovery=true \
  --input depth=25 \
  --input max_subreddits=20 \
  --input reddit_concurrency=5 \
  -o output/devtools-deep.json

curl -X POST "$FABRIC_URL/v1/workflows/run?name=research/problem-intelligence" \
  -H "Authorization: Bearer $FABRIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "input": {
      "niche": "developer tools",
      "reddit_discovery": true,
      "depth": 25,
      "max_subreddits": 20,
      "reddit_concurrency": 5
    }
  }'

Scoring

All opportunity scores are deterministic (no LLM) and bounded [0, 1]:

pain        = frustration*0.4 + urgency*0.3 + (1 - sentiment)*0.3
demand      = log(mentions+1)/log(max+2)*0.6 + log(users+1)/log(max+2)*0.4
growth      = sigmoid(velocity * 2)
solution_gap = dissatisfaction*0.7 + (1 - solution_density)*0.3
recency     = exp(-days_since_last / 7)

opportunity = pain*0.30 + demand*0.25 + growth*0.15 + gap*0.20 + recency*0.10

Output

{
  "workflow": "research/problem-intelligence",
  "scope": "niche",
  "niche": "developer tools",
  "ranked_clusters": [
    {
      "id": "cluster_0",
      "canonical_problem": "...",
      "opportunity_score": 0.82,
      "mention_count": 12,
      "unique_users": 8,
      "avg_frustration": 0.75
    }
  ],
  "discovered_subreddits": [
    {"name": "webdev", "subscribers": 3214996}
  ],
  "source_documents": [],
  "problem_mentions": [],
  "clusters": [],
  "solution_mentions": [],
  "ideas": [],
  "specs": []
}

Idea Deep Dive

Workflow: research/idea-deep-dive

Broad market analysis for due diligence before committing to an idea. Runs 8 sequential LLM calls covering market validation, product variants, pricing, landing page, content strategy, go-to-market, and revenue projections.

Quick start

CLI
REST

# From problem-intelligence output (pick top idea)
fab-workflow research/idea-deep-dive \
  --input-file output/devtools.json --pick "ideas.0" \
  -o output/deep-dive.json

# Pick a different idea
fab-workflow research/idea-deep-dive \
  --input-file output/devtools.json --pick "ideas.1" \
  -o output/deep-dive-idea2.json

# Manual input
fab-workflow research/idea-deep-dive \
  --input name="TaskFlow" \
  --input description="AI project management for solo devs" \
  --input target_persona="indie developers" \
  -o output/deep-dive.json

curl -X POST "$FABRIC_URL/v1/workflows/run?name=research/idea-deep-dive" \
  -H "Authorization: Bearer $FABRIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "input": {
      "name": "TaskFlow",
      "description": "AI project management for solo devs",
      "target_persona": "indie developers"
    }
  }'

Pipeline

prepare_idea → validate_market → generate_product_variants →
research_pricing → design_landing_page → plan_content_strategy →
plan_go_to_market → project_revenue → format_output

What it produces

Section	Contents
`market_validation`	TAM/SAM/SOM, 5-10 competitors, timing, audience deep dive, demand signals
`product_variants`	All viable forms ranked (SaaS, mobile, extension, templates, course, community, etc.)
`pricing_research`	Willingness to pay, 3-4 tiers, pricing psychology, estimated ARPU
`landing_page`	Hero, problem, solution, features, social proof, FAQ — with actual copy
`content_strategy`	10 blog posts, 5 videos, 3 lead magnets, social plan, email sequence, SEO keywords
`go_to_market`	Pre-launch, launch week day-by-day, first 100 users, first 1000 users, partnerships
`revenue_projections`	3 scenarios with month-by-month MRR, breakeven timeline, LTV/CAC

Playbook Generation

Workflow: research/playbook

Generates a high-fidelity, execution-ready business playbook via 8 parallel LLM calls. Includes naming, MVP strategy, build spec, monetization, 14-day social schedule across 6 platforms (Twitter, Reddit, LinkedIn, TikTok, Instagram, YouTube Shorts), day-by-day execution plan, success metrics, and launch assets with ready-to-post content for every platform.

Quick start

CLI
REST

# From problem-intelligence output (pick top idea)
fab-workflow research/playbook \
  --input-file output/devtools.json --pick "ideas.0" \
  -o output/playbook.json

# Pick a different idea
fab-workflow research/playbook \
  --input-file output/devtools.json --pick "ideas.2" \
  -o output/playbook-idea3.json

# From a deep Reddit crawl
fab-workflow research/playbook \
  --input-file output/devtools-deep.json --pick "ideas.0" \
  -o output/playbook-deep.json

# Manual input (no prior workflow needed)
fab-workflow research/playbook \
  --input name="TaskFlow" \
  --input description="AI project management for solo devs" \
  --input target_persona="indie developers" \
  -o output/playbook.json

curl -X POST "$FABRIC_URL/v1/workflows/run?name=research/playbook" \
  -H "Authorization: Bearer $FABRIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "input": {
      "name": "TaskFlow",
      "description": "AI project management for solo devs",
      "target_persona": "indie developers"
    }
  }'

What it produces

Section	Contents
`name_suggestions`	8-10 brandable product names
`opportunity`	Problem, persona, why now, market signals
`evidence`	Summary, real user quotes, pain signals
`product`	Positioning, value prop, core features, MVP scope, what NOT to build
`mvp_strategy`	Where to start, day-1 version, week-1 version, validation question
`build`	Complexity, time to MVP, stack, file structure, DB schema, API endpoints, unknowns
`monetization`	Model, price points, competitor pricing, when/how to charge, free tier strategy
`success_metrics`	Day-1/week-1/month-1 signals, activation metric, failure signals, revenue target
`distribution`	14-day social schedule across 6 platforms, email templates, DM scripts, Fabric automation
`execution_plan`	Day-by-day plan (day 1 through day 7, then weeks 2-4) with hourly time estimates
`extensions`	What to build next, automation opportunities, feature/platform expansion
`risks`	Product, market, execution risks with likelihood and mitigation
`assets`	Landing page (hero, features, FAQ), launch posts for Twitter/Reddit/LinkedIn/TikTok/Instagram/YouTube Shorts, pitch

Design principles

Grounded — all claims tie back to real problem data and user quotes
Opinionated — makes decisions, chooses positioning, recommends strategy
Executable — everything answers “can someone act on this immediately?”
MVP-disciplined — aggressively limits scope, includes explicit “what not to build”

Piping Workflows with —input-file

All research workflows accept --input-file to load a previous workflow’s output. Combined with --pick (dot-notation path) and --map (rename fields), this enables chaining without glue code.

Pick an idea and generate a playbook

fab-workflow research/problem-intelligence \
  --input niche="developer tools" -o output/devtools.json

fab-workflow research/playbook \
  --input-file output/devtools.json --pick "ideas.0" \
  -o output/playbook.json

Re-run with Reddit discovery

fab-workflow research/problem-intelligence \
  --input-file output/devtools.json \
  --input reddit_discovery=true \
  --input depth=25 \
  --input 'platforms=["reddit"]' \
  -o output/devtools-deep.json

Generate playbooks for all top ideas

for i in 0 1 2 3 4; do
  fab-workflow research/playbook \
    --input-file output/devtools.json --pick "ideas.$i" \
    -o "output/playbook-idea-$i.json"
done

How —pick works

Pick path	Extracts
`ideas.0`	First idea object
`ideas.2`	Third idea object
`ranked_clusters.0`	Top-ranked cluster
`specs.0`	First SaaS spec

The extracted value becomes the input for the next workflow. Any --input K=V flags merge on top.

Choosing a Downstream Workflow

Use case	Workflow	Why
Start building today	`research/playbook`	Opinionated, concrete execution plan, launch assets
Validate before committing	`research/idea-deep-dive`	Market analysis, competitors, pricing, revenue
Both	Run both	They accept the same input format

Other Research Workflows

Deep Research

Workflow: research/deep_research

Multi-source fan-out research with parallel web, YouTube, Reddit, and RSS search.

CLI
REST

fab-workflow research/deep_research \
  --input query="Why are developers switching to Rust" \
  -o output/rust-research.json

curl -X POST "$FABRIC_URL/v1/workflows/run?name=research/deep_research" \
  -H "Authorization: Bearer $FABRIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "input": {
      "query": "Why are developers switching to Rust"
    }
  }'

Hot Topics

Workflow: research/hot_topics

Scans trending topics across categories with content opportunity scoring.

CLI
REST

fab-workflow research/hot_topics \
  --input categories='["tech", "business"]' \
  -o output/hot-topics.json

curl -X POST "$FABRIC_URL/v1/workflows/run?name=research/hot_topics" \
  -H "Authorization: Bearer $FABRIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "input": {
      "categories": ["tech", "business"]
    }
  }'

Competitive Intelligence

Workflow: research/competitive

Analyzes competitor content strategy to find gaps.

CLI
REST

fab-workflow research/competitive \
  --input competitors='["@mkbhd", "@fireship"]' \
  --input niche="tech education" \
  -o output/competitive.json

curl -X POST "$FABRIC_URL/v1/workflows/run?name=research/competitive" \
  -H "Authorization: Bearer $FABRIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "input": {
      "competitors": ["@mkbhd", "@fireship"],
      "niche": "tech education"
    }
  }'

Trend Research

Workflow: research/trends

Multi-signal trend analysis with content idea generation.

CLI
REST

fab-workflow research/trends \
  --input niche="AI agents" \
  --input platform="TikTok" \
  -o output/trends.json

curl -X POST "$FABRIC_URL/v1/workflows/run?name=research/trends" \
  -H "Authorization: Bearer $FABRIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "input": {
      "niche": "AI agents",
      "platform": "TikTok"
    }
  }'

Topic Discovery

Workflow: research/discover-topics

Finds trending topics for a niche. Lightweight wrapper around the SDK’s discover_topics stage.

CLI
REST

fab-workflow research/discover-topics --input niche="AI tools"

# Shorthand
fab discover "AI tools"

curl -X POST "$FABRIC_URL/v1/workflows/run?name=research/discover-topics" \
  -H "Authorization: Bearer $FABRIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "input": {
      "niche": "AI tools"
    }
  }'

Content Discovery

Workflow: research/discovery

Finds high-performing content in a niche for repurposing.

CLI
REST

fab-workflow research/discovery \
  --input niche="productivity" \
  --input platform="YouTube" \
  -o output/content-discovery.json

curl -X POST "$FABRIC_URL/v1/workflows/run?name=research/discovery" \
  -H "Authorization: Bearer $FABRIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "input": {
      "niche": "productivity",
      "platform": "YouTube"
    }
  }'

Trend Analyst

Workflow: research/trend-analyst

Cross-platform social media trend research with real crawling. Ingests content from up to 6 platforms (X/Twitter, Instagram, TikTok, LinkedIn, YouTube, Reddit) in parallel, then uses LLM analysis to identify and score trending topics on three dimensions: velocity, relevance, and opportunity.

Unlike research/trends (which uses LLM search grounding only), this workflow performs actual platform crawling via APIs and web fallbacks, producing data-grounded trend scores.

CLI
REST

# Basic niche analysis (default 5 platforms)
fab-workflow research/trend-analyst \
  --input niche="AI productivity tools" \
  --input target_audience="solopreneurs" \
  --input content_pillars="tutorials,reviews,news" \
  -o output/trends.json

# Specific platforms + Reddit
fab-workflow research/trend-analyst \
  --input niche="fitness tech" \
  --input platforms="youtube,tiktok,reddit" \
  --input trends_per_platform=3 \
  -o output/fitness-trends.json

curl -X POST "$FABRIC_URL/v1/workflows/run?name=research/trend-analyst" \
  -H "Authorization: Bearer $FABRIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "input": {
      "niche": "AI productivity tools",
      "target_audience": "solopreneurs",
      "content_pillars": "tutorials,reviews,news",
      "platforms": "x,instagram,tiktok,linkedin,youtube"
    }
  }'

Pipeline

plan_trend_research
       │
  ┌────┼────────────────────────────────┐
  x  instagram  tiktok  linkedin  youtube  reddit
  └────┼────────────────────────────────┘
       │
  merge_trend_sources
       │
  score_trends          (LLM: velocity/relevance/opportunity 1-100)
       │
  format_trend_output   (composite score, sort, normalize)

Input

Parameter	Type	Default	Description
`niche`	string	(required)	Niche or industry to analyze
`target_audience`	string	`""`	Who the content is for
`content_pillars`	string	`""`	Comma-separated content pillars
`platforms`	string	`"x,instagram,tiktok,linkedin,youtube"`	Platforms to scan (also supports `reddit`)
`trends_per_platform`	int	`5`	Trends per platform (3-5)

Output

{
  "trendsBySource": {
    "youtube": [
      {
        "topic": "AI coding assistants replacing Stack Overflow",
        "score": 85,
        "signals": { "velocity": 90, "relevance": 80, "opportunity": 85 },
        "summary": "Rapidly growing discussion around AI pair programming tools",
        "suggestedAngle": "Compare top 5 AI coding assistants with real benchmarks"
      }
    ],
    "tiktok": [ ... ],
    "linkedin": [ ... ]
  },
  "capturedAt": "2026-04-17T12:00:00Z"
}

Trends are grouped by source platform, sorted by composite score within each group. The composite score is weighted: velocity × 0.3 + relevance × 0.4 + opportunity × 0.3. Defaults to local LLM (quality=prefer-local) — override with --input quality=cheap or --input quality=premium for cloud models.

Optimal Schedule

Workflow: research/optimal-schedule

Takes trending-topic snapshots (e.g. from research/trend-analyst) plus the creator’s niche, audience, and timezone, and uses LLM analysis to determine the optimal posting times per platform for the next 7 days. Returns 2-3 prioritized time slots per platform (10-15 total), staggered to avoid cross-platform clashes.

CLI
REST

# Pipe trend-analyst output directly
fab-workflow research/trend-analyst \
  --input niche="AI productivity tools" \
  -o output/trends.json

fab-workflow research/optimal-schedule \
  --input niche="AI productivity tools" \
  --input targetAudience="solopreneurs" \
  --input timezone="America/New_York" \
  --input-file output/trends.json --pick trendsBySource \
  --map trends=trendsBySource \
  -o output/schedule.json

curl -X POST "$FABRIC_URL/v1/workflows/run?name=research/optimal-schedule" \
  -H "Authorization: Bearer $FABRIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "input": {
      "niche": "AI productivity tools",
      "targetAudience": "solopreneurs",
      "timezone": "America/New_York",
      "trends": "[{\"topic\":\"AI coding assistants\",\"source\":\"youtube\",\"score\":85,\"velocity\":90,\"relevance\":80,\"opportunity\":85,\"summary\":\"Rapidly growing discussion\"}]",
      "currentSlots": "[{\"provider\":\"instagram\",\"dow\":1,\"hour\":12}]"
    }
  }'

Pipeline

validate_inputs        (parse JSON, validate timezone, extract platforms)
       │
compute_schedule       (LLM: platform-specific timing + trend alignment)

Input

Parameter	Type	Default	Description
`niche`	string	(required)	Creator’s content niche
`targetAudience`	string	`""`	Target audience description
`timezone`	string	`"UTC"`	Creator’s timezone (IANA, e.g. `America/New_York`)
`trends`	string (JSON)	(required)	JSON array of trend objects with topic, source, score, velocity, relevance, opportunity, summary
`currentSlots`	string (JSON)	`"[]"`	JSON array of existing schedule slots `[{provider, dow, hour}]`

Output

{
  "slots": [
    {
      "provider": "youtube",
      "dow": 2,
      "hour": 18,
      "priority": 1,
      "reasoning": "Tuesday evening UTC aligns with peak US afternoon YouTube viewership; high-velocity AI coding trend needs immediate coverage",
      "trendAlignment": "AI coding assistants replacing Stack Overflow"
    },
    {
      "provider": "linkedin",
      "dow": 3,
      "hour": 12,
      "priority": 2,
      "reasoning": "Wednesday noon UTC = morning East Coast LinkedIn peak; professional audience engages with productivity content",
      "trendAlignment": "AI productivity tools for enterprise"
    }
  ],
  "strategy": "Front-load high-velocity trends (YouTube, X) in first 2 days; space LinkedIn and Instagram mid-week; reserve TikTok for evening/weekend slots",
  "computedAt": "2026-04-21T12:00:00Z"
}

Slots are sorted by priority (1 = highest). All hours are in UTC. The LLM accounts for the creator’s timezone when mapping platform peak windows to UTC hours.

Post Performance Analyst

Workflow: global/post-performance-analyst

Analyzes why a published social media post performed the way it did. Takes the post content (caption, hashtags, media type) plus platform metrics (impressions, interactions, comments, watch time) and returns a structured performance analysis with scores, strengths, weaknesses, and actionable recommendations.

Engagement rate and performance grade are computed deterministically using platform-specific benchmarks. Qualitative analysis (hook effectiveness, structure, hashtag strategy, timing, platform fit) is performed by LLM.

CLI
REST

fab-workflow global/post-performance-analyst \
  --input post_id="ig-20260415-001" \
  --input provider="instagram" \
  --input caption="3 things nobody tells you about cold showers" \
  --input 'hashtags=["coldshower","wellness","health"]' \
  --input media_type="video" \
  --input 'metrics={"impressions":50000,"interactions":2100,"comments":85,"watchTimeSeconds":120}' \
  --input published_at="2026-04-15T09:30:00Z" \
  --input platform_account_follower_count=12000 \
  -o output/post-analysis.json

curl -X POST "$FABRIC_URL/v1/workflows/run?name=global/post-performance-analyst" \
  -H "Authorization: Bearer $FABRIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "input": {
      "post_id": "ig-20260415-001",
      "provider": "instagram",
      "caption": "3 things nobody tells you about cold showers",
      "hashtags": ["coldshower", "wellness", "health"],
      "media_type": "video",
      "metrics": {
        "impressions": 50000,
        "interactions": 2100,
        "comments": 85,
        "watchTimeSeconds": 120
      },
      "published_at": "2026-04-15T09:30:00Z",
      "platform_account_follower_count": 12000
    }
  }'

Pipeline

compute_engagement_metrics   (deterministic: rate + grade)
       │
analyze_performance          (LLM: 5-dimension scoring + recommendations)

Input

Parameter	Type	Default	Description
`post_id`	string	(required)	Unique identifier of the published post
`provider`	string	(required)	Platform: instagram, tiktok, youtube, twitter, linkedin
`caption`	string	`""`	Post caption/text content
`hashtags`	string[]	`[]`	Hashtags used on the post
`media_type`	string	`"image"`	Media type: image, video, carousel, text
`metrics`	object	`{}`	`{impressions, interactions, comments, watchTimeSeconds}`
`published_at`	string	`""`	ISO 8601 timestamp of publication
`platform_account_follower_count`	int	`null`	Follower count at time of post

Output

{
  "postId": "ig-20260415-001",
  "provider": "instagram",
  "performanceGrade": "B",
  "engagementRate": 4.2,
  "analysis": {
    "hookScore": 85,
    "structureScore": 70,
    "hashtagScore": 60,
    "timingScore": 90,
    "platformFitScore": 80
  },
  "strengths": ["Strong opening hook with curiosity gap", "Good use of video format"],
  "weaknesses": ["Only 3 hashtags limits discoverability"],
  "recommendations": ["Add 15-20 niche hashtags", "Include a CTA in the first line"],
  "predictedActions": {
    "wouldImproveEngagement": ["Shorten caption to under 150 chars", "Add CTA in first line"],
    "avoidNextTime": ["Too few hashtags limits organic reach"]
  },
  "analyzedAt": "2026-04-15T14:00:00Z"
}

Grade thresholds vary by platform. For example, Instagram grades A+ at >6% engagement while TikTok requires >10% for the same grade, reflecting different baseline engagement levels.

Platform Export

Workflow: video/export-platforms

Takes a finished 9:16 video and produces platform-ready exports with resize, duration trimming, and LLM-generated metadata.

CLI
REST

# Export a video for multiple platforms
fab-workflow video/export-platforms \
  --input media_path=output/short.mp4 \
  --input topic="AI productivity tools" \
  --input 'platforms=["tiktok","instagram","youtube_shorts"]' \
  -o output/exports.json

curl -X POST "$FABRIC_URL/v1/workflows/run?name=video/export-platforms" \
  -H "Authorization: Bearer $FABRIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "input": {
      "media_path": "output/short.mp4",
      "topic": "AI productivity tools",
      "platforms": ["tiktok", "instagram", "youtube_shorts"]
    }
  }'

Supported platforms

Platform	Aspect	Resolution	Max Duration	Metadata
`tiktok`	9:16	1080x1920	180s	Description (150 char), hashtags, sound suggestion
`instagram`	9:16	1080x1920	90s	Caption (2200 char), 20-30 hashtags, cover frame
`youtube_shorts`	9:16	1080x1920	60s	Title, description, tags, thumbnail text
`youtube`	16:9	1920x1080	unlimited	Title, description, 10-15 tags, thumbnail
`instagram_feed`	1:1	1080x1080	60s	Caption, 20-30 hashtags
`linkedin`	9:16	1080x1920	600s	Professional post text, 3-5 hashtags

Aspect ratio changes use blur-fill (blurred background, no black bars). Videos exceeding platform max duration are trimmed.

Platform Adapters (Ingestion)

Platform	API	Auth Required	Rate Limit
Reddit	Public JSON API (old.reddit.com)	No	2s between calls
Hacker News	Algolia API	No	0.5s between calls
YouTube	yt-dlp + comments	No	—
YouTube Shorts	yt-dlp + `#shorts` filter (90s max)	No	—
TikTok	yt-dlp `tiktoksearch` or DuckDuckGo fallback	No	—
Instagram	Graph API or DuckDuckGo + Jina Reader fallback	`INSTAGRAM_ACCESS_TOKEN` for Graph API	2s between calls
Twitter	API v2 or DuckDuckGo fallback	`TWITTER_BEARER_TOKEN` for API v2	—
Forums	Jina Reader	No	—

Environment Variables

Variable	Required	Description
`GEMINI_API_KEY`	Yes	LLM extraction, ideation, spec generation, playbook, deep dive
`OPENAI_API_KEY`	No	Embeddings (falls back to sentence-transformers locally)
`TWITTER_BEARER_TOKEN`	No	Twitter API v2 (falls back to web search)
`INSTAGRAM_ACCESS_TOKEN`	No	Instagram Graph API (falls back to web search)

Reference Format Analysis

Workflow: research/reference-format-analysis

Analyzes a local short-form video (Reel, TikTok, Short) and extracts its reusable structural format — “format DNA”. Outputs a machine-readable recreation blueprint that can be consumed by video/recreate-from-format to generate original content in the same format shape.

Analyzes 18 dimensions: shots, transitions, composition, motion, color, transcript, pauses, retention hooks, speaker energy, music, OCR, structural phases, hook type, ending type, archetype, emotional arc, and edit grammar.

CLI
REST

# Analyze from a URL (YouTube, TikTok, Instagram)
fab-workflow research/reference-format-analysis \
  -i reference_video_url="https://www.instagram.com/reel/ABC123/" \
  -i platform="instagram_reels" \
  -i artifact_dir="output/analysis" \
  -v

# Analyze a local file
fab-workflow research/reference-format-analysis \
  -i reference_video_path="reference_reel.mp4" \
  -i platform="instagram_reels" \
  -i artifact_dir="output/analysis" \
  -v

# Heuristic-only (no LLM, faster, no API key)
fab-workflow research/reference-format-analysis \
  -i reference_video_url="https://www.tiktok.com/@user/video/123" \
  -i platform="tiktok" \
  -i enable_tone_inference=false \
  -i artifact_dir="output/analysis" \
  -v

curl -X POST "$FABRIC_URL/v1/workflows/run?name=research/reference-format-analysis" \
  -H "Authorization: Bearer $FABRIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "input": {
      "reference_video_path": "reference_reel.mp4",
      "platform": "instagram_reels"
    }
  }'

Pipeline

validate_and_probe → detect_shots_and_visual_analysis → transcribe_and_analyze_audio → infer_format_dna → emit_analysis_artifacts

Key outputs

format_dna.json — complete 18-dimension analysis
recreation_blueprint.json — actionable constraints for recreation
summary.md — human-readable format explanation
transcript.json, shots.json — raw analysis data

CLI Flags

Flag	Description
`-o FILE`	Save output JSON to file
`-v` / `--verbose`	Print full JSON to terminal
`--input K=V`	Set input key-value (repeatable)
`--input-file FILE`	Load input from JSON file
`--pick PATH`	Extract nested field from input file
`--map TO=FROM`	Rename fields from input file
`--model MODEL`	Override LLM model
`--quality PROFILE`	Quality profile (local, cheap, premium)