Content Strategy

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

Generates structured content briefs from keyword and topic inputs.
Includes target audience, search intent classification, recommended
structure, word count guidance, and internal linking suggestions.

Usage:
    python content_brief_generator.py --keyword "cloud cost optimization"
    python content_brief_generator.py --keyword "SEO audit checklist" --audience "marketing managers" --json
    python content_brief_generator.py --keyword "best CRM for startups" --funnel consideration
"""

import argparse
import json
import re
import sys


INTENT_PATTERNS = {
    "informational": r'\b(what is|how to|guide|tutorial|explain|definition|overview|learn)\b',
    "commercial": r'\b(best|top|review|comparison|vs|alternative|software|tool|platform)\b',
    "transactional": r'\b(buy|price|pricing|discount|free trial|download|sign up)\b',
    "navigational": r'\b(login|docs|documentation|support|contact)\b',
}

CONTENT_STRUCTURES = {
    "informational": {
        "format": "Comprehensive Guide",
        "word_count": "1,500-2,500",
        "sections": [
            "Definition and overview",
            "Why it matters",
            "Key components or steps",
            "Best practices",
            "Common mistakes",
            "Tools and resources",
            "FAQ",
        ],
    },
    "commercial": {
        "format": "Comparison / Buyer's Guide",
        "word_count": "2,000-3,000",
        "sections": [
            "Overview of the category",
            "Key evaluation criteria",
            "Detailed comparison (table format)",
            "Pros and cons of each option",
            "Best for specific use cases",
            "Pricing comparison",
            "Recommendation and verdict",
        ],
    },
    "transactional": {
        "format": "Product-Focused Landing Content",
        "word_count": "800-1,500",
        "sections": [
            "Problem statement",
            "Solution overview",
            "Key features and benefits",
            "Social proof (testimonials, case studies)",
            "Pricing and plans",
            "Getting started steps",
            "FAQ",
        ],
    },
    "navigational": {
        "format": "Resource Page",
        "word_count": "500-1,000",
        "sections": [
            "Direct answer or resource",
            "Quick navigation links",
            "Related resources",
        ],
    },
}

FUNNEL_GUIDANCE = {
    "awareness": {
        "reader_mindset": "I have a problem or question but don't know solutions yet",
        "content_goal": "Educate and attract — establish your expertise",
        "cta": "Newsletter signup, related content, or resource download",
        "tone": "Educational, helpful, non-promotional",
    },
    "consideration": {
        "reader_mindset": "I know my options and I'm evaluating them",
        "content_goal": "Build trust and differentiate your solution",
        "cta": "Demo request, free trial, or case study download",
        "tone": "Authoritative, balanced, evidence-based",
    },
    "decision": {
        "reader_mindset": "I'm ready to choose — convince me this is the right one",
        "content_goal": "Remove objections and drive conversion",
        "cta": "Sign up, purchase, or contact sales",
        "tone": "Confident, specific, proof-heavy",
    },
}


def classify_intent(keyword):
    """Classify search intent."""
    kw = keyword.lower()
    scores = {}
    for intent, pattern in INTENT_PATTERNS.items():
        scores[intent] = len(re.findall(pattern, kw))
    if max(scores.values()) == 0:
        return "informational"
    return max(scores, key=scores.get)


def estimate_word_count(intent, funnel):
    """Estimate target word count."""
    base = CONTENT_STRUCTURES[intent]["word_count"]
    if funnel == "awareness":
        return base  # Standard
    elif funnel == "consideration":
        return f"{base} (lean toward upper range for depth)"
    else:
        return "800-1,500 (concise, action-oriented)"


def generate_brief(keyword, audience=None, funnel=None):
    """Generate a complete content brief."""
    intent = classify_intent(keyword)
    if funnel is None:
        funnel_map = {
            "informational": "awareness",
            "commercial": "consideration",
            "transactional": "decision",
            "navigational": "awareness",
        }
        funnel = funnel_map[intent]

    structure = CONTENT_STRUCTURES[intent]
    funnel_guide = FUNNEL_GUIDANCE.get(funnel, FUNNEL_GUIDANCE["awareness"])

    brief = {
        "keyword": keyword,
        "intent": intent,
        "funnel_stage": funnel,
        "target": {
            "primary_keyword": keyword,
            "secondary_keywords": [
                f"{keyword} guide",
                f"{keyword} examples",
                f"how to {keyword}",
                f"best {keyword}",
                f"{keyword} tips",
            ],
            "search_intent": intent,
        },
        "audience": {
            "profile": audience or "[Define: role, seniority, industry]",
            "reader_mindset": funnel_guide["reader_mindset"],
            "awareness_level": funnel.capitalize(),
        },
        "content_spec": {
            "format": structure["format"],
            "target_word_count": estimate_word_count(intent, funnel),
            "tone": funnel_guide["tone"],
            "cta": funnel_guide["cta"],
            "content_goal": funnel_guide["content_goal"],
        },
        "structure": {
            "h1": f"[Working Title] — include '{keyword}'",
            "sections": structure["sections"],
        },
        "requirements": {
            "internal_links": "3-5 links to related content",
            "external_links": "2-3 links to authoritative sources",
            "images": "1 per 500 words minimum",
            "schema_markup": "Article schema at minimum; FAQPage if FAQ section included",
            "meta_title": f"Under 60 chars, includes '{keyword}'",
            "meta_description": "140-160 chars with keyword and clear value proposition",
        },
        "seo_checklist": [
            f"Primary keyword in H1, first 100 words, and 2+ H2s",
            "Keyword density 0.5-2.5%",
            "All images have descriptive alt text",
            "URL slug is short, keyword-first, no stop words",
            "Heading hierarchy: H1 > H2 > H3 (no skips)",
        ],
        "competitive_research": {
            "instruction": f"Analyze top 5 ranking pages for '{keyword}'",
            "what_to_record": [
                "Content format and angle",
                "Word count and depth",
                "What they cover well",
                "What they miss (your gap to fill)",
            ],
        },
    }

    return brief


def main():
    parser = argparse.ArgumentParser(description="Generate content briefs")
    parser.add_argument("--keyword", required=True, help="Target keyword")
    parser.add_argument("--audience", help="Target audience description")
    parser.add_argument("--funnel", choices=["awareness", "consideration", "decision"])
    parser.add_argument("--json", action="store_true")
    args = parser.parse_args()

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

    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"  Intent: {brief['intent']} | Funnel: {brief['funnel_stage']}")
        print(f"  Format: {brief['content_spec']['format']}")
        print(f"  Word Count: {brief['content_spec']['target_word_count']}")
        print(f"  Tone: {brief['content_spec']['tone']}")
        print(f"  CTA: {brief['content_spec']['cta']}")

        print(f"\n  Audience:")
        print(f"    Profile: {brief['audience']['profile']}")
        print(f"    Mindset: {brief['audience']['reader_mindset']}")

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

        print(f"\n  SEO Checklist:")
        for item in brief["seo_checklist"]:
            print(f"    [ ] {item}")

        print(f"\n  Secondary Keywords:")
        for kw in brief["target"]["secondary_keywords"]:
            print(f"    - {kw}")

        print()


if __name__ == "__main__":
    main()

#!/usr/bin/env python3
"""
Content Calendar Planner

