Content Production

#!/usr/bin/env python3
"""
Content Brief Generator for Production

Generates production-ready content briefs with keyword targets, audience
definition, recommended structure, competitive research prompts, and
SEO requirements. Designed for the content production pipeline.

Usage:
    python content_brief_generator.py --keyword "cloud cost optimization"
    python content_brief_generator.py --keyword "SEO audit" --audience "CTOs" --json
    python content_brief_generator.py --keyword "best CRM" --format comparison
"""

import argparse
import json
import re
import sys


def classify_intent(keyword):
    """Classify search intent."""
    kw = keyword.lower()
    if re.search(r'\b(what is|how to|guide|tutorial|explain|learn|overview)\b', kw):
        return "informational"
    if re.search(r'\b(best|top|review|vs|compare|alternative|tool|software)\b', kw):
        return "commercial"
    if re.search(r'\b(buy|price|pricing|discount|free trial|sign up|download)\b', kw):
        return "transactional"
    return "informational"


FORMAT_SPECS = {
    "guide": {
        "name": "Comprehensive Guide",
        "word_count": "1,800-2,500",
        "h2_count": "5-7",
        "sections": [
            "What is [topic] (definition)",
            "Why [topic] matters",
            "How to [topic] (step-by-step)",
            "Best practices",
            "Common mistakes to avoid",
            "Tools and resources",
            "FAQ",
        ],
    },
    "comparison": {
        "name": "Comparison / Buyer's Guide",
        "word_count": "2,000-3,000",
        "h2_count": "6-8",
        "sections": [
            "Overview of options",
            "Evaluation criteria",
            "Detailed comparison (table)",
            "Pros and cons per option",
            "Best for [use case 1]",
            "Best for [use case 2]",
            "Pricing comparison",
            "Our recommendation",
        ],
    },
    "listicle": {
        "name": "List Article",
        "word_count": "1,500-2,000",
        "h2_count": "7-12",
        "sections": [
            "Introduction (why this list matters)",
            "[Item 1] — description + use case",
            "[Item 2] — description + use case",
            "[Item N] — description + use case",
            "How to choose the right one",
            "FAQ",
        ],
    },
    "how_to": {
        "name": "How-To Tutorial",
        "word_count": "1,200-2,000",
        "h2_count": "5-8",
        "sections": [
            "What you need before starting",
            "Step 1: [action]",
            "Step 2: [action]",
            "Step N: [action]",
            "Common issues and fixes",
            "Next steps",
        ],
    },
}


def generate_brief(keyword, audience=None, content_format=None):
    """Generate a production-ready content brief."""
    intent = classify_intent(keyword)

    if content_format is None:
        format_map = {
            "informational": "guide",
            "commercial": "comparison",
            "transactional": "how_to",
        }
        content_format = format_map.get(intent, "guide")

    spec = FORMAT_SPECS.get(content_format, FORMAT_SPECS["guide"])

    return {
        "brief_type": "production",
        "keyword": keyword,
        "intent": intent,
        "audience": audience or "[Define target reader: role, seniority, industry]",
        "format": spec["name"],
        "target_word_count": spec["word_count"],
        "structure": {
            "h1": f"[Compelling title with '{keyword}' front-loaded, under 60 chars]",
            "target_h2_count": spec["h2_count"],
            "sections": spec["sections"],
        },
        "seo_requirements": {
            "primary_keyword": keyword,
            "secondary_keywords": [
                f"{keyword} guide",
                f"{keyword} best practices",
                f"how to {keyword}",
                f"{keyword} examples",
                f"{keyword} {str(2026)}",
            ],
            "keyword_in_h1": True,
            "keyword_in_first_100_words": True,
            "keyword_in_2_plus_h2s": True,
            "meta_title": f"Under 60 chars with '{keyword}'",
            "meta_description": "140-160 chars with keyword + value prop + hook",
            "url_slug": f"/{keyword.lower().replace(' ', '-')}",
            "internal_links": "3-5 to related content",
            "external_links": "2-3 to authoritative sources",
            "schema": "Article (minimum), FAQPage if FAQ included",
        },
        "quality_requirements": {
            "readability": "Flesch Reading Ease 60-70",
            "max_paragraph_length": "4 sentences",
            "images": "1 per 500 words",
            "active_voice": "80%+ of sentences",
            "no_ai_filler_words": True,
            "sources_required": "3-5 credible, citable sources",
        },
        "competitive_research": {
            "task": f"Analyze top 5 ranking pages for '{keyword}'",
            "record_per_competitor": [
                "URL, format, word count",
                "Key angle or unique perspective",
                "What they cover well",
                "What they miss (your opportunity)",
            ],
        },
        "production_timeline": {
            "brief_review": "Day 0",
            "research_and_outline": "Days 1-2",
            "first_draft": "Days 3-5",
            "editorial_review": "Days 6-7",
            "revisions": "Day 8",
            "seo_optimization": "Day 9",
            "final_review_and_staging": "Day 10",
            "publish": "Day 11",
        },
    }


