Skip to content

gds.ir

Models

Bases: BaseModel

A complete composed system — the top-level IR unit.

Domain packages wrap this with additional metadata (e.g., terminal conditions, action spaces for open games).

Source code in packages/gds-framework/gds/ir/models.py 
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
class SystemIR(BaseModel):
    """A complete composed system — the top-level IR unit.

    Domain packages wrap this with additional metadata (e.g., terminal
    conditions, action spaces for open games).
    """

    name: str
    blocks: list[BlockIR] = Field(default_factory=list)
    wirings: list[WiringIR] = Field(default_factory=list)
    inputs: list[InputIR] = Field(default_factory=list)
    composition_type: CompositionType = CompositionType.SEQUENTIAL
    hierarchy: HierarchyNodeIR | None = None
    source: str = ""
    metadata: dict[str, Any] = Field(default_factory=dict)
    parameter_schema: ParameterSchema = Field(default_factory=ParameterSchema)

Bases: BaseModel

A single block in the flat IR representation.

The block_type is a plain string — domain packages define their own type taxonomies (e.g., "decision", "policy", "mechanism").

Source code in packages/gds-framework/gds/ir/models.py 
57
58
59
60
61
62
63
64
65
66
67
68
69
class BlockIR(BaseModel):
    """A single block in the flat IR representation.

    The ``block_type`` is a plain string — domain packages define their own
    type taxonomies (e.g., "decision", "policy", "mechanism").
    """

    name: str
    block_type: str = ""
    signature: tuple[str, str, str, str] = ("", "", "", "")
    logic: str = ""
    color_code: int = 1
    metadata: dict[str, Any] = Field(default_factory=dict)

Bases: BaseModel

A directed connection (edge) between blocks in the IR.

is_feedback and is_temporal flags distinguish special wiring categories for verification. The category field is an open string that domain packages can use for domain-specific edge classification; the generic protocol only interprets "dataflow".

Source code in packages/gds-framework/gds/ir/models.py 
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
class WiringIR(BaseModel):
    """A directed connection (edge) between blocks in the IR.

    ``is_feedback`` and ``is_temporal`` flags distinguish special wiring
    categories for verification. The ``category`` field is an open string
    that domain packages can use for domain-specific edge classification;
    the generic protocol only interprets ``"dataflow"``.
    """

    source: str
    target: str
    label: str
    wiring_type: str = ""
    direction: FlowDirection
    is_feedback: bool = False
    is_temporal: bool = False
    category: str = "dataflow"

Bases: BaseModel

An external input to the system.

Layer 0 defines only name and a generic metadata bag. Domain packages store their richer fields (e.g., input_type, schema_hint) inside metadata when projecting to SystemIR.

Source code in packages/gds-framework/gds/ir/models.py 
106
107
108
109
110
111
112
113
114
115
class InputIR(BaseModel, frozen=True):
    """An external input to the system.

    Layer 0 defines only ``name`` and a generic ``metadata`` bag.
    Domain packages store their richer fields (e.g., input_type, schema_hint)
    inside ``metadata`` when projecting to SystemIR.
    """

    name: str
    metadata: dict[str, Any] = Field(default_factory=dict)

Bases: BaseModel

A node in the composition tree for visualization.

Leaf nodes (composition_type=None) map 1:1 to a BlockIR. Interior nodes represent composition operators and contain children.

Source code in packages/gds-framework/gds/ir/models.py 
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
class HierarchyNodeIR(BaseModel):
    """A node in the composition tree for visualization.

    Leaf nodes (composition_type=None) map 1:1 to a BlockIR.
    Interior nodes represent composition operators and contain children.
    """

    id: str
    name: str
    composition_type: CompositionType | None = None
    children: list[HierarchyNodeIR] = Field(default_factory=list)
    block_name: str | None = None
    exit_condition: str = ""

Bases: StrEnum

Direction of an information flow in a block composition.

  • COVARIANT — forward data flow (forward_in → forward_out direction).
  • CONTRAVARIANT — backward feedback flow (backward_out → backward_in direction).
Source code in packages/gds-framework/gds/ir/models.py 
31
32
33
34
35
36
37
38
39
class FlowDirection(StrEnum):
    """Direction of an information flow in a block composition.

    - COVARIANT — forward data flow (forward_in → forward_out direction).
    - CONTRAVARIANT — backward feedback flow (backward_out → backward_in direction).
    """

    COVARIANT = "covariant"
    CONTRAVARIANT = "contravariant"

Bases: StrEnum

How blocks are composed within a system.

  • SEQUENTIAL — output of one feeds input of next (stack).
  • PARALLEL — blocks run side-by-side with no shared wires.
  • FEEDBACK — backward_out→backward_in connections within a timestep.
  • TEMPORAL — forward_out→forward_in connections across timesteps.
Source code in packages/gds-framework/gds/ir/models.py 
42
43
44
45
46
47
48
49
50
51
52
53
54
class CompositionType(StrEnum):
    """How blocks are composed within a system.

    - SEQUENTIAL — output of one feeds input of next (stack).
    - PARALLEL — blocks run side-by-side with no shared wires.
    - FEEDBACK — backward_out→backward_in connections within a timestep.
    - TEMPORAL — forward_out→forward_in connections across timesteps.
    """

    SEQUENTIAL = "sequential"
    PARALLEL = "parallel"
    FEEDBACK = "feedback"
    TEMPORAL = "temporal"

Utilities

Convert an arbitrary name to a valid IR/Mermaid identifier.

Replaces any character that is not alphanumeric or underscore with _. Prepends _ if the result starts with a digit.

Source code in packages/gds-framework/gds/ir/models.py 
19
20
21
22
23
24
25
26
27
28
def sanitize_id(name: str) -> str:
    """Convert an arbitrary name to a valid IR/Mermaid identifier.

    Replaces any character that is not alphanumeric or underscore with ``_``.
    Prepends ``_`` if the result starts with a digit.
    """
    sanitized = re.sub(r"[^A-Za-z0-9_]", "_", name)
    if sanitized and sanitized[0].isdigit():
        sanitized = "_" + sanitized
    return sanitized

Serialization

Bases: BaseModel

Top-level IR document containing one or more systems.

Source code in packages/gds-framework/gds/ir/serialization.py 
19
20
21
22
23
24
class IRDocument(BaseModel):
    """Top-level IR document containing one or more systems."""

    version: str = "1.0"
    systems: list[SystemIR]
    metadata: IRMetadata

Bases: BaseModel

Metadata envelope for an IR document.

Source code in packages/gds-framework/gds/ir/serialization.py 
11
12
13
14
15
16
class IRMetadata(BaseModel):
    """Metadata envelope for an IR document."""

    sources: list[str] = Field(default_factory=list)
    generated_at: datetime = Field(default_factory=lambda: datetime.now(UTC))
    version: str = "0.2.1"

Serialize an IR document to JSON.

Source code in packages/gds-framework/gds/ir/serialization.py 
27
28
29
def save_ir(doc: IRDocument, path: Path) -> None:
    """Serialize an IR document to JSON."""
    path.write_text(doc.model_dump_json(indent=2))

Deserialize an IR document from JSON.

Source code in packages/gds-framework/gds/ir/serialization.py 
32
33
34
def load_ir(path: Path) -> IRDocument:
    """Deserialize an IR document from JSON."""
    return IRDocument.model_validate_json(path.read_text())