gds-framework 0.2.0__py3-none-any.whl

gds/__init__.py

@@ -0,0 +1,175 @@
+"""Generalized Dynamical Systems — typed compositional specifications for complex systems.
+
+GDS synthesizes ideas from GDS theory (Roxin, Zargham & Shorish), MSML (BlockScience),
+BDP-lib (Block Diagram Protocol), and categorical cybernetics (Ghani, Hedges et al.)
+into a single, dependency-light Python framework.
+"""
+
+__version__ = "0.1.0"
+
+# ── Composition algebra ─────────────────────────────────────
+from gds.blocks.base import AtomicBlock, Block
+from gds.blocks.composition import (
+    FeedbackLoop,
+    ParallelComposition,
+    StackComposition,
+    TemporalLoop,
+    Wiring,
+)
+from gds.blocks.errors import GDSCompositionError, GDSError, GDSTypeError
+
+# ── GDS block roles ─────────────────────────────────────────
+from gds.blocks.roles import (
+    BoundaryAction,
+    ControlAction,
+    HasConstraints,
+    HasOptions,
+    HasParams,
+    Mechanism,
+    Policy,
+)
+
+# ── Canonical projection ───────────────────────────────────
+from gds.canonical import CanonicalGDS, project_canonical
+from gds.compiler.compile import compile_system
+
+# ── Convenience helpers ────────────────────────────────────
+from gds.helpers import (
+    all_checks,
+    entity,
+    gds_check,
+    get_custom_checks,
+    interface,
+    space,
+    state_var,
+    typedef,
+)
+
+# ── IR and serialization ────────────────────────────────────
+from gds.ir.models import (
+    BlockIR,
+    CompositionType,
+    FlowDirection,
+    HierarchyNodeIR,
+    SystemIR,
+    WiringIR,
+)
+from gds.ir.serialization import IRDocument, IRMetadata, load_ir, save_ir
+
+# ── Parameters ─────────────────────────────────────────────
+from gds.parameters import ParameterDef, ParameterSchema
+
+# ── Query engine ────────────────────────────────────────────
+from gds.query import SpecQuery
+from gds.serialize import spec_to_dict, spec_to_json
+
+# ── Typed spaces and state ──────────────────────────────────
+from gds.spaces import EMPTY, TERMINAL, Space
+
+# ── Specification registry ──────────────────────────────────
+from gds.spec import GDSSpec, SpecWiring, Wire
+from gds.state import Entity, StateVariable
+from gds.tagged import Tagged
+from gds.types.interface import Interface, Port, port
+from gds.types.tokens import tokenize, tokens_overlap, tokens_subset
+
+# ── Type system ─────────────────────────────────────────────
+from gds.types.typedef import (
+    AgentID,
+    NonNegativeFloat,
+    PositiveInt,
+    Probability,
+    Timestamp,
+    TokenAmount,
+    TypeDef,
+)
+
+# ── Verification ────────────────────────────────────────────
+from gds.verification.engine import verify
+from gds.verification.findings import Finding, Severity, VerificationReport
+from gds.verification.spec_checks import (
+    check_canonical_wellformedness,
+    check_completeness,
+    check_determinism,
+    check_parameter_references,
+    check_reachability,
+    check_type_safety,
+)
+
+__all__ = [
+    "EMPTY",
+    "TERMINAL",
+    "AgentID",
+    "AtomicBlock",
+    "Block",
+    "BlockIR",
+    "BoundaryAction",
+    "CanonicalGDS",
+    "CompositionType",
+    "ControlAction",
+    "Entity",
+    "FeedbackLoop",
+    "Finding",
+    "FlowDirection",
+    "GDSCompositionError",
+    "GDSError",
+    "GDSSpec",
+    "GDSTypeError",
+    "HasConstraints",
+    "HasOptions",
+    "HasParams",
+    "HierarchyNodeIR",
+    "IRDocument",
+    "IRMetadata",
+    "Interface",
+    "Mechanism",
+    "NonNegativeFloat",
+    "ParallelComposition",
+    "ParameterDef",
+    "ParameterSchema",
+    "Policy",
+    "Port",
+    "PositiveInt",
+    "Probability",
+    "Severity",
+    "Space",
+    "SpecQuery",
+    "SpecWiring",
+    "StackComposition",
+    "StateVariable",
+    "SystemIR",
+    "Tagged",
+    "TemporalLoop",
+    "Timestamp",
+    "TokenAmount",
+    "TypeDef",
+    "VerificationReport",
+    "Wire",
+    "Wiring",
+    "WiringIR",
+    "all_checks",
+    "check_canonical_wellformedness",
+    "check_completeness",
+    "check_determinism",
+    "check_parameter_references",
+    "check_reachability",
+    "check_type_safety",
+    "compile_system",
+    "entity",
+    "gds_check",
+    "get_custom_checks",
+    "interface",
+    "load_ir",
+    "port",
+    "project_canonical",
+    "save_ir",
+    "space",
+    "spec_to_dict",
+    "spec_to_json",
+    "state_var",
+    "tokenize",
+    "tokens_overlap",
+    "tokens_subset",
+    "typedef",
+    "verify",
+]

