Skip to content

ogs.ir

Models

Bases: BaseModel

A single open game component in the flat IR representation.

Source code in packages/gds-games/ogs/ir/models.py 
25
26
27
28
29
30
31
32
33
34
35
36
37
class OpenGameIR(BaseModel):
    """A single open game component in the flat IR representation."""

    name: str
    game_type: GameType
    signature: tuple[str, str, str, str]  # (X, Y, R, S)
    logic: str = ""
    gds_function: str | None = None
    constraints: list[str] = Field(default_factory=list)
    parent_pattern: str | None = None
    color_code: int
    contained_nodes: list[str] = Field(default_factory=list)
    tags: dict[str, str] = Field(default_factory=dict)

Bases: BaseModel

A directed information flow (edge) between components in the IR.

Source code in packages/gds-games/ogs/ir/models.py 
40
41
42
43
44
45
46
47
48
49
class FlowIR(BaseModel):
    """A directed information flow (edge) between components in the IR."""

    source: str
    target: str
    label: str
    flow_type: FlowType
    direction: FlowDirection
    is_feedback: bool = False
    is_corecursive: bool = False

Bases: BaseModel

A complete composite pattern — the top-level unit of specification.

Source code in packages/gds-games/ogs/ir/models.py 
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
class PatternIR(BaseModel):
    """A complete composite pattern — the top-level unit of specification."""

    name: str
    games: list[OpenGameIR] = Field(default_factory=list)
    flows: list[FlowIR] = Field(default_factory=list)
    inputs: list[InputIR] = Field(default_factory=list)
    composition_type: CompositionType
    terminal_conditions: list[TerminalCondition] | None = None
    action_spaces: list[ActionSpace] | None = None
    initialization: list[StateInitialization] | None = None
    hierarchy: HierarchyNodeIR | None = None
    source_canvas: str
    source_spec_notes: str | None = None

    def to_system_ir(self) -> SystemIR:
        """Project this OGS PatternIR to a GDS SystemIR.

        Enables interop with any GDS tool that accepts SystemIR, including
        GDS generic verification checks (G-001 through G-006).

        Mapping:
        - OpenGameIR → BlockIR (game_type → block_type, constraints/tags → metadata)
        - FlowIR → WiringIR (flow_type → wiring_type, is_corecursive → is_temporal)
        - OGS CORECURSIVE → GDS TEMPORAL
        """
        from gds.ir.models import BlockIR, SystemIR, WiringIR
        from gds.ir.models import CompositionType as GDSCompositionType
        from gds.ir.models import InputIR as GDSInputIR

        blocks = [
            BlockIR(
                name=g.name,
                block_type=g.game_type.value,
                signature=g.signature,
                logic=g.logic,
                color_code=g.color_code,
                metadata={"constraints": g.constraints, "tags": g.tags},
            )
            for g in self.games
        ]

        wirings = [
            WiringIR(
                source=f.source,
                target=f.target,
                label=f.label,
                wiring_type=f.flow_type.value,
                direction=f.direction,
                is_feedback=f.is_feedback,
                is_temporal=f.is_corecursive,
            )
            for f in self.flows
        ]

        # Map OGS composition types to GDS (CORECURSIVE → TEMPORAL)
        comp_map = {
            "sequential": "SEQUENTIAL",
            "parallel": "PARALLEL",
            "feedback": "FEEDBACK",
            "corecursive": "TEMPORAL",
        }
        gds_comp = GDSCompositionType[comp_map[self.composition_type.value]]

        inputs = [
            GDSInputIR(
                name=i.name,
                metadata={
                    "input_type": i.input_type.value,
                    "schema_hint": i.schema_hint,
                    "shape": i.shape,
                },
            )
            for i in self.inputs
        ]

        return SystemIR(
            name=self.name,
            blocks=blocks,
            wirings=wirings,
            inputs=inputs,
            composition_type=gds_comp,
            source=self.source_canvas,
        )

to_system_ir()

Project this OGS PatternIR to a GDS SystemIR.

