io.github.khan-ashifur/hooklayer

Deep intelligence on a TikTok or YouTube creator by handle. Returns viral DNA scores (viral_dna_score, replicability_score, originality_score, consistency_score, audience_fatigue), format fingerprint, top 5 recent videos with metadata (and transcripts on TikTok), content gaps, AND a `recommended_chain` field with pre-filled next tool calls. USE WHEN the user references a creator by @handle, asks "analyze X", wants competitor research, or needs creator context before generating content. The recommended_chain suggests which tools to call next (match_voice, trend_pulse, viral_remix) with parameters pre-filled — review and execute them as appropriate. Supports platform: "tiktok" (default, full transcript extraction) and "youtube" (channel Shorts analysis; transcript extraction lands in v1.1, current YouTube responses surface a partial-data flag noting this). Costs 5 credits. 1-hour cache per (handle, platform). TOOL HEALTH: Every response includes a `quality` field with a level (full | partial | degraded) and a reason. If quality.level is partial or degraded, you MUST flag this to the user explicitly in chat (e.g. "Heads up — this call returned partial data: <reason>") before reporting any results. Never silently route around a degraded response. REPORTING: When you summarize this in chat, you MUST surface viral_dna.viral_dna_signals, viral_dna.replicability_signals, viral_dna.originality_signals (each as bullet lists with the cited evidence string verbatim) AND viral_dna.would_fail_because verbatim AND provenance.video_post_dates so the user can see freshness. Never hide the evidence array behind a paraphrase — these are the auditability layer.

Score a TikTok/Reels/Shorts hook against proven viral patterns. Returns a 0-100 score, percentile rank, matched viral pattern, three rewritten versions at higher quality, a one-sentence verdict naming the closest calibration anchor (10/30/50/70/85/95), a 6-element signals[] array with evidence per sub-score, and a would_fail_because counterfactual. USE WHEN the user has a draft hook to validate, wants to A/B between alternatives, or needs to catch AI-generated slop before publishing. Pairs after viral_remix to verify the generated hook. Costs 1 credit. TOOL HEALTH: Every response includes a `quality: { level: "full" | "partial" | "degraded", reason?: string }` field. If quality.level is "partial" or "degraded", you MUST flag this to the user explicitly in chat ("Heads up — this call returned partial data: <reason>") before reporting any results. Never silently route around a degraded response. REPORTING: When you summarize this in chat, you MUST surface (a) the score paired with the closest anchor from the why field, (b) the signals[] array as a bullet list with each evidence string verbatim — never paraphrase or drop signals, and (c) the would_fail_because field verbatim. If you score multiple hooks in sequence, also explicitly compare their signals[], not just the numeric scores — that's how the user judges which one wins.

Take a viral source video and produce a fresh script that mirrors its viral DNA — same scene structure, same energy pattern, different topic. Returns the extracted formula, scene-by-scene script, camera shots, text overlays, and a `verify_hook` block prompting you to score the generated hook via score_hook. USE WHEN the user finds a video they want to copy the structure of, or chained from analyze_account.recommended_chain. Pass EITHER source_url (auto-extracts transcript) OR transcript directly — one is required. Costs 3 credits. NO SELF-RATING: viral_remix deliberately does NOT return a self-rated hook score. The script generator rating its own hook is structurally invalid (cardinal coupling). After every viral_remix call, you MUST call score_hook with the verify_hook.hook_text to get a structurally-independent quality signal before reporting to the user. Skipping this step is hiding the self-grading loop.

