scripts/format_summary.py
10.8 KB| 1 | #!/usr/bin/env python3 |
| 2 | """ |
| 3 | research-summarizer: Summary Formatter |
| 4 | |
| 5 | Generate structured research summary templates for different source types. |
| 6 | Produces fill-in-the-blank frameworks for academic papers, web articles, |
| 7 | technical reports, and executive briefs. |
| 8 | |
| 9 | Usage: |
| 10 | python scripts/format_summary.py --template academic |
| 11 | python scripts/format_summary.py --template executive --length brief |
| 12 | python scripts/format_summary.py --list-templates |
| 13 | python scripts/format_summary.py --template article --output json |
| 14 | """ |
| 15 | |
| 16 | import argparse |
| 17 | import json |
| 18 | import sys |
| 19 | import textwrap |
| 20 | from datetime import datetime |
| 21 | |
| 22 | |
| 23 | # --- Templates --- |
| 24 | |
| 25 | TEMPLATES = { |
| 26 | "academic": { |
| 27 | "name": "Academic Paper Summary", |
| 28 | "description": "IMRAD structure for peer-reviewed papers and research studies", |
| 29 | "sections": [ |
| 30 | ("Title", "[Full paper title]"), |
| 31 | ("Author(s)", "[Author names, affiliations]"), |
| 32 | ("Publication", "[Journal/Conference, Year, DOI]"), |
| 33 | ("Source Type", "Academic Paper"), |
| 34 | ("Key Thesis", "[1-2 sentences: the central research question and answer]"), |
| 35 | ("Methodology", "[Study design, sample size, data sources, analytical approach]"), |
| 36 | ("Key Findings", "1. [Finding 1 with supporting data]\n2. [Finding 2 with supporting data]\n3. [Finding 3 with supporting data]"), |
| 37 | ("Statistical Significance", "[Key p-values, effect sizes, confidence intervals]"), |
| 38 | ("Limitations", "- [Limitation 1: scope, sample, methodology gap]\n- [Limitation 2]"), |
| 39 | ("Implications", "- [What this means for practice]\n- [What this means for future research]"), |
| 40 | ("Notable Quotes", '> "[Direct quote]" (p. X)'), |
| 41 | ("Quality Assessment", "Credibility: [High/Med/Low] | Evidence: [High/Med/Low] | Recency: [High/Med/Low] | Objectivity: [High/Med/Low]"), |
| 42 | ], |
| 43 | }, |
| 44 | "article": { |
| 45 | "name": "Web Article Summary", |
| 46 | "description": "Claim-evidence-implication structure for online articles and blog posts", |
| 47 | "sections": [ |
| 48 | ("Title", "[Article title]"), |
| 49 | ("Author", "[Author name]"), |
| 50 | ("Source", "[Publication/Website, Date, URL]"), |
| 51 | ("Source Type", "Web Article"), |
| 52 | ("Central Claim", "[1-2 sentences: main argument or thesis]"), |
| 53 | ("Supporting Evidence", "1. [Evidence point 1]\n2. [Evidence point 2]\n3. [Evidence point 3]"), |
| 54 | ("Counterarguments Addressed", "- [Counterargument and author's response]"), |
| 55 | ("Implications", "- [What this means for the reader]"), |
| 56 | ("Bias Check", "Author affiliation: [?] | Funding: [?] | Balanced perspective: [Yes/No]"), |
| 57 | ("Actionable Takeaways", "- [What to do with this information]\n- [Next step]"), |
| 58 | ("Quality Assessment", "Credibility: [High/Med/Low] | Evidence: [High/Med/Low] | Recency: [High/Med/Low] | Objectivity: [High/Med/Low]"), |
| 59 | ], |
| 60 | }, |
| 61 | "report": { |
| 62 | "name": "Technical Report Summary", |
| 63 | "description": "Structured summary for industry reports, whitepapers, and technical documentation", |
| 64 | "sections": [ |
| 65 | ("Title", "[Report title]"), |
| 66 | ("Organization", "[Publishing organization]"), |
| 67 | ("Date", "[Publication date]"), |
| 68 | ("Source Type", "Technical Report"), |
| 69 | ("Executive Summary", "[2-3 sentences: scope, key conclusion, recommendation]"), |
| 70 | ("Scope", "[What the report covers and what it excludes]"), |
| 71 | ("Key Data Points", "1. [Statistic or data point with context]\n2. [Statistic or data point with context]\n3. [Statistic or data point with context]"), |
| 72 | ("Methodology", "[How data was collected — survey, analysis, case study]"), |
| 73 | ("Recommendations", "1. [Recommendation with supporting rationale]\n2. [Recommendation with supporting rationale]"), |
| 74 | ("Limitations", "- [Sample bias, geographic scope, time period]"), |
| 75 | ("Relevance", "[Why this matters for our context — specific applicability]"), |
| 76 | ("Quality Assessment", "Credibility: [High/Med/Low] | Evidence: [High/Med/Low] | Recency: [High/Med/Low] | Objectivity: [High/Med/Low]"), |
| 77 | ], |
| 78 | }, |
| 79 | "executive": { |
| 80 | "name": "Executive Brief", |
| 81 | "description": "Condensed decision-focused summary for leadership consumption", |
| 82 | "sections": [ |
| 83 | ("Source", "[Title, Author, Date]"), |
| 84 | ("Bottom Line", "[1 sentence: the single most important takeaway]"), |
| 85 | ("Key Facts", "1. [Fact]\n2. [Fact]\n3. [Fact]"), |
| 86 | ("So What?", "[Why this matters for our business/product/strategy]"), |
| 87 | ("Action Required", "- [Specific next step with owner and timeline]"), |
| 88 | ("Confidence", "[High/Medium/Low] — based on source quality and evidence strength"), |
| 89 | ], |
| 90 | }, |
| 91 | "comparison": { |
| 92 | "name": "Comparative Analysis", |
| 93 | "description": "Side-by-side comparison matrix for 2-5 sources on the same topic", |
| 94 | "sections": [ |
| 95 | ("Topic", "[Research topic or question being compared]"), |
| 96 | ("Sources Compared", "1. [Source A — Author, Year]\n2. [Source B — Author, Year]\n3. [Source C — Author, Year]"), |
| 97 | ("Comparison Matrix", "| Dimension | Source A | Source B | Source C |\n|-----------|---------|---------|---------|" |
| 98 | "\n| Central Thesis | ... | ... | ... |" |
| 99 | "\n| Methodology | ... | ... | ... |" |
| 100 | "\n| Key Finding | ... | ... | ... |" |
| 101 | "\n| Sample/Scope | ... | ... | ... |" |
| 102 | "\n| Credibility | High/Med/Low | High/Med/Low | High/Med/Low |"), |
| 103 | ("Consensus Findings", "[What most sources agree on]"), |
| 104 | ("Contested Points", "[Where sources disagree — with strongest evidence for each side]"), |
| 105 | ("Gaps", "[What none of the sources address]"), |
| 106 | ("Synthesis", "[Weight-of-evidence recommendation: what to believe and do]"), |
| 107 | ], |
| 108 | }, |
| 109 | "literature": { |
| 110 | "name": "Literature Review", |
| 111 | "description": "Thematic organization of multiple sources for research synthesis", |
| 112 | "sections": [ |
| 113 | ("Research Question", "[The question this review addresses]"), |
| 114 | ("Search Scope", "[Databases, keywords, date range, inclusion/exclusion criteria]"), |
| 115 | ("Sources Reviewed", "[Total count, breakdown by type]"), |
| 116 | ("Theme 1: [Name]", "Summary: [Theme overview]\nKey Sources: [Author (Year), Author (Year)]\nFindings: [What sources say about this theme]"), |
| 117 | ("Theme 2: [Name]", "Summary: [Theme overview]\nKey Sources: [Author (Year), Author (Year)]\nFindings: [What sources say about this theme]"), |
| 118 | ("Theme 3: [Name]", "Summary: [Theme overview]\nKey Sources: [Author (Year), Author (Year)]\nFindings: [What sources say about this theme]"), |
| 119 | ("Gaps in Literature", "- [Under-researched area 1]\n- [Under-researched area 2]"), |
| 120 | ("Synthesis", "[Overall state of knowledge — what we know, what we don't, where to go next]"), |
| 121 | ], |
| 122 | }, |
| 123 | } |
| 124 | |
| 125 | LENGTH_CONFIGS = { |
| 126 | "brief": {"max_sections": 4, "label": "Brief (key points only)"}, |
| 127 | "standard": {"max_sections": 99, "label": "Standard (full template)"}, |
| 128 | "detailed": {"max_sections": 99, "label": "Detailed (full template with extended guidance)"}, |
| 129 | } |
| 130 | |
| 131 | |
| 132 | def render_template(template_key, length="standard", output_format="text"): |
| 133 | """Render a summary template.""" |
| 134 | template = TEMPLATES[template_key] |
| 135 | sections = template["sections"] |
| 136 | |
| 137 | if length == "brief": |
| 138 | # Keep only first 4 sections for brief output |
| 139 | sections = sections[:4] |
| 140 | |
| 141 | if output_format == "json": |
| 142 | result = { |
| 143 | "template": template_key, |
| 144 | "name": template["name"], |
| 145 | "description": template["description"], |
| 146 | "length": length, |
| 147 | "generated": datetime.now().strftime("%Y-%m-%d"), |
| 148 | "sections": [], |
| 149 | } |
| 150 | for title, content in sections: |
| 151 | result["sections"].append({ |
| 152 | "heading": title, |
| 153 | "placeholder": content, |
| 154 | }) |
| 155 | return json.dumps(result, indent=2) |
| 156 | |
| 157 | # Text/Markdown output |
| 158 | lines = [] |
| 159 | lines.append(f"# {template['name']}") |
| 160 | lines.append(f"_{template['description']}_\n") |
| 161 | lines.append(f"Length: {LENGTH_CONFIGS[length]['label']}") |
| 162 | lines.append(f"Generated: {datetime.now().strftime('%Y-%m-%d')}\n") |
| 163 | lines.append("---\n") |
| 164 | |
| 165 | for title, content in sections: |
| 166 | lines.append(f"## {title}\n") |
| 167 | # Indent content for readability |
| 168 | for line in content.split("\n"): |
| 169 | lines.append(line) |
| 170 | lines.append("") |
| 171 | |
| 172 | lines.append("---") |
| 173 | lines.append("_Template from research-summarizer skill_") |
| 174 | |
| 175 | return "\n".join(lines) |
| 176 | |
| 177 | |
| 178 | def list_templates(output_format="text"): |
| 179 | """List all available templates.""" |
| 180 | if output_format == "json": |
| 181 | result = [] |
| 182 | for key, tmpl in TEMPLATES.items(): |
| 183 | result.append({ |
| 184 | "key": key, |
| 185 | "name": tmpl["name"], |
| 186 | "description": tmpl["description"], |
| 187 | "sections": len(tmpl["sections"]), |
| 188 | }) |
| 189 | return json.dumps(result, indent=2) |
| 190 | |
| 191 | lines = [] |
| 192 | lines.append("Available Summary Templates\n") |
| 193 | lines.append(f"{'KEY':<15} {'NAME':<30} {'SECTIONS':>8} DESCRIPTION") |
| 194 | lines.append(f"{'─' * 90}") |
| 195 | for key, tmpl in TEMPLATES.items(): |
| 196 | lines.append( |
| 197 | f"{key:<15} {tmpl['name']:<30} {len(tmpl['sections']):>8} {tmpl['description'][:40]}" |
| 198 | ) |
| 199 | return "\n".join(lines) |
| 200 | |
| 201 | |
| 202 | def main(): |
| 203 | parser = argparse.ArgumentParser( |
| 204 | description="research-summarizer: Generate structured summary templates" |
| 205 | ) |
| 206 | parser.add_argument( |
| 207 | "--template", "-t", |
| 208 | choices=list(TEMPLATES.keys()), |
| 209 | help="Template type to generate", |
| 210 | ) |
| 211 | parser.add_argument( |
| 212 | "--length", "-l", |
| 213 | choices=["brief", "standard", "detailed"], |
| 214 | default="standard", |
| 215 | help="Output length (default: standard)", |
| 216 | ) |
| 217 | parser.add_argument( |
| 218 | "--output", "-o", |
| 219 | choices=["text", "json"], |
| 220 | default="text", |
| 221 | help="Output format (default: text)", |
| 222 | ) |
| 223 | parser.add_argument( |
| 224 | "--list-templates", |
| 225 | action="store_true", |
| 226 | help="List all available templates", |
| 227 | ) |
| 228 | args = parser.parse_args() |
| 229 | |
| 230 | if args.list_templates: |
| 231 | print(list_templates(args.output)) |
| 232 | return |
| 233 | |
| 234 | if not args.template: |
| 235 | print("No template specified. Available templates:\n") |
| 236 | print(list_templates(args.output)) |
| 237 | print("\nUsage: python scripts/format_summary.py --template academic") |
| 238 | return |
| 239 | |
| 240 | print(render_template(args.template, args.length, args.output)) |
| 241 | |
| 242 | |
| 243 | if __name__ == "__main__": |
| 244 | main() |
文件内容是平台检查时读出的文本，只供查看。平台不会运行包里的任何脚本或程序。
