MarketReportKit

MarketReportKit is a Python library for cross-market analysis and HTML report generation. It turns OHLCV data into daily market state, seasonality, time-of-day, correlation, trend, profile, gap, and signal diagnostics with interactive Plotly charts.

The package includes free data adapters for Yahoo Finance, Stooq, FRED macro series, and Alpha Vantage, plus CSV loading for local datasets, deterministic synthetic data for examples and tests, and a small CLI for generating reports end to end.

Features

• Data sources: Yahoo Finance, Stooq, FRED macro series, Alpha Vantage, CSV, pandas DataFrame, and deterministic synthetic OHLCV.
• Daily state: relative volume/range, ATR, historical volatility, projected range, key levels, active signals, and nearest historical analogs.
• Seasonality: weekday and hour-of-day effects with permutation bands and return/volume heatmaps.
• Correlations: static and rolling correlations plus volatility-adjusted relative performance.
• Market lenses: equity/ETF risk snapshots, benchmark beta/correlation, FX session diagnostics, macro context, and futures curve term-structure tables.
• Trend diagnostics: candle body ratio, efficiency ratio, session breakdowns, and volume/range predictors.
• Profile and gap tools: volume profile classification, weekend/session gap statistics, and open-interest trend tests.
• Reports: self-contained HTML reports with tables and interactive charts.
• Tests: network-free unit tests over deterministic sample data.

Install

pip install marketreportkit

For local development from this repository:

python -m pip install -e ".[dev]"
pytest

Quick Start

Generate a full report from deterministic sample data:

marketreportkit sample --output reports/sample_report.html --periods 720 --timeframe 1h

Download free market data directly:

marketreportkit download --symbol SPY --interval 1d --period 1y --output reports/spy_report.html

Use Stooq daily/weekly/monthly data with a free Stooq API key:

marketreportkit download --source stooq --symbol spy.us --interval 1d --api-key "$STOOQ_API_KEY" --output reports/spy_stooq.html

Use Alpha Vantage with a free API key:

marketreportkit download --source alpha-vantage --symbol IBM --interval 1d --api-key "$ALPHAVANTAGE_API_KEY" --output reports/ibm.html

Download a free FRED macro series to CSV:

marketreportkit macro --series DGS10 --output data/dgs10.csv

Use a CSV file with columns such as timestamp, open, high, low, close, and volume:

marketreportkit report --csv data/spy_1d.csv --symbol SPY --output reports/spy_report.html

Attach macro context and a simple futures curve to a local report:

marketreportkit report \
	--csv data/spy_1d.csv \
	--symbol SPY \
	--macro-csv DGS10=data/dgs10.csv \
	--futures-curve M1=100.0 \
	--futures-curve M2=101.2 \
	--output reports/spy_cross_market.html

Python API

from marketreportkit import SyntheticDataSource, generate_html_report

source = SyntheticDataSource(seed=7)
market = source.fetch_ohlcv("SPY", timeframe="1h", limit=720)

report = generate_html_report(market.frame, symbol=market.symbol)
report.write("reports/spy_report.html")

Download with free providers:

from marketreportkit import FREDSeriesSource, StooqOHLCVSource, YFinanceOHLCVSource, generate_html_report

market = YFinanceOHLCVSource().fetch_ohlcv("SPY", timeframe="1d", period="1y")
stooq_market = StooqOHLCVSource().fetch_ohlcv("spy.us", timeframe="1d")
rates = FREDSeriesSource().fetch_series("DGS10").series

generate_html_report(
	market.frame,
	symbol=market.symbol,
	macro_series={"DGS10": rates},
	futures_curve={"M1": 100.0, "M2": 101.2, "M3": 100.7},
).write("reports/spy.html")

Build individual analytics:

from marketreportkit.metrics import relative_activity
from marketreportkit.seasonality import weekday_report, hourly_report
from marketreportkit.levels import key_levels, projected_range
from marketreportkit.market_types import equity_factor_snapshot, fx_session_report, futures_term_structure, macro_series_snapshot

weekday = weekday_report(market.frame)
hourly = hourly_report(market.frame)
levels = key_levels(market.frame)
projection = projected_range(market.frame)
relative_volume = relative_activity(market.frame["volume"])
risk = equity_factor_snapshot(market.frame)
fx_sessions = fx_session_report(market.frame)
macro = macro_series_snapshot(rates)
curve = futures_term_structure({"M1": 100.0, "M2": 101.2, "M3": 100.7})

Report Sections

The default HTML report includes:

• Market summary and recent OHLCV context.
• Projected range from ATR and realized volatility.
• Key levels with distance and historical reach probability.
• Active signal table with historical forward-return statistics.
• Price chart with moving averages and projected range bands.
• Weekday seasonality tables, bar charts, and heatmaps.
• Hour-of-day effects and session diagnostics for intraday data.
• Volume profile classification and simple gap diagnostics.
• Equity/ETF risk snapshot, benchmark beta/correlation when a benchmark is supplied, FX session lens for intraday data, macro context tables, and futures term-structure diagnostics.

Correlation sections can be added by passing a DataFrame of close prices from any market mix:

from marketreportkit.reports import generate_html_report

report = generate_html_report(
	market.frame,
	symbol="SPY",
	correlation_prices=close_price_frame,
	correlation_base="SPY",
)

Supported Markets

The analytics are instrument-agnostic as long as the input is normalized OHLCV. Typical uses include:

• Equities and ETFs such as SPY, QQQ, AAPL, MSFT.
• Index proxies and volatility products such as DIA, IWM, GLD, TLT.
• FX proxies, cross-asset ETFs, and intraday FX-style session analysis.
• Commodities and futures proxies available through Yahoo Finance, Stooq, or local CSVs.
• Macro series from FRED, such as yields, inflation, employment, liquidity, and activity indicators.
• Alpha Vantage symbols when you provide a free API key.
• Local CSV exports from brokers, exchanges, or research pipelines.

Free Data Sources

Source	Coverage	Notes
Yahoo Finance	Equities, ETFs, indices, FX proxies, commodities, selected futures/crypto tickers	No key required. Intraday history has retention limits.
Stooq	Stocks, indices, ETFs, FX, commodities, daily/weekly/monthly history	Free API key currently required. Symbols often use suffixes such as spy.us.
FRED	Macro and rates time series	No key required through the public CSV graph endpoint.
Alpha Vantage	Equities, ETFs, FX, crypto, technical data depending on endpoint	Free API key required; rate limits apply.

Data Model

All analytics use a normalized OHLCV DataFrame indexed by UTC timestamps with these columns:

open, high, low, close, volume

normalize_ohlcv accepts common vendor and CSV shapes and coerces numeric columns, sorts by time, removes duplicate timestamps, and preserves a timezone-aware UTC index.

License

MIT