Financial Statement Analyzer

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

# Basic usage: analyze financial data in JSON format
python scripts/analyze_financials.py data.json

# Output results in JSON format
python scripts/analyze_financials.py data.json --json

# Export to a file
python scripts/analyze_financials.py data.json --output report.json

# Generate sample data file (for testing)
python scripts/analyze_financials.py --sample > sample_data.json

# Customize anomaly detection thresholds
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, 3100, 2900, 3500, 3400, 3600, 3200, 4100],
    "operating_income": [800, 850, 750, 1000, 780, 820, 700, 900],
    "net_income": [600, 650, 560, 780, 580, 620, 520, 680]
  },
  "balance_sheet": {
    "accounts_receivable": [2000, 2100, 2200, 2300, 2800, 3200, 3600, 4200],
    "inventory": [1000, 1050, 1100, 1200, 1100, 1150, 1200, 1300],
    "total_current_assets": [5000, 5200, 5400, 5800, 6000, 6500, 7000, 7500],
    "goodwill": [500, 500, 500, 500, 500, 500, 500, 500],
    "total_assets": [15000, 15500, 16000, 16500, 17000, 17500, 18000, 18500],
    "accounts_payable": [1500, 1600, 1550, 1700, 1650, 1750, 1700, 1800],
    "total_current_liabilities": [4000, 4200, 4100, 4500, 4300, 4600, 4500, 4900],
    "total_liabilities": [8000, 8200, 8400, 8600, 8800, 9000, 9200, 9500],
    "total_equity": [7000, 7300, 7600, 7900, 8200, 8500, 8800, 9000]
  },
  "cash_flow": {
    "operating_cash_flow": [700, 750, 620, 850, 300, 280, 250, 200],
    "investing_cash_flow": [-200, -180, -250, -300, -400, -350, -300, -280],
    "financing_cash_flow": [-100, -50, -80, -120, 200, 150, 100, 50],
    "capex": [180, 160, 230, 280, 380, 330, 280, 260]
  }
}

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 | 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 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:

1. Data Extraction: Convert the user-provided financial data into the JSON format above and save as a temporary file
2. Run Analysis: Execute scripts/analyze_financials.py for quantitative analysis
3. 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)

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: null0xxx
• Source: null0xxx/kimi-atlas
• License: MIT

Install and usage instructions live in the source repository linked above.