Copywriting

#!/usr/bin/env python3
"""
CTA Optimizer

Analyzes and scores call-to-action text for strength,
friction level, and conversion potential.

Usage:
    python cta_optimizer.py "Start my free trial"
    python cta_optimizer.py --file ctas.txt --json
"""

import argparse
import json
import re
import sys

STRONG_CTAS = {
    "start": 90, "get": 85, "create": 85, "build": 85, "try": 80,
    "discover": 80, "claim": 85, "unlock": 80, "see": 75, "join": 80,
    "book": 75, "download": 75, "access": 80, "activate": 85,
}

WEAK_CTAS = {
    "submit": 30, "click here": 25, "click": 30, "send": 35,
    "go": 40, "enter": 35, "continue": 40,
}

MODERATE_CTAS = {
    "learn more": 50, "sign up": 60, "get started": 65,
    "contact us": 45, "request": 55, "register": 55,
    "subscribe": 55, "buy now": 60, "order": 55,
}

FRICTION_REDUCERS = [
    "free", "no credit card", "no card", "cancel anytime",
    "2 minutes", "instant", "no commitment", "risk-free",
    "money-back", "guarantee", "try", "no obligation",
]

OWNERSHIP_WORDS = ["my", "your", "our"]


def score_cta(cta: str) -> dict:
    lower = cta.lower().strip()
    words = lower.split()
    result = {
        "cta": cta,
        "word_count": len(words),
        "scores": {},
        "analysis": {},
        "improvements": [],
    }

    # Action strength
    first_word = words[0] if words else ""
    action_score = 50

    if first_word in STRONG_CTAS:
        action_score = STRONG_CTAS[first_word]
        result["analysis"]["action_strength"] = "strong"
    elif lower in WEAK_CTAS or first_word in WEAK_CTAS:
        action_score = WEAK_CTAS.get(lower, WEAK_CTAS.get(first_word, 35))
        result["analysis"]["action_strength"] = "weak"
        result["improvements"].append(f"Replace '{first_word}' with a stronger verb (start, get, create, build).")
    elif lower in MODERATE_CTAS or first_word in MODERATE_CTAS:
        action_score = MODERATE_CTAS.get(lower, MODERATE_CTAS.get(first_word, 55))
        result["analysis"]["action_strength"] = "moderate"
    else:
        action_score = 55
        result["analysis"]["action_strength"] = "unknown"

    result["scores"]["action_strength"] = action_score

    # Specificity -- does it tell them what they get?
    has_what = len(words) > 2
    has_benefit_word = bool(re.search(r"(trial|demo|guide|report|analysis|dashboard|account|plan|checklist|template)", lower))

    specificity = 40
    if has_what and has_benefit_word:
        specificity = 90
        result["analysis"]["specificity"] = "high -- tells user what they receive"
    elif has_what:
        specificity = 65
        result["analysis"]["specificity"] = "medium -- action but vague outcome"
        result["improvements"].append("Add what they get: 'Start my free trial' > 'Start'")
    else:
        specificity = 35
        result["analysis"]["specificity"] = "low -- too generic"
        result["improvements"].append("Expand CTA: [Action Verb] + [What They Get]")

    result["scores"]["specificity"] = specificity

    # Ownership language
    has_ownership = any(w in words for w in OWNERSHIP_WORDS)
    if has_ownership:
        result["scores"]["ownership"] = 85
        result["analysis"]["ownership"] = "Uses ownership language ('my/your') -- increases click rate"
    else:
        result["scores"]["ownership"] = 50
        result["improvements"].append("Try ownership: 'Start free trial' -> 'Start my free trial'")

    # Friction assessment
    friction_signals = [f for f in FRICTION_REDUCERS if f in lower]
    if friction_signals:
        result["scores"]["friction"] = 90
        result["analysis"]["friction_level"] = "low -- friction reducers present"
    elif any(w in lower for w in ["buy", "purchase", "pay", "subscribe", "commit"]):
        result["scores"]["friction"] = 35
        result["analysis"]["friction_level"] = "high -- purchase commitment"
    else:
        result["scores"]["friction"] = 60
        result["analysis"]["friction_level"] = "medium"
        result["improvements"].append("Add supporting text below CTA: 'No credit card required' or 'Free for 14 days'")

    # Length
    if 3 <= len(words) <= 6:
        result["scores"]["length"] = 90
    elif len(words) <= 2:
        result["scores"]["length"] = 55
        result["improvements"].append("CTA is too short. Aim for 3-6 words.")
    else:
        result["scores"]["length"] = 60
        result["improvements"].append("CTA is long. Trim to 3-6 words.")

    # Overall
    weights = {"action_strength": 0.30, "specificity": 0.25, "ownership": 0.15, "friction": 0.15, "length": 0.15}
    overall = sum(result["scores"].get(k, 50) * w for k, w in weights.items())
    result["overall_score"] = round(overall)
    result["grade"] = "A" if overall >= 85 else "B" if overall >= 70 else "C" if overall >= 55 else "D" if overall >= 40 else "F"

    if not result["improvements"]:
        result["improvements"].append("Strong CTA. A/B test against 2-3 variants.")

    return result


