SymageDocs Python SDK

Generate synthetic documents, identities, and tabular datasets for testing, ML training, and compliance.

Installation

pip install symagedocs

For progress bars during long jobs:

pip install symagedocs[progress]

Quick Start

from symagedocs import Client

client = Client(api_key="sk_live_...")

# List available forms
forms = client.forms.list()
for f in forms:
    print(f"{f.id}: {f.name} ({f.credit_cost} credits)")

# Generate 100 W-2 documents
# JSON ground truth and CSV are always included in the dataset zip — no need to request them.
job = client.generate.create(
    "irs_w2_2025",
    quantity=100,
    output_formats=["pdf_typed"],  # see "Output formats" for all valid tokens
    # Augmentation knobs. `degradation_profile` affects credit cost —
    # `scanned`/`faxed` add 20%, `photographed` 30%, `mixed` 25% (`clean` = no surcharge).
    # `coherence_mode` controls cross-form identity correlation in multi-form jobs.
    degradation_profile="scanned",
    coherence_mode="coherent",
)
result = client.generate.wait(job.job_id)  # polls until complete
# "dataset" = one zip with every artifact + manifest.json; "json" and "csv"
# fetch just that ground-truth slice — see "Downloading results".
client.generate.download(job.job_id, "dataset", "./w2_documents.zip")

# Per-item training data
job = client.generate.create(
    form_id="irs_w2_2025",
    quantity=10,
    output_formats=["pdf_typed", "bio"],
    idempotency_key="my-retry-safe-key",
)
client.generate.wait(job.job_id)
for example in client.generate.iter_training_examples(job.job_id, format="bio"):
    print(example.item_id, len(example.bio.tokens))

# Generate tabular data from a description
schema = client.tabular.parse("name, age, SSN, city, state, annual income")
tab_job = client.tabular.generate(columns=schema.columns, quantity=5000)
client.tabular.wait(tab_job.job_id)
client.tabular.download(tab_job.job_id, "csv", "./dataset.csv")

# Check credit balance
balance = client.account.balance()
print(f"Credits used: {balance.credits_used}")

Authentication

Get your API key at symagedocs.ai/account?tab=api.

# Pass directly
client = Client(api_key="sk_live_...")

# Or set environment variable
# export SYMAGEDOCS_API_KEY=sk_live_...
client = Client()  # reads from env

Async Support

from symagedocs import AsyncClient

async with AsyncClient(api_key="sk_live_...") as client:
    forms = await client.forms.list()
    job = await client.generate.create("irs_w2_2025", quantity=10)
    result = await client.generate.wait(job.job_id)

Configuration

client = Client(
    api_key="sk_live_...",
    base_url="https://symagedocs.ai",  # custom server
    timeout=30.0,                       # request timeout (seconds)
    max_retries=3,                      # retry on 429/5xx
)

Method Reference

Forms

Generation

client.generation alias. client.generation and client.generate reference the same resource — use whichever name you prefer.

Identities

Tabular

Account

Pricing

The pricing endpoints are public/unauthenticated on the backend, but the SDK still requires an API key at construction time for consistency; the auth header is sent and ignored by these routes.

Health

Output formats

generate.create(output_formats=[...]) accepts exactly these tokens; any other value is rejected with 400 code=invalid_output_format:

Rules enforced at job creation:

• Foundational ground truth is always included. Per-instance JSON, tabular CSV, and FUNSD per-page annotations ship in every dataset automatically; "csv", "json", and "funsd" are not requestable tokens and return 400.
• PNG travels with its PDF. png_typed requires pdf_typed in the same request; png_handwritten requires pdf_handwritten.
• ML formats are feature-gated. bio/coco/yolo/donut require the ml-output-formats-enabled feature flag on your account (400 code=ml_formats_disabled otherwise) and at least one render format (pdf_typed, pdf_handwritten, or png_typed) in the same request, since annotations are derived from the render pipeline.

Downloading results

generate.download(job_id, format="dataset", path=".") accepts exactly three formats:

• dataset (default) — one zip with every artifact the job produced (PDFs, PNGs, ML annotations, per-item JSON ground truth, tabular CSV) plus a manifest.json describing the contents. The response is streamed to disk in 64 KiB chunks, so multi-GB datasets download with flat memory use.
• json — flat per-instance JSON array (no images/PDFs).
• csv — tabular identity data.

Anything else raises ValueError client-side before a request is made. (The pre-rename token bundle is not accepted by the SDK.)

When path is a directory (the default "."), a filename is appended automatically: symagedocs_<job_id>.zip for dataset, <job_id>.json for json, <job_id>.csv for csv.

