Skip to content

ogs.dsl.pattern

Bases: BaseModel

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

Source code in packages/gds-games/ogs/dsl/pattern.py 
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 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
class Pattern(BaseModel):
    """A complete named composite pattern — the top-level specification unit."""

    name: str
    game: OpenGame
    inputs: list[PatternInput] = []
    composition_type: CompositionType = CompositionType.FEEDBACK
    terminal_conditions: list[TerminalCondition] | None = None
    action_spaces: list[ActionSpace] | None = None
    initializations: list[StateInitialization] | None = None
    source: str = "dsl"

    def specialize(
        self,
        name: str,
        terminal_conditions: list[TerminalCondition] | None = None,
        action_spaces: list[ActionSpace] | None = None,
        initializations: list[StateInitialization] | None = None,
        inputs: list[PatternInput] | None = None,
        composition_type: CompositionType | None = None,
        source: str | None = None,
    ) -> Pattern:
        """Create a derived pattern that inherits this pattern's game tree.

        Produces a new ``Pattern`` with the same ``game`` composition tree,
        overriding only the fields explicitly provided.  ``inputs`` are
        inherited from the base pattern unless a replacement list is supplied,
        preventing the input-drift problem where derived patterns silently fall
        out of sync with their base.

        Args:
            name: Required name for the derived pattern.
            terminal_conditions: Domain-specific terminal conditions.  Replaces
                the base value if provided; otherwise inherits.
            action_spaces: Domain-specific action spaces.  Replaces the base
                value if provided; otherwise inherits.
            initializations: Domain-specific state initializations.  Replaces
                the base value if provided; otherwise inherits.
            inputs: If provided, replaces the inherited ``PatternInput`` list
                entirely.  If omitted, a copy of the base pattern's inputs is
                used.
            composition_type: Override the composition type.  Defaults to the
                base pattern's ``composition_type``.
            source: Override the provenance tag.  Defaults to the base
                pattern's ``source``.

        Returns:
            A new ``Pattern`` instance.  The ``game`` object is shared (not
            deep-copied) — modifications to the game tree after calling
            ``specialize()`` will affect both patterns.

        Example::

            from patterns.multi_party_agreement_zoomed_in import pattern as base

            resource_exchange = base.specialize(
                name="Multi-Party Resource Exchange",
                terminal_conditions=[
                    TerminalCondition(name="Agreement", actions={...}, outcome="..."),
                ],
                action_spaces=[
                    ActionSpace(game="Agent 1 Reactive Decision", actions=["accept", "reject"]),
                ],
                # inputs inherited from base automatically
            )
        """
        return Pattern(
            name=name,
            game=self.game,
            inputs=list(inputs) if inputs is not None else list(self.inputs),
            composition_type=composition_type
            if composition_type is not None
            else self.composition_type,
            terminal_conditions=terminal_conditions
            if terminal_conditions is not None
            else self.terminal_conditions,
            action_spaces=action_spaces
            if action_spaces is not None
            else self.action_spaces,
            initializations=initializations
            if initializations is not None
            else self.initializations,
            source=source if source is not None else self.source,
        )

    # ── Compilation ─────────────────────────────────────────

    def compile(self) -> GDSSpec:
        """Compile this pattern to a GDS specification."""
        from ogs.dsl.spec_bridge import compile_pattern_to_spec

        return compile_pattern_to_spec(self)

    def compile_system(self) -> SystemIR:
        """Compile this pattern to a flat SystemIR for verification + visualization."""
        from ogs.dsl.compile import compile_to_ir

        return compile_to_ir(self).to_system_ir()

specialize(name, terminal_conditions=None, action_spaces=None, initializations=None, inputs=None, composition_type=None, source=None)

Create a derived pattern that inherits this pattern's game tree.

Produces a new Pattern with the same game composition tree, overriding only the fields explicitly provided. inputs are inherited from the base pattern unless a replacement list is supplied, preventing the input-drift problem where derived patterns silently fall out of sync with their base.

Parameters:

Name Type Description Default
name str

Required name for the derived pattern.

 required
terminal_conditions list[TerminalCondition] | None

Domain-specific terminal conditions. Replaces the base value if provided; otherwise inherits.

 None
action_spaces list[ActionSpace] | None

Domain-specific action spaces. Replaces the base value if provided; otherwise inherits.

 None
initializations list[StateInitialization] | None

Domain-specific state initializations. Replaces the base value if provided; otherwise inherits.

 None
inputs list[PatternInput] | None

If provided, replaces the inherited PatternInput list entirely. If omitted, a copy of the base pattern's inputs is used.

 None
composition_type CompositionType | None

Override the composition type. Defaults to the base pattern's composition_type.

 None
source str | None

Override the provenance tag. Defaults to the base pattern's source.

 None

Returns:

Type Description
Pattern

A new Pattern instance. The game object is shared (not
Pattern

deep-copied) — modifications to the game tree after calling
Pattern

specialize() will affect both patterns.

Example::

from patterns.multi_party_agreement_zoomed_in import pattern as base