Generates a structured content calendar from a topic list, distributing
content across weeks by pillar, funnel stage, content type, and priority.
Supports weekly and bi-weekly cadences.

Usage:
    python content_calendar_planner.py --topics topics.csv --cadence weekly
    python content_calendar_planner.py --topics topics.csv --weeks 8 --json
    python content_calendar_planner.py --topics topics.csv --cadence biweekly --start 2026-04-01
"""

import argparse
import csv
import json
import re
import sys
from datetime import date, timedelta
from pathlib import Path


def load_topics(filepath):
    """Load topics from CSV."""
    topics = []
    with open(filepath, 'r', encoding='utf-8') as f:
        sample = f.read(1024)
        f.seek(0)
        if ',' in sample or '\t' in sample:
            try:
                dialect = csv.Sniffer().sniff(sample, delimiters=',\t')
            except csv.Error:
                dialect = csv.excel
            reader = csv.DictReader(f, dialect=dialect)
            for row in reader:
                topic = {}
                for key in ['topic', 'Topic', 'title', 'Title', 'keyword', 'Keyword']:
                    if key in row and row[key]:
                        topic["topic"] = row[key].strip()
                        break
                if "topic" not in topic and row:
                    topic["topic"] = list(row.values())[0].strip()

                for key in ['pillar', 'Pillar', 'category', 'Category']:
                    if key in row and row[key]:
                        topic["pillar"] = row[key].strip()

                for key in ['funnel', 'Funnel', 'stage', 'Stage']:
                    if key in row and row[key]:
                        topic["funnel"] = row[key].strip().lower()

                for key in ['type', 'Type', 'format', 'Format']:
                    if key in row and row[key]:
                        topic["content_type"] = row[key].strip()

                for key in ['priority', 'Priority', 'score', 'Score']:
                    if key in row and row[key]:
                        try:
                            topic["priority"] = int(str(row[key]).strip())
                        except ValueError:
                            topic["priority"] = {"high": 3, "medium": 2, "low": 1}.get(
                                row[key].strip().lower(), 2
                            )

                for key in ['volume', 'Volume']:
                    if key in row and row[key]:
                        try:
                            topic["volume"] = int(str(row[key]).replace(',', '').strip())
                        except ValueError:
                            pass

                if topic.get("topic"):
                    topics.append(topic)
        else:
            for line in f:
                t = line.strip()
                if t:
                    topics.append({"topic": t})

    return topics


def classify_topic(topic):
    """Auto-classify topic if metadata is missing."""
    t = topic.get("topic", "").lower()

    # Funnel stage
    if "funnel" not in topic:
        if any(w in t for w in ['what is', 'guide', 'introduction', 'basics', 'overview', 'how to']):
            topic["funnel"] = "awareness"
        elif any(w in t for w in ['vs', 'compare', 'best', 'review', 'alternative', 'case study']):
            topic["funnel"] = "consideration"
        elif any(w in t for w in ['pricing', 'demo', 'tutorial', 'setup', 'getting started']):
            topic["funnel"] = "decision"
        else:
            topic["funnel"] = "awareness"

    # Content type
    if "content_type" not in topic:
        if 'how to' in t or 'guide' in t or 'tutorial' in t:
            topic["content_type"] = "guide"
        elif 'vs' in t or 'compare' in t or 'best' in t:
            topic["content_type"] = "comparison"
        elif 'what is' in t:
            topic["content_type"] = "explainer"
        elif 'case study' in t or 'example' in t:
            topic["content_type"] = "case_study"
        else:
            topic["content_type"] = "article"

    # Priority
    if "priority" not in topic:
        topic["priority"] = 2

    return topic


def plan_calendar(topics, cadence="weekly", weeks=8, start_date=None):
    """Plan content calendar distributing topics across weeks."""
    if start_date is None:
        start_date = date.today()
    elif isinstance(start_date, str):
        start_date = date.fromisoformat(start_date)

    # Sort by priority (highest first)
    topics.sort(key=lambda t: t.get("priority", 2), reverse=True)

    # Determine posts per week
    posts_per_week = 2 if cadence == "weekly" else 1

    calendar = []
    topic_index = 0

    for week in range(weeks):
        week_start = start_date + timedelta(weeks=week)
        week_end = week_start + timedelta(days=6)

        week_plan = {
            "week": week + 1,
            "start_date": week_start.isoformat(),
            "end_date": week_end.isoformat(),
            "content": [],
        }

        for slot in range(posts_per_week):
            if topic_index < len(topics):
                topic = topics[topic_index]
                day_offset = 0 if slot == 0 else 3  # Mon and Thu
                publish_date = week_start + timedelta(days=day_offset)

                week_plan["content"].append({
                    "topic": topic["topic"],
                    "publish_date": publish_date.isoformat(),
                    "brief_due": (publish_date - timedelta(days=14)).isoformat(),
                    "draft_due": (publish_date - timedelta(days=9)).isoformat(),
                    "review_due": (publish_date - timedelta(days=5)).isoformat(),
                    "pillar": topic.get("pillar", "Unassigned"),
                    "funnel": topic.get("funnel", "awareness"),
                    "content_type": topic.get("content_type", "article"),
                    "priority": topic.get("priority", 2),
                    "volume": topic.get("volume"),
                })
                topic_index += 1

        # Add refresh slot every 4th week
        if (week + 1) % 4 == 0:
            week_plan["content"].append({
                "topic": "[REFRESH: Update highest-performing existing post]",
                "publish_date": (week_start + timedelta(days=4)).isoformat(),
                "content_type": "refresh",
                "pillar": "Cross-pillar",
                "funnel": "mixed",
                "priority": 3,
            })

        calendar.append(week_plan)

    return {
        "cadence": cadence,
        "total_weeks": weeks,
        "total_pieces": topic_index,
        "remaining_topics": len(topics) - topic_index,
        "calendar": calendar,
    }


def main():
    parser = argparse.ArgumentParser(
        description="Plan a content calendar from topic list"
    )
    parser.add_argument("--topics", required=True, help="CSV file with topics")
    parser.add_argument("--cadence", choices=["weekly", "biweekly"], default="weekly")
    parser.add_argument("--weeks", type=int, default=8, help="Number of weeks to plan (default: 8)")
    parser.add_argument("--start", help="Start date (YYYY-MM-DD, default: today)")
    parser.add_argument("--json", action="store_true")
    args = parser.parse_args()

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

    topics = load_topics(fp)
    if not topics:
        print("No topics found.", file=sys.stderr)
        sys.exit(1)

    topics = [classify_topic(t) for t in topics]
    calendar = plan_calendar(topics, args.cadence, args.weeks, args.start)

    if args.json:
        print(json.dumps(calendar, indent=2))
    else:
        print(f"\n{'='*70}")
        print(f"  CONTENT CALENDAR — {calendar['total_weeks']} weeks, {calendar['total_pieces']} pieces")
        print(f"{'='*70}")
        print(f"  Cadence: {args.cadence} | Remaining topics: {calendar['remaining_topics']}")

        for week in calendar["calendar"]:
            print(f"\n  Week {week['week']} ({week['start_date']} to {week['end_date']}):")
            for item in week["content"]:
                funnel = item.get("funnel", "")[:5].upper()
                ctype = item.get("content_type", "")[:10]
                print(f"    [{funnel}] {item['publish_date']} | {ctype:<10} | {item['topic'][:50]}")

        # Summary by funnel
        funnel_counts = {"awareness": 0, "consideration": 0, "decision": 0, "mixed": 0}
        for week in calendar["calendar"]:
            for item in week["content"]:
                f = item.get("funnel", "awareness")
                funnel_counts[f] = funnel_counts.get(f, 0) + 1

        print(f"\n  Funnel Distribution:")
        for f, c in funnel_counts.items():
            if c > 0:
                print(f"    {f.capitalize()}: {c} pieces")

        print()


if __name__ == "__main__":
    main()

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

Analyzes headlines for SEO effectiveness, click-worthiness, emotional
impact, and readability. Scores headlines 0-100 and provides specific
improvement recommendations.

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

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


POWER_WORDS = {
    "urgency": ["now", "today", "immediately", "hurry", "fast", "quick", "instant"],
    "exclusivity": ["secret", "insider", "exclusive", "hidden", "little-known", "underground"],
    "value": ["free", "save", "proven", "guaranteed", "essential", "ultimate", "complete"],
    "curiosity": ["surprising", "unexpected", "strange", "weird", "shocking", "bizarre"],
    "authority": ["expert", "research", "study", "data", "science", "official", "definitive"],
    "emotion": ["amazing", "brilliant", "terrible", "devastating", "incredible", "powerful"],
}

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

HEADLINE_FORMULAS = {
    "number_list": r'^\d+\s+',
    "how_to": r'^how\s+to\b',
    "question": r'\?$',
    "why": r'^why\s+',
    "what": r'^what\s+',
    "guide": r'\bguide\b',
    "vs_comparison": r'\bvs\.?\b|\bversus\b',
    "year": r'\b202[4-9]\b|\b203\d\b',
}


def analyze_headline(headline, keyword=None):
    """Analyze a single headline."""
    hl = headline.strip()
    hl_lower = hl.lower()
    words = hl_lower.split()
    word_count = len(words)
    char_count = len(hl)

    checks = {}

    # Length (characters)
    checks["char_length"] = {
        "value": char_count,
        "pass": 40 <= char_count <= 65,
        "detail": f"{char_count} chars (target: 50-60 for SEO, max 65)",
    }

    # Word count
    checks["word_count"] = {
        "value": word_count,
        "pass": 6 <= word_count <= 12,
        "detail": f"{word_count} words (optimal: 6-12)",
    }

    # Number presence
    has_number = bool(re.search(r'\d+', hl))
    checks["has_number"] = {
        "pass": has_number,
        "detail": "Contains a number" if has_number else "No number — numbered headlines get 36% higher CTR",
    }

    # Power words
    found_power = []
    for category, pw_list in POWER_WORDS.items():
        for word in pw_list:
            if word in hl_lower:
                found_power.append(f"{word} ({category})")
    checks["power_words"] = {
        "pass": len(found_power) >= 1,
        "count": len(found_power),
        "found": found_power[:5],
        "detail": f"{len(found_power)} power words found" + (f": {', '.join(found_power[:3])}" if found_power else ""),
    }

    # Weak words
    found_weak = [w for w in WEAK_WORDS if w in words]
    checks["no_weak_words"] = {
        "pass": len(found_weak) == 0,
        "found": found_weak,
        "detail": f"{len(found_weak)} weak words" + (f": {', '.join(found_weak)}" if found_weak else " — clean"),
    }

    # Formula match
    matched_formula = None
    for name, pattern in HEADLINE_FORMULAS.items():
        if re.search(pattern, hl_lower):
            matched_formula = name
            break
    checks["proven_formula"] = {
        "pass": matched_formula is not None,
        "formula": matched_formula,
        "detail": f"Matches '{matched_formula}' formula" if matched_formula else "No proven headline formula detected",
    }

    # Front-loaded keyword
    if keyword:
        kw = keyword.lower()
        in_headline = kw in hl_lower
        front_loaded = hl_lower.startswith(kw) or hl_lower.find(kw) < char_count * 0.4
        checks["keyword_placement"] = {
            "pass": in_headline and front_loaded,
            "in_headline": in_headline,
            "front_loaded": front_loaded,
            "detail": f"Keyword {'front-loaded' if front_loaded else 'present but not front-loaded' if in_headline else 'MISSING'}",
        }

    # Emotional score (based on power words + formula)
    emotional_score = len(found_power) * 15 + (20 if has_number else 0) + (15 if matched_formula else 0)
    emotional_score = min(emotional_score, 100)
    checks["emotional_impact"] = {
        "value": emotional_score,
        "pass": emotional_score >= 30,
        "detail": f"Emotional impact: {emotional_score}/100",
    }

    # Capitalization
    is_title_case = hl[0].isupper()
    checks["proper_case"] = {
        "pass": is_title_case,
        "detail": "Proper capitalization" if is_title_case else "Starts with lowercase",
    }

    # Calculate score
    passed = sum(1 for c in checks.values() if c.get("pass", False))
    score = round((passed / len(checks)) * 100, 1)

    # Grade
    grade = "A" if score >= 80 else "B" if score >= 65 else "C" if score >= 50 else "D" if score >= 35 else "F"

    return {
        "headline": hl,
        "score": score,
        "grade": grade,
        "checks": checks,
    }


def main():
    parser = argparse.ArgumentParser(description="Analyze headlines for SEO and CTR")
    group = parser.add_mutually_exclusive_group(required=True)
    group.add_argument("--headline", help="Single headline to analyze")
    group.add_argument("--headlines", help="File with headlines (one per line)")
    parser.add_argument("--keyword", help="Target keyword for placement check")
    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 = [analyze_headline(h, args.keyword) for h in headlines]

    if args.json:
        print(json.dumps({"headlines": results, "total": len(results)}, indent=2))
    else:
        for r in results:
            print(f"\n{'='*60}")
            print(f"  HEADLINE: {r['headline']}")
            print(f"  Score: {r['score']}/100 (Grade: {r['grade']})")
            print(f"{'='*60}")
            for key, check in r["checks"].items():
                status = "PASS" if check.get("pass") else "FAIL"
                print(f"  [{status}] {key}: {check['detail']}")

        if len(results) > 1:
            avg = round(sum(r["score"] for r in results) / len(results), 1)
            best = max(results, key=lambda r: r["score"])
            print(f"\n  Average score: {avg}/100")
            print(f"  Best: \"{best['headline']}\" ({best['score']}/100)")
        print()


if __name__ == "__main__":
    main()