def format_human(results: list) -> str:
    lines = ["\n" + "=" * 55, "  CTA OPTIMIZER", "=" * 55]
    for r in results:
        lines.append(f"\n  \"{r['cta']}\"")
        lines.append(f"  Score: {r['overall_score']}/100 ({r['grade']})")
        for k, v in r["analysis"].items():
            lines.append(f"    {k.replace('_', ' ').title()}: {v}")
        for imp in r["improvements"]:
            lines.append(f"    > {imp}")
        lines.append("-" * 55)
    return "\n".join(lines)


def main():
    parser = argparse.ArgumentParser(description="Score and optimize CTA copy.")
    parser.add_argument("cta", nargs="?")
    parser.add_argument("--file", "-f")
    parser.add_argument("--json", action="store_true", dest="json_output")
    args = parser.parse_args()

    ctas = []
    if args.file:
        with open(args.file) as f:
            ctas = [l.strip() for l in f if l.strip()]
    elif args.cta:
        ctas = [args.cta]
    else:
        parser.print_help()
        sys.exit(1)

    results = [score_cta(c) for c in ctas]
    if args.json_output:
        print(json.dumps(results if len(results) > 1 else results[0], indent=2))
    else:
        print(format_human(results))


if __name__ == "__main__":
    main()

#!/usr/bin/env python3
"""
Headline Scorer

Scores marketing headlines for clarity, benefit strength,
specificity, and conversion potential.

Usage:
    python headline_scorer.py "Build landing pages in minutes without writing code"
    python headline_scorer.py --file headlines.txt --json
"""

import argparse
import json
import re
import sys

POWER_WORDS = [
    "free", "new", "proven", "guaranteed", "instant", "exclusive",
    "secret", "discover", "revolutionary", "breakthrough", "simple",
    "easy", "fast", "powerful", "ultimate", "complete", "essential",
]

ACTION_VERBS = [
    "build", "create", "get", "start", "grow", "reduce", "cut", "save",
    "boost", "increase", "automate", "ship", "hire", "scale", "stop",
    "eliminate", "transform", "unlock", "achieve", "discover", "join",
]

VAGUE_WORDS = [
    "innovative", "cutting-edge", "best-in-class", "world-class",
    "industry-leading", "state-of-the-art", "next-generation",
    "synergy", "holistic", "leverage", "optimize", "solutions",
    "ecosystem", "paradigm",
]

WE_PATTERNS = re.compile(r"^(we |our |at \w+)", re.IGNORECASE)
YOU_PATTERNS = re.compile(r"\b(you|your|you're)\b", re.IGNORECASE)


