| name | financial-statement-analyzer |
| description | Analyzes income statement, balance sheet, and cash flow statement data to generate YoY/QoQ trend analysis and flag anomalies like AR surges or cash flow divergence. Trigger when users ask to analyze financials, compare YoY/QoQ, detect red flags, or assess earnings quality. |
| license | MIT |
Financial Statement Analysis — YoY/QoQ Trends + Anomaly Detection
Perform structured analysis of a company's income statement, balance sheet, and cash flow statement: automatically compute year-over-year (YoY) and quarter-over-quarter (QoQ) changes, run multi-dimensional anomaly detection rules (AR surge, cash flow divergence from profit, inventory buildup, gross margin shifts, etc.), and produce a readable report.
Capabilities
| Capability | Description |
|---|
| YoY Analysis | Compare same-period data (e.g., 2024Q1 vs 2023Q1) to identify trend changes |
| QoQ Analysis | Compare consecutive periods (e.g., 2024Q2 vs 2024Q1) to capture short-term fluctuations |
| Financial Ratios | Gross margin, net margin, debt-to-asset ratio, current ratio, DSO, and more |
| Anomaly Detection | 10 built-in rules with automatic scanning, risk severity levels, and explanations |
Quick Start
python scripts/analyze_financials.py data.json
python scripts/analyze_financials.py data.json --json
python scripts/analyze_financials.py data.json --output report.json
python scripts/analyze_financials.py --sample > sample_data.json
python scripts/analyze_financials.py data.json --ar-threshold 0.25 --ocf-ratio 0.4
Input Data Format
The script accepts a JSON file in the following format:
{
"company": "Acme Corp",
"currency": "USD",
"unit": "thousands",
"periods": ["2023Q1","2023Q2","2023Q3","2023Q4","2024Q1","2024Q2","2024Q3","2024Q4"],
"income_statement": {
"revenue": [5000, 5200, 4800, 6000, 5500, 5800, 5100, 6500],
"cost_of_revenue": [3000
Field descriptions:
periods supports quarterly format (2024Q1) and annual format (2024); the script auto-detects the type- All arrays must match the length of
periods
- Missing fields are skipped gracefully (no errors thrown)
unit is a display label used only in report output
Parameters
| Parameter | Short | Required | Default | Description |
|---|
input | - | Yes* | - | Path to input JSON file |
--json | -j | No | false | Output in JSON format |
--output | -o | No | stdout | Output file path (.json) |
--sample | -s | No | false | Print sample data to stdout |
--ar-threshold | - | No | 0.20 | AR anomaly threshold (growth rate gap) |
--inv-threshold | - | No | 0.15 | Inventory anomaly threshold (growth rate gap) |
--ocf-ratio | - | No | 0.50 | Cash flow / profit divergence threshold |
--margin-threshold | - | No | 0.05 | Gross margin shift threshold |
--debt-ceiling | - | No | 0.70 | Debt-to-asset ratio warning level |
--current-floor | - | No | 1.00 | Current ratio warning level |
--goodwill-ceiling | - | No | 0.30 | Goodwill-to-asset ratio warning level |
* input is not required when using --sample.
Anomaly Detection Rules
The script includes the following 10 built-in anomaly detection rules:
| # | Rule | Trigger Condition | Risk Implication |
|---|
| 1 | AR Surge | AR growth - Revenue growth > threshold | Possible aggressive revenue recognition or collection difficulties |
| 2 | Cash Flow Divergence | OCF / Net Income < threshold | Low earnings quality; profits may contain significant accruals |
| 3 | Inventory Buildup | Inventory growth - Revenue growth > threshold | Potential product obsolescence or write-down risk |
| 4 | Gross Margin Shift | Gross margin change > threshold | Significant change in pricing power or cost structure |
| 5 | Net Margin Shift | Net margin change > threshold | Abnormal expense control or non-recurring items |
| 6 | Persistent Negative OCF | OCF < 0 for 2+ consecutive periods | Insufficient organic cash generation |
| 7 | Excessive Goodwill | Goodwill / Total Assets > threshold | Impairment risk if acquired entities underperform |
| 8 | High Leverage | Liabilities / Assets > threshold | Elevated debt repayment pressure |
| 9 | Low Current Ratio | Current Assets / Current Liabilities < threshold | Weak short-term liquidity |
| 10 | AP Anomaly | AP growth significantly deviates from COGS growth | Supply chain stress or working capital strain |
LLM Interpretation Guide
When a user provides financial report data (PDF / image / table / text), follow these steps:
- Data Extraction: Convert the user-provided financial data into the JSON format above and save as a temporary file
- Run Analysis: Execute
scripts/analyze_financials.py for quantitative analysis
- Comprehensive Interpretation: Combine the script output with the analysis framework below to provide a thorough interpretation
Cross-Statement Analysis Framework
- Income Statement → Balance Sheet: Is revenue growth driven by accounts receivable? Is net income converting to retained earnings?
- Income Statement → Cash Flow Statement: Does net income match operating cash flow? Are depreciation and amortization add-backs reasonable?
- Balance Sheet → Cash Flow Statement: Where is the funding for asset expansion coming from? Are investing activities consistent with capital expenditures?
Contextual Judgment for Anomaly Signals
An anomaly signal does not necessarily mean "the company has a problem" — it must be interpreted in the context of industry and business conditions:
- An AR surge may be normal seasonal behavior at year-end for B2B companies
- High leverage is typical in utilities and real estate industries
- Negative short-term cash flow can be reasonable for high-growth companies (e.g., SaaS)
Recommended Output Format
## Financial Statement Analysis Report — [Company Name]
### Key Metrics at a Glance
(Summary table of key indicators)
### YoY/QoQ Change Highlights
(Top 3-5 most significant changes with interpretation)
### Anomaly Signals
(Each detected anomaly explained with severity and possible causes)
### Cross-Statement Analysis
(Cross-statement logical validation conclusions)
### Summary & Recommendations
(1-2 paragraph overall assessment)