Enables interop with any GDS tool that accepts SystemIR, including GDS generic verification checks (G-001 through G-006).

Mapping: - OpenGameIR → BlockIR (game_type → block_type, constraints/tags → metadata) - FlowIR → WiringIR (flow_type → wiring_type, is_corecursive → is_temporal) - OGS CORECURSIVE → GDS TEMPORAL

Source code in packages/gds-games/ogs/ir/models.py 
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
def to_system_ir(self) -> SystemIR:
    """Project this OGS PatternIR to a GDS SystemIR.

    Enables interop with any GDS tool that accepts SystemIR, including
    GDS generic verification checks (G-001 through G-006).

    Mapping:
    - OpenGameIR → BlockIR (game_type → block_type, constraints/tags → metadata)
    - FlowIR → WiringIR (flow_type → wiring_type, is_corecursive → is_temporal)
    - OGS CORECURSIVE → GDS TEMPORAL
    """
    from gds.ir.models import BlockIR, SystemIR, WiringIR
    from gds.ir.models import CompositionType as GDSCompositionType
    from gds.ir.models import InputIR as GDSInputIR

    blocks = [
        BlockIR(
            name=g.name,
            block_type=g.game_type.value,
            signature=g.signature,
            logic=g.logic,
            color_code=g.color_code,
            metadata={"constraints": g.constraints, "tags": g.tags},
        )
        for g in self.games
    ]

    wirings = [
        WiringIR(
            source=f.source,
            target=f.target,
            label=f.label,
            wiring_type=f.flow_type.value,
            direction=f.direction,
            is_feedback=f.is_feedback,
            is_temporal=f.is_corecursive,
        )
        for f in self.flows
    ]

    # Map OGS composition types to GDS (CORECURSIVE → TEMPORAL)
    comp_map = {
        "sequential": "SEQUENTIAL",
        "parallel": "PARALLEL",
        "feedback": "FEEDBACK",
        "corecursive": "TEMPORAL",
    }
    gds_comp = GDSCompositionType[comp_map[self.composition_type.value]]

    inputs = [
        GDSInputIR(
            name=i.name,
            metadata={
                "input_type": i.input_type.value,
                "schema_hint": i.schema_hint,
                "shape": i.shape,
            },
        )
        for i in self.inputs
    ]

    return SystemIR(
        name=self.name,
        blocks=blocks,
        wirings=wirings,
        inputs=inputs,
        composition_type=gds_comp,
        source=self.source_canvas,
    )

Bases: HierarchyNodeIR

OGS hierarchy node — extends GDS with CORECURSIVE composition type.

Inherits id, name, block_name, exit_condition, and children from GDS. Overrides composition_type to use the OGS enum which includes CORECURSIVE (mapped to GDS TEMPORAL).

The game_name property is a backwards-compatible alias for block_name (inherited from GDS).

Source code in packages/gds-games/ogs/ir/models.py 
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
class HierarchyNodeIR(_GDSHierarchyNodeIR):
    """OGS hierarchy node — extends GDS with CORECURSIVE composition type.

    Inherits ``id``, ``name``, ``block_name``, ``exit_condition``, and
    ``children`` from GDS. Overrides ``composition_type`` to use the OGS
    enum which includes CORECURSIVE (mapped to GDS TEMPORAL).

    The ``game_name`` property is a backwards-compatible alias for
    ``block_name`` (inherited from GDS).
    """

    composition_type: CompositionType | None = None  # type: ignore[assignment]  # OGS enum (has CORECURSIVE)
    children: list[HierarchyNodeIR] = Field(default_factory=list)  # type: ignore[assignment]

    @property
    def game_name(self) -> str | None:
        """Backwards-compatible alias for ``block_name``."""
        return self.block_name

game_name property

Backwards-compatible alias for block_name.

Serialization

Bases: BaseModel

Top-level IR document containing one or more patterns.

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

    version: str = "1.0"
    patterns: list[PatternIR]
    metadata: IRMetadata

Serialize an IR document to JSON.

Source code in packages/gds-games/ogs/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-games/ogs/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())