Your first useful run
The fastest way to understand Medicare-Synth is to follow one fixture through the same boundaries used for source-backed work:
1. Validate a known-good cohort
uv run medicare-synth validate --scenario valid_baseline_cohort
This small cohort contains beneficiaries plus carrier, outpatient, inpatient,
prescription, post-acute, hospice, and MBSF-shaped records. A passing result
means the fixture satisfies the checks enabled by validate for that scenario;
it does not mean that the data represent real Medicare utilization.
2. Inspect the scenario catalog
uv run medicare-synth catalog
uv run medicare-synth catalog --json
The catalog currently contains three valid teaching fixtures and eighteen
intentional anomaly fixtures. Anomaly names make the broken contract explicit,
for example invalid_orphaned_claim and invalid_temporal_inversion.
3. Observe a deliberate failure
uv run medicare-synth validate --scenario invalid_orphaned_claim
The command should report Valid: False and one critical REL-001 finding.
The claim points at a beneficiary that is absent from the parent table. This is
useful test data: a failing fixture confirms that the validator catches a
specific relationship violation rather than that the package is malfunctioning.
4. Call the Python API
import medicare_synth as ms
slice_data = ms.ScenarioCompiler.valid_baseline_cohort()
report = ms.RelationalValidator().validate_slice(slice_data)
if not report.is_valid:
raise ValueError(report.findings)
audit = ms.AuditEngine().audit_dataset(slice_data)
print(audit.overall_privacy_score)
Use the Python API when you need typed records, Polars tables, or a composed workflow. Use the CLI when you need a repeatable shell step or a CI fixture.
What to learn next
Need command syntax?
The CLI reference lists every subcommand, defaults, and output artifact.
Need bigger or custom data?
The scenario guide covers catalog, audit, and expansion workflows.
Need a shareable bundle?
The release guide explains manifests, checksums, and formats.