@m13v/s4l 1.6.197-rc.7

package/scripts/top_dud_linkedin_queries.py

@@ -0,0 +1,71 @@
+#!/usr/bin/env python3
+"""
+top_dud_linkedin_queries.py
+
+Returns recent LinkedIn search queries that produced ZERO usable candidates
+OR that returned candidates from a low-quality SERP (serp_quality_score < 4),
+so the LLM scanner can be told "do not redraft these phrasings, they have
+been flat or audience-wrong for the last week".
+
+Why both signals (zero-result AND low-SERP-quality):
+- Zero-result query: keyword too narrow, typos, or LinkedIn search index
+  rejects the phrasing. Standard dud.
+- Low-quality SERP: query returns 30 hits but all from influencer-bait
+  accounts; technically not zero, but useless for our outbound posting.
+  Same dud-class for the LLM's purposes.
+
+Pair with top_linkedin_queries.py (positive signal).
+
+    python3 scripts/top_dud_linkedin_queries.py [--project NAME] [--search-topic TOPIC] [--limit 30] [--window-days 7]
+
+Output: JSON list of
+    {"query": ..., "project": ..., "search_topic": ..., "attempts": N,
+     "last_ran_h_ago": F, "reason": "zero_results"|"low_serp_quality"}
+
+Window default 7 days (vs Twitter's 48h). LinkedIn cycle frequency is much
+lower; need a wider window to gather enough samples.
+
+Source: linkedin_search_attempts (one row per query per cycle, written by
+run-linkedin.sh after Phase A scrape parses queries_used).
+
+Migrated 2026-06-01 from direct db.py SELECTs to the s4l.ai HTTP API
+(GET /api/v1/linkedin-search-attempts/duds). No DATABASE_URL needed.
+"""
+import argparse
+import json
+import os
+import sys
+
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+from http_api import api_get
+
+
+def main():
+    p = argparse.ArgumentParser()
+    p.add_argument("--limit", type=int, default=30)
+    p.add_argument("--window-days", type=int, default=7,
+                   help="Look back this many days for dud queries.")
+    p.add_argument("--low-serp-threshold", type=float, default=4.0,
+                   help="serp_quality_score below this counts as a dud.")
+    p.add_argument("--project", default=None)
+    p.add_argument("--search-topic", default=None)
+    args = p.parse_args()
+
+    query = {
+        "limit": args.limit,
+        "window_days": args.window_days,
+        "low_serp_threshold": args.low_serp_threshold,
+    }
+    if args.project:
+        query["project"] = args.project
+    if args.search_topic:
+        query["search_topic"] = args.search_topic
+
+    resp = api_get("/api/v1/linkedin-search-attempts/duds", query)
+    out = (resp.get("data") or {}).get("duds") or []
+    json.dump(out, sys.stdout)
+    print("", file=sys.stdout)
+
+
+if __name__ == "__main__":
+    main()

package/scripts/top_dud_reddit_queries.py

@@ -0,0 +1,67 @@
+#!/usr/bin/env python3
+"""
+top_dud_reddit_queries.py
+
+Returns recent Reddit search queries that produced ZERO post-filter
+candidates so post_reddit.py:build_prompt can tell the LLM scanner
+"do not redraft these phrasings, they were flat in the last N hours".
+Counterpart to top_search_topics.py (positive signal): this is the
+negative-signal feed.
+
+    python3 scripts/top_dud_reddit_queries.py [--project NAME] [--limit 30] [--window-hours 168]
+
+Output: JSON list of
+  {"query": ..., "subreddits": ..., "project": ..., "attempts": N, "last_ran_h_ago": F}
+sorted by most-attempted dud first (so the most-wasteful repeats surface
+at the top of the prompt anti-list).
+
+Source: reddit_search_attempts (one row per (query, subreddits, project)
+per cmd_search call, written by reddit_tools.py:cmd_search). Routed
+through GET /api/v1/reddit-search-attempts/dud-queries on the website
+to keep this script HTTP-only (no psycopg2 / no DATABASE_URL).
+"""
+import argparse
+import json
+import os
+import sys
+
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+from http_api import api_get
+
+
+def main():
+    p = argparse.ArgumentParser()
+    p.add_argument("--project", default=None,
+                   help="Filter to a single project (matches project_name).")
+    p.add_argument("--limit", type=int, default=30)
+    p.add_argument("--window-hours", type=int, default=168,
+                   help="Look back this many hours for dud queries (default 7d).")
+    args = p.parse_args()
+
+    query = {
+        "limit": args.limit,
+        "window_hours": args.window_hours,
+    }
+    if args.project:
+        query["project"] = args.project
+
+    resp = api_get("/api/v1/reddit-search-attempts/dud-queries", query=query)
+    data = (resp or {}).get("data") or {}
+    rows = data.get("rows") or []
+
+    out = [
+        {
+            "query": r.get("query"),
+            "subreddits": r.get("subreddits") or None,
+            "project": r.get("project") or "",
+            "attempts": int(r.get("attempts") or 0),
+            "last_ran_h_ago": round(float(r.get("last_ran_h_ago") or 0), 1),
+        }
+        for r in rows
+    ]
+    json.dump(out, sys.stdout)
+    print("", file=sys.stdout)
+
+
+if __name__ == "__main__":
+    main()