def score_headline(headline: str) -> dict:
    words = headline.split()
    lower = headline.lower()
    result = {
        "headline": headline,
        "word_count": len(words),
        "char_count": len(headline),
        "scores": {},
        "strengths": [],
        "weaknesses": [],
        "suggestions": [],
    }

    total = 100

    # Length
    wc = len(words)
    if 6 <= wc <= 12:
        result["scores"]["length"] = 95
        result["strengths"].append("Optimal headline length (6-12 words).")
    elif 4 <= wc <= 15:
        result["scores"]["length"] = 75
    elif wc < 4:
        result["scores"]["length"] = 50
        result["weaknesses"].append("Headline may be too short to convey full value.")
        total -= 8
    else:
        result["scores"]["length"] = 45
        result["weaknesses"].append("Headline is too long. Cut to 6-12 words.")
        total -= 12

    # Specificity
    has_number = bool(re.search(r"\d+", headline))
    has_specific_metric = bool(re.search(r"\d+%|\d+ (hours|minutes|days|weeks|x|teams|customers)", headline, re.IGNORECASE))
    has_timeframe = bool(re.search(r"in \d+ (minutes|hours|days|weeks|months)", headline, re.IGNORECASE))

    specificity_score = 40
    if has_specific_metric:
        specificity_score += 35
        result["strengths"].append("Specific metric makes claim believable.")
    if has_number:
        specificity_score += 15
    if has_timeframe:
        specificity_score += 10
        result["strengths"].append("Timeframe adds credibility.")

    found_vague = [w for w in VAGUE_WORDS if w in lower]
    if found_vague:
        specificity_score -= 20
        result["weaknesses"].append(f"Vague words: {', '.join(found_vague)}. Replace with specifics.")
        total -= 10

    result["scores"]["specificity"] = min(100, specificity_score)

    # Benefit clarity
    has_action = any(lower.startswith(v) or f" {v} " in lower for v in ACTION_VERBS)
    has_benefit = bool(re.search(r"(without|in \d|save|reduce|increase|grow|cut|boost|get|achieve)", lower))
    has_pain_removal = bool(re.search(r"(without|no |stop |eliminate|never )", lower))

    benefit_score = 40
    if has_action:
        benefit_score += 20
        result["strengths"].append("Starts with or contains an action verb.")
    if has_benefit:
        benefit_score += 25
    if has_pain_removal:
        benefit_score += 15
        result["strengths"].append("Includes pain removal framing (strong for conversion).")

    result["scores"]["benefit_clarity"] = min(100, benefit_score)

    # Customer focus
    starts_with_we = bool(WE_PATTERNS.match(headline))
    has_you = bool(YOU_PATTERNS.search(headline))

    if starts_with_we:
        result["weaknesses"].append("Starts with 'We/Our' -- lead with the customer's world instead.")
        total -= 8
    if has_you:
        result["strengths"].append("Uses 'you/your' -- customer-focused language.")

    # Emotional resonance
    power_found = [w for w in POWER_WORDS if w in lower]
    emotional_score = 50
    if power_found:
        emotional_score += min(30, len(power_found) * 10)
    if "?" in headline:
        emotional_score += 10
        result["strengths"].append("Question format creates curiosity.")

    result["scores"]["emotional_pull"] = min(100, emotional_score)

    # Overall
    weights = {"length": 0.15, "specificity": 0.30, "benefit_clarity": 0.35, "emotional_pull": 0.20}
    weighted = sum(result["scores"].get(k, 50) * w for k, w in weights.items())
    total = min(100, max(0, int(weighted)))

    result["overall_score"] = total
    result["grade"] = "A" if total >= 85 else "B" if total >= 70 else "C" if total >= 55 else "D" if total >= 40 else "F"

    if not result["suggestions"]:
        if total < 70:
            result["suggestions"].append("Try formula: '[Achieve outcome] without [pain point]'")
            result["suggestions"].append("Add a specific number or metric for credibility.")
        else:
            result["suggestions"].append("Test 2-3 variants of this headline via A/B testing.")

    return result


def format_human(results: list) -> str:
    lines = ["\n" + "=" * 60, "  HEADLINE SCORER", "=" * 60]
    for r in results:
        lines.append(f"\n  \"{r['headline']}\"")
        lines.append(f"  Score: {r['overall_score']}/100 ({r['grade']}) | {r['word_count']} words, {r['char_count']} chars")
        for k, v in r["scores"].items():
            lines.append(f"    {k.replace('_', ' ').title()}: {v}/100")
        for s in r["strengths"]:
            lines.append(f"    + {s}")
        for w in r["weaknesses"]:
            lines.append(f"    - {w}")
        for s in r["suggestions"]:
            lines.append(f"    > {s}")
        lines.append("-" * 60)
    return "\n".join(lines)


def main():
    parser = argparse.ArgumentParser(description="Score marketing headlines for conversion potential.")
    parser.add_argument("headline", nargs="?")
    parser.add_argument("--file", "-f")
    parser.add_argument("--json", action="store_true", dest="json_output")
    args = parser.parse_args()

    headlines = []
    if args.file:
        with open(args.file) as f:
            headlines = [l.strip() for l in f if l.strip()]
    elif args.headline:
        headlines = [args.headline]
    else:
        parser.print_help()
        sys.exit(1)

    results = [score_headline(h) for h in headlines]
    if args.json_output:
        print(json.dumps(results if len(results) > 1 else results[0], indent=2))
    else:
        print(format_human(results))


if __name__ == "__main__":
    main()

