synthera 0.2.8

Python client for Synthera AI API

Synthera AI SDK

A Python SDK for accessing the Synthera AI API.

Installation

The package is compatible with Python 3.9-3.13.

pip install synthera

Changelog

0.2.8

Changed

• Response data format: compressed feather & base64

0.2.7

Added

• Request fallback_on_missing_date parameter
• Request conditional_vol_factor parameter
• version to Client and request headers

Changed

• Request no_of_days parameter to no_days
• Request no_of_samples parameter to no_samples
• Model metadata simulation_steps to max_simulate_days
• Model metadata conditional_steps to conditional_days
• FixedIncome model_labels to get_model_labels
• FixedIncome model_metadata to get_model_metadata
• FixedIncome simulation_past_date to simulate
• FixedIncome SimulationPastDateRestuls to SimulateResults

API Key

You are required to use an API key to access the Synthera AI API.

For ease of use, set as an environment variable: SYNTHERA_API_KEY:

export SYNTHERA_API_KEY=<api_key>

Or you can pass directly to the client.

Getting Started

Import the Synthera client:

from synthera import SyntheraClient

Create a client:

client = SyntheraClient()

Show client version

client.version
# Output: 0.2.8

Check the connection works:

client.healthy()
# Output: True

Note: the health endpoint is open; the API key is not verified.

For more advanced connection options, pass arguments to the client:

SyntheraClient(api_key="<api_key>", host="<host>", port=<port>, timeout_secs=<timeout>)
# Output: <SyntheraClient>

Fixed Income

To run Fixed Income Yield Curve simulation.

View Available Models

View the model labels:

client.fixed_income.get_model_labels()
# Example output: ['YieldGAN-Augur-15days-v0.1-Q42019', 'YieldGAN-Augur-15days-v0.1-Q42024']

Name	Description
YieldGAN	Model name
Augur	Dataset used for training & inference
15days	Maximum simulation days
v0.1-Q42019	Version (including training end period)

View Model Metadata

View the metadata for a model label:

client.fixed_income.get_model_metadata(model_label="YieldGAN-Augur-15days-v0.1-Q42024")
# Example output: ModelMetadata(model_label='YieldGAN-Augur-15days-v0.1-Q42024', dataset='Augur', universe='g3_par_curves', curve_labels=['USA', 'GBR', 'DEU'], start_date_training='2000-01-01', end_date_training='2025-01-01', max_simulate_days=15, conditional_days=15, tenors=[0.5, 1.0, 1.5, 2.0, 2.5, 3.0, 3.5, 4.0, 4.5, 5.0, 6.0, 7.0, 8.0, 9.0, 10.0, 12.0, 14.0, 16.0, 18.0, 20.0, 25.0, 30.0])

Name	Description
model_label	Unique identifier for the model
dataset	Dataset model is trained on (e.g. Augur Labs)
universe	Data universe used for training (e.g., g3_par_curves)
curve_labels	List of yield curve identifiers included in the model
start_date_training	Start date of the training data period (YYYY-MM-DD) (inclusive)
end_date_training	End date of the training data period (YYYY-MM-DD) (exclusive)
max_simulate_days	Maximum number of forward simulation days
conditional_days	Number of conditional simulation days
tenors	List of tenors (in years) for which yields are generated

Simulation

Prepare input parameters.

Parameter	Type	Description	Values
model_label	string	Version of the model to use	Valid model label: "YieldGAN-<dataset>-<max simulation days>-v<version>"
curve_labels	list[string]	List of yield curves labels to simulate, using ISO 3166-1 alpha-3 country codes	List of curve names (e.g., ["USA", "GBR", "DEU"])
no_days	integer	Number of days to simulate forward from the reference date	> 0 (e.g., 3, 30, 60, 120)
no_samples	integer	Number of paths to simulate	> 0 (e.g., 100, 1024, 5000)
reference_date	string	Reference date for the generation (in the past)	YYYY-MM-DD format
fallback_on_missing_date	boolean	Whether to fallback to an available date in the dataset	true or false
conditional_vol_factor	float	Conditional volatility factor	e.g. 0.1, 1.0, 10.0, 100

For example:

params = {
    "model_label": "YieldGAN-Augur-10days-v0.1-Q42024",
    "curve_labels": ["USA", "GBR"],
    "no_days": 15,
    "no_samples": 100,
    "reference_date": "2010-01-01"
    "fallback_on_missing_date": true
    "conditional_vol_factor: 1.0
}

Run simulation directly:

results = client.fixed_income.simulate(params=params)
# Output: SimulateResults

View yield curves labels:

results.names
# Example output: ['USA', 'GBR']

View yield curve dataframe column names:

results.column_names
# Output: ['IDX', 'SAMPLE', 'YC_0', 'YC_1', ...]

View a specific yield curve dataframe, e.g. for USA:

results.dataframes["USA"]
# Output: pandas.DataFrame

View all yield curves in a single numpy ndarray (order is same as names):

results.ndarray
# Output: ndarray of shape (samples, countries, days, columns)

View request metadata:

results.metadata
# Output: dict

Simulate Results

The SimulateResults object provides several utility and plotting methods for analyzing and visualizing outputs.

Utility Methods

Get dates:

results.get_dates()
# Output: [Timestamp('2010-01-01 00:00:00'), ...]

Get yield curve column indices:

results.get_yc_indices()
# Output: [2, 3, 4, ...]

Get all yield curve samples (as ndarray):

results.get_yc_samples()
# Output: ndarray of shape (samples, countries, days, maturities)

Get all samples for a specific country:

results.get_country_yc_samples("USA")
# Output: ndarray of shape (samples, days, maturities)

Get a single sample for a country:

results.get_yc_sample("USA", sample_num=0)
# Output: ndarray of shape (days, maturities)

Get a single sample at a specific time index:

results.get_country_sample_at_t("USA", time_idx=1, sample_num=0)
# Output: ndarray of shape (maturities,)

Plotting Methods

All plotting methods return a matplotlib Figure. Set show_plot=True to display immediately (non-Jupyter environments).

Plot a single sample for a country at a specific time:

results.plot_country_sample_at_time("USA", time_idx=1, sample_num=0, show_plot=True)
# Output: matplotlib.figure.Figure

Plot all samples for a country at a specific time:

results.plot_country_all_samples_at_time("USA", time_idx=1, show_plot=True)
# Output: matplotlib.figure.Figure

Plot a single sample's yield curve evolution over time (3D):

results.plot_country_sample_yield_curve_over_time("USA", sample_num=0, show_plot=True)
# Output: matplotlib.figure.Figure