package/scripts/top_dud_twitter_queries.py

@@ -0,0 +1,71 @@
+#!/usr/bin/env python3
+"""
+top_dud_twitter_queries.py
+
+Returns recent Twitter search queries that produced ZERO tweets so the
+LLM scanner can be told "do not redraft these phrasings — they were flat
+in the last N hours". Counterpart to top_twitter_queries.py (positive
+signal): this is the negative-signal feed.
+
+    python3 scripts/top_dud_twitter_queries.py [--limit 30] [--window-hours 48]
+
+Output: JSON list of
+    {"query": ..., "project": ..., "min_faves": N | null,
+     "attempts": N, "last_ran_h_ago": F}
+sorted by most-attempted dud first (so the most-wasteful repeats surface
+at the top of the prompt anti-list).
+
+The min_faves field is parsed from the query string (X operator
+`min_faves:N`). Surfacing it lets the model correlate "every studyly dud
+last 48h used min_faves:20" → drop the floor for that project.
+
+Source: twitter_search_attempts (one row per query per cycle, written by
+run-twitter-cycle.sh after the Phase 1 scan parses queries_used).
+
+Migrated 2026-05-18: reads now go through /api/v1/twitter-search-attempts/
+dud-queries via scripts/http_api.py instead of a direct psycopg2 query.
+"""
+import argparse
+import json
+import os
+import sys
+
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+from http_api import api_get  # noqa: E402
+
+
+def main():
+    p = argparse.ArgumentParser()
+    p.add_argument("--limit", type=int, default=30)
+    p.add_argument("--window-hours", type=int, default=48,
+                   help="Look back this many hours for dud queries.")
+    p.add_argument("--project", default=None,
+                   help="If set, only return duds for this project.")
+    args = p.parse_args()
+
+    query = {
+        "limit": args.limit,
+        "window_hours": args.window_hours,
+    }
+    if args.project:
+        query["project"] = args.project
+
+    resp = api_get("/api/v1/twitter-search-attempts/dud-queries", query=query)
+    rows = (resp.get("data") or {}).get("rows") or []
+
+    out = [
+        {
+            "query": r.get("query"),
+            "project": r.get("project") or "",
+            "min_faves": r.get("min_faves"),
+            "attempts": int(r.get("attempts") or 0),
+            "last_ran_h_ago": round(float(r.get("last_ran_h_ago") or 0), 1),
+        }
+        for r in rows
+    ]
+    json.dump(out, sys.stdout)
+    print("", file=sys.stdout)
+
+
+if __name__ == "__main__":
+    main()

package/scripts/top_dud_twitter_topics.py