#!/usr/bin/env python3
"""
Page Copy Auditor

Audits marketing page copy for conversion principles:
benefit clarity, specificity, customer focus, CTA strength,
objection handling, and social proof.

Usage:
    python page_copy_auditor.py page.txt
    python page_copy_auditor.py page.html --json
"""

import argparse
import json
import re
import sys
from pathlib import Path

HTML_TAG = re.compile(r"<[^>]+>")


def audit_copy(text: str) -> dict:
    # Strip HTML if present
    plain = HTML_TAG.sub(" ", text)
    plain = re.sub(r"\s+", " ", plain).strip()

    sentences = [s.strip() for s in re.split(r"[.!?]+", plain) if s.strip()]
    words = plain.split()
    word_count = len(words)

    result = {
        "word_count": word_count,
        "sentence_count": len(sentences),
        "scores": {},
        "checks": [],
        "issues": [],
        "suggestions": [],
    }

    # 1. Customer focus (you vs we)
    you_count = len(re.findall(r"\b(you|your|you're|yourself)\b", plain, re.IGNORECASE))
    we_count = len(re.findall(r"\b(we|our|we're|us)\b", plain, re.IGNORECASE))
    ratio = you_count / max(we_count, 1)

    if ratio >= 2:
        result["checks"].append({"name": "Customer Focus", "status": "PASS", "detail": f"You/Your: {you_count}, We/Our: {we_count} (ratio: {ratio:.1f}:1)"})
        result["scores"]["customer_focus"] = 90
    elif ratio >= 1:
        result["checks"].append({"name": "Customer Focus", "status": "OK", "detail": f"You: {you_count}, We: {we_count}"})
        result["scores"]["customer_focus"] = 65
    else:
        result["checks"].append({"name": "Customer Focus", "status": "FAIL", "detail": f"We/Our ({we_count}) outnumbers You/Your ({you_count})"})
        result["scores"]["customer_focus"] = 35
        result["issues"].append("Copy is company-focused. Rewrite to lead with 'you' and the customer's world.")

    # 2. Specificity
    numbers = re.findall(r"\d+", plain)
    specific_metrics = re.findall(r"\d+%|\d+x|\$\d+|\d+ (hours|minutes|days|teams|customers|companies)", plain, re.IGNORECASE)
    has_named_companies = bool(re.search(r"(Stripe|Notion|Slack|Linear|Figma|Shopify|HubSpot|\w+\.com)", plain))

    specificity = 30
    if len(specific_metrics) >= 3:
        specificity = 90
    elif len(specific_metrics) >= 1:
        specificity = 65
    if has_named_companies:
        specificity += 10
    if len(numbers) == 0:
        result["issues"].append("No numbers or metrics found. Add specific data for credibility.")

    result["scores"]["specificity"] = min(100, specificity)
    result["checks"].append({"name": "Specificity", "status": "PASS" if specificity >= 70 else "WARN", "detail": f"{len(specific_metrics)} specific metrics, {len(numbers)} numbers total"})

    # 3. Social proof
    social_proof_patterns = [
        re.compile(r"(trusted by|used by|join|loved by)\s+\d+", re.IGNORECASE),
        re.compile(r"\d+\s*(teams|companies|customers|users|businesses)", re.IGNORECASE),
        re.compile(r"(testimonial|review|rating|stars?|4\.\d|5\.0)", re.IGNORECASE),
        re.compile(r'".+"\s*[-—]\s*\w+', re.IGNORECASE),  # quoted testimonial
    ]
    proof_found = sum(1 for p in social_proof_patterns if p.search(plain))

    if proof_found >= 2:
        result["scores"]["social_proof"] = 85
        result["checks"].append({"name": "Social Proof", "status": "PASS", "detail": f"{proof_found} social proof elements found"})
    elif proof_found == 1:
        result["scores"]["social_proof"] = 55
        result["checks"].append({"name": "Social Proof", "status": "WARN", "detail": "Limited social proof"})
        result["suggestions"].append("Add more social proof: testimonials with names, metrics, and specific outcomes.")
    else:
        result["scores"]["social_proof"] = 20
        result["checks"].append({"name": "Social Proof", "status": "FAIL", "detail": "No social proof detected"})
        result["issues"].append("No social proof found. Add testimonials, customer counts, or review scores.")

    # 4. CTA presence
    cta_patterns = [
        re.compile(r"(start|get|try|book|sign up|create|download|claim|unlock|begin|join)\b", re.IGNORECASE),
    ]
    cta_found = sum(1 for p in cta_patterns if p.search(plain))
    cta_mentions = len(re.findall(r"(start|get started|try free|book|sign up|free trial)", plain, re.IGNORECASE))

    if cta_mentions >= 2:
        result["scores"]["cta_presence"] = 85
        result["checks"].append({"name": "CTA Presence", "status": "PASS", "detail": f"{cta_mentions} CTA mentions"})
    elif cta_mentions >= 1:
        result["scores"]["cta_presence"] = 60
        result["checks"].append({"name": "CTA Presence", "status": "WARN", "detail": "Single CTA -- add 2-3 throughout page"})
    else:
        result["scores"]["cta_presence"] = 25
        result["checks"].append({"name": "CTA Presence", "status": "FAIL", "detail": "No clear CTA found"})
        result["issues"].append("No clear CTA detected. Add action-oriented CTAs throughout the page.")

    # 5. Objection handling
    objection_patterns = [
        re.compile(r"(no credit card|cancel anytime|money.back|guarantee|refund|free trial|risk.free)", re.IGNORECASE),
        re.compile(r"(faq|frequently asked|common questions)", re.IGNORECASE),
        re.compile(r"(secure|encrypted|privacy|gdpr|soc 2|iso|compliant)", re.IGNORECASE),
    ]
    objection_count = sum(1 for p in objection_patterns if p.search(plain))

    if objection_count >= 2:
        result["scores"]["objection_handling"] = 85
    elif objection_count == 1:
        result["scores"]["objection_handling"] = 55
        result["suggestions"].append("Add risk reversal near CTAs: 'No credit card required' or 'Cancel anytime'.")
    else:
        result["scores"]["objection_handling"] = 20
        result["issues"].append("No objection handling found. Add FAQs, guarantees, or risk reversal copy.")

    result["checks"].append({"name": "Objection Handling", "status": "PASS" if objection_count >= 2 else "WARN" if objection_count == 1 else "FAIL", "detail": f"{objection_count} objection-handling elements"})

    # 6. Readability
    avg_words_per_sentence = word_count / max(len(sentences), 1)
    if avg_words_per_sentence <= 15:
        result["scores"]["readability"] = 90
    elif avg_words_per_sentence <= 20:
        result["scores"]["readability"] = 70
    else:
        result["scores"]["readability"] = 45
        result["suggestions"].append("Sentences are too long. Break into shorter, punchier sentences.")

    # Overall
    weights = {"customer_focus": 0.20, "specificity": 0.20, "social_proof": 0.20, "cta_presence": 0.15, "objection_handling": 0.15, "readability": 0.10}
    overall = sum(result["scores"].get(k, 50) * w for k, w in weights.items())
    result["overall_score"] = round(overall)
    result["grade"] = "A" if overall >= 85 else "B" if overall >= 70 else "C" if overall >= 55 else "D" if overall >= 40 else "F"

    return result


