How getzero11/sec-company-report-generator works
Purpose and Entry Points
This is a Python 3.9+ pipeline that produces company SEC Form 10-K analysis reports in Markdown and optionally DOCX. The primary CLI entry point is scripts/generate_report_main.py; a Claude-facing workflow is defined in SKILL.md. Inputs may be ticker, company name, or CIK.
Orchestration
scripts/generate_report_main.py owns end-to-end control flow: parse CLI options/API keys, resolve the company, fetch its filing, optionally enrich data, render Markdown, and invoke DOCX conversion. It supports SEC-only execution (--skip-enrich), custom Markdown destinations, and DOCX suppression (--no-docx).
Entity Resolution and Filing Acquisition
Company identifiers cross a normalization boundary in scripts/resolve_company.py, producing the canonical identity needed for SEC retrieval and downstream API calls. scripts/fetch_10k.py retrieves the latest filing from SEC EDGAR and parses filing HTML into structured report-relevant sections, including business, risks, MD&A, and financial-statement content.
Enrichment Boundary
scripts/enrich_data.py augments filing-derived facts with external market and operating context: financial histories/ratios, valuation and analyst estimates, recent news, and healthcare-specific clinical or regulatory data. This is an optional stage so core report generation can remain dependent only on SEC data.
External integrations include SEC EDGAR, Financial Modeling Prep (FMP), Yahoo Finance, News API, ClinicalTrials.gov, and FDA-related sources. Firecrawl can support SEC scraping. Optional MCP servers provide alternate/enhanced access to Firecrawl, Tinyfish, Yahoo Finance, FMP, and PubMed.
Report Composition
scripts/generate_report.py is the presentation boundary between normalized SEC/enrichment data and the report artifact. It renders a structured Markdown report covering executive summary, business and risk analysis, segment/geographic revenue, financials, valuation, news, clinical/FDA context, ESG, and governance. Markdown is the primary inspectable/version-controllable output.
Document Publishing
scripts/markdown_to_docx.py converts rendered Markdown into a formatted Word deliverable, adding document-oriented presentation such as title page, TOC, section hierarchy, and styled tables. This keeps content generation separate from Word formatting and allows Markdown-only operation.
Runtime, Dependencies, and Quality Gate
The repository runs as local Python scripts with dependencies documented in references/requirements.md. API credentials are supplied as CLI arguments or environment variables, notably FMP and News API keys. scripts/test_skill.py is the validation entry point, with scenario definitions in evals/evals.json; it validates the skill/pipeline across representative public-company inputs.
Components 17
Report Pipeline
Local Python workflow from identity input to published report.
- Report CLI · Owns options, API keys, and end-to-end execution.
scripts/generate_report_main.py - Claude Workflow
SKILL.md - Company Resolver · Converts ticker, name, or CIK into canonical company identity.
scripts/resolve_company.py - 10-K Fetcher & Parser · Retrieves the latest 10-K and extracts report-relevant sections.
scripts/fetch_10k.py - Optional Data Enrichment · Adds market, operating, news, and healthcare context.
scripts/enrich_data.py - Markdown Renderer · Combines normalized filing and enrichment data into the report.
scripts/generate_report.py - DOCX Publisher · Applies Word-oriented formatting to rendered Markdown.
scripts/markdown_to_docx.py
External Sources
SEC is required; market and domain sources are optional enrichment inputs.
- SEC EDGAR
- Market Data APIs · FMP and Yahoo Finance provide financial, valuation, and estimate data.
- News API
- Clinical & FDA Sources · ClinicalTrials.gov and FDA-related sources provide healthcare context.
- Optional MCP Servers · Can enhance access to Firecrawl, Tinyfish, finance, and PubMed services.
Report Artifacts
- Markdown Report · Inspectable, version-controllable analysis report.
- DOCX Report
Validation
- Runtime Dependencies · Documents local Python requirements.
references/requirements.md - Skill Validation · Runs representative public-company pipeline scenarios.
scripts/test_skill.py - Evaluation Scenarios
evals/evals.json
Connections 20
- Claude Workflow → Report CLI: guides workflow
- Report CLI → Company Resolver: resolve input
- Company Resolver → 10-K Fetcher & Parser: canonical identity
- 10-K Fetcher & Parser → SEC EDGAR: retrieve filing
- 10-K Fetcher & Parser → Optional Data Enrichment: filing facts
- Report CLI → Optional Data Enrichment: optional unless --skip-enrich
- Optional Data Enrichment → Market Data APIs: financial context
- Optional Data Enrichment → News API: recent news
- Optional Data Enrichment → Clinical & FDA Sources: clinical/FDA context
- Optional MCP Servers → 10-K Fetcher & Parser: alternate SEC access
- Optional MCP Servers → Optional Data Enrichment: enhanced source access
- 10-K Fetcher & Parser → Markdown Renderer: structured 10-K sections
- Optional Data Enrichment → Markdown Renderer: optional context
- Report CLI → Markdown Renderer: SEC-only path
- Markdown Renderer → Markdown Report: render
- Markdown Report → DOCX Publisher: convert unless --no-docx
- DOCX Publisher → DOCX Report: publish
- Runtime Dependencies → Report CLI: runtime dependencies
- Skill Validation → Report CLI: validate pipeline
- Evaluation Scenarios → Skill Validation: test scenarios