gds/blocks/__init__.py

@@ -0,0 +1,29 @@
+"""Block primitives, composition operators, and GDS roles."""
+
+from gds.blocks.base import AtomicBlock, Block
+from gds.blocks.composition import (
+    FeedbackLoop,
+    ParallelComposition,
+    StackComposition,
+    TemporalLoop,
+    Wiring,
+)
+from gds.blocks.errors import GDSCompositionError, GDSError, GDSTypeError
+from gds.blocks.roles import BoundaryAction, ControlAction, Mechanism, Policy
+
+__all__ = [
+    "AtomicBlock",
+    "Block",
+    "BoundaryAction",
+    "ControlAction",
+    "FeedbackLoop",
+    "GDSCompositionError",
+    "GDSError",
+    "GDSTypeError",
+    "Mechanism",
+    "ParallelComposition",
+    "Policy",
+    "StackComposition",
+    "TemporalLoop",
+    "Wiring",
+]

gds/blocks/base.py

@@ -0,0 +1,91 @@
+"""Abstract base class for Blocks in the GDS framework.
+
+A Block is the fundamental composable unit. It has a name and an Interface
+(directional port pairs). Composition operators build composite blocks
+from simpler ones, forming a tree that the compiler flattens into a list
+of atomic blocks + wiring.
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import TYPE_CHECKING
+
+from gds.tagged import Tagged
+from gds.types.interface import Interface
+
+if TYPE_CHECKING:
+    from gds.blocks.composition import (
+        FeedbackLoop,
+        ParallelComposition,
+        StackComposition,
+        TemporalLoop,
+        Wiring,
+    )
+
+
+class Block(Tagged, ABC):
+    """Abstract base for all Blocks — both atomic and composite.
+
+    Every block has a ``name`` and an ``interface`` describing its boundary
+    ports. Composition operators (``>>``, ``|``, ``.feedback()``, ``.loop()``)
+    build composite blocks from simpler ones.
+    """
+
+    name: str
+    interface: Interface = Interface()
+
+    @abstractmethod
+    def flatten(self) -> list[AtomicBlock]:
+        """Return all atomic blocks in evaluation order."""
+
+    def __rshift__(self, other: Block) -> StackComposition:
+        """``a >> b`` — stack (sequential) composition."""
+        from gds.blocks.composition import StackComposition
+
+        return StackComposition(
+            name=f"{self.name} >> {other.name}",
+            first=self,
+            second=other,
+        )
+
+    def __or__(self, other: Block) -> ParallelComposition:
+        """``a | b`` — parallel composition."""
+        from gds.blocks.composition import ParallelComposition
+
+        return ParallelComposition(
+            name=f"{self.name} | {other.name}",
+            left=self,
+            right=other,
+        )
+
+    def feedback(self, wiring: list[Wiring]) -> FeedbackLoop:
+        """Wrap with backward feedback within a single timestep."""
+        from gds.blocks.composition import FeedbackLoop
+
+        return FeedbackLoop(
+            name=f"{self.name} [feedback]",
+            inner=self,
+            feedback_wiring=wiring,
+        )
+
+    def loop(self, wiring: list[Wiring], exit_condition: str = "") -> TemporalLoop:
+        """Wrap with forward temporal iteration across timesteps."""
+        from gds.blocks.composition import TemporalLoop
+
+        return TemporalLoop(
+            name=f"{self.name} [loop]",
+            inner=self,
+            temporal_wiring=wiring,
+            exit_condition=exit_condition,
+        )
+
+
+class AtomicBlock(Block):
+    """Base class for non-decomposable (leaf) blocks.
+
+    Domain packages subclass this to define their own atomic block types.
+    """
+
+    def flatten(self) -> list[AtomicBlock]:
+        return [self]

gds/blocks/composition.py

@@ -0,0 +1,141 @@
+"""Composition operators: stack, parallel, feedback, and temporal loop.
+
+These operators combine blocks into larger composite systems:
+
+- **Stack** (``>>``) — chains blocks so one's output feeds another's input.
+- **Parallel** (``|``) — runs blocks side-by-side with no shared wires.
+- **Feedback** — connects backward_out to backward_in within a single timestep.
+- **Temporal Loop** — connects forward_out to forward_in across timesteps.
+"""
+
+from __future__ import annotations
+
+from typing import Self
+
+from pydantic import BaseModel, Field, model_validator
+
+from gds.blocks.base import AtomicBlock, Block
+from gds.blocks.errors import GDSTypeError
+from gds.ir.models import FlowDirection
+from gds.types.interface import Interface, Port
+
+
+class Wiring(BaseModel, frozen=True):
+    """An explicit connection between two blocks.
+
+    Covariant wirings (the default) carry data forward; contravariant
+    wirings carry feedback backward.
+    """
+
+    source_block: str
+    source_port: str
+    target_block: str
+    target_port: str
+    direction: FlowDirection = FlowDirection.COVARIANT
+
+
+class StackComposition(Block):
+    """``a >> b`` — stack (sequential) composition.
+
+    Output of the first block feeds input of the second. If no explicit
+    ``wiring`` is provided, the validator checks that forward_out tokens
+    overlap with forward_in tokens.
+    """
+
+    first: Block
+    second: Block
+    wiring: list[Wiring] = Field(default_factory=list)
+
+    @model_validator(mode="after")
+    def _compute_interface_and_validate(self) -> Self:
+        if not self.wiring:
+            first_out_tokens = _collect_tokens(self.first.interface.forward_out)
+            second_in_tokens = _collect_tokens(self.second.interface.forward_in)
+
+            if first_out_tokens and second_in_tokens and not (first_out_tokens & second_in_tokens):
+                raise GDSTypeError(
+                    f"Stack composition {self.name!r}: "
+                    f"first.forward_out tokens {first_out_tokens} have no overlap with "
+                    f"second.forward_in tokens {second_in_tokens}"
+                )
+
+        self.interface = Interface(
+            forward_in=self.first.interface.forward_in + self.second.interface.forward_in,
+            forward_out=self.first.interface.forward_out + self.second.interface.forward_out,
+            backward_in=self.first.interface.backward_in + self.second.interface.backward_in,
+            backward_out=self.first.interface.backward_out + self.second.interface.backward_out,
+        )
+        return self
+
+    def flatten(self) -> list[AtomicBlock]:
+        return self.first.flatten() + self.second.flatten()
+
+
+class ParallelComposition(Block):
+    """``a | b`` — parallel composition: blocks run independently."""
+
+    left: Block
+    right: Block
+
+    @model_validator(mode="after")
+    def _compute_interface(self) -> Self:
+        self.interface = Interface(
+            forward_in=self.left.interface.forward_in + self.right.interface.forward_in,
+            forward_out=self.left.interface.forward_out + self.right.interface.forward_out,
+            backward_in=self.left.interface.backward_in + self.right.interface.backward_in,
+            backward_out=self.left.interface.backward_out + self.right.interface.backward_out,
+        )
+        return self
+
+    def flatten(self) -> list[AtomicBlock]:
+        return self.left.flatten() + self.right.flatten()
+
+
+class FeedbackLoop(Block):
+    """Backward feedback within a single timestep (backward_out -> backward_in)."""
+
+    inner: Block
+    feedback_wiring: list[Wiring]
+
+    @model_validator(mode="after")
+    def _validate_and_compute_interface(self) -> Self:
+        self.interface = self.inner.interface
+        return self
+
+    def flatten(self) -> list[AtomicBlock]:
+        return self.inner.flatten()
+
+
+class TemporalLoop(Block):
+    """Forward temporal iteration across timesteps (forward_out -> forward_in).
+
+    All temporal wiring must be covariant direction.
+    """
+
+    inner: Block
+    temporal_wiring: list[Wiring]
+    exit_condition: str = ""
+
+    @model_validator(mode="after")
+    def _validate_and_compute_interface(self) -> Self:
+        for w in self.temporal_wiring:
+            if w.direction != FlowDirection.COVARIANT:
+                raise GDSTypeError(
+                    f"TemporalLoop {self.name!r}: temporal wiring "
+                    f"{w.source_block}.{w.source_port} → {w.target_block}.{w.target_port} "
+                    f"must be COVARIANT (got {w.direction.value})"
+                )
+
+        self.interface = self.inner.interface
+        return self
+
+    def flatten(self) -> list[AtomicBlock]:
+        return self.inner.flatten()
+
+
+def _collect_tokens(ports: tuple[Port, ...]) -> frozenset[str]:
+    """Collect all type tokens from a tuple of ports."""
+    tokens: set[str] = set()
+    for p in ports:
+        tokens.update(p.type_tokens)
+    return frozenset(tokens)

gds/blocks/errors.py

@@ -0,0 +1,17 @@
+"""GDS-specific error types.
+
+Raised at construction time during Pydantic validation when a block
+or composition violates structural constraints.
+"""
+
+
+class GDSError(Exception):
+    """Base class for all GDS errors."""
+
+
+class GDSTypeError(GDSError):
+    """Port type mismatch or invalid port structure during construction."""
+
+
+class GDSCompositionError(GDSError):
+    """Invalid composition structure."""

gds/blocks/roles.py

@@ -0,0 +1,129 @@
+"""GDS block roles from the MSML decomposition.
+
+These roles decompose the transition function h into typed components:
+
+- **BoundaryAction** — exogenous input (GDS admissible inputs U)
+- **ControlAction** — endogenous control (reads state, emits signals)
+- **Policy** — decision logic (maps signals to mechanism inputs)
+- **Mechanism** — state update (the only component that writes state)
+
+Each role subclasses AtomicBlock, inheriting composition operators and
+flatten(). Role-specific validators enforce structural constraints.
+
+Protocols
+---------
+``HasParams``, ``HasConstraints``, and ``HasOptions`` describe the structural
+attributes shared by multiple role types without requiring a common base class.
+Use ``isinstance(block, HasParams)`` for safe narrowing instead of
+``cast(Any, block)`` or ``hasattr`` guards.
+"""
+
+from __future__ import annotations
+
+from typing import Protocol, Self, runtime_checkable
+
+from pydantic import Field, model_validator
+
+from gds.blocks.base import AtomicBlock
+from gds.blocks.errors import GDSCompositionError
+
+
+@runtime_checkable
+class HasParams(Protocol):
+    """Structural protocol for blocks that declare parameter dependencies."""
+
+    params_used: list[str]
+
+
+@runtime_checkable
+class HasConstraints(Protocol):
+    """Structural protocol for blocks that carry constraint annotations."""
+
+    constraints: list[str]
+
+
+@runtime_checkable
+class HasOptions(Protocol):
+    """Structural protocol for blocks that enumerate named strategy options."""
+
+    options: list[str]
+
+
+class BoundaryAction(AtomicBlock):
+    """Exogenous input — enters the system from outside.
+
+    In GDS terms: part of the admissible input set U.
+    Boundary actions model external agents, oracles, user inputs,
+    environmental signals — anything the system doesn't control.
+
+    Enforces ``forward_in = ()`` since boundary actions receive no
+    internal forward signals.
+    """
+
+    kind: str = "boundary"
+    options: list[str] = Field(default_factory=list)
+    params_used: list[str] = Field(default_factory=list)
+    constraints: list[str] = Field(default_factory=list)
+
+    @model_validator(mode="after")
+    def _enforce_no_forward_in(self) -> Self:
+        if self.interface.forward_in:
+            raise GDSCompositionError(
+                f"BoundaryAction {self.name!r}: forward_in must be empty "
+                f"(boundary actions receive no internal forward signals)"
+            )
+        return self
+
+
+class ControlAction(AtomicBlock):
+    """Endogenous control — reads state, emits control signals.
+
+    These are internal feedback loops: the system observing itself
+    and generating signals that influence downstream policy/mechanism blocks.
+    """
+
+    kind: str = "control"
+    options: list[str] = Field(default_factory=list)
+    params_used: list[str] = Field(default_factory=list)
+    constraints: list[str] = Field(default_factory=list)
+
+
+class Policy(AtomicBlock):
+    """Decision logic — maps signals to mechanism inputs.
+
+    Policies select from feasible actions. Named options support
+    scenario analysis and A/B testing.
+
+    In GDS terms: policies implement the decision mapping
+    within the admissibility constraint.
+    """
+
+    kind: str = "policy"
+    options: list[str] = Field(default_factory=list)
+    params_used: list[str] = Field(default_factory=list)
+    constraints: list[str] = Field(default_factory=list)
+
+
+class Mechanism(AtomicBlock):
+    """State update — the only block type that writes to state.
+
+    Mechanisms are the atomic state transitions that compose into h.
+    They have no backward ports (state writes don't propagate signals).
+
+    ``updates`` lists (entity_name, variable_name) pairs specifying
+    which state variables this mechanism modifies.
+    """
+
+    kind: str = "mechanism"
+    updates: list[tuple[str, str]] = Field(default_factory=list)
+    params_used: list[str] = Field(default_factory=list)
+    constraints: list[str] = Field(default_factory=list)
+
+    @model_validator(mode="after")
+    def _enforce_no_backward(self) -> Self:
+        if self.interface.backward_in or self.interface.backward_out:
+            raise GDSCompositionError(
+                f"Mechanism {self.name!r}: backward ports must be empty "
+                f"(mechanisms write state, they don't pass backward signals)"
+            )
+        return self