Python API reference
Everything below is importable from the top-level package (import misata)
unless a module is named. Signatures are those of Misata 0.9.8; each section
links to the guide that explains the behaviour in full.
| Call | Returns | What it does |
|---|
misata.from_ddl(ddl, *, infer_fks=True, default_rows=1000) | SchemaConfig | Parses CREATE TABLE statements: keys, NOT NULL, UNIQUE, composite keys, CHECK ranges, enums and column-to-column rules, self-references. Guide |
misata.load_yaml_schema(path, rows=1000, seed=42) | SchemaConfig | Loads a misata.yaml file. Guide |
misata.yaml_schema.load_schema_file(path, *, seed=None, rows=None) | SchemaConfig | Loads any schema file form the CLI accepts: misata.yaml, a SchemaConfig dump or the dict form. |
misata.save_yaml_schema(schema, path) | Path | Writes every declaration back to YAML; load_yaml_schema reads it back to an equal model. |
misata.from_dict_schema(schemas, row_count=None) | SchemaConfig | Converts a plain dict of tables and columns. Guide |
misata.schema_from_db(db_url, *, default_rows=1000, include_tables=None) | SchemaConfig | Introspects a live database, foreign keys included. Guide |
misata.from_django(models=None, *, app_labels=None, default_rows=1000, include_contrib=False) | SchemaConfig | Reads Django models after django.setup(). Guide |
misata.parse(story, rows=10000) | SchemaConfig | Turns a sentence into a schema without generating. Guide |
misata.preview(story, rows=10000) | DetectionReport | What a sentence was understood as: domain, scale, events, tables. |
misata.apply_preset(schema, name, *, scale=None, today=None) | SchemaConfig | A copy with the demo, test, load, ml or eval defaults filled in. Guide |
A SchemaConfig carries its seed as schema.seed; set it before generating
when the source did not declare one.
| Call | Returns | What it does |
|---|
misata.explain(schema) | Explanation | Planned rows (exact, curve plans included), approximate memory, which declaration writes which column, the invariants an attestation will check, and every conflict with its remedy. summary() prints it; to_dict() is the JSON form. The CLI is misata explain. |
| Call | Returns | What it does |
|---|
misata.generate(story, rows=10000, seed=None, ...) | dict[str, DataFrame] | One sentence to a set of related tables. |
misata.generate_from_schema(schema, ..., strict=True, preset=None) | dict[str, DataFrame] | Generates from a SchemaConfig. Contradictory declarations raise InfeasibleSchema before any row is generated; strict=False keeps the old behaviour. |
misata.generate_stream(story, rows=10000, seed=None) | iterator of (table, DataFrame) | Bounded-memory generation from a story, a dict schema, a SchemaConfig, a schema file or DDL. One-hop roll-ups reconcile while streaming. Guide |
misata.mimic(source, rows=None, seed=None, table_name="table") | dict[str, DataFrame] | A twin fitted to a CSV or DataFrame. Fitted to real rows, so not anonymous. Guide |
| Call | Returns | What it does |
|---|
misata.seed_database(config, db_url, *, create=False, truncate=False, batch_size=10000, append=False, ...) | SeedReport | Generates from a SchemaConfig and inserts parents first, in one transaction. truncate wipes target tables first; never pass it without the owner's consent. append keeps populated tables and fills only the empty ones. Guide |
SeedReport has total_rows, table_rows, created_tables,
truncated_tables and duration_seconds.
| Call | Returns | What it does |
|---|
misata.realism_report(tables, schema=None, *, skip=()) | RealismReport | Looks for the statistical tells of generated data, with no real data needed. score, passed, summary(), to_dict(). Guide |
misata.coherence_audit(tables, *, repair=False, seed=42, schema=None) | CoherenceReport | Reader-visible contradictions: a churn date on an active subscription, a payment before its customer existed. |
misata.fingerprint(tables) | dict[str, str] | A canonical hash per table and for the whole dataset ("__all__"), independent of file format and dtype. Put it in fixtures you commit. |
misata.validate_csv(path_or_df, schema=None, story=None, table_name=None) | CsvValidationReport | Profiles a CSV, optionally against a schema. Guide |
misata.fidelity_report(synthetic, real, target_column=None, ml_efficacy=True) | FidelityReport | How closely a synthetic table matches a real one, when you have the real one. |
| Call | Returns | What it does |
|---|
misata.attest(data_dir, schema, *, spec_path=None, write=True, script_name="verify.py") | Attestation | Re-checks every invariant the schema implies against the files on disk with DuckDB, pins each file by SHA-256, and writes attestation.intoto.json, attestation.dsse.json and verify.py. passed, invariants, failures, statement, summary(). Guide |
The predicate is specified in Certificate predicate v1.
| Call | Returns | What it does |
|---|
misata.solve(schema, runner, targets, *, tolerance="1%", max_iterations=25, max_seconds=None, damping=0.85) | SolveResult | Moves the outcome curves each target names as its lever until the pipeline's metrics hit their per-period targets. Guide |
misata.Target(metric, lever, values, direction="direct") | | A metric, the table.column curve that moves it, and its value per period. direction="inverse" for levers that lower their metric. |
misata.SQLRunner(queries, *, timeout=60.0, memory_limit=None) | | DuckDB SQL over the generated tables, one query per metric, in a sandbox. |
misata.DbtDuckDBRunner(project_dir, metrics, *, select=None, source_schema="main", seeds=False, ...) | | A dbt project built on a temporary DuckDB warehouse. |
misata.PythonRunner(fn, name=None) | | Any function of the tables that returns {metric: values by period}. A plain function passed as runner is wrapped in one. |
SolveResult has converged, reason, iterations, best, summary(),
write(dir) (the closest dataset, schema.solved.json, the solved YAML and
solve.json) and attest(dir), which adds each solved period of a SQL
pipeline as an invariant.
| Call | Returns | What it does |
|---|
misata.evalpack.build_evalpack(schema, output_dir, *, tables=None, rotations=1) | EvalPackResult | Questions with answers fixed by the declarations, a database per rotation, gold SQL verified on every one. all_verified, questions, dropped, summary(). Guide |
misata.evalpack.verify_questions(con, questions) | (shipped, dropped, certificate) | Keeps the questions whose gold SQL returns the expected answer on a connection, for packs built from an answer key rather than from declarations. Dropped questions carry their drop_reason. |
| Call | Returns | What it does |
|---|
misata.prepare_hub_release(directory, repo_id, *, license_id="cc-by-4.0", schema_path=None, allow_fitted=False) | HubRelease | Re-verifies every digest and invariant and assembles the upload. Raises misata.publish.PublishRefused when anything does not hold. write_card() writes DATASET_CARD.md. |
misata.publish_to_hub(release, *, private=False, commit_message=None) | str | Uploads the release to the Hugging Face Hub in one commit and returns its URL. Guide |
| Call | What it writes |
|---|
misata.to_parquet(tables, output_dir, compression="snappy") | one Parquet file per table |
misata.to_duckdb(tables, db_path=None, *, replace=True) | a DuckDB database; returns the connection |
misata.to_jsonl(tables, output_dir, schema=None) | one JSON Lines file per table, nested columns as objects |
misata.to_sql(tables, output_dir, dialect="ansi") | one .sql file per table with CREATE TABLE and INSERT |
misata.to_seed_sql(tables, output_path, *, dialect="postgresql", config=None, truncate=False) | one seed file, tables in dependency order |
misata.to_arrow(tables, output_dir) | one Arrow IPC file per table |
misata.to_polars(tables, schema=None) | Polars DataFrames, in memory |
For CSV, write each DataFrame with pandas (df.to_csv(path, index=False)),
or use misata generate --format csv. More in Export.
misata.MisataWarning is the category of every warning Misata emits.misata.ConformanceWarning marks the ones where a declaration will not
hold exactly as written. Both subclass UserWarning, so
warnings.simplefilter("error", misata.ConformanceWarning) makes them
fatal in CI.misata.feasibility.InfeasibleSchema is raised before generation when
declarations cannot all hold; the CLI exits 3 with the same conflicts.
When Misata refuses explains each warning and refusal.
