misata-mcp
Misata
Proof-backed synthetic data — realistic multi-table datasets with validation reports, from a sentence, YAML, or your own database.
Misata generates consistent, referentially-intact multi-table datasets from a plain-English description, a YAML schema file, or an existing database schema. Every normal generation run can also write an Oracle report: a shareable proof bundle for row counts, referential integrity, constraints, temporal consistency, locale/domain fit, privacy notes, fidelity scores, and reproducibility metadata.
No machine-learning model is required. No real data is needed.
Built for:
Database seeding — fill dev and staging environments with production-like data
Integration tests — relational fixtures with FK integrity across every table
Demos and prototypes — realistic numbers, names, and distributions, no PII
BI and dashboard development — data shaped like your real domain before launch
Install
pip install misataOptional extras:
pip install "misata[llm]" # multi-provider LLM schema generation
pip install "misata[documents]" # PDF output via weasyprint
pip install "misata[advanced]" # SDV/CTGAN statistical synthesis
pip install "misata[mcp]" # MCP server — expose Misata to Claude, Cursor, and other AI agentsRelated MCP server: MCP Data Visualization Server
Use Misata from Claude / Cursor / Windsurf (MCP)
Misata ships a built-in Model Context Protocol server. Once configured, any MCP-compatible AI assistant can generate realistic synthetic data for you from natural language — no Python required on your end.
1. Install:
pip install "misata[mcp]"2. Add to Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json):
{
"mcpServers": {
"misata": {
"command": "misata-mcp"
}
}
}Restart Claude Desktop. Then just ask:
"Generate a fintech dataset with 1 000 customers, payments, and a 2% fraud rate."
"Show me what tables Misata would produce for an HR system with 200 employees."
"I need SaaS data: MRR from $50k in January, doubled by December, with a Q3 slump."
Claude calls Misata, writes CSVs to disk, and returns the file paths plus a preview of each table. See the MCP guide for Cursor/Windsurf/Zed setup and all five available tools.
Quick start
misata generate \
--story "Brazilian fintech with R$ payments, CPF verification, and 3% fraud" \
--rows 1000 \
--output-dir ./demo_data
# Writes CSVs plus:
# ./demo_data/oracle_report.jsonimport misata
# One sentence → multi-table DataFrame dict
tables = misata.generate("A SaaS company with 5k users, monthly subscriptions, and 20% churn")
print(tables["users"].head())
print(tables["subscriptions"].head())# Or from the CLI
misata generate --story "A SaaS company with 5k users and 20% churn" --rows 5000Misata Oracle
The Oracle report is Misata's proof layer. It separates hard guarantees from advisory realism checks so generated data can be trusted in CI, demos, notebooks, and research comparisons.
Guaranteed checks:
referential integrity across configured relationships
requested row-count fulfillment
schema validation and configured constraints
deterministic reproducibility when a seed is set
Advisory checks:
quality score and plausibility warnings
privacy heuristics
schema-vs-output fidelity score
locale/domain fit for countries, cities, phone prefixes, and national IDs
data-card metadata
import misata
schema = misata.parse("Brazilian fintech with CPF verification", rows=1000)
tables = misata.generate_from_schema(schema)
oracle = misata.build_oracle_report(tables, schema, seed=schema.seed)
print(oracle["passed"])
print(oracle["advisory"]["locale_domain_fit"]["locale"])Six ways to generate data
1. Plain English — no config required
tables = misata.generate("A fintech startup with 10k customers, fraud rate 3%, and IBAN accounts")Misata reads the story, infers domain (fintech), scale (10 000 rows), and column semantics (fraud flag, IBAN format) — no schema authoring needed.
2. YAML schema-as-code — commit it to git
misata init # scaffolds misata.yaml in the current directory
misata generate # reads misata.yaml automatically# misata.yaml
name: my-app
seed: 42
tables:
users:
rows: 1000
columns:
user_id: { type: int, unique: true }
email: { type: text, text_type: email }
plan: { type: categorical, choices: [free, pro, enterprise] }
orders:
rows: 5000
columns:
order_id: { type: int, unique: true }
user_id: { type: foreign_key }
amount: { type: float, min: 5.0, max: 500.0 }
relationships:
- "users.user_id → orders.user_id"
constraints:
- name: amount_above_cost
table: orders
type: inequality
column_a: amount
operator: ">"
column_b: costschema = misata.load_yaml_schema("misata.yaml")
tables = misata.generate_from_schema(schema)3. Seed an existing database directly
from misata import schema_from_db, generate_from_schema, seed_database
# Introspect the live schema — no manual column definitions
schema = schema_from_db("postgresql://user:pass@localhost/myapp")
tables = generate_from_schema(schema)
# Seed it back — insert order respects FK dependencies automatically
report = seed_database(tables, "postgresql://user:pass@localhost/myapp_dev")
# SeedReport: seeded 6 tables, 47,300 rows in 1.2s# One-command workflow
misata init --db postgresql://user:pass@localhost/myapp # writes misata.yaml
misata generate --db-url postgresql://user:pass@localhost/myapp_dev --db-createSQLAlchemy models are supported too:
from misata import seed_from_sqlalchemy_models
from myapp.models import Base
report = seed_from_sqlalchemy_models(Base, db_url="sqlite:///test.db", row_count=500, create_tables=True)4. Python dict schema
schema = misata.from_dict_schema({
"customers": {
"id": {"type": "integer", "primary_key": True},
"email": {"type": "email"},
"plan": {"type": "string", "enum": ["free", "pro", "enterprise"]},
},
"orders": {
"id": {"type": "integer", "primary_key": True},
"customer_id": {"type": "integer", "foreign_key": {"table": "customers", "column": "id"}},
"amount": {"type": "float", "min": 1.0, "max": 999.0},
},
}, row_count=5_000)
tables = misata.generate_from_schema(schema)5. LLM-assisted generation — richer semantics, optional
from misata import LLMSchemaGenerator
gen = LLMSchemaGenerator(provider="groq") # free tier, fast
# gen = LLMSchemaGenerator(provider="anthropic") # Claude
# gen = LLMSchemaGenerator(provider="ollama", model="llama3") # fully local, no API key
schema = gen.generate_from_story(
"A fraud detection dataset — 2% positive rate, FICO scores, transaction velocity features"
)
tables = misata.generate_from_schema(schema)Requires pip install "misata[llm]" plus one of GROQ_API_KEY, OPENAI_API_KEY, ANTHROPIC_API_KEY, GOOGLE_API_KEY.
6. Incremental generation — grow a dataset without re-seeding
tables = misata.generate("A fintech company with 1000 customers", seed=1)
# Add 1 000 more rows — IDs auto-offset, FK integrity maintained across both batches
tables = misata.generate_more(tables, schema, n=1000, seed=2)
print(len(tables["customers"])) # 2000Localisation
Misata automatically detects the country context from your story and generates statistically accurate data for that locale — the right names, salary distributions, national ID formats, currencies, postcodes, and company naming conventions.
# Locale is detected automatically — no extra flag needed
tables = misata.generate("German SaaS company in Berlin with 2k enterprise customers")
# → names from de_DE Faker pool, salary ~ lognormal(μ=10.71, σ=0.5) ≈ €45k median,
# postcodes are 5-digit, company names end in GmbH/AG/UG
tables = misata.generate("Brazilian fintech with R$ payments and CPF verification, 50k users")
# → pt_BR names, salary median ~BRL 33.6k, national IDs match CPF format ###.###.###-##
tables = misata.generate("Indian startup in Bangalore with ₹ salary bands and Aadhaar KYC")
# → hi_IN names, salary median ~₹350k/yr, national IDs match Aadhaar 12-digit formatForce or override a locale explicitly:
schema = misata.parse("An ecommerce store with 10k orders")
tables = misata.generate_from_schema(schema) # defaults to en_US
# CLI
misata generate --story "Ecommerce store" --locale ja_JP15 built-in locales
Locale | Country | Currency | Salary median | National ID |
| United States | USD / $ | $62 000 | SSN |
| United Kingdom | GBP / £ | £34 000 | NIN |
| Germany | EUR / € | €45 000 | Steuer-IdNr |
| France | EUR / € | €38 000 | NIR |
| Brazil | BRL / R$ | R$33 600 | CPF |
| Spain | EUR / € | €27 000 | NIE |
| India | INR / ₹ | ₹350 000 | Aadhaar |
| Japan | JPY / ¥ | ¥4 400 000 | My Number |
| China | CNY / ¥ | ¥90 000 | Resident ID |
| Saudi Arabia | SAR | SAR 96 000 | National ID |
| South Korea | KRW / ₩ | ₩42 000 000 | RRN |
| Netherlands | EUR / € | €42 000 | BSN |
| Italy | EUR / € | €29 000 | Codice Fiscale |
| Poland | PLN | PLN 72 000 | PESEL |
| Turkey | TRY | TRY 720 000 | TC Kimlik |
Each pack carries real salary distributions (median and lognormal priors), age distributions, top-ranked cities, phone-number prefixes, postcode patterns, company suffixes, and VAT rates — sourced from OECD, World Bank, ILO, and national statistics offices (2023–24 data).
# Inspect a locale pack directly
pack = misata.get_locale_pack("de_DE")
print(pack.salary_median) # 45000
print(pack.currency_symbol) # €
print(pack.top_cities[:3]) # ['Berlin', 'Hamburg', 'Munich']
print(pack.company_suffixes) # ['GmbH', 'AG', 'UG', 'KG', 'e.K.']
# Auto-detect from a story
locale = misata.detect_locale("South Korean company in Seoul with KRW salaries")
# → "ko_KR"Constraints
Enforce business rules that survive every row of generation:
from misata.constraints import (
InequalityConstraint, # price > cost on every row
ColumnRangeConstraint, # min_price <= price <= max_price
RatioConstraint, # 70% free / 30% pro
UniqueConstraint, # no duplicate (user_id, date) pairs
SumConstraint, # total_hours per employee per day <= 8
NotNullConstraint, # no nulls in required columns
)
c = InequalityConstraint("price", ">", "cost")
df = c.apply(df)Constraints can also be declared in misata.yaml — they run at generation time, not as a post-processing step.
Export
misata.to_parquet(tables, "data/")
misata.to_duckdb(tables, "data/dataset.duckdb")
misata.to_jsonl(tables, "data/")Document generation
Render one document per row from any table — useful for demo datasets that need to look real end-to-end:
# Built-in templates: invoice, patient_report, transaction_receipt, user_profile
paths = misata.generate_documents(
tables, "invoice", table="orders", output_dir="/tmp/invoices", format="html"
)
# format="pdf" requires: pip install "misata[documents]"
# Custom Jinja2 template
tmpl = "<h1>Order #{{ order_id }}</h1><p>Amount: ${{ amount }}</p>"
paths = misata.generate_documents(tables, tmpl, table="orders", output_dir="/tmp/custom")Quality and privacy analysis
bundle = misata.analyze_generation(tables, schema)
print(bundle.data_card.summary()) # row counts, null rates, type distribution
print(bundle.fidelity_report.score) # 0–1 statistical fidelity score vs. schema intent
print(bundle.privacy_report.pii_risk) # column-level PII exposure analysisSupported domains
18 built-in domain schemas — each generates a fully relational, multi-table dataset with realistic distributions, FK integrity, and domain-appropriate column semantics.
Domain | Trigger keywords | Tables generated |
SaaS | saas, subscription, mrr, churn | users, subscriptions, invoices |
Ecommerce | ecommerce, orders, store, retail | customers, products, orders, order_items |
Fintech | fintech, payments, banking, fraud | customers, accounts, transactions |
Healthcare | healthcare, patients, doctors, clinic | doctors, patients, appointments |
Marketplace | marketplace, sellers, buyers, listings | sellers, buyers, listings, orders |
Logistics | logistics, shipping, drivers, routes | drivers, vehicles, routes, shipments |
HR | hr, employees, payroll, workforce | departments, employees, payroll |
Social | social media, instagram, feed, followers | users, posts, follows, reactions |
Real Estate | real estate, housing, mortgage | agents, properties, transactions |
Pharma | pharma, clinical, trials | researchers, projects, trials, timesheets |
Food Delivery | food delivery, restaurant, takeout | restaurants, customers, couriers, orders, order_items |
EdTech | edtech, courses, students, enrollments | instructors, courses, students, enrollments, quiz_attempts |
Gaming | gaming, players, leaderboard, esports | players, matches, sessions, achievements |
CRM | crm, salesforce, deals, pipeline | companies, contacts, deals, activities |
Crypto / Web3 | crypto, blockchain, ethereum, defi | wallets, tokens, transactions, token_prices |
Insurance | insurance, policy, claims, premium | customers, policies, claims, payments |
Travel | travel, hotel, flights, bookings | users, hotels, flights, bookings, reviews |
Streaming | streaming, netflix, subscribers, watch history | subscribers, content, watch_history, ratings |
No keyword match → generic single-table schema with smart column inference.
How it works
story / YAML / dict / DB introspection / MCP tool call
↓
StoryParser · locale detection · load_yaml_schema · schema_from_db
↓
DetectionReport (domain, confidence, near_misses, table_preview, warnings)
↓
SchemaConfig ← validate_schema() catches issues before any rows are generated
↓
DataSimulator
├─ topological sort (FK dependency order)
├─ domain priors → locale priors (salary, age, monetary)
├─ constraint engine (inequality, range, ratio, sum, unique)
├─ outcome curves (monthly targets from narrative control points)
├─ Iman-Conover correlation engine (Cholesky, preserves marginals)
└─ RealisticTextGenerator (Faker locale + Kaggle vocabulary assets)
↓
{table_name: DataFrame}
↓
seed_database · to_parquet · to_duckdb · generate_documents · MCP CSV outputDomain priors — monetary columns get log-normal distributions. Categoricals use Zipf sampling. Blood types, country distributions, and salary bands reflect real-world statistics.
Locale priors — salary and age distributions are overridden with country-specific lognormal/normal parameters sourced from national statistics. "Brazilian fintech" in your story means salaries are sampled from the BRL distribution, not the USD one.
Outcome curves — natural-language narrative is parsed into exact monthly control points. Named events, quarters, and multipliers all work:
# All of these produce precise, shaped outcome curves:
misata.generate("SaaS mrr from $50k in Jan to $200k in Dec, with a Q3 slump")
misata.generate("Ecommerce orders, Black Friday spike, Christmas peak")
misata.generate("SaaS startup — MRR 10x growth over the year")
misata.generate("Fintech payments — strong Q4, dip in Q1")Realism rules — cost is always less than price. delivered_at is always after shipped_at. hire_date is after date_of_birth + 18 years and never in the future. tenure_years is derived on the same row from hire_date. Email addresses derive from first and last name columns.
What makes Misata different
Faker | Synth | syda | SDV | Misata | |
No config, one line to multi-table data | — | — | — | — | Yes |
Story auto-detects locale + country stats | — | — | — | — | Yes |
18 built-in domain schemas (SaaS → streaming) | — | — | — | — | Yes |
Narrative curves (Q4 push, Black Friday, 10×) | — | — | — | — | Yes |
Mimic mode — clone distributions from a CSV | — | — | — | Yes | Yes |
Pairwise correlation enforcement (Iman-Conover) | — | — | — | Yes | Yes |
Geospatial columns (lat, lng, postal_code) | — | — | — | — | Yes |
Anomaly injection (per-column outlier rate) | — | — | — | — | Yes |
MCP server — usable from Claude / Cursor | — | — | — | — | Yes |
YAML schema committed to git | — | Yes | Yes | — | Yes |
JSON Schema validation + editor auto-complete | — | — | — | — | Yes |
DB introspection → generate → re-seed | — | Yes | — | Limited | Yes |
Direct DB seeding (Postgres / MySQL / SQLite) | — | — | — | — | Yes |
SQLAlchemy model seeding | — | — | — | — | Yes |
Referential integrity across all FK tables | — | Yes | Yes | Yes | Yes |
Inequality / range constraints ( | — | Limited | — | Yes | Yes |
Aggregate target curves (monthly MRR shape) | — | — | — | — | Yes |
Domain-realistic distributions | — | — | — | Limited | Yes |
Multi-provider LLM (Groq / OpenAI / Claude / Gemini / Ollama) | — | — | Yes | — | Yes |
Fully offline, no LLM required | Yes | Yes | — | Yes | Yes |
Document generation (HTML / PDF per row) | — | — | — | — | Yes |
Quality + privacy reports | — | — | — | Limited | Yes |
Pure Python, no external services | Yes | — | — | Yes | Yes |
Faker generates individual fake values — not relational, no schema, no statistical accuracy.
Synth excels at schema-as-code git workflows; limited distribution control.
syda uses an LLM for every row — semantically rich but expensive, slow, and requires an API key.
SDV learns from real data — a different problem (you need real data first).
Misata generates from intent, offline by default, seeds databases directly, and now brings country-accurate statistics to every column automatically.
Performance
Measured on Apple M-series (single core, no GPU):
Workload | Rows | Time | Throughput |
Single table, lognormal | 1 000 000 | 0.06 s | ~16M rows/s |
Star schema (5 tables, 4 FKs) | 1 055 030 | 1.54 s | ~687k rows/s |
Contributing
git clone https://github.com/rasinmuhammed/misata
cd misata
pip install -e ".[dev]"
pytest tests/Issues and PRs welcome — github.com/rasinmuhammed/misata/issues
Available Tools
15 toolsattest_datasetAttest a dataset against its schemaAIdempotent
Prove a written dataset holds what its schema declared, in a standard format.
Recomputes every invariant the schema implies (outcome-curve totals, rate
anchors, group shares, ledger identities, foreign keys, unique columns)
with DuckDB against the files, and pins each file by SHA-256. Writes
attestation.intoto.json (an in-toto v1 Statement that cosign and
GitHub's actions/attest accept), attestation.dsse.json and
verify.py into dataset_dir. Anyone can rerun python verify.py
with only duckdb installed.
Use it after generate_from_schema with the same schema and seed, and
report result to the user: PASSED means every declared property
holds in the files on disk.
Args:
dataset_dir: Folder with one <table>.csv or <table>.parquet
per table (the output_dir of generate_from_schema).
schema: The same schema dict passed to generate_from_schema.
seed: The seed used to generate, recorded in the Statement.
max_invariants: How many invariants to include in the response.
Returns:
{"ok", "result", "invariants_held", "invariants_total", "failures", "subjects", "files", "invariants"}.
Inputs: schema (required), dataset_dir (required), seed, max_invariants. Returns: result
audit_datasetAudit a dataset for reader-visible contradictionsARead-onlyIdempotent
Score a folder of CSVs for the contradictions a human reader would catch.
This is Misata's coherence audit run on data that already exists — data an agent generated in an earlier step, data a user built by hand, or the output of some other tool. It checks, among other things:
timestamps that run backwards (shipped before ordered, resolved before opened),
derived columns that do not reconcile with their inputs (
total!=quantity * unit_price),geographic fields that disagree (city / state / postcode / country),
near-constant columns (98% one value — a distribution tell),
filler text and out-of-scale numerics.
A score of 100 is clean. Below ~85 usually means the schema is missing
realism structure, not that individual rows need patching: add
__correlations__, profiles, time_series, a __state_machine__,
or an __outcome_curves__ declaration and regenerate.
Args:
dataset_dir: Directory containing one CSV per table (e.g. the
output_dir returned by generate_from_schema).
top_findings: Max findings to include in the response (default 20).
Returns:
{"score": 0-100, "clean": bool, "counts": {...}, "findings": [...]}.
Inputs: dataset_dir (required), top_findings. Returns: result
check_realismCheck a dataset for the tells of synthetic dataARead-onlyIdempotent
Find the statistical shapes that make a dataset look generated.
Where audit_dataset finds contradictions, this finds shapes real data
almost never has, with no real data to compare against: money spread
evenly from min to max, every customer with about the same number of
orders, perfectly balanced categories, flat weekday or hour-of-day
profiles, timestamps piled up at midnight, placeholder values
(@example.com, John Doe), emails unrelated to names, small name pools,
templated or repetitive free text, prose with a tiny vocabulary, review
text whose tone ignores its rating, descriptions unrelated to their
titles, tables with no nulls at all. Works on data from any generator,
including a script you wrote.
Fix a finding in the schema, not the rows: lognormal for money, a curve or
weights for time, sampling on foreign keys, null_rate or
__missingness__ for optional fields. Pass skip for tells that are
intended (a randomised A/B split is balanced on purpose).
Args:
dataset_dir: Directory with one CSV per table (the output_dir from
generate_from_schema).
skip: Check names to leave out, e.g. ["too_clean"].
Returns:
{"score": 0-1, "passed": bool, "counts": {...}, "tells": [...]},
each tell with its check, table, column, status and evidence.
Inputs: dataset_dir (required), skip. Returns: result
create_sandboxCreate an instant sandbox databaseAIdempotent
Create and seed a real, isolated SQLite sandbox database for testing.
Perfect for AI coding agents: spins up a queryable database with realistic, referentially intact tables (0 orphan foreign keys) so you can test SQL queries, analytics logic, or application code immediately without touching a real database.
Args: domain: Pre-built domain template ('saas', 'ecommerce', 'fintech', 'healthcare'). story: Plain-English description (e.g. 'A restaurant with tables, bookings, and guests'). schema: Explicit schema dict if you want exact column control. rows: Base row count (default: 100). Transactions scale proportionally. seed: Random seed for 100% reproducible results (default: 42). db_path: Target SQLite file path (default: '.misata/sandbox.db').
Returns: Dictionary with db_url, db_path, table summaries, DDL, and sample verification queries.
Inputs: rows, seed, story, domain, +2 more. Returns: result
explain_schemaExplain what a schema will generateARead-onlyIdempotent
Show what generate_from_schema would do with a schema, without generating.
Call it before generate_from_schema on a schema you designed: it is
cheap, and it catches the mistakes that would otherwise surface after a
long run. Returns each table's planned row count and approximate memory,
the declarations and the columns each one writes, any column two
declarations both write, every outcome curve's period plan and warnings,
and the invariants attest_dataset will check on the output. When
will_generate is false, conflicts names each contradiction with
the arithmetic and a remedy; fix those in the schema and call again.
Args: schema: The schema dict you would pass to generate_from_schema. seed: The seed you would generate with. max_invariants: How many invariants to include in the response.
Returns:
{"ok", "will_generate", "total_rows", "estimated_bytes", "tables", "relationships", "declarations", "writers", "overlaps", "conflicts", "conformance", "invariants", "invariants_total"}.
Inputs: schema (required), seed, max_invariants. Returns: result
generate_datasetGenerate a dataset from a sentenceA
Generate a synthetic dataset from a story and write it to disk as CSV files.
Returns the output directory, file paths, row counts per table, and a small sample of rows for each table so the agent can show the user what was produced without loading every row into context.
Args: story: Plain-English description of the dataset. rows: Default row count for the primary table. seed: Optional random seed (same seed → byte-identical output). output_dir: Where to write CSVs. Defaults to a fresh temp dir. sample_rows: Number of rows from each table to include in the response (max 50).
Inputs: story (required), rows, seed, output_dir, +1 more. Returns: result
generate_from_schemaGenerate a dataset from a schemaAIdempotent
Generate a dataset from a schema you design. This is the primary Misata tool.
DIVISION OF LABOUR You (the agent) design what the data should look like — the tables, columns, business rules, and declared targets. Misata handles the hard guarantees: every FK resolves, every rollup reconciles to the cent, every declared outcome curve is hit exactly, every seed produces byte-identical output. The response includes a per-relationship integrity proof.
SCHEMA FORMAT {table_name: {column_name: spec, ...}, ...}
TABLE-LEVEL KEYS (inside a table dict) "rows": 5000 Per-table row count; overrides the global rows arg. Always set this — one global count rarely fits all tables. "constraints" List of row-level business rules (see CONSTRAINTS below). "correlations" List of pairwise Pearson targets (see CORRELATIONS below). "state_machine" Markov terminal-state assignment (see STATE MACHINE below).
COLUMN TYPES integer, float, decimal Numeric. string Short categorical or free text. text Long free text (descriptions, notes). email, phone, url, uuid Semantic strings; always valid format. date, datetime Temporal; realistic granularity applied automatically. boolean True/False with declared probability. object (json) Nested object: {"type": "object", "fields": {"email": "email", "age": {"type": "integer", "min": 18}, "tags": {"type": "list", "items": "string"}}}. Optional: "optional": [...], "optional_rate". list (array) {"type": "list", "items": , "min_items": 0, "max_items": 5, "unique_items": true, "sorted": true}. Values are JSON text.
COLUMN SPEC KEYS (inside a column dict) primary_key: true Auto-incremented PK; column excluded from CSV output. foreign_key: {table, column} Child FK; referential integrity guaranteed + verified. min / max Numeric or date bounds. decimals: 2 Decimal places for float output. unique: true All values in the column are distinct. nullable: true Allow nulls (default true). enum: [...] Categorical choices. Add probabilities: [...] for weights; omit for realistic Zipf-shaped rank frequencies. probabilities: [...] Weights for enum choices; must sum to 1.0.
DISTRIBUTIONS (float / integer columns) distribution: normal Also: lognormal, uniform, exponential, gamma (shape, scale), beta (a, b), poisson (lambda), binomial (n, p), power_law (alpha). mean / std Normal params. Can be a scalar OR a per-row parent-entity lookup: mean: {formula: "@patients.hba1c_baseline"} The FK is resolved per-row so each child row's distribution is anchored to its parent's value. Use this for longitudinal data where within-entity variation should be modelled separately from between-entity variation. mu / sigma Lognormal params (mu and sigma are of log(x)). min / max Hard clamps applied after sampling. Use lognormal for money, file sizes, session durations — anything right-skewed and strictly positive. Use normal for measurements.
DERIVED COLUMNS formula: "quantity * unit_price" Row-level arithmetic; pandas eval syntax. formula: "hours * @employees.rate" Cross-table via FK: @parent_table.column. rollup: {from_table, fk, agg, column} Parent column that EXACTLY reconciles with child rows under JOIN. agg: sum/count/mean/ max/min. Add where: {col: val} to filter. RULE: use rollup (not formula) for any parent column that summarises child rows. Rollups are closed-form exact; formulas cannot cross the FK boundary correctly.
CODE-STYLE STRINGS pattern: "SKU-\d{5}" Single pattern expanded per row. pattern: ["A/\d{5}", "\d{6}"] List: one shape drawn per row. pattern_weights: [0.7, 0.3] Weights for pattern list (optional). Supported tokens: \d (digit), [A-Z] (uppercase letter), [a-z] (lowercase), literal chars, {n} repeat count. Example: "[A-Z]{2}-\d{4}" → "AB-3721".
TEXT SEMANTICS text_type: person_name Always beats column-name inference. Options: person_name, email, company, city, country, postal_code, phone, url, description, username, product_name, review_text, address, job_title. Dates: appointment times snap to 15-min business-hours grids; signups follow waking-hour rhythms; machine events keep sub-second precision. Names, genders, and emails are generated jointly and always agree.
STRATIFIED DISTRIBUTIONS (profiles) Use when different subgroups need different distributions for the same column. profiles: [ {when: "arm == 'placebo'", distribution: normal, mean: -0.35, std: 0.50}, {when: "arm == 'high_dose'", distribution: normal, mean: -1.25, std: 0.55}, ] Rows that match no profile get the column's top-level distribution. The when expression is a pandas eval string; reference any already-generated column in the same table. Always list profiles after the columns they reference.
INFORMATIVE MISSINGNESS (MAR) null_when: "dropout == False" Null this column when expression is true. missing_if: Missing-At-Random tied to a predictor column. predictor: hba1c_baseline relationship: higher_increases_probability # or lower_increases_probability base_rate: 0.05 # null probability at predictor median max_rate: 0.40 # null probability at predictor extreme Use null_when for status-conditional nulls (dropout_visit is null when not dropped out). Use missing_if when missingness is correlated with an observed variable.
EXACT INCIDENCE CONTROL exact_incidence: Hit the declared count exactly (not approximately). mode: exact rate: 0.22 # exactly floor(n * 0.22) rows become True group_by: arm # optional: apply per group rates: {placebo: 0.15, high_dose: 0.55} # per-group exact rates Use exact_incidence instead of probability on boolean columns when the user states a precise rate that must hold in the data, not just on average.
WITHIN-ENTITY TIME SERIES (longitudinal autocorrelation) time_series: Re-writes a column to have AR1 autocorrelation entity_id: patient_id within each entity group. order_by: visit_number model: AR1 # AR1 | linear_trend | random_walk | mean_reversion phi: 0.72 # autocorrelation coefficient (AR1 only) noise_std: 0.30 anchor_column: hba1c_baseline # starting value (column in the same table) trend: slope_mean: -0.08 # mean drift per step slope_std: 0.02 # per-entity slope variability Required for any longitudinal dataset (clinical visits, IoT sensors, user sessions). Without it every row is independent and the data fails any time-series test.
CONSTRAINTS (table-level constraints list) {"type": "inequality", "column_a": "visit_date", "operator": ">=", "column_b": "enroll_date", "action": "cap"} Enforces column_a OP column_b. action: "cap" (snap column_a to column_b) or "drop" (remove violating rows). Works on dates and numerics. {"type": "col_range", "low_column": "min_price", "column": "price", "high_column": "max_price", "action": "cap"} Keeps low_column <= column <= high_column. {"type": "max_per_group", "group_by": "user_id", "max_count": 3} Limits rows per group value. {"type": "unique_combination", "columns": ["user_id", "product_id"]} No duplicate (col_a, col_b) pairs. Use constraints for any business rule that must hold on every row: visit_date >= enrollment_date, price > cost, resolution_day > onset_day.
CORRELATIONS (table-level correlations list) [{"col_a": "bmi", "col_b": "systolic_bp", "r": 0.41}] Enforced via Iman-Conover (rank reordering): preserves each column's marginal distribution while hitting the declared Pearson r exactly. Declare correlations for any pair of measurements that co-vary in the real domain (bmi/bp, income/spending, tenure/salary). Also supports full matrix syntax: correlations: matrix: columns: [hba1c, glucose, bmi] values: hba1c: [1.00, 0.65, 0.28] glucose: [0.65, 1.00, 0.22] bmi: [0.28, 0.22, 1.00]
ICC CLUSTER EFFECTS (parent table cluster_effect) cluster_effect: affects_table: visits affects_columns: hba1c: icc: 0.18 # intraclass correlation coefficient sd_total: 1.5 # total standard deviation; sd_between = sqrt(icc)*sd_total systolic_bp: sd_between: 8.0 # supply sd_between directly if preferred Applies per-parent-entity random intercepts to the named child columns. Required for multi-site or multi-centre designs — without it all sites look identical and any ICC statistical test will detect the synthetic origin. icc: 0.10-0.30 is typical for clinical measurements across sites.
STATE MACHINE (table-level state_machine) state_machine: state_column: patient_status initial_state: enrolled transitions: enrolled: {on_treatment: 0.97, screen_failure: 0.03} on_treatment: {completed: 0.77, dropout: 0.23} Assigns one terminal state to every row by following the Markov chain. States with no outgoing transitions are terminal. Use for any process with defined states: clinical trial statuses, customer lifecycle, order fulfilment stages, support ticket resolution.
SCHEMA-LEVEL DIRECTIVES (top-level keys, siblings of the tables)
outcome_curves Declare aggregate targets the engine hits EXACTLY. [{"table": "orders", "column": "amount", "time_column": "order_date", "time_unit": "month", "value_mode": "absolute", "start_date": "2024-01-01", "avg_transaction_value": 120.0, "curve_points": [ {"month": 1, "target_value": 50000.0}, {"month": 6, "target_value": 110000.0}, {"month": 12, "target_value": 200000.0} ]}] ALWAYS use this when the user states what a number should sum to per period: "revenue grows from $50k to $200k", "Q4 spike", "10x growth". avg_transaction_value drives row count per period; set it to roughly the median row value for that column.
rate_curves Per-period rate targets for boolean/categorical columns. [{"table": "transactions", "column": "is_fraud", "time_column": "transaction_date", "rate_points": [ {"period": "2024-01", "rate": 0.02}, {"period": "2024-Q4", "rate": 0.05} ]}] Use when fraud rate, churn rate, or conversion rate changes over time.
group_shares Exact shares of a measure across a categorical column. [{"table": "orders", "measure": "amount", "group_column": "plan", "shares": {"Starter": 0.2, "Pro": 0.5, "Enterprise": 0.3}}] The measure sums to those proportions per group, exactly. Paired with an outcome_curves on the same table+measure, the split holds inside every declared period. Use for any "A is 40% of revenue, B is 35%..." statement.
waterfalls Movements that reconcile to declared running balances. [{"table": "mrr_movements", "starting_value": 100000, "points": [{"period": "2026-01", "ending_value": 106000}, ...], "inflow_shares": {"new": 0.7, "expansion": 0.3}, "outflow_shares": {"churn": 1.0}}] Use for MRR bridges, cash-flow statements, any "opening + inflows - outflows = closing" ledger that has to tie out.
stock_flows Per-unit inventory identity: closing = opening + received
shipped, enforced for every SKU across every period. Use for warehouse / inventory data where stock levels must be internally consistent. Add "opening": {"flour": 120, ...} to fix each SKU's first opening level, e.g. to continue from a previous run's closing stock.
no_overlap An entity is in one place at a time: its [start, end) intervals never overlap. [{"table": "visits", "key": "resident_id", "start": "arrived_at", "end": "left_at"}]
capacity A resource never holds more concurrent intervals than its capacity (a constant "capacity", or "capacity_column" on its table). [{"table": "visits", "resource": "place_id", "start": "arrived_at", "end": "left_at", "capacity_column": "seats"}] A relationship's "parent_end" keeps a child inside its parent's span: {"parent": "visits.visit_id", "child": "orders.visit_id", "parent_time": "arrived_at", "parent_end": "left_at", "child_time": "ordered_at"}
lifecycles A state machine with legal transitions (stricter than a table-level state_machine: illegal jumps are impossible, not just unlikely). [{"name": "order_flow", "table": "orders", "state_column": "status", "start_column": "placed_at", "initial": "placed", "states": [{"name": "placed"}, {"name": "paid"}, {"name": "shipped"}, {"name": "delivered"}, {"name": "refunded", "terminal": true}], "transitions": [["placed","paid"],["paid","shipped"], ["shipped","delivered"],["delivered","refunded"]]}]
missingness Why a value is missing, conditionally (schema-level MNAR). [{"table": "contacts", "column": "notes", "rate": 0.75, "else_rate": 0.05, "when_column": "is_active", "when_op": "==", "when_value": false}] The null rate is exact per branch. Use when missingness itself carries signal a cleaning step should be tested against.
processes How each case moves through steps over time, written out as an event-log table (one row per event: case key, step, activity, timestamp). Use for support tickets, claims, onboarding funnels, order fulfilment, anything where the user wants an event log, a process-mining dataset, rework loops or realistic step durations. [{"name": "ticket_flow", "cases_table": "tickets", "case_key": "ticket_id", "start_column": "opened_at", "initial": "opened", "transitions": {"opened": {"triaged": 1.0}, "triaged": {"resolved": 0.85, "escalated": 0.15}, "escalated": {"resolved": 1.0}, "resolved": {"closed": 0.9, "reopened": 0.1}, "reopened": {"triaged": 1.0}}, "dwell": {"opened": {"distribution": "lognormal", "mu": 0, "sigma": 0.8, "unit": "hours"}}, "final_state_column": "status"}] A state with no transitions row is terminal. Each row sums to 1. The event table is named "_events". Structure is exact and audited; path shares and durations are drawn from the declaration.
DIRTY DATA ON PURPOSE (exact counts, so a test has a known number to find) duplicates [{"table": "contacts", "count": 60}] typos [{"table": "contacts", "column": "city", "count": 120}] outliers [{"table": "orders", "column": "amount", "count": 40}] Each injects exactly that many defects, leaving primary/unique/foreign keys intact. Use when the user is building or testing a data-quality or cleaning pipeline.
preset Use-case defaults: "demo" (dates end today, clean), "test" (<=200 rows, fixed seed), "load" (x10 rows), "ml" (declared nulls/outliers/typos/duplicates, keys protected), "eval" (current dates, modest dirt). Declarations always win.
domain Domain hint for post-generation validation.
"domain": "clinical_trial" # or "clinical", "financial", "fintech"
When set, generate_from_schema runs domain validation automatically and
returns it as domain_validation in the response — no second call
needed. Built-in ranges: HbA1c 4-14 %, BMI 10-80, systolic BP 60-260,
age 0-130, glucose 2-40, cholesterol 1-20, hemoglobin 3-25 for clinical;
price >= 0, discount 0-1, rate -1 to 100 for financial.
There are ~24 schema-level declarations in total. The ones above cover the common cases; for the rest (retention cohorts, DAG edges, closure tables, graph motifs, time grids, bitemporal history) fetch https://misata.studio/docs/reference/declarations.md and check the exact key before inventing one.
DESIGN RULES — follow these to get the best result in one pass
Always set rows per table. A fintech schema with customers=2000, accounts=4000, transactions=50000 is far better than 1000 everywhere.
Every child table needs a FK column pointing to its parent PK. Without it orphan rows are generated and the integrity proof will fail.
Use lognormal for money, file sizes, response times (right-skewed, strictly positive). Use normal for measurements (height, score, temp).
Declare correlations for any pair that co-varies in the real domain. Generated data with an identity correlation matrix is the clearest synthetic-data tell there is.
Use exact_incidence instead of probability when the user states a precise rate. "3% fraud" with probability: 0.03 gives ~3% on average; exact_incidence gives exactly 3%.
Use rollup (not formula) for any parent column that must reconcile with child rows. customers.total_spent generated independently of orders will never match; a rollup makes it exact.
Use outcome_curves any time the user mentions a revenue shape, a growth trajectory, a seasonal pattern, or a specific period total. It is the single feature most likely to be forgotten and most visible when absent.
Use profiles when two groups need different distributions. A clinical trial where all arms share one HbA1c distribution is statistically wrong and the difference will be caught by any summary table.
For longitudinal data (visits, sessions, sensor readings), add time_series to the key measurement columns. Independent rows fail every autocorrelation test and are visually obvious when plotted.
Add state_machine to any entity that moves through a process. An order table with no status progression is not realistic order data. When the user wants the steps themselves (an event log, durations, loops), declare processes instead.
Typos are errors. An unknown distribution name or a misspelled parameter (lamda, mena) is rejected with a "did you mean" suggestion. Read the error and fix the key rather than dropping the parameter.
After generating, call check_realism on the output_dir and fix what it flags: uniform money, every customer with the same number of orders, flat hour or weekday profiles, emails unrelated to names, no nulls.
Args: schema: Dict of table defs plus optional schema-level directives. rows: Default row count for tables without rows. seed: Random seed (same seed → byte-identical output on any machine). output_dir: Where to write CSVs. Omit to use a fresh temp dir. sample_rows: Rows per table to include in the JSON response (max 50).
Inputs: schema (required), rows, seed, output_dir, +1 more. Returns: result
inspect_schemaInspect the schema behind a storyARead-only
Return the full schema (tables, columns, relationships) for a story without generating data.
Heavier than preview_story — includes every column with its type and
distribution params. Use when the user wants to see the structure they'll
get, or to author a misata.yaml file from a natural-language seed.
Args: story: Plain-English description of the dataset. rows: Default row count for the primary table.
Inputs: story (required), rows. Returns: result
list_domainsList built-in domainsARead-onlyIdempotent
List the 18 built-in business domains Misata can generate from natural language.
Each domain has trigger keywords and a sample story you can pass to
preview_story or generate_dataset. Use this when the user asks
"what kinds of data can you generate?" or to suggest a story format.
Inputs: no named parameters. Returns: result
preview_storyPreview how a story is interpretedARead-only
Inspect what Misata would generate from a story — without generating any rows.
Returns the detected domain, confidence, near-misses, locale, scale, and a preview of the tables that would be produced. Use this to confirm interpretation before committing to a (potentially large) generation.
Args: story: Plain-English description of the dataset. rows: Default row count for the primary table (affects preview only).
Inputs: story (required), rows. Returns: result
query_sandboxQuery the sandbox databaseARead-onlyIdempotent
Execute a read-only SQL query against the sandbox database.
Allows AI coding agents to verify SQL queries, test aggregations, or inspect data in the sandbox directly without opening external terminals.
Args: query: SQL SELECT query to execute. db_path: Optional path to the database (defaults to '.misata/sandbox.db'). limit: Max rows to return (default: 100).
Returns: Dict with columns, rows (as list of dicts), row_count, and execution status.
Inputs: query (required), limit, db_path. Returns: result
seed_databaseSeed a real databaseADestructive
Fill a live Postgres or SQLite database with realistic, connected data, read from the database's own schema.
Reads the tables, columns, and foreign keys directly from the target database, generates data that respects them, inserts parents before children, then queries the database back to confirm every foreign key resolves. No schema file and no ORM are needed: a connection string is enough.
SAFETY — this is the only Misata tool that writes to a user's database:
It plans by default. With
apply=False(the default) nothing is written; you get the table list, insert order, existing row counts, and what would be inserted. Show that plan to the user.Only call again with
apply=Trueafter the user has seen the plan and agreed. Never passapply=Trueon a first call.If any target table already has rows, the write is refused unless the user chooses
truncate=True(wipe and reseed) orappend=True(keep existing rows, seed only empty tables, and draw foreign keys from the rows already there). Never guess between these.truncate=TrueDESTROYS existing data. Only use it on a throwaway development database and only when the user explicitly asks.
Args:
db_url: Connection string, e.g. postgresql://localhost/myapp_dev
or sqlite:///dev.db.
rows: Base row count; reference and transaction tables scale from it.
apply: False (default) plans only. True performs the write.
truncate: Wipe target tables (children first) before seeding.
append: Keep populated tables and seed only the empty ones.
tables: Optional allow-list of table names to seed.
skip_tables: Tables to leave untouched (migrations, auth, etc.).
seed: Random seed; the same seed reproduces the same data.
Returns:
A plan (applied: false) or a result with per-table row counts and
a per-relationship integrity proof (integrity.verified).
Inputs: db_url (required), rows, seed, apply, +4 more. Returns: result
solve_outcomeSolve outcome curves to hit a pipeline's targetsARead-onlyIdempotent
Find outcome-curve values that make SQL metrics over the data hit targets.
Use it when the number that matters is computed from the generated
tables rather than declared on them: net revenue after refunds, revenue
after a fee, a ratio of two tables. Each query runs in DuckDB over the
generated tables and returns two columns, the period and the value, one
row per period. Each target names a metric, the table.column outcome
curve that moves it (the lever, which must have exact per-period
values), and the value per period. Set direction: "inverse" when a
larger lever lowers the metric, as refunds lower net revenue.
Nothing is written. On success, replace each lever curve's
curve_points in your schema with levers[lever], then generate as
usual; attest_dataset will confirm the curves hold.
Args:
schema: The schema dict, with an outcome curve per lever.
queries: Metric name to DuckDB query, e.g. {"net": "SELECT date_trunc('month', ordered_at), SUM(amount) * 0.97 FROM orders GROUP BY 1"}.
targets: [{"metric", "lever", "values": {"2025-01": 70000}, "direction"?}].
tolerance: Relative tolerance per period, e.g. "0.5%".
max_iterations: Generate-and-query rounds allowed, at most 40.
seed: Seed used for every round.
Returns:
{"ok", "converged", "reason", "message", "iterations", "best_iteration", "levers", "steps"}. reason is one of
converged, max_iterations, max_seconds, diverging, unresponsive,
infeasible, pipeline_error; message says what to change when it
is not converged.
Inputs: schema (required), queries (required), targets (required), seed, +2 more. Returns: result
validate_domainValidate a dataset against domain rulesARead-onlyIdempotent
Flag values that are physiologically or financially impossible for a domain.
Where audit_dataset checks internal consistency, this checks values
against what the outside world allows. Built-in ranges include, for
clinical / clinical_trial: HbA1c 4-14%, BMI 10-80, systolic BP
60-260, age 0-130, glucose 2-40, cholesterol 1-20, hemoglobin 3-25; for
financial / fintech: price >= 0, discount 0-1, rate -1 to 100.
Use after generating a dataset in a regulated or measurement-heavy domain, or when the user asks "is this data plausible for a real clinic / bank?".
Args:
dataset_dir: Directory containing one CSV per table.
domain: One of clinical_trial, clinical, financial,
fintech.
Returns:
{"passed": bool, "errors": [...], "warnings": [...]}. passed
is True when there are no ERROR-level findings.
Inputs: domain (required), dataset_dir (required). Returns: result
validate_yamlValidate a misata.yamlARead-onlyIdempotent
Validate a misata.yaml document at two levels.
Runs both checks in sequence:
Structural — the published JSON Schema (correct field types, required fields, enum values). Catches typos and shape errors.
Semantic —
misata.validate_schema(probabilities sum to 1.0, every foreign_key has a matching Relationship, no cycles, outcome curves reference real columns, etc.). These are the rules that would crash generation; the error messages include suggested fixes.
Use this when an agent has authored or edited a misata.yaml on the
user's behalf and wants to confirm it parses and will actually
generate before invoking generate_dataset.
Args: yaml_text: The full contents of a misata.yaml file as a string.
Returns:
{"valid": true} if both checks pass; otherwise
{"valid": false, "errors": [...], "stage": "structural"|"semantic"}
with the layer that failed first.
Inputs: yaml_text (required). Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 15 tools
Most tools are clearly separated and the descriptions even cross-reference each other (audit_dataset vs check_realism vs validate_domain, preview_story vs inspect_schema, generate_dataset vs generate_from_schema). The remaining soft spots are preview_story/inspect_schema/explain_schema, which all 'show you what you'd get' for slightly different inputs, and create_sandbox vs seed_database, which both write to a database but differ in source of truth.
Every name is snake_case with a verb-first pattern (validate_yaml, audit_dataset, attest_dataset, check_realism, seed_database). Minor deviation: generate_from_schema is verb_preposition_noun while its sibling is generate_dataset, a near-pair that differs only by a preposition.
15 tools sits at the top of the well-scoped band and each one owns a distinct stage: authoring, previewing, validating, generating, attesting, DB seeding, sandbox CRUD, and outcome solving. Nothing looks like filler or a redundant wrapper.
The lifecycle is fully covered end to end: domain discovery and story preview, schema dry-run and YAML validation, two generation paths, outcome solving, three complementary quality checks, cryptographic attestation, plus live DB seeding and a queryable sandbox. The only gaps are trivial (no sandbox delete/cleanup, no patch-in-place of an existing dataset), both workaroundable outside the tool surface.
Maintenance
Related MCP Connectors
Generate realistic, FK-consistent synthetic test data for your databases from your AI assistant.
Generate realistic relational test data — 156 field types, 22 locales, JSON/CSV/SQL, free previews.
Interactive data visualization and executive PDF dashboards for ChatGPT, Claude, and Cursor.
Privacy-safe synthetic financial data for LatAm fintech, AI agents, testing and ML.
Related MCP Servers
- AlicenseBqualityDmaintenanceGenerates realistic mock data using Faker.js for database seeding, API testing, and development environments. Supports person/company data, custom patterns, multi-locale generation, and structured datasets with referential integrity.462 npm7MIT
- AlicenseNot gradedqualityDmaintenanceEnables creating interactive data visualizations from natural language queries using DuckDB for local databases or Databricks for enterprise data warehouses. Supports multiple chart types, CSV imports, SQL queries, and automatic statistical analysis through Claude Desktop.19MIT
- FlicenseNot gradedqualityDmaintenanceGenerates realistic, context-aware synthetic data for AI agents to populate databases, mock APIs, and create test scenarios without exposing real PII.7 npm3-
- AlicenseAqualityDmaintenanceGenerates realistic, referentially-coherent test data (SQL INSERTs, JSON, or CSV) from your database schema, resolving foreign keys and respecting constraints. Paste CREATE TABLE DDL or a JSON schema and get ready-to-run seed data with valid relationships.2MIT