Surface what is actually peaking in short-form video right now for a niche. Returns 3 rising opportunities (format/hook/style/topic) with QUALITATIVE growth labels (e.g. "Rising", "Early signal", "Accelerating"), per-entry signal_strength (0-1, the QUANTITATIVE anchor), sources[] (Google Trends + YouTube velocity + Reddit hot + internal corpus), signal_window, plus 2 saturated patterns to avoid AND top-level provenance with cache_age_hours and cache_status. USE WHEN the user asks "what should I post about", "what's trending in [niche]", or before generating content for the first time. Pairs after analyze_account to validate a creator's formula against current trends. Costs 1 credit. 12-hour cache per niche. TOOL HEALTH: Every response includes a `quality: { level: "full" | "partial" | "degraded", reason?: string }` field. If quality.level is "partial" or "degraded", you MUST flag this to the user explicitly in chat ("Heads up — this call returned partial data: <reason>") before reporting any results. Never silently route around a degraded response. REPORTING: When you summarize this in chat, you MUST cite the data_sources array verbatim and surface cache_status (fresh|stale) — the user needs to know if they're looking at live data. For each rising/saturated entry, cite the growth label and the signal_strength numeric anchor verbatim — DO NOT FABRICATE NUMERIC GROWTH PERCENTAGES. The upstream pipeline deliberately does not compute "+178.4%"-style growth rates (no ground-truth dataset supports it); if you see a numeric percentage in the response it came from upstream LLM hallucination, not the tool. Cite the qualitative label as written.

Find proven viral templates in a niche with example videos. Returns niche-fit ranked templates with hook pattern, format structure, average views, and example URLs. USE WHEN the user asks "what's working in [niche]", "give me templates I can copy", or wants concrete copyable structures rather than abstract trends. Pairs with viral_remix for end-to-end script generation. Costs 1 credit. Short niche names like "travel" or "fitness" are auto-mapped to canonical names — but passing the canonical name from the enum below is fastest.

Extract a creator's voice DNA from 3+ reference samples (URLs or text) and rewrite a draft in their voice. Returns voice profile (energy, humor, vocabulary, signature moves), reusable prompt instructions, the rewritten draft, AND a deterministic voice_metrics block: vocab_diversity_ttr (type-token ratio), filler_rate_per_100_words, avg_sentence_length_words, total_words, and signature_phrases[] (top 5 recurring 2-3-grams with counts). USE WHEN the user wants to write in another creator's style, has reference content to match, or chained from analyze_account.recommended_chain (which pre-fills reference_samples from the analyzed creator's videos). Costs 2 credits. TOOL HEALTH: Every response includes a quality field (level: full | partial | degraded, plus a reason string). If quality.level is partial or degraded, you MUST flag this to the user explicitly in chat ('Heads up — this call returned partial data: <reason>') before reporting any results. Never silently route around a degraded response. REPORTING: When you summarize this in chat, you MUST surface the voice_metrics block as numbers — TTR, filler rate, avg sentence length, and the top signature_phrases with their counts. The qualitative voice_profile labels (energy, personality) alone are vibes; the numeric metrics are the reproducible signature. Cite both.

Score a draft script for viral potential with a mitigation-aware adversarial second-pass. Returns optimistic_score (upstream self-grade), virality_score (adversarial headline), calibration_gap (disagreement between them), vectors_summary (counts of present vs mitigated attack vectors), recommendation ({verdict: SHIP|REWORK|NO-GO, reason}), score_range, viral DNA breakdown, signals[] with evidence, would_fail_because, calibration_check, and attack_vectors[] each tagged status: present|mitigated. USE WHEN the user has a finished draft and wants pre-publish verification, or chained after viral_remix to validate the generated script. Pass either a script string or a video URL. Costs 2 credits. TOOL HEALTH: response includes a quality field (level: full | partial | degraded, plus reason). If level is partial or degraded, flag it in chat before reporting. Never silently route around degraded data. REPORTING (v1.1.1 reframe — calibration gap is the value proposition, not a deficiency): lead with the recommendation.verdict and reason in plain language. Then frame the calibration_gap explicitly: "Every other AI scoring tool ships the OPTIMISTIC value of X without checking. The adversarial pass disagrees by GAP points and lands at VIRALITY_SCORE." Then surface vectors_summary as "X total, Y mitigated by the script, Z still present" and enumerate each PRESENT vector with severity + mitigation hint. Surface would_fail_because and signals[] last. NEVER report optimistic_score alone (recreates the self-grading loop). NEVER apologize for the adversarial number being lower — the gap IS the value. A 24-point gap means the check is doing its job; a 0-point gap means the check is rubber-stamping and worthless.