Sharded datasets. Very large jobs are stored as a sharded dataset, which has no single archive; download(format="dataset") then raises ValueError pointing you at download_dataset(). download_dataset(job_id, out_dir, parallel=8, resume=True) is the universal accessor and works for both layouts: it fetches manifest.json and README.md, then either dataset.zip (single layout) or preview.zip followed by shards/shard_NNNNN.zip downloaded in parallel with size verification against the manifest (sharded layout). With resume=True, shards already on disk whose size matches the manifest are skipped, so a partially-failed download can be retried cheaply.

Job states. Downloads are allowed for terminal-but-not-completed jobs (CANCELED / FAILED / EXPIRED) so partial output is recoverable; downloading a job that is still running returns 409.

Tabular jobs have their own surface: tabular.download(job_id, format, path) accepts "csv" or "json".

Training data

Request ML annotation formats alongside a render format, then iterate per-item training examples:

job = client.generate.create(
    "irs_w2_2025",
    quantity=50,
    output_formats=["pdf_typed", "bio"],
    config={"label_scheme": "nist3"},  # default: "semantic_concept"
)
client.generate.wait(job.job_id)
for ex in client.generate.iter_training_examples(job.job_id, format="bio"):
    print(ex.item_id, len(ex.bio.tokens))  # BIO tags + word boxes

• iter_training_examples(job_id, format=...) yields "bio" (default), "funsd" (one example per page, with page_index set), or "donut" examples.
• config["label_scheme"] selects the annotation vocabulary: semantic_concept (default — concept names like social_security_number), nist3 (3-class name/ssn/data), field_id (form field IDs), or field_type (e.g. ssn, currency, text). Unknown values return 400 code=invalid_label_scheme.
• Per-item sidecars are also fetchable directly: get_bio_labels(job_id, item_id) and get_word_annotations(job_id, item_id).

See the API User Manual's Training Data section for the full annotation schemas and Donut consumer conventions.

Augmentation knobs

Two of the most-used keys in the freeform config={...} dict on generate.create are also exposed as typed kwargs:

• degradation_profile: Literal["clean", "scanned", "faxed", "photographed", "mixed"] | None
• coherence_mode: Literal["coherent", "shuffled", "random"] | None

Why bother? Two reasons:

1. degradation_profile affects credit cost. Non-clean profiles need extra rendering work (rasterization, noise, paper warp), so the billing engine applies a multiplier: scanned/faxed are billed at 1.2×, mixed at 1.25×, and photographed at 1.3×. A typo on the freeform config={...} form silently falls back to the default 1.0× multiplier — meaning you don't get the degradation you asked for AND the typo isn't caught until you notice the artifacts (or don't). The typed kwarg form catches typos at type-check time.
2. Pre-flight validation. The Literal types fence off unknown values at edit time in any IDE that supports type checking. The backend also rejects unknown values with 400 for both knobs, so even untyped callers get a fast failure — but the typed form catches the mistake before the network round-trip.

The SDK exports the canonical value tuples too:

from symagedocs import DEGRADATION_PROFILES, COHERENCE_MODES

assert "scanned" in DEGRADATION_PROFILES
assert "coherent" in COHERENCE_MODES

If you pass a value via both forms (e.g. config={"degradation_profile": "X"} AND degradation_profile="Y"), the value in config wins and a RuntimeWarning is emitted so the conflict isn't silent.

# Typed kwarg form — recommended.
job = client.generate.create(
    "irs_w2_2025",
    quantity=100,
    degradation_profile="scanned",   # billed at 1.2× — see above
    coherence_mode="coherent",
)

# Equivalent freeform form — still supported, but typos cost money.
job = client.generate.create(
    "irs_w2_2025",
    quantity=100,
    config={"degradation_profile": "scanned", "coherence_mode": "coherent"},
)

Error Handling

The SDK raises typed exceptions for API errors and retries automatically on 429 and 5xx:

from symagedocs import Client, AuthenticationError, RateLimitError, NotFoundError

try:
    forms = client.forms.list()
except AuthenticationError:
    print("Invalid API key")
except RateLimitError:
    print("Too many requests — SDK retries automatically")
except NotFoundError:
    print("Resource not found")

All error classes:

Examples

The examples/ directory (in the repository and the source distribution; not installed with the wheel) contains complete working scripts:

• list_forms.py — Browse available forms and credit costs
• generate_w2s.py — Full pipeline: create job, wait, download the dataset zip
• tabular_dataset.py — Parse NL description, generate 5k rows, download CSV
• train_kie_model.py — Create a job with NIST3 labels and BIO output, iterate training examples, fetch word annotations

Documentation

• API User Manual — long-form guide with worked examples
• API Explorer — interactive Swagger UI
• API Reference — three-panel ReDoc reference

License

MIT