Agency Client Report Factory

Produce a report a client can use to decide what happens next. The full ZIP includes a deterministic reconciliation helper, sample data and a printable HTML report layout. Python 3.10+ runs the helper without dependencies; browser PDF export is optional. It does not fetch analytics or create a slide deck automatically.

Establish comparability

Read metric rules before normalizing exports. Identify client, previous/current date windows, timezone, attribution window, currency, filters and data completeness. Keep raw exports intact. Do not compare a partial month to a complete month without prominent qualification.

Map exports to metrics.csv and definitions in report.json. Each metric/period/source row represents a disjoint partition; sources must have traceable filenames or export references. Use a sum for additive counts/amounts, and a rate for numerator/denominator pairs. Deduplicate overlapping exports before normalization. Do not sum daily unique users or average conversion percentages.

The sample files are fictional fixtures, not client performance. Replace their figures and notes with verified data. Missing observations are not zero. Keep conversions, revenue and currencies separate when their definitions differ.

Build the report

Write a few short contextual notes from actual completed tasks and observed changes. State the next action, owner and decision it supports. Do not attribute causality to your work from coincident changes alone.

python3 scripts/build-report.py /path/to/report.json /path/to/metrics.csv /path/to/new-report

The helper produces report.html and reconciled.json. It calculates weighted rates from totals, percentage-point changes, and relative changes only when the previous value is nonzero. It rejects duplicate keys, nonfinite values, invalid rates and missing periods. The HTML is self-contained with print styling and escaped client/source text. Color is configurable; use client-approved branding.

Review and deliver

Reconcile at least one summed metric and one rate independently against raw exports. Open the report at desktop and narrow widths. Check source labels, long names, every number, comparison language and notes. For PDF, use the available browser print/export tool, inspect all rendered pages for breaks and clipped content, and include the HTML as an editable source. If a deck or XLSX was requested, build that format using the environment's document tools and the same reconciled data; do not relabel HTML as a deck.

Return the requested report format, reconciled data, mapping from original exports, and unresolved comparability issues. Sharing to the client remains subject to the user's authorization.