def format_human(result: dict) -> str:
    lines = ["\n" + "=" * 60, "  PAGE COPY AUDITOR", "=" * 60]
    lines.append(f"\n  Score: {result['overall_score']}/100 ({result['grade']}) | {result['word_count']} words, {result['sentence_count']} sentences")

    lines.append(f"\n  Checks:")
    for c in result["checks"]:
        icon = {"PASS": "+", "WARN": "!", "FAIL": "X", "OK": "~"}
        lines.append(f"    [{icon.get(c['status'], '?')}] {c['name']}: {c['detail']}")

    lines.append(f"\n  Scores:")
    for k, v in sorted(result["scores"].items(), key=lambda x: -x[1]):
        lines.append(f"    {k.replace('_', ' ').title():<20} {v}/100")

    if result["issues"]:
        lines.append(f"\n  Issues:")
        for i in result["issues"]:
            lines.append(f"    X {i}")

    if result["suggestions"]:
        lines.append(f"\n  Suggestions:")
        for s in result["suggestions"]:
            lines.append(f"    > {s}")

    lines.append("")
    return "\n".join(lines)


def main():
    parser = argparse.ArgumentParser(description="Audit marketing page copy for conversion potential.")
    parser.add_argument("file", help="Text or HTML file to audit")
    parser.add_argument("--json", action="store_true", dest="json_output")
    args = parser.parse_args()

    try:
        text = Path(args.file).read_text()
    except FileNotFoundError:
        print(f"Error: {args.file} not found", file=sys.stderr)
        sys.exit(1)

    result = audit_copy(text)
    if args.json_output:
        print(json.dumps(result, indent=2))
    else:
        print(format_human(result))


if __name__ == "__main__":
    main()