research/viral-gate-status

research/viral-gate-status — weekly viral-gate evaluation.

Category: research
Source: workflows/social/viral_gate_status.py

Input Schema

Field	Type	Default	Description
posts_log_path	string	""	Path to a TSV posts log. Empty = look for ~/.fabric/posts.tsv. The committed examples/viral-gate/posts.example.tsv template documents the expected columns.
primary_required_hits	integer	2	How many primary-threshold hits constitute MET.
primary_threshold	integer	50000	Per-output view threshold for the primary gate (plan 073). ≥primary_required_hits runs at this bar = MET.
regenerate	object	—	When set, this run is a regeneration. Workflows may read direction / keep / extra_instructions to modulate prompts; the engine persists parent_run_id and parent_variant_index as run lineage columns.
secondary_threshold	integer	250000	Per-output view threshold for the secondary gate. ≥1 run at this bar = MET regardless of primary count.
skip_fetch	boolean	false	When true, evaluate against the existing snapshot file without making any network calls. Useful for re-running the gate with tightened thresholds.
snapshots_path	string	""	Path to the JSONL snapshot history. Empty = ~/.fabric/post-engagement-snapshots.jsonl. Snapshots are appended on every run so trajectory data survives across evaluations.
variants	integer	1	Number of independent variant executions (1–10). When > 1, the engine runs the workflow N times with different sampling, producing N outputs.
window_days	integer	14	Evaluation window from posted_at, in days.

Output Schema

Field	Type	Default	Description
cohorts	any[]	—
evaluated_at	string	required
kind	object	—	Variant card shape: video / carousel / image / text. Surfaced on the per-variant entry of the run-output API and used by gallery UIs to pick the right layout.
posts_log_path	string	required
primary_threshold	integer	required
roster_state	string	required	Roster-level rollup of cohort gate states.
secondary_threshold	integer	required
snapshots_path	string	required
snapshots_written	integer	0	Number of new engagement snapshots appended this run.
window_days	integer	required

Task Pipeline

load_log → fetch_engagement → persist_and_merge → join_costs → evaluate_gate → finalize

Task	Description
load_log	Resolve paths + load + validate the posts log.
fetch_engagement	Fetch engagement for every URL in the log (in parallel, by URL).
persist_and_merge	Append the new snapshots to the JSONL file and load the full history.
join_costs	Best-effort cost-per-run join via the workflow runs API.
evaluate_gate	Apply plan 073’s gate criterion to each cohort.
finalize	Shape the aggregate output.

Run-spec example

Save the YAML below as my-run.yaml, edit the values, and run with the CLI or POST it to the API. Required fields are uncommented; optional knobs are documented above the input: block — copy any line under input: and uncomment to set.

workflow: research/viral-gate-status

# Optional fields — copy any line(s) under `input:` and uncomment to set:
# Path to a TSV posts log. Empty = look for ~/.fabric/posts.tsv. The committed examples/viral-gate/posts.example.tsv template documents the expected columns.
#   posts_log_path: ""
#
# How many primary-threshold hits constitute MET.
# [min=1, max=20]
#   primary_required_hits: 2
#
# Per-output view threshold for the primary gate (plan 073). ≥primary_required_hits runs at this bar = MET.
# [min=1]
#   primary_threshold: 50000
#
# Per-output view threshold for the secondary gate. ≥1 run at this bar = MET regardless of primary count.
# [min=1]
#   secondary_threshold: 250000
#
# When true, evaluate against the existing snapshot file without making any network calls. Useful for re-running the gate with tightened thresholds.
#   skip_fetch: false
#
# Path to the JSONL snapshot history. Empty = ~/.fabric/post-engagement-snapshots.jsonl. Snapshots are appended on every run so trajectory data survives across evaluations.
#   snapshots_path: ""
#
# Evaluation window from posted_at, in days.
# [min=1, max=365]
#   window_days: 14
#

input: {}

Run it locally:

fab-workflow --from-file my-run.yaml

Or submit over the wire — the same file is the request body:

curl -X POST 'https://gofabric.dev/v1/workflows/runs?name=research/viral-gate-status' \
  -H 'Authorization: Bearer fab_xxx' \
  -H 'content-type: application/yaml' \
  --data-binary @my-run.yaml

Every workflow also accepts the universal WorkflowInput fields — variants (1–10 fan-out) and regenerate (creative-direction hints with run lineage). See Run-specs (YAML / TOML / JSON) for the full top-level shape (metadata, priority, bundle, parent, etc.).