Skip to content

Manifest

@dataclass
class Manifest()

Manifest is the schema for manifest.json at the root of every .sdsge archive. It indexes the included members, records provenance, and (optionally) carries the simulation prefill inline.

Fields:

Name Type Description
created_by str Library version string. Defaults to "SymbolicDSGE <version>" when produced by BundleBuilder.
created_at str \| None UTC ISO-8601 timestamp set at write time.
sdsge_version int Format version. Readers reject bundles with sdsge_version > SDSGE_FORMAT_VERSION.
members list[Member] Member inventory — every archive entry has one.
simulation SimSpec \| None Inline simulation prefill (no separate member).
checksums dict[str, str] SHA-256 hex digests keyed by member path.

Methods:

Manifest.members_by_kind(
    kind: str,
) -> list[Member]

Return every member with the given kind (e.g. "model_config", "estimation_data").

Manifest.model_member(
    role: str,
) -> Member | None

Convenience accessor — return the model_config member with the given role ("reference" or "dgp"), or None if absent.

Manifest.to_dict() -> dict[str, Any]
Manifest.to_json(*, indent: int | None = 2) -> str
Manifest.from_dict(data: Mapping[str, Any]) -> Manifest      # @classmethod
Manifest.from_json(text: str) -> Manifest                    # @classmethod

Round-trippable JSON shape. from_dict / from_json validate sdsge_version and raise ValueError when the bundle is newer than the installed library supports.

Forward / backward compatibility

Readers are forward-tolerant on older versions (a v1 reader opens v1 bundles) but strict on newer ones (a v1 reader refuses a v2 bundle). Bump SDSGE_FORMAT_VERSION only on breaking manifest changes.

Member

@dataclass
class Member()

One archive entry described in the manifest.

Fields:

Name Type Description
path str POSIX path inside the archive (e.g. model/reference.yaml).
kind str Semantic kind — one of MEMBER_KINDS (see below).
format str "yaml" / "json" / "csv" / "parquet". Inferred from path extension when omitted on construction.
role str \| None "reference" / "dgp" for model members.
columns list[str] \| None Column names for tabular members (e.g. observable names on estimation_data).
options dict[str, Any] Kind-specific metadata. For model_config this carries compile_kwargs / solve_kwargs.

Recognized kinds (MEMBER_KINDS):

Kind Purpose
model_config YAML configuration for a role.
raw_data Raw observable file (CSV or Parquet).
estimation_spec EstimationSpec JSON.
estimation_result Wrapped {"type": "mcmc" \| "optimization", "data": {...}}.
estimation_data Observed y matrix (CSV or Parquet).
estimation_trace MCMC posterior columns (CSV or Parquet).
mc_pipeline PipelineSpec JSON.
mc_result Trace-free MC run document (JSON).
mc_trace MC trace columns (CSV or Parquet).
mc_raw_data Raw-data arrays referenced by MC raw_data nodes.
mc_custom_op Bundle-safe custom operation referenced by MC custom nodes.
Kind whitelist

Member.__post_init__ raises ValueError for any kind outside MEMBER_KINDS. Adding a new kind requires bumping SDSGE_FORMAT_VERSION so older readers don't silently drop it.

SimSpec

@dataclass
class SimSpec()

Simulation prefill — the receiver clicks Run in the GUI to reproduce the author's intended simulation. Stored inline in Manifest.simulation, not as a member.

Fields:

Name Type Description
role str Active model slot — typically "reference".
T int Periods to simulate.
observables bool Include observable paths in the output.
shock_scale float Multiplier applied to all shocks.
shock_generation ShockGeneration \| None RNG settings; None if raw shock paths are supplied instead.
shock_std dict[str, float] Per-shock standard deviation overrides.
shock_corr dict[str, float] Pairwise shock correlation overrides keyed by "a,b" syntax.
shocks dict[str, list[float]] \| None Optional raw shock paths inline.
Determinism

Sim results are not stored. Replaying the prefill against the preloaded model reproduces the intended run because numpy PCG64 + a fixed ShockGeneration.seed are deterministic.

ShockGeneration

@dataclass
class ShockGeneration()

RNG settings for replayed shock generation.

Fields:

Name Type Description
dist str Distribution name — "norm" / "t" / "uni".
seed int \| None RNG seed for reproducibility.
loc float Location parameter.
df float Degrees of freedom (Student's t).

Example

from SymbolicDSGE.bundle import Manifest, Member, SimSpec, ShockGeneration

manifest = Manifest(
    created_by="experiment-1",
    members=[
        Member(
            path="model/reference.yaml",
            kind="model_config",
            role="reference",
            options={"compile_kwargs": {"linearize": False}},
        ),
        Member(
            path="estimation/spec.json",
            kind="estimation_spec",
        ),
        Member(
            path="estimation/observed.csv",
            kind="estimation_data",
            columns=["Infl", "Rate"],
        ),
    ],
    simulation=SimSpec(
        role="reference",
        T=25,
        shock_generation=ShockGeneration(seed=42),
    ),
)

print(manifest.to_json())

See also