def main():
    parser = argparse.ArgumentParser(description="Generate production content briefs")
    parser.add_argument("--keyword", required=True)
    parser.add_argument("--audience", help="Target audience")
    parser.add_argument("--format", choices=list(FORMAT_SPECS.keys()), help="Content format")
    parser.add_argument("--json", action="store_true")
    args = parser.parse_args()

    brief = generate_brief(args.keyword, args.audience, args.format)

    if args.json:
        print(json.dumps(brief, indent=2))
    else:
        print(f"\n{'='*60}")
        print(f"  CONTENT BRIEF: {args.keyword}")
        print(f"{'='*60}")
        print(f"  Format: {brief['format']} | Intent: {brief['intent']}")
        print(f"  Word count: {brief['target_word_count']}")
        print(f"  Audience: {brief['audience']}")

        print(f"\n  Structure ({brief['structure']['target_h2_count']} H2s):")
        print(f"  H1: {brief['structure']['h1']}")
        for i, s in enumerate(brief["structure"]["sections"], 1):
            print(f"  H2.{i}: {s}")

        print(f"\n  SEO Requirements:")
        print(f"  - Meta title: {brief['seo_requirements']['meta_title']}")
        print(f"  - URL: {brief['seo_requirements']['url_slug']}")
        print(f"  - Internal links: {brief['seo_requirements']['internal_links']}")
        print(f"  - Schema: {brief['seo_requirements']['schema']}")

        print(f"\n  Timeline:")
        for stage, day in brief["production_timeline"].items():
            print(f"  - {stage.replace('_', ' ').title()}: {day}")

        print()


if __name__ == "__main__":
    main()

#!/usr/bin/env python3
"""
Production Headline Analyzer

Analyzes and scores headline options for content production. Checks
SEO length compliance, power word usage, number presence, emotional
impact, and formula matching. Recommends the best headline from a set.

Usage:
    python headline_analyzer.py --headline "10 Ways to Cut Cloud Costs in 2026"
    python headline_analyzer.py --headlines headlines.txt --json
    python headline_analyzer.py --headline "Title Here" --keyword "cloud costs"
"""

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


POWER_WORDS = [
    'proven', 'ultimate', 'complete', 'essential', 'free', 'new', 'easy',
    'fast', 'quick', 'simple', 'guaranteed', 'powerful', 'secret', 'insider',
    'surprising', 'unexpected', 'amazing', 'incredible', 'best', 'top',
    'guide', 'step', 'hack', 'strategy', 'framework', 'checklist', 'template',
]

WEAK_WORDS = [
    'things', 'stuff', 'nice', 'good', 'bad', 'great', 'awesome', 'interesting',
    'important', 'very', 'really', 'basically', 'actually',
]

FORMULAS = {
    "number_list": (r'^\d+\s+', "Numbered list — high CTR format"),
    "how_to": (r'^how\s+to\b', "How-to — matches informational intent"),
    "question": (r'\?$', "Question — triggers curiosity"),
    "year": (r'\b202[4-9]\b', "Year tag — signals freshness"),
    "guide": (r'\bguide\b', "Guide label — promises comprehensiveness"),
    "comparison": (r'\bvs\.?\b|\bversus\b', "Comparison — matches commercial intent"),
    "colon_format": (r':', "Colon format — establishes topic then value"),
}


