Research Summarizer

#!/usr/bin/env python3
"""
research-summarizer: Citation Extractor

Extract and format citations from text documents. Detects DOIs, URLs,
author-year patterns, and numbered references. Outputs in APA, IEEE,
Chicago, Harvard, or MLA format.

Usage:
    python scripts/extract_citations.py document.txt
    python scripts/extract_citations.py document.txt --format ieee
    python scripts/extract_citations.py document.txt --format apa --output json
    python scripts/extract_citations.py --stdin < document.txt
"""

import argparse
import json
import re
import sys
from collections import OrderedDict


# --- Citation Detection Patterns ---

PATTERNS = {
    "doi": re.compile(
        r"(?:https?://doi\.org/|doi:\s*)(10\.\d{4,}/[^\s,;}\]]+)", re.IGNORECASE
    ),
    "url": re.compile(
        r"https?://[^\s,;}\])\"'>]+", re.IGNORECASE
    ),
    "author_year": re.compile(
        r"(?:^|\(|\s)([A-Z][a-z]+(?:\s(?:&|and)\s[A-Z][a-z]+)?(?:\set\sal\.?)?)\s*\((\d{4})\)",
    ),
    "numbered_ref": re.compile(
        r"^\[(\d+)\]\s+(.+)$", re.MULTILINE
    ),
    "footnote": re.compile(
        r"^\d+\.\s+([A-Z].+?(?:\d{4}).+)$", re.MULTILINE
    ),
}


def extract_dois(text):
    """Extract DOI references."""
    citations = []
    for match in PATTERNS["doi"].finditer(text):
        doi = match.group(1).rstrip(".")
        citations.append({
            "type": "doi",
            "doi": doi,
            "raw": match.group(0).strip(),
            "url": f"https://doi.org/{doi}",
        })
    return citations


def extract_urls(text):
    """Extract URL references (excluding DOI URLs already captured)."""
    citations = []
    for match in PATTERNS["url"].finditer(text):
        url = match.group(0).rstrip(".,;)")
        if "doi.org" in url:
            continue
        citations.append({
            "type": "url",
            "url": url,
            "raw": url,
        })
    return citations


def extract_author_year(text):
    """Extract author-year citations like (Smith, 2023) or Smith & Jones (2021)."""
    citations = []
    for match in PATTERNS["author_year"].finditer(text):
        author = match.group(1).strip()
        year = match.group(2)
        citations.append({
            "type": "author_year",
            "author": author,
            "year": year,
            "raw": f"{author} ({year})",
        })
    return citations


def extract_numbered_refs(text):
    """Extract numbered reference list entries like [1] Author. Title..."""
    citations = []
    for match in PATTERNS["numbered_ref"].finditer(text):
        num = match.group(1)
        content = match.group(2).strip()
        citations.append({
            "type": "numbered",
            "number": int(num),
            "content": content,
            "raw": f"[{num}] {content}",
        })
    return citations


def deduplicate(citations):
    """Remove duplicate citations based on raw text."""
    seen = OrderedDict()
    for c in citations:
        key = c.get("doi") or c.get("url") or c.get("raw", "")
        key = key.lower().strip()
        if key and key not in seen:
            seen[key] = c
    return list(seen.values())


def classify_source(citation):
    """Classify citation as primary, secondary, or tertiary."""
    raw = citation.get("content", citation.get("raw", "")).lower()
    if any(kw in raw for kw in ["meta-analysis", "systematic review", "literature review", "survey of"]):
        return "secondary"
    if any(kw in raw for kw in ["textbook", "encyclopedia", "handbook", "dictionary"]):
        return "tertiary"
    return "primary"


# --- Formatting ---

def format_apa(citation):
    """Format citation in APA 7 style."""
    if citation["type"] == "doi":
        return f"https://doi.org/{citation['doi']}"
    if citation["type"] == "url":
        return f"Retrieved from {citation['url']}"
    if citation["type"] == "author_year":
        return f"{citation['author']} ({citation['year']})."
    if citation["type"] == "numbered":
        return citation["content"]
    return citation.get("raw", "")


