Synth SDK

The Synth SDK is fully type-safe. It provides typed API groups, request bodies, and responses. A type checker can find invalid fields before your code calls the API.

Install the SDK

Once published you will install with:

pip install pleias-synth

Initializing the client

Create the authenticated API client inside an async function. Set SYNTH_BASE_URL, SYNTH_TOKEN, and SYNTH_ORG before you run the code.

import os

from synth_client import AuthenticatedClient, SynthApi

client = AuthenticatedClient(
    base_url=os.environ["SYNTH_BASE_URL"],
    token=os.environ["SYNTH_TOKEN"],
)
api = SynthApi(client)
org = os.environ["SYNTH_ORG"]

Create a dataset

Create a dataset before you create a generation. The response contains the dataset ID.

response = await api.datasets.create_dataset(
    org=org,
    body={
        "name": "my-dataset",
        "description": "Dataset created with the Synth SDK.",
    },
)

print(response.parsed)

Create a generation

Use the dataset ID from the create-dataset response. Put the generation body directly in the API call.

response = await api.generations.create_generation(
    org=org,
    dataset_id=dataset_id,
    body={
        "type": ["general_purpose"],
        "rowCount": 100,
        "languages": ["EN"],
        "domains": ["example.com"],
    },
)

print(response.parsed)

Start a generation

Use the generation ID from the create-generation response to start the job.

response = await api.generations.start_generation(
    org=org,
    dataset_id=dataset_id,
    gen_id=generation_id,
)

print(response.parsed)

Download a completed generation

Wait until the generation reaches the completed state. List the dataset outputs to find the output file ID for the generation.

response = await api.outputs.list_dataset_outputs(
    org=org,
    dataset_id=dataset_id,
)

print(response.parsed)

Use the output id as output_file_id. Download the file content and write it to a local Parquet file.

from http import HTTPStatus
from pathlib import Path

response = await api.outputs.download_dataset_output(
    org=org,
    dataset_id=dataset_id,
    output_file_id=output_file_id,
)

if response.status_code != HTTPStatus.OK:
    raise RuntimeError(response.content.decode(errors="replace"))

Path("generation-output.parquet").write_bytes(response.content)