# MVP Specification - synthmulti

## Scope

The MVP must generate synthetic tabular data with a latent multivariate normal layer and
support:

- continuous variables (`mean`, `sd`)
- binary variables (`prevalence`)
- ordinal variables (`probs`)
- categorical variables (`probs` dictionary)

## Public API Contract

- `SynthSchema` must support:
  - `add_continuous(name, mean, sd)`
  - `add_binary(name, prevalence)`
  - `add_ordinal(name, probs)`
  - `add_categorical(name, probs)`
  - `set_dependency(method, matrix)`
- `SynthGenerator(schema, random_state)` must support:
  - `sample(n, ranges=None, rounding=None) -> pandas.DataFrame`
  - `diagnostics(dataframe, real_dataframe=None, variable_types=None) -> dict[str, object]`
  - `build_metadata(version="1.0.0")`

## Invariants

- Correlation matrices are square, symmetric, and positive definite.
- Correlation/partial values are within `[-1, 1]`.
- Binary prevalence is between `0` and `1`.
- Ordinal and categorical probabilities are positive and sum to `1`.
- Samples are reproducible with fixed seed.

## Acceptance Criteria

1. A full pipeline test passes for mixed variable types.
2. Matrix validation rejects invalid inputs.
3. Binary/ordinal/categorical frequencies are close to target probabilities.
4. Diagnostics report includes descriptive stats and correlation error.
5. Metadata export includes seed, version, and schema hash.
6. Optional real-vs-synth diagnostics include:
   - marginal distance metrics (KS/Wasserstein for continuous, TVD for discrete),
   - real/synthetic correlation matrices and absolute difference matrix,
   - pairwise correlations by variable pair (`varA__varB`),
   - association alignment via Pearson correlation of upper triangles.

## Requirement-to-Test Traceability

- Matrix validation -> `tests/unit/test_latent.py`
- Transform distributions -> `tests/unit/test_transforms.py`
- Pipeline reproducibility -> `tests/integration/test_generator_pipeline.py`
- Constraints/export/privacy -> `tests/unit/test_constraints_export_privacy.py`
- Real-vs-synth report -> `tests/unit/test_diagnostics_real.py`