def format_ieee(citation):
    """Format citation in IEEE style."""
    if citation["type"] == "doi":
        return f"doi: {citation['doi']}"
    if citation["type"] == "url":
        return f"[Online]. Available: {citation['url']}"
    if citation["type"] == "author_year":
        return f"{citation['author']}, {citation['year']}."
    if citation["type"] == "numbered":
        return f"[{citation['number']}] {citation['content']}"
    return citation.get("raw", "")


def format_chicago(citation):
    """Format citation in Chicago style."""
    if citation["type"] == "doi":
        return f"https://doi.org/{citation['doi']}."
    if citation["type"] == "url":
        return f"{citation['url']}."
    if citation["type"] == "author_year":
        return f"{citation['author']}. {citation['year']}."
    if citation["type"] == "numbered":
        return citation["content"]
    return citation.get("raw", "")


def format_harvard(citation):
    """Format citation in Harvard style."""
    if citation["type"] == "doi":
        return f"doi:{citation['doi']}"
    if citation["type"] == "url":
        return f"Available at: {citation['url']}"
    if citation["type"] == "author_year":
        return f"{citation['author']} ({citation['year']})"
    if citation["type"] == "numbered":
        return citation["content"]
    return citation.get("raw", "")


def format_mla(citation):
    """Format citation in MLA 9 style."""
    if citation["type"] == "doi":
        return f"doi:{citation['doi']}."
    if citation["type"] == "url":
        return f"{citation['url']}."
    if citation["type"] == "author_year":
        return f"{citation['author']}. {citation['year']}."
    if citation["type"] == "numbered":
        return citation["content"]
    return citation.get("raw", "")


FORMATTERS = {
    "apa": format_apa,
    "ieee": format_ieee,
    "chicago": format_chicago,
    "harvard": format_harvard,
    "mla": format_mla,
}


# --- Demo Data ---

DEMO_TEXT = """
Recent studies in product management have shown significant shifts in methodology.
According to Smith & Jones (2023), agile adoption has increased by 47% since 2020.
Patel et al. (2022) found that cross-functional teams deliver 2.3x faster.

Several frameworks have been proposed:
[1] Cagan, M. Inspired: How to Create Tech Products Customers Love. Wiley, 2018.
[2] Torres, T. Continuous Discovery Habits. Product Talk LLC, 2021.
[3] Gothelf, J. & Seiden, J. Lean UX. O'Reilly Media, 2021. doi: 10.1234/leanux.2021

For further reading, see https://www.svpg.com/articles/ and the meta-analysis
by Chen (2024) on product discovery effectiveness.

Related work: doi: 10.1145/3544548.3581388
"""


def run_extraction(text, fmt, output_mode):
    """Run full extraction pipeline."""
    all_citations = []
    all_citations.extend(extract_dois(text))
    all_citations.extend(extract_author_year(text))
    all_citations.extend(extract_numbered_refs(text))
    all_citations.extend(extract_urls(text))

    citations = deduplicate(all_citations)

    for c in citations:
        c["classification"] = classify_source(c)

    formatter = FORMATTERS.get(fmt, format_apa)

    if output_mode == "json":
        result = {
            "format": fmt,
            "total": len(citations),
            "citations": [],
        }
        for i, c in enumerate(citations, 1):
            result["citations"].append({
                "index": i,
                "type": c["type"],
                "classification": c["classification"],
                "formatted": formatter(c),
                "raw": c.get("raw", ""),
            })
        print(json.dumps(result, indent=2))
    else:
        print(f"Citations ({fmt.upper()}) — {len(citations)} found\n")
        primary = [c for c in citations if c["classification"] == "primary"]
        secondary = [c for c in citations if c["classification"] == "secondary"]
        tertiary = [c for c in citations if c["classification"] == "tertiary"]

        for label, group in [("Primary Sources", primary), ("Secondary Sources", secondary), ("Tertiary Sources", tertiary)]:
            if group:
                print(f"### {label}")
                for i, c in enumerate(group, 1):
                    print(f"  {i}. {formatter(c)}")
                print()

    return citations


