synthera 0.2.12

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.12

Added

• inflation-curves on simulate: request inflation curve payloads from inflation-capable models via outputs, alongside yields, FX spot, and FX forwards. Defaults stay unchanged.

Changed

• Model metadata curve_labels follows the live API combined discovery list, so inflation-capable models expose yield and inflation curve labels through the same field.
• Inflation output column names in each curve DataFrame are canonicalized like yields, using labels such as USA_Inflation10.0Y instead of raw YC-10.0.
• views.yields request validation remains aligned with the current API: canonical yield keys such as USA10.0Y are accepted, while inflation keys such as USA_Inflation10.0Y are not yet part of the request contract.

0.2.11

Added

• Distribution yield views (views.yields with type: distribution): re-weight scenarios toward a target shift or band at the horizon instead of only dropping paths that miss a filter.
• outputs on simulate: pick which columns you get per curve—yield curves, FX spot, FX forwards, or any combination. Defaults stay yields plus FX spot (typical for USD PnL). Drop what you do not need to shrink downloads.
• maturities on simulate (optional): request only the maturities you care about instead of the full model grid.
• Valid reference-date range: model and simulate metadata may include conditional_min_date and conditional_max_date (YYYY-MM-DD) for the dataset behind the deployment.
• macro_factors on metadata: see which macro factor keys the model allows before building views.macro (None if unspecified, [] if none).
• SimulateOutputKind in synthera.fixed_income for type-checking outputs values.

Changed

• Macro views match the live API: one entry per factor key. For GDP, CPI, and UNRATE, paths are still per curve; for other factors, pass a single series (one dated entry or a list). Only use keys listed in macro_factors.
• Quantile plots use scenario weights automatically when you used distribution yield views.
• Yield column names in each curve DataFrame read like USA10.0Y (curve + maturity) instead of raw YC-10.0; plotting and yield helpers accept both legacy and canonical names.
• curve_labels accepts a single string when you simulate one curve (e.g. "USA").
• Breaking: canonical maturity keys only in views.yields. Yield view keys must now use "{CURVE}{maturity}Y" (for example, USA10.0Y). Underscore keys such as USA_10.0Y are rejected during SDK request validation.
• Simulate metadata includes outputs, mirroring which series were returned (after de-duplicating your request).
• GET calls (model labels, metadata) retry with backoff on transient failures, consistent with simulate POSTs.
• get_yc_samples() raises ValueError if you excluded yield curves via outputs—include "yield-curves" when you need that slice.

0.2.10

Added

• macro view support in views: condition simulations on macro paths using relative or absolute targets per curve and date (legacy API shape with fixed GDP / CPI / UNRATE fields; superseded in 0.2.11)

Changed

• Increased default Client timeout to 90 seconds to accommodate the additional latency introduced by view-conditioned simulations.
• Requests that time out are no longer retried. Previously, a timeout would trigger up to 5 retry attempts (with a 2-second wait between each). Timeouts now immediately raise a SyntheraClientError.
• Renamed country to curve in SimulateResults methods: get_curve_yc_samples, get_curve_sample_at_t, plot_curve_sample_at_time, plot_curve_all_samples_at_time, plot_curve_sample_yield_curve_over_time.

0.2.9

Added

• Request views parameter: optional yield-view constraints (point, range, min, max per curve/maturity) to filter scenarios by change in bps at end of horizon
• Response metadata no_samples_returned and views_applied when views are used
• SSL options on SyntheraClient: verify_ssl (default True) and ca_bundle (optional path). Environment variables SYNTHERA_API_VERIFY_SSL and SYNTHERA_API_CA_BUNDLE to override. Supports corporate proxies and custom CA bundles.

Changed

• Model and simulate response metadata: tenors renamed to maturities.

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.

SSL / TLS

SSL verification is configurable for environments (e.g. corporate proxies or custom CA bundles).

Constructor options:

• verify_ssl — Enable or disable server certificate verification (default: True).
• ca_bundle — Path to a CA bundle file for verification (optional). When set, this path is used instead of the default system trust store.

Environment variables (overridden by explicit constructor args):