resource_exchange = base.specialize(
    name="Multi-Party Resource Exchange",
    terminal_conditions=[
        TerminalCondition(name="Agreement", actions={...}, outcome="..."),
    ],
    action_spaces=[
        ActionSpace(game="Agent 1 Reactive Decision", actions=["accept", "reject"]),
    ],
    # inputs inherited from base automatically
)
Source code in packages/gds-games/ogs/dsl/pattern.py 
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 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
def specialize(
    self,
    name: str,
    terminal_conditions: list[TerminalCondition] | None = None,
    action_spaces: list[ActionSpace] | None = None,
    initializations: list[StateInitialization] | None = None,
    inputs: list[PatternInput] | None = None,
    composition_type: CompositionType | None = None,
    source: str | None = None,
) -> Pattern:
    """Create a derived pattern that inherits this pattern's game tree.

    Produces a new ``Pattern`` with the same ``game`` composition tree,
    overriding only the fields explicitly provided.  ``inputs`` are
    inherited from the base pattern unless a replacement list is supplied,
    preventing the input-drift problem where derived patterns silently fall
    out of sync with their base.

    Args:
        name: Required name for the derived pattern.
        terminal_conditions: Domain-specific terminal conditions.  Replaces
            the base value if provided; otherwise inherits.
        action_spaces: Domain-specific action spaces.  Replaces the base
            value if provided; otherwise inherits.
        initializations: Domain-specific state initializations.  Replaces
            the base value if provided; otherwise inherits.
        inputs: If provided, replaces the inherited ``PatternInput`` list
            entirely.  If omitted, a copy of the base pattern's inputs is
            used.
        composition_type: Override the composition type.  Defaults to the
            base pattern's ``composition_type``.
        source: Override the provenance tag.  Defaults to the base
            pattern's ``source``.

    Returns:
        A new ``Pattern`` instance.  The ``game`` object is shared (not
        deep-copied) — modifications to the game tree after calling
        ``specialize()`` will affect both patterns.

    Example::

        from patterns.multi_party_agreement_zoomed_in import pattern as base

        resource_exchange = base.specialize(
            name="Multi-Party Resource Exchange",
            terminal_conditions=[
                TerminalCondition(name="Agreement", actions={...}, outcome="..."),
            ],
            action_spaces=[
                ActionSpace(game="Agent 1 Reactive Decision", actions=["accept", "reject"]),
            ],
            # inputs inherited from base automatically
        )
    """
    return Pattern(
        name=name,
        game=self.game,
        inputs=list(inputs) if inputs is not None else list(self.inputs),
        composition_type=composition_type
        if composition_type is not None
        else self.composition_type,
        terminal_conditions=terminal_conditions
        if terminal_conditions is not None
        else self.terminal_conditions,
        action_spaces=action_spaces
        if action_spaces is not None
        else self.action_spaces,
        initializations=initializations
        if initializations is not None
        else self.initializations,
        source=source if source is not None else self.source,
    )

compile()

Compile this pattern to a GDS specification.

Source code in packages/gds-games/ogs/dsl/pattern.py 
151
152
153
154
155
def compile(self) -> GDSSpec:
    """Compile this pattern to a GDS specification."""
    from ogs.dsl.spec_bridge import compile_pattern_to_spec

    return compile_pattern_to_spec(self)

compile_system()

Compile this pattern to a flat SystemIR for verification + visualization.

Source code in packages/gds-games/ogs/dsl/pattern.py 
157
158
159
160
161
def compile_system(self) -> SystemIR:
    """Compile this pattern to a flat SystemIR for verification + visualization."""
    from ogs.dsl.compile import compile_to_ir

    return compile_to_ir(self).to_system_ir()

Bases: BaseModel

An external input that crosses the pattern boundary.

Links to a target game via target_game and flow_label so the compiler can generate input→game flows automatically.

Source code in packages/gds-games/ogs/dsl/pattern.py 
18
19
20
21
22
23
24
25
26
27
28
29
class PatternInput(BaseModel):
    """An external input that crosses the pattern boundary.

    Links to a target game via ``target_game`` and ``flow_label``
    so the compiler can generate input→game flows automatically.
    """

    name: str
    input_type: InputType
    schema_hint: str = ""
    target_game: str = ""
    flow_label: str = ""

Bases: BaseModel

A condition under which a corecursive loop should terminate.

Each terminal condition specifies a combination of actions from named games (or agents) that triggers termination, along with the resulting outcome and optional payoff description.

Source code in packages/gds-games/ogs/dsl/pattern.py 
32
33
34
35
36
37
38
39
40
41
42
43
44
class TerminalCondition(BaseModel):
    """A condition under which a corecursive loop should terminate.

    Each terminal condition specifies a combination of actions from
    named games (or agents) that triggers termination, along with the
    resulting outcome and optional payoff description.
    """

    name: str
    actions: dict[str, str]
    outcome: str
    description: str = ""
    payoff_description: str = ""

Bases: BaseModel

The set of available actions for a decision game, with optional constraints.

Source code in packages/gds-games/ogs/dsl/pattern.py 
47
48
49
50
51
52
class ActionSpace(BaseModel):
    """The set of available actions for a decision game, with optional constraints."""

    game: str
    actions: list[str]
    constraints: list[str] = Field(default_factory=list)

Bases: BaseModel

An initial state variable for simulation in mathematical notation.

Source code in packages/gds-games/ogs/dsl/pattern.py 
55
56
57
58
59
60
61
class StateInitialization(BaseModel):
    """An initial state variable for simulation in mathematical notation."""

    symbol: str
    space: str
    description: str = ""
    game: str = ""