Synthera AI SDK

A Python SDK for accessing the Synthera AI API.

Installation

The package is compatible with Python 3.10-3.14.

pip install synthera

Changelog

0.2.14

Added

• controls on simulate: optional day-1 moves. swap-curves keys are {curve}{tenor}Y (10Y or 10.0Y) with type: day1_move (multi-key allowed in schema); swap-forwards keys are {curve}{start}Y{tenor}Y with one-decimal years only (e.g. 1.0Y1.0Y) and type: day1_forward_move / lift_mode (sampled | deterministic). Empty object / omit = control off. Unset families are omitted from the dump. Serving remains capability-gated (API 400 until the bundle supports the shape).
• controls_applied on simulate metadata: echoes applied controls when the API returns them.
• Control diagnostics on simulate metadata (optional, omit when unset): control_realised_node_moves, control_sampled_pairs, control_realised_forward_moves.
• Day1MoveControl / Day1ForwardMoveControl / SimulateControls exported from synthera.fixed_income.
• SWAP_CURVES_CONTROL_FAMILY / SWAP_FORWARDS_CONTROL_FAMILY kebab-case wire name constants exported from synthera.fixed_income.
• swap-curves on simulate: request swap curve payloads from swap-capable models via outputs, alongside yields, inflation, FX spot, and FX forwards.
• active_families and families on model metadata: MarketModel composition fields matching the API (active_families for kebab-case risk-factor wire names; families for per-family labels/universe/maturities/units). Tenor grids live only under families[].maturities (no top-level maturities on metadata). Both default to [] when omitted so older payloads still parse.
• FamilyMetadata / CurveFamilyUnits exported from synthera.fixed_income for typing composition metadata.
• SC-* swap tenor columns: simulate helpers recognize SC-* as swap curve tenors (yield/inflation stay YC-* / canonical). Swap columns are not rewritten to yield-style labels.
• family_maturities_for_curve helper (exported from synthera.fixed_income) for reading tenors from families[] by curve label.
• pytest --import-mode=importlib: required so unit/integration suites with matching basenames collect together.

Changed

• HTTP retries on GET and POST sleep uniformly from the minimum wait up to min(max, jitter * 2^attempt), where the attempt number starts at 1. The ceiling is never below the minimum. Defaults are 5 attempts, minimum 2 seconds, jitter 2 seconds, and maximum 60 seconds, so the first retry is uniform on 2–4 seconds. A numeric Retry-After on HTTP 429 is waited exactly, capped at the maximum, and is not raised to the minimum. Set SYNTHERA_API_HTTP_RETRIES, SYNTHERA_API_HTTP_RETRY_WAIT_SECS, SYNTHERA_API_HTTP_RETRY_JITTER_SECS, and SYNTHERA_API_HTTP_RETRY_MAX_WAIT_SECS before import. Timeouts and HTTP 400 are not retried.
• Python support: drop Python 3.9. The package requires Python 3.10–3.14.
• pyarrow: minimum version raised to 23.0.1 so consumers cannot resolve a version affected by CVE-2026-25087.
• swap-curves payloads use SC-* tenor columns only (not YC-*).
• Breaking: SimulateControls.swap_curves is optional (None or omit); use the model’s trained/capabilities node key (e.g. USD_SOFR_PROXY2.0Y for 2y bundles), not a hardcoded 10y key.
• Breaking: maturities on simulate is now an optional per-family map ({"yield-curves": [2.0, 10.0]}, keys yield-curves | inflation-curves | swap-curves), not a flat list. Empty list per family raises; omit the field for full grids. Null maturities / outputs are omitted from the request dump.
• Breaking: outputs on simulate defaults to None (omit from dump); the API derives curve families from curve_labels (no automatic FX). Explicit lists are sent unchanged.
• Breaking: metadata family names use kebab-case wire names in active_families and families[].name (e.g. yield-curves, fx-rates, inflation-curves, swap-curves), aligned with simulate maturities / outputs keys.
• Breaking: metadata tenors on getModelMetadata live under families[].maturities (full model grids); top-level maturities / tenors on ModelMetadata are rejected.
• Simulate metadata maturities echoes the request per-family subset map when sent; families[].maturities stays the full model grid.
• Simulate metadata outputs defaults to [] when absent from the response.