• SYNTHERA_API_VERIFY_SSL — Set to false, 0, or no (case-insensitive) to disable verification; any other value enables it.
• SYNTHERA_API_CA_BUNDLE — Path to your CA bundle file (e.g. /path/to/ca-bundle.pem).

Example:

# Default: verify with system CA bundle
client = SyntheraClient(api_key="<api_key>")

# Disable verification (e.g. for testing)
client = SyntheraClient(api_key="<api_key>", verify_ssl=False)

# Use a custom CA bundle (e.g. for corporate proxies)
client = SyntheraClient(
    api_key="<api_key>",
    verify_ssl=True,
    ca_bundle="/path/to/your/ca-bundle.pem",
)

Or via environment:

export SYNTHERA_API_VERIFY_SSL=false
export SYNTHERA_API_CA_BUNDLE=/path/to/ca-bundle.pem

Getting Started

Import the Synthera client:

from synthera import SyntheraClient

Create a client:

client = SyntheraClient()

Show client version

client.version
# Installed package version string

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>, # default: 90 seconds
    verify_ssl=True,   # default; set False to disable SSL verification
    ca_bundle=None,    # optional path to CA bundle file
)
# 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-v0.3-Q42019', 'YieldGAN-augur-v0.4-Q42020']

Name	Description
YieldGAN	Model name
augur	Dataset used for training & inference
v0.4-Q42020	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-v0.4-Q42020")
# Example output: ModelMetadata(..., macro_factors=['GDP', 'CPI', 'UNRATE'], ...)

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
maturities	List of maturities (in years) for which yields are generated
macro_factors	Optional list of macro factor keys this model supports (None if not declared; [] if none)
conditional_min_date	Optional minimum calendar date (YYYY-MM-DD) allowed for reference_date on the deployed dataset
conditional_max_date	Optional maximum calendar date (YYYY-MM-DD) allowed for reference_date on the deployed dataset

Simulation

Prepare input parameters.