def score_headline(headline, keyword=None):
    """Score a headline 0-100."""
    hl = headline.strip()
    hl_lower = hl.lower()
    words = hl_lower.split()
    chars = len(hl)
    score = 0
    checks = []

    # Character length (max 30 points)
    if 45 <= chars <= 60:
        score += 30
        checks.append(("PASS", f"Length: {chars} chars (optimal)"))
    elif 35 <= chars <= 65:
        score += 20
        checks.append(("PASS", f"Length: {chars} chars (acceptable)"))
    else:
        score += 5
        checks.append(("FAIL", f"Length: {chars} chars (target 50-60)"))

    # Number (15 points)
    if re.search(r'\d+', hl):
        score += 15
        checks.append(("PASS", "Contains number"))
    else:
        checks.append(("FAIL", "No number — adds 36% CTR lift"))

    # Power words (15 points)
    found = [w for w in POWER_WORDS if w in hl_lower]
    if found:
        score += 15
        checks.append(("PASS", f"Power words: {', '.join(found[:3])}"))
    else:
        checks.append(("FAIL", "No power words detected"))

    # No weak words (10 points)
    weak = [w for w in WEAK_WORDS if w in words]
    if not weak:
        score += 10
        checks.append(("PASS", "No weak words"))
    else:
        checks.append(("FAIL", f"Weak words: {', '.join(weak)}"))

    # Formula match (15 points)
    matched = None
    for name, (pattern, desc) in FORMULAS.items():
        if re.search(pattern, hl_lower):
            matched = desc
            break
    if matched:
        score += 15
        checks.append(("PASS", f"Formula: {matched}"))
    else:
        checks.append(("FAIL", "No proven formula pattern"))

    # Keyword (15 points)
    if keyword:
        kw = keyword.lower()
        if kw in hl_lower:
            pos = hl_lower.find(kw)
            if pos < chars * 0.4:
                score += 15
                checks.append(("PASS", "Keyword front-loaded"))
            else:
                score += 10
                checks.append(("PASS", "Keyword present but not front-loaded"))
        else:
            checks.append(("FAIL", f"Keyword '{keyword}' missing"))
    else:
        score += 8  # Neutral if no keyword given

    return {
        "headline": hl,
        "score": min(score, 100),
        "grade": "A" if score >= 80 else "B" if score >= 65 else "C" if score >= 50 else "D" if score >= 35 else "F",
        "char_count": chars,
        "word_count": len(words),
        "checks": checks,
    }


def main():
    parser = argparse.ArgumentParser(description="Analyze headlines for production")
    group = parser.add_mutually_exclusive_group(required=True)
    group.add_argument("--headline", help="Single headline")
    group.add_argument("--headlines", help="File with headlines")
    parser.add_argument("--keyword")
    parser.add_argument("--json", action="store_true")
    args = parser.parse_args()

    headlines = []
    if args.headline:
        headlines = [args.headline]
    else:
        fp = Path(args.headlines)
        if not fp.exists():
            print(f"Error: {fp} not found", file=sys.stderr)
            sys.exit(1)
        headlines = [l.strip() for l in fp.read_text().splitlines() if l.strip()]

    results = [score_headline(h, args.keyword) for h in headlines]

    if args.json:
        print(json.dumps({"headlines": results}, indent=2))
    else:
        for r in results:
            print(f"\n  {'='*55}")
            print(f"  {r['headline']}")
            print(f"  Score: {r['score']}/100 (Grade: {r['grade']}) | {r['char_count']} chars")
            for status, detail in r["checks"]:
                print(f"  [{status}] {detail}")

        if len(results) > 1:
            best = max(results, key=lambda r: r["score"])
            print(f"\n  RECOMMENDED: \"{best['headline']}\" ({best['score']}/100)")
        print()


if __name__ == "__main__":
    main()

#!/usr/bin/env python3
"""
Content Readability Scorer

Comprehensive readability analysis including Flesch Reading Ease,
Flesch-Kincaid Grade Level, sentence length analysis, paragraph
analysis, passive voice detection, and web readability scoring.

Usage:
    python readability_scorer.py article.md
    python readability_scorer.py article.md --json
    python readability_scorer.py article.md --verbose
"""

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


def strip_markdown(text):
    """Remove markdown formatting for analysis."""
    text = re.sub(r'^#{1,6}\s+', '', text, flags=re.MULTILINE)
    text = re.sub(r'\*\*([^*]+)\*\*', r'\1', text)
    text = re.sub(r'\*([^*]+)\*', r'\1', text)
    text = re.sub(r'`[^`]+`', '', text)
    text = re.sub(r'```.*?```', '', text, flags=re.DOTALL)
    text = re.sub(r'\[([^\]]+)\]\([^)]+\)', r'\1', text)
    text = re.sub(r'^\s*[\-\*]\s+', '', text, flags=re.MULTILINE)
    text = re.sub(r'^\s*\d+\.\s+', '', text, flags=re.MULTILINE)
    text = re.sub(r'^\|.*\|$', '', text, flags=re.MULTILINE)
    text = re.sub(r'^---+$', '', text, flags=re.MULTILINE)
    text = re.sub(r'\n{3,}', '\n\n', text)
    return text.strip()