def main():
    parser = argparse.ArgumentParser(
        description="research-summarizer: Extract and format citations from text"
    )
    parser.add_argument("file", nargs="?", help="Input text file (omit for demo)")
    parser.add_argument(
        "--format", "-f",
        choices=["apa", "ieee", "chicago", "harvard", "mla"],
        default="apa",
        help="Citation format (default: apa)",
    )
    parser.add_argument(
        "--output", "-o",
        choices=["text", "json"],
        default="text",
        help="Output mode (default: text)",
    )
    parser.add_argument(
        "--stdin",
        action="store_true",
        help="Read from stdin instead of file",
    )
    args = parser.parse_args()

    if args.stdin:
        text = sys.stdin.read()
    elif args.file:
        try:
            with open(args.file, "r", encoding="utf-8") as f:
                text = f.read()
        except FileNotFoundError:
            print(f"Error: File not found: {args.file}", file=sys.stderr)
            sys.exit(1)
        except IOError as e:
            print(f"Error reading file: {e}", file=sys.stderr)
            sys.exit(1)
    else:
        print("No input file provided. Running demo...\n")
        text = DEMO_TEXT

    run_extraction(text, args.format, args.output)


if __name__ == "__main__":
    main()

#!/usr/bin/env python3
"""
research-summarizer: Summary Formatter

Generate structured research summary templates for different source types.
Produces fill-in-the-blank frameworks for academic papers, web articles,
technical reports, and executive briefs.

Usage:
    python scripts/format_summary.py --template academic
    python scripts/format_summary.py --template executive --length brief
    python scripts/format_summary.py --list-templates
    python scripts/format_summary.py --template article --output json
"""

import argparse
import json
import sys
import textwrap
from datetime import datetime


# --- Templates ---