Parameter	Type	Description	Values
model_label	string	Version of the model to use	Valid model label: "YieldGAN-<dataset>-v<version>"
curve_labels	list[string] or string	Curve labels to simulate, selected from model metadata curve_labels	e.g. ["USA", "GBR", "USA_Inflation"] or a single curve "USA"
maturities	list[float] (optional)	Subset of the model maturity grid to return	Non-empty list of maturities from model metadata; omit for all maturities
outputs	list[string] (optional)	Which data families to include in each per-curve payload	Literals yield-curves, inflation-curves, fx-spot-rates, fx-forwards; default ["yield-curves", "fx-spot-rates"]; at least one kind; duplicates are removed preserving order. If curve_labels includes an inflation curve such as USA_Inflation, the API automatically includes inflation-curves in the returned payload
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
views	object (optional)	Optional constraints for scenarios	yields: dict of curve_maturity (e.g. "USA10.0Y") to yield view, or None. Filter views use `{"type": "filter", "view": "point

For example:

params = {
    "model_label": "YieldGAN-augur-v0.4-Q42020",
    "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,
}

Optional maturities and outputs (see model metadata for valid maturities):

meta = client.fixed_income.get_model_metadata(model_label="YieldGAN-augur-v0.4-Q42020")
params = {
    "model_label": "YieldGAN-augur-v0.4-Q42020",
    "curve_labels": "USA",  # single string is accepted
    "no_days": 5,
    "no_samples": 500,
    "reference_date": "2010-01-01",
    "maturities": [float(meta.maturities[0]), float(meta.maturities[-1])],
    "outputs": ["yield-curves", "fx-spot-rates", "fx-forwards"],
}

If you request an inflation curve label, the API automatically includes "inflation-curves" in the returned payload even when outputs is omitted:

params = {
    "model_label": "YieldGAN-augur-v0.4-Q42020",
    "curve_labels": ["USA_Inflation"],
    "no_days": 5,
    "no_samples": 500,
    "reference_date": "2010-01-01",
    "outputs": ["inflation-curves"] # optional: will be added automatically
}

With optional views to filter scenarios by yield change (in basis points) at the end of the simulation horizon:

Set "yields": None when you do not want yield constraints.

params = {
    "model_label": "YieldGAN-augur-v0.4-Q42020",
    "curve_labels": ["USA", "GBR", "DEU"],
    "no_days": 5,
    "no_samples": 1000,
    "reference_date": "2010-01-01",
    "fallback_on_missing_date": True,
    "views": {
        "yields": {
            "USA10.0Y": {"type": "filter", "view": "range", "min_bp": 20, "max_bp": 25},
            "DEU2.0Y": {"type": "filter", "view": "point", "value_bp": 10, "tolerance_bp": 2},
        },
        "macro": None,
    },
}
# When views are applied, result.ndarray.shape[0] may be less than no_samples;
# use results.metadata["no_samples_returned"] for the actual count.

With optional distribution yield views to re-weight scenarios toward a terminal-horizon target change vs the conditional/reference level (instead of filtering out scenarios):

params = {
    "model_label": "YieldGAN-augur-v0.4-Q42020",
    "curve_labels": ["USA", "GBR", "DEU"],
    "no_days": 5,
    "no_samples": 1000,
    "reference_date": "2010-01-01",
    "views": {
        "yields": {
            # Shift mode: target +15bp terminal change vs conditional/reference level
            "USA10.0Y": {"type": "distribution", "view": "shift", "shift_bp": 15.0},
        }
    },
}

Distribution yield views must follow API constraints:

• you can request multiple curve_labels in one simulation request
• include exactly one yield entry in views["yields"]
• that entry must be type: "distribution"
• the single distribution entry applies to one curve/maturity key (for example "USA10.0Y")
• do not combine distribution and filter yield views in the same request

For a distribution range view, send a single distribution entry like:

params["views"] = {
    "yields": {
        "GBR2.0Y": {
            "type": "distribution",
            "view": "range",
            "shift_bp": 5.0,
            "tolerance_bp": 2.0,
        }
    }
}

Distribution yield view fields:

• type: must be distribution
• view: shift or range
• shift_bp: target terminal change in bps vs conditional/reference level at end horizon
• tolerance_bp: required for range, omitted for shift

When distribution views are applied, results.metadata can include scenario_probabilities and weighted quantile methods use these probabilities automatically.

With optional macro views, first read which factor keys the model supports, then send only those keys under views["macro"]:

meta = client.fixed_income.get_model_metadata(model_label="YieldGAN-augur-v0.4-Q42020")
# meta.macro_factors e.g. ["GDP", "CPI", "UNRATE"] — use only these keys in the macro view.

params = {
    "model_label": "YieldGAN-augur-v0.4-Q42020",
    "curve_labels": ["USA", "GBR", "DEU"],
    "no_days": 5,
    "no_samples": 1000,
    "reference_date": "2010-01-01",
    "views": {
        "macro": {
            "GDP": {
                # Relative: USA GDP 10 bp above its conditional value on 2010-01-05
                "USA": [{"date": "2010-01-05", "type": "delta_bp", "value": 10}],
                # Absolute: DEU GDP pinned to a specific level on 2010-01-10
                "DEU": [{"date": "2010-01-10", "type": "target_amount", "value": 3_000_000_000_000.0}],
            },
            "CPI": {
                # Relative: USA CPI index +1.5 points above conditional on 2010-01-05
                "USA": [{"date": "2010-01-05", "type": "delta_ip", "value": 1.5}],
                # Absolute: GBR CPI pinned to a specific index level
                "GBR": [{"date": "2010-01-05", "type": "target_ip", "value": 115.0}],
            },
            "UNRATE": {
                # Relative: USA unemployment rate -0.5 pp below conditional
                "USA": [{"date": "2010-01-05", "type": "delta_pp", "value": -0.5}],
                # Absolute: DEU unemployment rate pinned to 5.0%
                "DEU": [{"date": "2010-01-05", "type": "target_rate", "value": 5.0}],
            },
        }
    },
}

For GDP, CPI, and UNRATE, each factor’s value is an object mapping curve label → list of dated entries. For other macro factors (for example UK_REAL_GDP), the value is a single series: either a JSON array of entries or one entry object with date, type, and value. Multiple dates can be specified in the list form. Unspecified simulation dates carry forward the last known conditional value. The API rejects factor keys that are not in the model’s allowlist.

You can mix both shapes in one views["macro"] object:

"views": {
    "macro": {
        "GDP": {
            "USA": [{"date": "2010-01-05", "type": "delta_bp", "value": 10}],
        },
        # Single-series factor: one entry object (or use a list of entries)
        "UK_REAL_GDP": {"date": "2010-01-05", "type": "delta_bp", "value": 10},
    },
}

Example — single-series factor only:

"views": {
    "macro": {
        "UK_REAL_GDP": {"date": "2010-01-05", "type": "delta_bp", "value": 10},
    },
}

Semantic (typical factors)	Entry type	Meaning
Amount (e.g. GDP)	delta_bp	Relative: target = cond × (1 + value / 100). Value in basis points.
Amount	target_amount	Absolute: target level in local currency.
Index (e.g. CPI)	delta_ip	Relative: target = cond + value. Value in index points.
Index	target_ip	Absolute: target index level.
Rate (e.g. unemployment)	delta_pp	Relative: target = cond + value. Value in percentage points.
Rate	target_rate	Absolute: target rate in % (e.g. 5.0 means 5.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
# Example: ['IDX', 'SAMPLE', 'USA10.0Y', 'USA2.0Y', 'FX-SPOT', ...]
# Yield columns use canonical {CURVE}{maturity}Y labels (legacy API YC-* names are renamed per curve).

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); width depends on outputs (yields, FX spot, forwards).

View request metadata:

results.metadata
# Output: dict

When views are applied, metadata includes no_samples_returned (number of scenarios after filtering) and views_applied; results.ndarray.shape[0] matches no_samples_returned.

Metadata also includes outputs: the output kinds included in each per-curve payload (see the outputs request field).

Get scenario probabilities (when distribution views are used):

scenario_probabilities = results.metadata.get("scenario_probabilities")
# Output: list[float] | None

For safety, validate they align with returned samples before using them:

probs = results.metadata.get("scenario_probabilities")
if isinstance(probs, list) and len(probs) == results.ndarray.shape[0]:
    print("Using weighted probabilities.")
else:
    print("No valid scenario probabilities available; use equal weights.")

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)
# Requires yield columns: raises ValueError if the request omitted yield-curves (outputs without "yield-curves").

Get all samples for a specific curve:

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

Get a single sample for a curve:

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_curve_sample_at_t("USA", time_idx=1, sample_num=0)
# Output: ndarray of shape (maturities,)

Get quantiles by curve (uniform vs weighted):

uniform_quantiles = results.quantiles_uniform_by_curve
weighted_quantiles = results.quantiles_weighted_by_curve
# Output: dict[str, list[list[float]]] for each (curve -> [maturity][quantile])

• quantiles_uniform_by_curve: baseline equal-weight quantiles from returned scenarios.
• quantiles_weighted_by_curve: distribution-weighted quantiles when a distribution yield view is applied; may be empty/None for non-distribution runs.

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 curve at a specific time:

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

Plot all samples for a curve at a specific time:

results.plot_curve_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_curve_sample_yield_curve_over_time("USA", sample_num=0, show_plot=True)
# Output: matplotlib.figure.Figure

Plot distribution-aware quantiles across maturities:

results.plot_quantiles_curve(["USA", "GBR"], show_plot=True)
# Output: matplotlib.figure.Figure

plot_quantiles_curve behavior:

• Without a distribution view, plots original (equal-weight) quantiles.
• With a distribution view in views_applied, overlays weighted quantiles using scenario weights.

Plot terminal yield distributions for selected points:

results.plot_probability_density_per_yield(["USA10.0Y", "GBR2.0Y"], show_plot=True)
# Output: matplotlib.figure.Figure

plot_probability_density_per_yield behavior:

• Always plots the equal-weight baseline density.
• When results.metadata["scenario_probabilities"] matches returned samples, overlays the weighted density.