0.2.13

Changed

• Plotting backend: all SimulateResults chart methods return interactive plotly.graph_objects.Figure objects instead of matplotlib figures. Set show_plot=True to display outside Jupyter; charts share styling via synthera.plot_theme.

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. Simulate POSTs in this release still retry with a fixed 2 second wait.
• 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']

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'], ...)

Simulation

Prepare input parameters.

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 (tenors from families[] via curve label):

from synthera.fixed_income import family_maturities_for_curve

meta = client.fixed_income.get_model_metadata(model_label="YieldGAN-augur-v0.4-Q42020")
curve_mats = family_maturities_for_curve(meta.families, "USA")
if not curve_mats:
    raise ValueError("No families[].maturities for USA")
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": {"yield-curves": [float(curve_mats[0]), float(curve_mats[-1])]},
    "outputs": ["yield-curves", "fx-spot-rates", "fx-forwards"],
}

When outputs is omitted, the API derives curve families from curve_labels (for example inflation labels yield inflation-curves; no automatic FX):

params = {
    "model_label": "YieldGAN-augur-v0.4-Q42020",
    "curve_labels": ["USA_Inflation"],
    "no_days": 5,
    "no_samples": 500,
    "reference_date": "2010-01-01",
}

Or request inflation explicitly:

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"],
}

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 controls for a day-1 move (omit controls entirely when unused — do not send null). Use the node key the model was trained / capability-gated for:

params = {
    "model_label": "YieldGAN-augur-v0.4-Q42020",
    "curve_labels": ["USA", "USD_SOFR_PROXY"],
    "no_days": 5,
    "no_samples": 1000,
    "reference_date": "2010-01-01",
    "outputs": ["yield-curves", "swap-curves", "fx-spot-rates"],
    "controls": {
        "swap-curves": {
            # Match the bundle's supported node (e.g. 10y or 2y), not a hardcoded tenor.
            "USD_SOFR_PROXY10.0Y": {"type": "day1_move", "move_bp": 25.0},
        },
    },
}
# When applied, metadata may include controls_applied echoing the request.

Multi-key swap-curves and swap-forwards are first-class in the schema (capability-gated to 400 until bundles support them):

params = {
    "model_label": "YieldGAN-augur-v0.4-Q42020",
    "curve_labels": ["USD_SOFR_PROXY"],
    "no_days": 5,
    "no_samples": 1000,
    "reference_date": "2010-01-01",
    "outputs": ["swap-curves"],
    "controls": {
        "swap-curves": {
            "USD_SOFR_PROXY2.0Y": {"type": "day1_move", "move_bp": 10.0},
            "USD_SOFR_PROXY10.0Y": {"type": "day1_move", "move_bp": 25.0},
        },
        # Or forwards (do not combine with swap-curves until the API allows it):
        # "swap-forwards": {
        #     "USD_SOFR_PROXY1.0Y1.0Y": {
        #         "type": "day1_forward_move",
        #         "move_bp": 5.0,
        #         "lift_mode": "deterministic",  # default: "sampled"
        #     },
        # },
    },
}

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},
    },
}

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).
# Swap-curve columns keep SC-* labels (not rewritten to yield-style names).

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 curve tenor column indices:

results.get_yc_indices()
# Output: [2, 3, 4, ...]
# Includes yield (YC-*/canonical) and swap (SC-*) tenor columns.

Get all curve tenor samples (as ndarray):

results.get_yc_samples()
# Output: ndarray of shape (samples, countries, days, maturities)
# Requires curve tenor columns: raises ValueError if the request omitted
# yield-curves / inflation-curves / swap-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 an interactive plotly.graph_objects.Figure. Set show_plot=True to display immediately in non-Jupyter environments. Charts share styling via synthera.plot_theme.

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: plotly.graph_objects.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: plotly.graph_objects.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: plotly.graph_objects.Figure

Plot distribution-aware quantiles across maturities:

results.plot_quantiles_curve(["USA", "GBR"], show_plot=True)
# Output: plotly.graph_objects.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: plotly.graph_objects.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.