def count_syllables(word):
    """Estimate syllable count."""
    word = word.lower().strip('.,!?;:()[]{}"\'-')
    if len(word) <= 3:
        return 1
    count = 0
    vowels = 'aeiouy'
    prev = False
    for c in word:
        v = c in vowels
        if v and not prev:
            count += 1
        prev = v
    if word.endswith('e') and count > 1:
        count -= 1
    if word.endswith('le') and len(word) > 2 and word[-3] not in vowels:
        count += 1
    return max(count, 1)


def get_sentences(text):
    """Split text into sentences."""
    sentences = re.split(r'(?<=[.!?])\s+(?=[A-Z])', text)
    return [s.strip() for s in sentences if s.strip() and len(s.split()) >= 3]


def get_paragraphs(text):
    """Split text into paragraphs."""
    return [p.strip() for p in re.split(r'\n\s*\n', text) if p.strip()]


def flesch_reading_ease(words, sentences, syllables):
    """Calculate Flesch Reading Ease score."""
    if words == 0 or sentences == 0:
        return 0
    return round(206.835 - 1.015 * (words / sentences) - 84.6 * (syllables / words), 1)


def flesch_kincaid_grade(words, sentences, syllables):
    """Calculate Flesch-Kincaid Grade Level."""
    if words == 0 or sentences == 0:
        return 0
    return round(0.39 * (words / sentences) + 11.8 * (syllables / words) - 15.59, 1)


def detect_passive_voice(text):
    """Detect passive voice constructions."""
    passive_patterns = [
        r'\b(is|are|was|were|been|being)\s+\w+ed\b',
        r'\b(is|are|was|were|been|being)\s+\w+en\b',
        r'\b(got|get|gets|getting)\s+\w+ed\b',
    ]
    count = 0
    examples = []
    sentences = get_sentences(text)
    for sent in sentences:
        for pattern in passive_patterns:
            if re.search(pattern, sent, re.IGNORECASE):
                count += 1
                if len(examples) < 5:
                    examples.append(sent[:80] + "..." if len(sent) > 80 else sent)
                break
    return count, examples


def analyze_sentence_variety(sentences):
    """Analyze sentence length variety."""
    if not sentences:
        return {}

    lengths = [len(s.split()) for s in sentences]
    avg = sum(lengths) / len(lengths)
    variance = sum((l - avg) ** 2 for l in lengths) / len(lengths)
    std_dev = math.sqrt(variance)

    # Classify
    short = sum(1 for l in lengths if l < 10)
    medium = sum(1 for l in lengths if 10 <= l <= 20)
    long_s = sum(1 for l in lengths if l > 20)
    very_long = sum(1 for l in lengths if l > 30)

    return {
        "average_length": round(avg, 1),
        "std_deviation": round(std_dev, 1),
        "shortest": min(lengths),
        "longest": max(lengths),
        "distribution": {
            "short_under_10": short,
            "medium_10_to_20": medium,
            "long_over_20": long_s,
            "very_long_over_30": very_long,
        },
        "variety_rating": "Good" if std_dev > 5 else "Moderate" if std_dev > 3 else "Low (monotonous)",
    }


def score_web_readability(flesch, avg_sentence, passive_rate, para_analysis):
    """Calculate web-specific readability score 0-100."""
    score = 0

    # Flesch Reading Ease (target 60-70 for web)
    if 55 <= flesch <= 75:
        score += 30
    elif 45 <= flesch <= 80:
        score += 20
    else:
        score += 10

    # Sentence length (target 15-20 avg)
    if 12 <= avg_sentence <= 22:
        score += 25
    elif 10 <= avg_sentence <= 25:
        score += 15
    else:
        score += 5

    # Passive voice (target < 10%)
    if passive_rate < 10:
        score += 20
    elif passive_rate < 20:
        score += 10
    else:
        score += 5

    # Paragraph length
    if para_analysis.get("avg_sentences", 0) <= 4:
        score += 25
    elif para_analysis.get("avg_sentences", 0) <= 6:
        score += 15
    else:
        score += 5

    return min(score, 100)