TEMPLATES = {
    "academic": {
        "name": "Academic Paper Summary",
        "description": "IMRAD structure for peer-reviewed papers and research studies",
        "sections": [
            ("Title", "[Full paper title]"),
            ("Author(s)", "[Author names, affiliations]"),
            ("Publication", "[Journal/Conference, Year, DOI]"),
            ("Source Type", "Academic Paper"),
            ("Key Thesis", "[1-2 sentences: the central research question and answer]"),
            ("Methodology", "[Study design, sample size, data sources, analytical approach]"),
            ("Key Findings", "1. [Finding 1 with supporting data]\n2. [Finding 2 with supporting data]\n3. [Finding 3 with supporting data]"),
            ("Statistical Significance", "[Key p-values, effect sizes, confidence intervals]"),
            ("Limitations", "- [Limitation 1: scope, sample, methodology gap]\n- [Limitation 2]"),
            ("Implications", "- [What this means for practice]\n- [What this means for future research]"),
            ("Notable Quotes", '> "[Direct quote]" (p. X)'),
            ("Quality Assessment", "Credibility: [High/Med/Low] | Evidence: [High/Med/Low] | Recency: [High/Med/Low] | Objectivity: [High/Med/Low]"),
        ],
    },
    "article": {
        "name": "Web Article Summary",
        "description": "Claim-evidence-implication structure for online articles and blog posts",
        "sections": [
            ("Title", "[Article title]"),
            ("Author", "[Author name]"),
            ("Source", "[Publication/Website, Date, URL]"),
            ("Source Type", "Web Article"),
            ("Central Claim", "[1-2 sentences: main argument or thesis]"),
            ("Supporting Evidence", "1. [Evidence point 1]\n2. [Evidence point 2]\n3. [Evidence point 3]"),
            ("Counterarguments Addressed", "- [Counterargument and author's response]"),
            ("Implications", "- [What this means for the reader]"),
            ("Bias Check", "Author affiliation: [?] | Funding: [?] | Balanced perspective: [Yes/No]"),
            ("Actionable Takeaways", "- [What to do with this information]\n- [Next step]"),
            ("Quality Assessment", "Credibility: [High/Med/Low] | Evidence: [High/Med/Low] | Recency: [High/Med/Low] | Objectivity: [High/Med/Low]"),
        ],
    },
    "report": {
        "name": "Technical Report Summary",
        "description": "Structured summary for industry reports, whitepapers, and technical documentation",
        "sections": [
            ("Title", "[Report title]"),
            ("Organization", "[Publishing organization]"),
            ("Date", "[Publication date]"),
            ("Source Type", "Technical Report"),
            ("Executive Summary", "[2-3 sentences: scope, key conclusion, recommendation]"),
            ("Scope", "[What the report covers and what it excludes]"),
            ("Key Data Points", "1. [Statistic or data point with context]\n2. [Statistic or data point with context]\n3. [Statistic or data point with context]"),
            ("Methodology", "[How data was collected — survey, analysis, case study]"),
            ("Recommendations", "1. [Recommendation with supporting rationale]\n2. [Recommendation with supporting rationale]"),
            ("Limitations", "- [Sample bias, geographic scope, time period]"),
            ("Relevance", "[Why this matters for our context — specific applicability]"),
            ("Quality Assessment", "Credibility: [High/Med/Low] | Evidence: [High/Med/Low] | Recency: [High/Med/Low] | Objectivity: [High/Med/Low]"),
        ],
    },
    "executive": {
        "name": "Executive Brief",
        "description": "Condensed decision-focused summary for leadership consumption",
        "sections": [
            ("Source", "[Title, Author, Date]"),
            ("Bottom Line", "[1 sentence: the single most important takeaway]"),
            ("Key Facts", "1. [Fact]\n2. [Fact]\n3. [Fact]"),
            ("So What?", "[Why this matters for our business/product/strategy]"),
            ("Action Required", "- [Specific next step with owner and timeline]"),
            ("Confidence", "[High/Medium/Low] — based on source quality and evidence strength"),
        ],
    },
    "comparison": {
        "name": "Comparative Analysis",
        "description": "Side-by-side comparison matrix for 2-5 sources on the same topic",
        "sections": [
            ("Topic", "[Research topic or question being compared]"),
            ("Sources Compared", "1. [Source A — Author, Year]\n2. [Source B — Author, Year]\n3. [Source C — Author, Year]"),
            ("Comparison Matrix", "| Dimension | Source A | Source B | Source C |\n|-----------|---------|---------|---------|"
             "\n| Central Thesis | ... | ... | ... |"
             "\n| Methodology | ... | ... | ... |"
             "\n| Key Finding | ... | ... | ... |"
             "\n| Sample/Scope | ... | ... | ... |"
             "\n| Credibility | High/Med/Low | High/Med/Low | High/Med/Low |"),
            ("Consensus Findings", "[What most sources agree on]"),
            ("Contested Points", "[Where sources disagree — with strongest evidence for each side]"),
            ("Gaps", "[What none of the sources address]"),
            ("Synthesis", "[Weight-of-evidence recommendation: what to believe and do]"),
        ],
    },
    "literature": {
        "name": "Literature Review",
        "description": "Thematic organization of multiple sources for research synthesis",
        "sections": [
            ("Research Question", "[The question this review addresses]"),
            ("Search Scope", "[Databases, keywords, date range, inclusion/exclusion criteria]"),
            ("Sources Reviewed", "[Total count, breakdown by type]"),
            ("Theme 1: [Name]", "Summary: [Theme overview]\nKey Sources: [Author (Year), Author (Year)]\nFindings: [What sources say about this theme]"),
            ("Theme 2: [Name]", "Summary: [Theme overview]\nKey Sources: [Author (Year), Author (Year)]\nFindings: [What sources say about this theme]"),
            ("Theme 3: [Name]", "Summary: [Theme overview]\nKey Sources: [Author (Year), Author (Year)]\nFindings: [What sources say about this theme]"),
            ("Gaps in Literature", "- [Under-researched area 1]\n- [Under-researched area 2]"),
            ("Synthesis", "[Overall state of knowledge — what we know, what we don't, where to go next]"),
        ],
    },
}