@@ -0,0 +1,102 @@
+#!/usr/bin/env python3
+"""
+top_dud_twitter_topics.py
+
+Returns recent Twitter search_topic SEEDS that are pulling in alive-but-off-fit
+candidates: the search returns viral tweets, Phase 1 stamps them on
+twitter_candidates rows, but Phase 2b's draft gate keeps skipping them (or
+they expire un-drafted). The CONCEPT SEED is finding noise, not buyers.
+
+Where this fits in the feedback ladder:
+- top_search_topics.py        = positive signal (seed -> posted -> engagement)
+- top_dud_twitter_queries.py  = "search returned 0 tweets" signal (the query
+                                phrasing is dead; reword the phrasing)
+- THIS                        = "search returned viral content, draft gate
+                                killed it" signal (the CONCEPT is off-fit;
+                                reword the seed narrower or drop it)
+
+Output: JSON list (so build_discover_prompt can paste it directly), sorted
+most-skipped first:
+
+    [{"search_topic": "...", "project": "...",
+      "posted_n": N, "skipped_n": M,
+      "avg_virality_posted": F, "avg_virality_skipped": F,
+      "omit_rate": 0.NN, "last_skip_h_ago": F.F,
+      "sample_skip_reasons": ["off_brand_crypto", "audience_mismatch", ...]}]
+
+Usage:
+    python3 scripts/top_dud_twitter_topics.py [--project NAME] [--limit 15] [--window-hours 168]
+
+Routed through GET /api/v1/twitter-candidates/dud-topics. omit_rate and
+last_skip_h_ago are computed server-side; the route returns the legacy CLI
+contract directly so the Python wrapper is thin.
+"""
+import argparse
+import json
+import os
+import sys
+
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+from http_api import api_get  # noqa: E402
+
+
+def main():
+    p = argparse.ArgumentParser()
+    p.add_argument("--project", default=None,
+                   help="Filter to a single project (matches matched_project).")
+    p.add_argument("--limit", type=int, default=15)
+    p.add_argument("--window-hours", type=int, default=168,
+                   help="Look back this many hours (default 7d).")
+    p.add_argument("--min-skips", type=int, default=3,
+                   help="Suppress seeds with fewer than this many "
+                        "skipped/expired candidates in the window "
+                        "(default 3; below that the signal is too thin).")
+    args = p.parse_args()
+
+    query = {
+        "limit": args.limit,
+        "window_hours": args.window_hours,
+        "min_skips": args.min_skips,
+    }
+    if args.project:
+        query["project"] = args.project
+
+    resp = api_get("/api/v1/twitter-candidates/dud-topics", query=query)
+    rows = (resp.get("data") or {}).get("rows") or []
+
+    # Route already returns the legacy shape. Mirror keys explicitly so
+    # downstream callers see a stable contract even if the route adds
+    # extra fields later.
+    out = [
+        {
+            "search_topic": r.get("search_topic"),
+            "project": r.get("project") or "",
+            "posted_n": int(r.get("posted_n") or 0),
+            "skipped_n": int(r.get("skipped_n") or 0),
+            "avg_virality_posted": (
+                round(float(r["avg_virality_posted"]), 2)
+                if r.get("avg_virality_posted") is not None
+                else None
+            ),
+            "avg_virality_skipped": (
+                round(float(r["avg_virality_skipped"]), 2)
+                if r.get("avg_virality_skipped") is not None
+                else None
+            ),
+            "omit_rate": round(float(r.get("omit_rate") or 0), 2),
+            "last_skip_h_ago": (
+                round(float(r["last_skip_h_ago"]), 1)
+                if r.get("last_skip_h_ago") is not None
+                else None
+            ),
+            "sample_skip_reasons": r.get("sample_skip_reasons") or [],
+        }
+        for r in rows
+    ]
+
+    json.dump(out, sys.stdout)
+    print("", file=sys.stdout)
+
+
+if __name__ == "__main__":
+    main()

package/scripts/top_linkedin_queries.py

@@ -0,0 +1,55 @@
+#!/usr/bin/env python3
+"""
+top_linkedin_queries.py
+
+Returns the top-performing historical LinkedIn search queries by how many
+candidates they produced that actually got posted. Used as STYLE inspiration
+for the LLM that drafts new queries, NOT as literal keyword reuse (LinkedIn
+SERP shifts daily, so reusing the exact same query is wasteful).
+
+Pair with top_dud_linkedin_queries.py (negative signal).
+
+    python3 scripts/top_linkedin_queries.py [--project NAME] [--search-topic TOPIC] [--limit 20] [--window-days 30]
+
+Output: JSON list of {"query": ..., "project": ..., "search_topic": ..., "posts": N, "avg_velocity": X, "avg_serp_quality": Y}
+
+Window default 30 days (vs Twitter's 14): LinkedIn cycle is sparser, longer
+window captures enough samples.
+
+Migrated 2026-06-01 from direct db.py SELECTs to the s4l.ai HTTP API
+(GET /api/v1/linkedin-candidates/top-queries). No DATABASE_URL needed.
+"""
+import argparse
+import json
+import os
+import sys
+
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+from http_api import api_get
+
+
+def main():
+    p = argparse.ArgumentParser()
+    p.add_argument("--limit", type=int, default=20)
+    p.add_argument("--window-days", type=int, default=30)
+    p.add_argument("--project", default=None)
+    p.add_argument("--search-topic", default=None)
+    args = p.parse_args()
+
+    query = {
+        "limit": args.limit,
+        "window_days": args.window_days,
+    }
+    if args.project:
+        query["project"] = args.project
+    if args.search_topic:
+        query["search_topic"] = args.search_topic
+
+    resp = api_get("/api/v1/linkedin-candidates/top-queries", query)
+    out = (resp.get("data") or {}).get("queries") or []
+    json.dump(out, sys.stdout)
+    print("", file=sys.stdout)
+
+
+if __name__ == "__main__":
+    main()

