# Reporting automation: concrete teaching handover

**Review status:** instructional handover for a local synthetic workflow. No deployment, live scheduler, external API connection, human distribution approval or message send has occurred.

## Purpose and contract

Prepare a weekly paid-event report for an explicit UTC interval and region. The original fixture selects January 5 inclusive through January 12 exclusive, with source extraction at January 12 01:00 UTC. Three selected events total 3,500 paise. Region totals: North 1,000, South 2,000, Unknown 500.

## Files and responsibilities

| Artifact | Role |
|---|---|
| [README](../labs/report-automation/README.md) | Setup, metric contract and limits |
| [pipeline.py](../labs/report-automation/pipeline.py) | Validate source/configuration, select events, reconcile and prepare a local bundle |
| [source manifest](../labs/report-automation/source-manifest.json) | Declared source identity, count, watermark and extraction time |
| [report configuration](../labs/report-automation/report-config.json) | Reproducible analytical parameters; no secrets |
| [scheduled_run.py](../labs/report-automation/scheduled_run.py) | Local attempt logging, timeout and child exit-code propagation |
| [api_extract.py](../labs/report-automation/api_extract.py) | Separate simulated API schema, pagination and retry contract |
| [verify.py](../labs/report-automation/verify.py) | Local reference, rerun, corruption, CLI and wrapper checks |
| [verify_api.py](../labs/report-automation/verify_api.py) | Simulated API failure and completeness checks |
| [RUNBOOK](../labs/report-automation/RUNBOOK.md) | Diagnosis and bounded recovery |

## Runtime and setup

The core workflow uses Python 3.12 standard library. Pandas is used in one accompanying dataframe tutorial, not by the core pipeline or its verification scripts. Use the recorded verification JSON files to identify the actual runtime and test counts rather than assuming that installed dependencies match another machine.

Start from the supplied CSV/JSON fixtures. `build_fixture.py` intentionally regenerates those synthetic inputs; it is not a production extractor and should never be used as an incident-data repair tool.

## Acceptance demonstration for a receiving analyst

1. Run both verification scripts and inspect their results and stated limits.
2. Invoke `pipeline.py` with absolute paths from a different working directory.
3. Confirm three selected events and 3,500 paise, then verify the output bundle.
4. Repeat identical inputs and show that the existing bundle is reused without changing bytes.
5. Change only the region to North and show a new 1,000-paise version, preserving the original.
6. Inject a stale source watermark and identify the correct runbook path.
7. Explain why a prepared bundle is not approved or distributed and why source-manifest consistency is not independent proof of upstream completeness.

## Operational decisions still required for a real adoption

The adopting team must choose a report owner and backup, actual source contract, period-generation schedule, account/access mechanism, expected-run monitoring, retention policy and authorized review/distribution path. These are deployment-specific decisions; this teaching package does not pretend they have already been made.

The existing code demonstrates local bundle preparation and controlled failures. It does not establish live API behavior, distributed concurrency, object-store atomicity, power-loss durability, external alert delivery or production service-level compliance.

## Change control

Version metric definitions, source contracts and configuration. Preserve prior report evidence when corrections occur. Run the relevant failure and reference checks after changes, and make a new review decision for the changed artifact and scope before any real distribution.

This handover supports the proposed assessment depth of the [Data Analytics with Generative AI course](https://www.neurapath.in/courses/da), without adding live hours or claiming that every deployment-specific component already exists in the course.