Automated quarterly financial report generation with dividend-adjusted total return calculations. Use when generating stock performance reports, quarterly ea...
---
name: financial-report-automator
description: Automated quarterly financial report generation with dividend-adjusted total return calculations. Use when generating stock performance reports, quarterly earnings summaries, or return analytics for any ticker with CSV price data.
version: 1.2.1
tags: ['finance', 'reporting', 'quarterly', 'returns', 'dividends']
---
# Financial Report Automator
Generates quarterly stock performance reports with **dividend-adjusted total return**.
## What It Does
- Parses CSV price data (Yahoo Finance export format)
- Computes **price return** (raw close) and **total return** (adjusted close with dividends)
- Produces structured quarterly reports: start/end price, returns, high/low, avg volume, dividends paid
## Key Fix (v1.0.1)
Previous versions used raw close for return calculations, which **understated returns for dividend-paying stocks** like AAPL. v1.0.1 introduces:
1. **Column name normalization** — handles mixed-case CSV headers (`Date` → `date`)
2. **Adjusted close computation** — backward-adjusts prices for dividends so total return reflects reinvested dividends
3. **Separate price_return vs total_return** — both are reported for transparency
4. **Dividend tracking** — `dividend` column is optional; defaults to 0 if absent
## Usage
### As a Python module
```python
from scripts.stock_analyzer import StockAnalyzer
analyzer = StockAnalyzer(data_path="finance/AAPL.csv")
# 30-day total return (dividend-adjusted)
print(analyzer.calculate_returns(30))
# 30-day price return only (no dividends)
print(analyzer.calculate_returns(30, use_adj=False))
# Full quarterly report
report = analyzer.generate_quarterly_report(quarter=2, year=2026)
print(report)
```
### CLI
```bash
python3 scripts/stock_analyzer.py
```
## CSV Format Expected
```
Date,Close,Volume,Open,High,Low
01/02/2026,$269.77,21755774,$272.05,$277.82,$269.11
```
Optional columns:
- `dividend` — per-share dividend on ex-div date
- `adj_close` — pre-computed adjusted close (overrides internal calculation)
## Report Output
```json
{
"quarter": "Q2 2026",
"start_date": "2026-04-01",
"end_date": "2026-06-30",
"start_price": 223.0,
"end_price": 235.5,
"price_return_pct": 5.61,
"total_return_pct": 6.12,
"dividends_per_share": 0.25,
"highest_price": 240.0,
"lowest_price": 218.5,
"average_volume": 35000000
}
```
## Requirements
- Python 3.10+
- pandas
don't have the plugin yet? install it then click "run inline in claude" again.