LENGTH_CONFIGS = {
    "brief": {"max_sections": 4, "label": "Brief (key points only)"},
    "standard": {"max_sections": 99, "label": "Standard (full template)"},
    "detailed": {"max_sections": 99, "label": "Detailed (full template with extended guidance)"},
}


def render_template(template_key, length="standard", output_format="text"):
    """Render a summary template."""
    template = TEMPLATES[template_key]
    sections = template["sections"]

    if length == "brief":
        # Keep only first 4 sections for brief output
        sections = sections[:4]

    if output_format == "json":
        result = {
            "template": template_key,
            "name": template["name"],
            "description": template["description"],
            "length": length,
            "generated": datetime.now().strftime("%Y-%m-%d"),
            "sections": [],
        }
        for title, content in sections:
            result["sections"].append({
                "heading": title,
                "placeholder": content,
            })
        return json.dumps(result, indent=2)

    # Text/Markdown output
    lines = []
    lines.append(f"# {template['name']}")
    lines.append(f"_{template['description']}_\n")
    lines.append(f"Length: {LENGTH_CONFIGS[length]['label']}")
    lines.append(f"Generated: {datetime.now().strftime('%Y-%m-%d')}\n")
    lines.append("---\n")

    for title, content in sections:
        lines.append(f"## {title}\n")
        # Indent content for readability
        for line in content.split("\n"):
            lines.append(line)
        lines.append("")

    lines.append("---")
    lines.append("_Template from research-summarizer skill_")

    return "\n".join(lines)


def list_templates(output_format="text"):
    """List all available templates."""
    if output_format == "json":
        result = []
        for key, tmpl in TEMPLATES.items():
            result.append({
                "key": key,
                "name": tmpl["name"],
                "description": tmpl["description"],
                "sections": len(tmpl["sections"]),
            })
        return json.dumps(result, indent=2)

    lines = []
    lines.append("Available Summary Templates\n")
    lines.append(f"{'KEY':<15} {'NAME':<30} {'SECTIONS':>8}  DESCRIPTION")
    lines.append(f"{'─' * 90}")
    for key, tmpl in TEMPLATES.items():
        lines.append(
            f"{key:<15} {tmpl['name']:<30} {len(tmpl['sections']):>8}  {tmpl['description'][:40]}"
        )
    return "\n".join(lines)


def main():
    parser = argparse.ArgumentParser(
        description="research-summarizer: Generate structured summary templates"
    )
    parser.add_argument(
        "--template", "-t",
        choices=list(TEMPLATES.keys()),
        help="Template type to generate",
    )
    parser.add_argument(
        "--length", "-l",
        choices=["brief", "standard", "detailed"],
        default="standard",
        help="Output length (default: standard)",
    )
    parser.add_argument(
        "--output", "-o",
        choices=["text", "json"],
        default="text",
        help="Output format (default: text)",
    )
    parser.add_argument(
        "--list-templates",
        action="store_true",
        help="List all available templates",
    )
    args = parser.parse_args()

    if args.list_templates:
        print(list_templates(args.output))
        return

    if not args.template:
        print("No template specified. Available templates:\n")
        print(list_templates(args.output))
        print("\nUsage: python scripts/format_summary.py --template academic")
        return

    print(render_template(args.template, args.length, args.output))


if __name__ == "__main__":
    main()