Quickstart

This guide walks you from a fresh install to your first synthetic dataset. Expected time: 5 minutes. You'll generate 100,000 schema-matched synthetic rows with 15% positive class labeling.

1

Install the SDK

Install Twynvex from PyPI. Requires Python 3.9+.

pip install twynvex

Verify installation:

python -c "import twynvex; print(twynvex.__version__)"
# 0.9.4
2

Authenticate with your API key

Find your API key in the Twynvex dashboard under Settings → API Keys. Keys are prefixed twx_sk_live_.

import twynvex as twx

twx.configure(api_key="twx_sk_live_yourKeyHere")

Alternatively, set the environment variable TWYNVEX_API_KEY and call twx.configure() with no arguments.

3

Upload your schema or sample

You can infer a schema from a real CSV sample, or define one manually. The sample is used only to fit statistical parameters — no raw rows are stored.

import twynvex as twx

schema = twx.from_csv("transactions.csv")
print(schema.summary())
# Columns: 12
# Rows in sample: 40,000
# Column types: 4 float, 3 int, 3 categorical, 1 datetime, 1 bool
# Detected label: "fraud" (categorical, P=0.008)

If you prefer to define a schema manually without any real data:

schema = twx.Schema()
schema.add_column("amount",    type="float",       min=0.01, max=50000, dist="log-normal")
schema.add_column("category",  type="categorical", values=["retail","food","travel","other"])
schema.add_column("hour",      type="int",         min=0, max=23)
schema.add_column("fraud",     type="categorical", values=["legit","fraud"])
4

Configure and run generation

Create a generation job. Specify how many rows, how much to weight toward the distribution tail, and target class ratios for labeled columns.

job = schema.generate(
    num_rows=100_000,
    tail_weight=0.3,         # 30% of rows from distribution tail
    label_ratio={"fraud": 0.15}   # 15% positive class
)

print(f"Job ID: {job.id}")
print(f"Status: {job.status}")
# Job ID: gen_7f3a2b...
# Status: running

Generation runs asynchronously. A 100K row job typically completes in 20–40 seconds depending on schema complexity.

5

Download your synthetic dataset

Pull the completed job as a pandas DataFrame, or save directly to disk.

df = job.to_dataframe()
print(df.shape)
# (100000, 12)

print(df["fraud"].value_counts(normalize=True))
# legit    0.850
# fraud    0.150

df.to_parquet("synthetic_train.parquet")

Check your quality report:

print(job.report)
# Fidelity score:  0.93  (JS divergence vs. real sample)
# Utility AUC:     0.91  (train-on-synthetic, test-on-real)
# Privacy NN dist: 0.84  (nearest-neighbor distance check)

What just happened?

Here's what Twynvex did behind the scenes in those 30 seconds:

  1. Fitted marginal distributions for each column from your sample (or your manual definitions). Selected the best-fit distribution family per column — log-normal for amount, empirical categorical for category, etc.
  2. Estimated pairwise correlations between columns. The relationship between amount and fraud (high amounts more likely fraud) is preserved in the synthetic output.
  3. Applied tail-weighting by shifting the generation probability mass toward low-frequency regions of the fitted distributions. This is where your edge cases come from.
  4. Enforced label ratio by conditioning generation on the specified class distribution, then solving the constraint problem (high-amount transactions required for fraud rows per the learned correlation).
  5. Ran quality scoring — comparing synthetic column distributions to real, testing utility via a held-out classifier, and verifying no synthetic row is close to any real row by nearest-neighbor distance.

Your synthetic_train.parquet file has the same column names, types, and ordering as your source. Merge it with your real training data, or use it alone. No additional preprocessing needed.

Next steps

  • Explore the REST API if you want to trigger generation from your CI/CD pipeline or from a language other than Python.
  • Read How It Works for a deeper explanation of the statistical modeling and constraint solver.
  • See Use Cases for worked examples in fraud detection, NLP, and healthcare tabular data.