package/scripts/top_omitted_reddit_topics.py

@@ -0,0 +1,91 @@
+#!/usr/bin/env python3
+"""
+top_omitted_reddit_topics.py
+
+Returns recent Reddit search_topic seeds whose threads consistently survived
+the ripen gate (numerical engagement check) but were then OMITTED by
+post_reddit.py's draft-time SELECTION GATE (build_draft_prompt's bridge test).
+
+Why this matters:
+- top_search_topics.py = positive signal (seed -> posted -> engagement)
+- top_dud_reddit_queries.py = "no results returned" signal (search dud)
+- THIS = "results returned, ripen survived, draft gate killed them" signal
+  i.e. the seed is producing alive-but-unfit threads. Category-level
+  mismatch, the LLM should drop or rephrase that seed.
+
+Output: JSON list (so build_discover_prompt can paste it directly), sorted
+by most-omitted first:
+
+    [{"search_topic": "...", "project": "...",
+      "draft_omits": N, "ripen_survivors": M, "posted": P,
+      "omit_rate": 0.NN, "last_omit_h_ago": F.F,
+      "sample_subreddits": ["r/foo", "r/bar", ...]}]
+
+Usage:
+    python3 scripts/top_omitted_reddit_topics.py [--project NAME] [--limit 15] [--window-hours 168]
+
+Routed through GET /api/v1/reddit-candidates/omitted-topics on the
+website. omit_rate and last_omit_h_ago are computed server-side; the
+shape returned by the route already matches the legacy CLI contract,
+so callers (build_discover_prompt et al.) don't need to change.
+"""
+import argparse
+import json
+import os
+import sys
+
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+from http_api import api_get
+
+
+def main():
+    p = argparse.ArgumentParser()
+    p.add_argument("--project", default=None,
+                   help="Filter to a single project (matches matched_project).")
+    p.add_argument("--limit", type=int, default=15)
+    p.add_argument("--window-hours", type=int, default=168,
+                   help="Look back this many hours (default 7d).")
+    p.add_argument("--min-omits", type=int, default=1,
+                   help="Suppress seeds with fewer than this many draft omits "
+                        "in the window (default 1).")
+    args = p.parse_args()
+
+    query = {
+        "limit": args.limit,
+        "window_hours": args.window_hours,
+        "min_omits": args.min_omits,
+    }
+    if args.project:
+        query["project"] = args.project
+
+    resp = api_get("/api/v1/reddit-candidates/omitted-topics", query=query)
+    data = (resp or {}).get("data") or {}
+    rows = data.get("rows") or []
+
+    # Route already returns the legacy shape. Mirror keys explicitly so
+    # downstream callers see a stable contract even if the route adds
+    # extra fields later.
+    out = [
+        {
+            "search_topic": r.get("search_topic"),
+            "project": r.get("project") or "",
+            "draft_omits": int(r.get("draft_omits") or 0),
+            "ripen_survivors": int(r.get("ripen_survivors") or 0),
+            "posted": int(r.get("posted") or 0),
+            "omit_rate": round(float(r.get("omit_rate") or 0), 2),
+            "last_omit_h_ago": (
+                round(float(r["last_omit_h_ago"]), 1)
+                if r.get("last_omit_h_ago") is not None
+                else None
+            ),
+            "sample_subreddits": r.get("sample_subreddits") or [],
+        }
+        for r in rows
+    ]
+
+    json.dump(out, sys.stdout)
+    print("", file=sys.stdout)
+
+
+if __name__ == "__main__":
+    main()