Skip to content
Beta · version 0.8.1 · commands and the JSON format may still change.

Python API: Generate

tabalyst.build_generate_plan() and tabalyst.generate_datasets() plan and produce synthetic datasets from Generate packages or packaged examples. tabalyst.list_available_anomaly_profiles() inspects the catalog of anomaly profiles.

import tabalyst
# Plan and generate the insurance reference dataset with ground truth
plan = tabalyst.build_generate_plan(
example="insurance",
anomaly_profile="rare_events",
rows=100_000,
seed=42,
output_dir="artifacts/insurance_run",
)
result = tabalyst.generate_datasets(plan)
print(f"Created {len(result.paths)} files.")

Validate a Generate definition or package and plan every artifact before writing.

plan = tabalyst.build_generate_plan(
definition_path=None,
example="insurance",
output=None,
output_dir="out",
rows=10000,
seed=42,
as_of_date="2026-09-16",
anomaly_profile="format_vs_business",
force=False,
output_profile="default",
relational=False,
row_order="default",
english=False,
)
ParameterTypeDefaultMeaning
definition_pathstr | Path | NoneNonePath to a package directory or its dataset.yaml.
examplestr | NoneNonePackaged example: "crm", "insurance", or "computer".
outputstr | Path | NoneNoneOne CSV file destination (requires single clean CSV or single altered file with changes).
output_dirstr | Path | NoneNoneDirectory for all planned artifacts.
rowsint | NoneNoneNumber of generated rows.
seedint | NoneNoneRoot random seed for deterministic reproducibility.
as_of_datestr | NoneNoneReference date in YYYY-MM-DD format.
anomaly_profilestr | tuple[str, ...] | NoneNoneProfile name or comma-separated list of profiles to inject.
forceboolFalseOverwrite existing files.
output_profilestr | NoneNoneOutput column profile. Computer: "compact", "standard", "extended". Insurance: "default" (34 cols), "extended" (44 cols), "complete" (51 cols), or flattened profiles ("flattened", "flattened-extended", "flattened-complete").
relationalboolFalseInsurance: generate 4 relational tables (clients, contrats, reclamations, paiements) with ground truth.
row_orderstr"default"Insurance row ordering: "default", "branch", "chronological", "agency", "shuffled".
englishboolFalseInsurance: translate column names to English and localize categorical values.
validate_onlyboolFalseValidate configuration without creating artifacts.

Returns a GeneratePlan (or ComputerPlan for the Computer example).

Execute a validated generation plan, writing CSV files and ground-truth artifacts atomically.

result = tabalyst.generate_datasets(plan, on_progress=None)
ParameterTypeDefaultMeaning
planGeneratePlan | ComputerPlanrequiredPlan created by build_generate_plan().
on_progressCallable[[GenerateProgress], None] | NoneNoneOptional callback reporting generation stage and row progress.

Returns a GenerateResult object:

  • result.paths: tuple of Path objects written.
  • result.row_counts: dictionary mapping dataset identifiers to written row counts.
  • result.anomaly_counts: dictionary mapping dataset/profile keys to changed cells count.
  • result.artifacts: tuple of planned GenerateArtifact instances with their roles.

tabalyst.list_available_anomaly_profiles()

Section titled “tabalyst.list_available_anomaly_profiles()”

List available anomaly profiles, target datasets, and minimum row thresholds.

# List profiles for the Insurance example
profiles = tabalyst.list_available_anomaly_profiles(example="insurance")
for p in profiles["insurance"]:
print(p["id"], p.get("min_rows"))
# List profiles across all built-in examples
all_profiles = tabalyst.list_available_anomaly_profiles()

Returns a dictionary mapping package identifiers to lists of profile descriptors.

Validate that a Generate package directory or dataset.yaml complies with package specifications without planning outputs.

validation = tabalyst.validate_generate_package("path/to/package")
if not validation.valid:
print(validation.errors)