Functional overview

Tiny DSA is organized around a small generated Python API rather than direct workbook navigation. The workflow has three layers:

Create an evaluation context with make_context().
Configure the scenario with set_* functions.
Read the public output series with compute_* functions.

The same conceptual separation is preserved from the workbook design: inputs feed the calculation layer, and downstream consumers should read only the stable output functions. Internal baseline and shocked paths are calculation surfaces; production code should use compute_output_baseline, compute_output_shocked, and compute_output_delta.

A. API management rules

Tiny DSA’s Python interface replaces workbook formatting conventions with explicit function boundaries:

User-editable inputs are set through set_* functions.
Country profile initial-debt values are loaded by default and can be updated for existing profile countries with set_country_initial_debt when required.
Computed outputs are read-only from the caller’s perspective. Do not write output values into the context; call the relevant compute_* function instead.
Intermediate calculation ranges are not part of the stable public API.

The workbook’s number formats are not applied by the API. Computed records return numeric values, and presentation code should format ratios, signed deltas, and shock magnitudes as needed.

Use the documented input domains when configuring scenarios:

set_country_name selects the country profile. The setter checks record structure but does not, by itself, validate the country name against the profile table.
set_shock_year is intended for projection years 1 through 5.
set_shock_type uses 1 for real GDP growth, 2 for the real interest rate, and 3 for the primary balance.

The stable Python contract is summarized below.

Workbook concept	Python API	Role
Selected country	set_country_name	Sets the country used to resolve initial debt-to-GDP from the profile data
Country initial debt profile	set_country_initial_debt	Updates initial debt-to-GDP values for keyed country records when a profile override is needed
Baseline real GDP growth	set_growth_baseline	Sets the five-year growth path
Baseline real interest rate	set_interest_baseline	Sets the five-year interest-rate path
Baseline primary balance	set_primary_balance_baseline	Sets the five-year primary-balance path
Shock year	set_shock_year	Sets the first projection year in which the shock applies
Shock type	set_shock_type	Selects the affected parameter: growth, interest, or primary balance
Shock magnitudes	set_shock_magnitudes	Sets the available shock magnitudes by shock parameter
Baseline output path	compute_output_baseline	Returns the public baseline debt-to-GDP series
Shocked output path	compute_output_shocked	Returns the public shocked debt-to-GDP series
Shock impact	compute_output_delta	Returns shocked minus baseline, in percentage points

B. Selecting a country

The first scenario input is the country name. In Python, create a context and set the selected country with set_country_name(ctx, "Borvelia") or another supported profile name.

Tiny DSA ships with a small profile table containing Borvelia, Litellia, and Aurelium. Their default initial debt-to-GDP ratios are 60.0, 80.0, and 40.0 percent of GDP, respectively. The selected country drives the initial-debt lookup used in the debt path calculations.

In normal use, treat the profile data as reference data. If a scenario requires an override to an existing country profile, use set_country_initial_debt with keyed records containing COUNTRY and OBS_VALUE.

C. Setting the baseline parameters

The baseline scenario is defined by three five-period series:

set_growth_baseline sets real GDP growth, in percent per annum.
set_interest_baseline sets the effective real interest rate on outstanding government debt, in percent per annum.
set_primary_balance_baseline sets the primary balance, in percent of GDP; positive values denote a surplus.

Series setters accept either a one-dimensional sequence in projection-year order or keyed records with TIME_PERIOD and OBS_VALUE. For example, [3.5, 3.5, 3.5, 3.5, 3.5] sets years 1 through 5 in order.

The default baseline is a flat 3.5 percent growth path, a flat 4.0 percent real interest-rate path, and a fiscal-consolidation path from a primary deficit of 1.0 percent of GDP in year 1 to a surplus of 1.0 percent of GDP in year 5.

D. Configuring the shock

The shock is defined by three inputs:

set_shock_year sets the first year in which the shock takes effect. The shock applies from that year through the end of the five-year horizon.
set_shock_type selects the affected parameter: 1 for growth, 2 for interest, and 3 for primary balance.
set_shock_magnitudes sets the available magnitude for each shock parameter.

The default configuration is a growth shock beginning in year 2. The default magnitudes are -2.0 percentage points for growth, +2.0 percentage points for interest, and -1.0 percentage point for the primary balance. Only the magnitude associated with the selected shock type is applied in a given run.

E. Reading the outputs

The output API returns three public time series for years 1 through 5:

compute_output_baseline(ctx=ctx) returns the baseline debt-to-GDP path.
compute_output_shocked(ctx=ctx) returns the shocked debt-to-GDP path.
compute_output_delta(ctx=ctx) returns shocked minus baseline, in percentage points.

Each compute function returns a list of records with TIME_PERIOD, OBS_VALUE, and output metadata fields such as SCENARIO and UNIT_MEASURE. Convert these records to a Polars DataFrame for reporting or downstream processing.

import polars as pl

from tiny_dsa.api import (
    make_context,
    set_country_name,
    set_growth_baseline,
    set_interest_baseline,
    set_primary_balance_baseline,
    set_shock_year,
    set_shock_type,
    set_shock_magnitudes,
    compute_output_baseline,
    compute_output_shocked,
    compute_output_delta,
)


def path_frame(records: list[dict[str, object]], alias: str) -> pl.DataFrame:
    return (
        pl.DataFrame(records)
        .sort("TIME_PERIOD")
        .select(
            "TIME_PERIOD",
            pl.col("OBS_VALUE").alias(alias),
        )
    )


ctx = make_context()

set_country_name(ctx, "Borvelia")
set_growth_baseline(ctx, [3.5, 3.5, 3.5, 3.5, 3.5])
set_interest_baseline(ctx, [4.0, 4.0, 4.0, 4.0, 4.0])
set_primary_balance_baseline(ctx, [-1.0, -0.5, 0.0, 0.5, 1.0])
set_shock_year(ctx, 2)
set_shock_type(ctx, 1)
set_shock_magnitudes(
    ctx,
    [
        {"SHOCK_PARAMETER": "Growth", "OBS_VALUE": -2.0},
        {"SHOCK_PARAMETER": "Interest", "OBS_VALUE": 2.0},
        {"SHOCK_PARAMETER": "Primary balance", "OBS_VALUE": -1.0},
    ],
)

baseline = path_frame(compute_output_baseline(ctx=ctx), "Baseline debt (% GDP)")
shocked = path_frame(compute_output_shocked(ctx=ctx), "Shocked debt (% GDP)")
delta = path_frame(compute_output_delta(ctx=ctx), "Delta (pp)")

output = baseline.join(shocked, on="TIME_PERIOD").join(delta, on="TIME_PERIOD")
output

shape: (5, 4)

TIME_PERIOD	Baseline debt (% GDP)	Shocked debt (% GDP)	Delta (pp)
i64	f64	f64	f64
1	61.289855	61.289855	0.0
2	62.085941	63.299457	1.213516
3	62.385873	64.858557	2.472684
4	62.187254	65.956059	3.768804
5	61.487676	66.580592	5.092916

This table is the Python equivalent of the workbook’s public Outputs sheet. Keep scenario context such as country name, shock year, and shock type in the calling code or adjacent metadata, and use the compute functions as the stable read-only interface for trajectory values.