def main():
    parser = argparse.ArgumentParser(description="Score content readability")
    parser.add_argument("file", help="Content file to analyze")
    parser.add_argument("--json", action="store_true")
    parser.add_argument("--verbose", action="store_true")
    args = parser.parse_args()

    fp = Path(args.file)
    if not fp.exists():
        print(f"Error: {fp} not found", file=sys.stderr)
        sys.exit(1)

    raw_text = fp.read_text(encoding="utf-8", errors="replace")
    text = strip_markdown(raw_text)

    words_list = text.split()
    word_count = len(words_list)
    sentences = get_sentences(text)
    sentence_count = len(sentences)
    syllable_count = sum(count_syllables(w) for w in words_list)
    paragraphs = get_paragraphs(text)

    # Core scores
    fre = flesch_reading_ease(word_count, sentence_count, syllable_count)
    fkg = flesch_kincaid_grade(word_count, sentence_count, syllable_count)

    # Sentence analysis
    variety = analyze_sentence_variety(sentences)
    avg_sentence_len = variety.get("average_length", 0)

    # Passive voice
    passive_count, passive_examples = detect_passive_voice(text)
    passive_rate = round(passive_count / max(sentence_count, 1) * 100, 1)

    # Paragraph analysis
    para_sentence_counts = [len(get_sentences(p)) for p in paragraphs]
    para_analysis = {
        "count": len(paragraphs),
        "avg_sentences": round(sum(para_sentence_counts) / max(len(para_sentence_counts), 1), 1),
        "long_paragraphs": sum(1 for c in para_sentence_counts if c > 5),
    }

    # Web readability score
    web_score = score_web_readability(fre, avg_sentence_len, passive_rate, para_analysis)

    # Reading level label
    if fre >= 80:
        level = "Easy (6th grade)"
    elif fre >= 60:
        level = "Standard (8th-9th grade)"
    elif fre >= 40:
        level = "Difficult (College level)"
    else:
        level = "Very Difficult (Graduate level)"

    result = {
        "file": str(fp),
        "word_count": word_count,
        "sentence_count": sentence_count,
        "paragraph_count": len(paragraphs),
        "flesch_reading_ease": fre,
        "flesch_kincaid_grade": fkg,
        "reading_level": level,
        "web_readability_score": web_score,
        "sentence_variety": variety,
        "passive_voice": {
            "count": passive_count,
            "rate": passive_rate,
            "examples": passive_examples,
        },
        "paragraph_analysis": para_analysis,
    }

    if args.json:
        print(json.dumps(result, indent=2))
    else:
        grade = "A" if web_score >= 80 else "B" if web_score >= 65 else "C" if web_score >= 50 else "D"
        print(f"\n{'='*55}")
        print(f"  READABILITY SCORE: {web_score}/100 (Grade: {grade})")
        print(f"{'='*55}")
        print(f"  File: {fp}")
        print(f"  Words: {word_count} | Sentences: {sentence_count} | Paragraphs: {len(paragraphs)}")
        print(f"\n  Flesch Reading Ease: {fre} ({level})")
        print(f"  Flesch-Kincaid Grade: {fkg}")
        print(f"  Avg sentence length: {avg_sentence_len} words")
        print(f"  Sentence variety: {variety.get('variety_rating', 'N/A')} (std dev: {variety.get('std_deviation', 0)})")
        print(f"  Passive voice: {passive_count} instances ({passive_rate}%)")
        print(f"  Avg paragraph: {para_analysis['avg_sentences']} sentences")
        print(f"  Long paragraphs (>5 sentences): {para_analysis['long_paragraphs']}")

        if args.verbose and passive_examples:
            print(f"\n  Passive voice examples:")
            for ex in passive_examples:
                print(f"    - {ex}")

        # Recommendations
        recs = []
        if fre < 50:
            recs.append("Simplify language — target Flesch 60-70 for web content")
        if avg_sentence_len > 22:
            recs.append("Shorten sentences — target 15-20 words average")
        if passive_rate > 15:
            recs.append(f"Reduce passive voice from {passive_rate}% to under 10%")
        if para_analysis["long_paragraphs"] > 0:
            recs.append(f"Break up {para_analysis['long_paragraphs']} long paragraphs (max 4 sentences)")
        if variety.get("std_deviation", 0) < 4:
            recs.append("Vary sentence length more — mix short and long for rhythm")

        if recs:
            print(f"\n  Recommendations:")
            for r in recs:
                print(f"    - {r}")

        print()


if __name__ == "__main__":
    main()