AI agent skill that researches any topic across Reddit, X, YouTube, HN, Polymarket, and the web - then synthesizes a grounded summary
Python ai-promptsai-skillblueskyclaudeclaude-codeclawhubdeep-researchhackernewsinstagramopenclawpolymarketrecencyredditresearchsocial-mediatiktoktrendstwitterweb-searchyoutube
"""Normalization, identity, and ranking behavior for Meta Ad Library items."""
from lib import fusion, normalize, planner, rerank, schema, signals
FROM_DATE = "2026-08-15"
TO_DATE = "2026-09-14"
def raw_ad(**over):
base = {
"id": "1000000000000001",
"title": "Better mornings start here.",
"text": "Better mornings start here. Use code SUMMER30 on the Brightpan kettle.",
"url": "https://www.facebook.com/ads/library/?id=1000000000000001",
"date": "2026-09-01",
"advertiser": "Brightpan",
"page_id": "300000000000001",
"is_active": True,
"ended_on": None,
"display_format": "DCO",
"cta": "Shop now",
"landing_url": "https://brightpan.example/collections/kettles",
"placements": ["FACEBOOK", "INSTAGRAM"],
"promo_code": "SUMMER30",
"variants": 3,
"has_video": False,
"transcript": "",
}
base.update(over)
return base
def normalize_one(**over):
items = normalize.normalize_source_items(
"meta_ads", [raw_ad(**over)], FROM_DATE, TO_DATE
)
assert len(items) == 1
return items[0]
class TestNormalizer:
def test_source_is_registered(self):
# A missing dispatch entry raises "Unsupported source" at runtime.
assert normalize.normalize_source_items("meta_ads", [], FROM_DATE, TO_DATE) == []
def test_identity_is_the_ad_library_permalink(self):
item = normalize_one()
assert item.url.endswith("id=1000000000000001")
assert item.metadata["landing_url"] == "https://brightpan.example/collections/kettles"
def test_launch_date_is_the_published_date(self):
assert normalize_one().published_at == "2026-09-01"
def test_creative_fields_ride_in_metadata(self):
meta = normalize_one().metadata
assert meta["advertiser"] == "Brightpan"
assert meta["cta"] == "Shop now"
assert meta["promo_code"] == "SUMMER30"
assert meta["display_format"] == "DCO"
assert meta["placements"] == ["FACEBOOK", "INSTAGRAM"]
assert meta["variants"] == 3
def test_variant_count_is_the_engagement_proxy(self):
assert normalize_one().engagement == {"variants": 3}
def test_transcript_rides_on_the_item(self):
item = normalize_one(has_video=True, transcript="Stop making boring drinks.")
assert item.metadata["transcript_snippet"].startswith("Stop making")
assert "Stop making boring drinks." in item.snippet
def test_items_are_grounding_exempt(self):
assert normalize_one().metadata["grounding_exempt"] is True
def test_pre_window_creative_is_filtered_out(self):
# The adapter already classifies, but the shared window filter is the
# backstop and must agree with it rather than drop everything.
items = normalize.normalize_source_items(
"meta_ads", [raw_ad(date="2026-04-03")], FROM_DATE, TO_DATE
)
assert items == []
def test_missing_advertiser_still_yields_a_reason(self):
assert normalize_one(advertiser="").why_relevant == "Running paid creative"
class TestIdentityThroughFusion:
def test_creatives_sharing_a_landing_page_stay_distinct(self):
# Ten creatives for one product commonly share a landing URL. Keying
# identity on it would collapse the campaign into a single candidate.
first = normalize_one(id="1", url="https://www.facebook.com/ads/library/?id=1")
second = normalize_one(id="2", url="https://www.facebook.com/ads/library/?id=2")
assert fusion.candidate_key(first) != fusion.candidate_key(second)
def test_same_creative_from_two_streams_shares_one_key(self):
one = normalize_one()
two = normalize_one(variants=4)
assert fusion.candidate_key(one) == fusion.candidate_key(two)
class TestRankingRegistries:
def test_grounding_exemption_skips_the_entity_miss_demotion(self):
# Ad copy that never names the brand is the normal case, so the
# entity-miss demotion must not reach these items.
item = normalize_one(text="Stop making boring drinks.", title="Boring drinks")
candidate = schema.Candidate(
candidate_id="c1",
item_id=item.item_id,
source="meta_ads",
title=item.title,
url=item.url,
snippet=item.snippet,
subquery_labels=[],
native_ranks={},
local_relevance=0.1,
freshness=1,
engagement=None,
source_quality=signals.source_quality("meta_ads"),
rrf_score=0.0,
source_items=[item],
)
assert rerank._is_grounding_exempt(candidate) is True
def test_source_quality_is_registered(self):
assert signals.source_quality("meta_ads") == 0.72
def test_engagement_weights_use_variants(self):
assert signals.ENGAGEMENT_WEIGHTS["meta_ads"] == [("variants", 1.0)]
def test_planner_capabilities_are_pinned(self):
assert planner.SOURCE_CAPABILITIES["meta_ads"] == {
"reference",
"company_signal",
"product_signal",
}
class TestActivityWording:
"""Ended-in-window creatives are kept on purpose, so say so accurately."""
def test_running_creative_reads_as_running(self):
assert normalize_one(is_active=True).why_relevant.startswith(
"Running paid creative"
)
def test_ended_creative_is_not_called_active(self):
item = normalize_one(is_active=False, ended_on="2026-09-05")
assert "Running" not in item.why_relevant
assert "2026-09-05" in item.why_relevant
def test_ended_creative_without_a_date_still_reads_as_ended(self):
item = normalize_one(is_active=False, ended_on=None)
assert "since ended" in item.why_relevant
def test_activity_state_is_preserved_in_metadata(self):
meta = normalize_one(is_active=False, ended_on="2026-09-05").metadata
assert meta["is_active"] is False
assert meta["ended_on"] == "2026-09-05"