gds-framework 0.2.2__tar.gz → 0.2.3__tar.gz

{gds_framework-0.2.2 → gds_framework-0.2.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gds-framework
-Version: 0.2.2
+Version: 0.2.3
 Summary: Generalized Dynamical Systems — typed compositional specifications for complex systems
 Project-URL: Homepage, https://github.com/BlockScience/gds-core
 Project-URL: Repository, https://github.com/BlockScience/gds-core

{gds_framework-0.2.2 → gds_framework-0.2.3}/gds/__init__.py

@@ -6,7 +6,7 @@ cybernetics (Ghani, Hedges et al.) into a single, dependency-light
 Python framework.
 """
 
-__version__ = "0.2.1"
+__version__ = "0.2.3"
 
 # ── Composition algebra ─────────────────────────────────────
 from gds.blocks.base import AtomicBlock, Block
@@ -32,7 +32,14 @@ from gds.blocks.roles import (
 
 # ── Canonical projection ───────────────────────────────────
 from gds.canonical import CanonicalGDS, project_canonical
-from gds.compiler.compile import compile_system
+from gds.compiler.compile import (
+    StructuralWiring,
+    WiringOrigin,
+    compile_system,
+    extract_hierarchy,
+    extract_wirings,
+    flatten_blocks,
+)
 
 # ── Convenience helpers ────────────────────────────────────
 from gds.helpers import (
@@ -52,8 +59,10 @@ from gds.ir.models import (
     CompositionType,
     FlowDirection,
     HierarchyNodeIR,
+    InputIR,
     SystemIR,
     WiringIR,
+    sanitize_id,
 )
 from gds.ir.serialization import IRDocument, IRMetadata, load_ir, save_ir
 
@@ -122,6 +131,7 @@ __all__ = [
     "HierarchyNodeIR",
     "IRDocument",
     "IRMetadata",
+    "InputIR",
     "Interface",
     "Mechanism",
     "NonNegativeFloat",
@@ -138,6 +148,7 @@ __all__ = [
     "SpecWiring",
     "StackComposition",
     "StateVariable",
+    "StructuralWiring",
     "SystemIR",
     "Tagged",
     "TemporalLoop",
@@ -148,6 +159,7 @@ __all__ = [
     "Wire",
     "Wiring",
     "WiringIR",
+    "WiringOrigin",
     "all_checks",
     "check_canonical_wellformedness",
     "check_completeness",
@@ -157,12 +169,16 @@ __all__ = [
     "check_type_safety",
     "compile_system",
     "entity",
+    "extract_hierarchy",
+    "extract_wirings",
+    "flatten_blocks",
     "gds_check",
     "get_custom_checks",
     "interface",
     "load_ir",
     "port",
     "project_canonical",
+    "sanitize_id",
     "save_ir",
     "space",
     "spec_to_dict",

gds_framework-0.2.3/gds/compiler/__init__.py

@@ -0,0 +1,19 @@
+"""Generic compilation pipeline: Block tree → flat SystemIR."""
+
+from gds.compiler.compile import (
+    StructuralWiring,
+    WiringOrigin,
+    compile_system,
+    extract_hierarchy,
+    extract_wirings,
+    flatten_blocks,
+)
+
+__all__ = [
+    "StructuralWiring",
+    "WiringOrigin",
+    "compile_system",
+    "extract_hierarchy",
+    "extract_wirings",
+    "flatten_blocks",
+]

{gds_framework-0.2.2 → gds_framework-0.2.3}/gds/compiler/compile.py

@@ -6,13 +6,19 @@ The compiler performs three transformations:
 2. **Wire** — extracts explicit wirings and auto-wires stack compositions.
 3. **Hierarchy** — captures the composition tree structure for visualization.
 
+Each stage is exposed as a standalone generic function (``flatten_blocks``,
+``extract_wirings``, ``extract_hierarchy``) so domain packages can reuse the
+DFS traversal with custom callbacks instead of forking the compiler.
+
 Domain packages provide a ``block_compiler`` callback to convert their
-specific atomic block types into BlockIR.
+specific atomic block types into BlockIR, and optionally a
+``wiring_emitter`` callback to transform structural wirings into domain IR.
 """
 
 from __future__ import annotations
 
-import re
+from dataclasses import dataclass
+from enum import StrEnum
 from typing import TYPE_CHECKING
 
 from gds.blocks.base import AtomicBlock, Block
@@ -28,8 +34,10 @@ from gds.ir.models import (
     CompositionType,
     FlowDirection,
     HierarchyNodeIR,
+    InputIR,
     SystemIR,
     WiringIR,
+    sanitize_id,
 )
 
 if TYPE_CHECKING:
@@ -38,12 +46,126 @@ if TYPE_CHECKING:
     from gds.types.interface import Port
 
 
+# ---------------------------------------------------------------------------
+# Structural intermediates
+# ---------------------------------------------------------------------------
+
+
+class WiringOrigin(StrEnum):
+    """How a structural wiring was discovered during DFS traversal."""
+
+    AUTO = "auto"
+    EXPLICIT = "explicit"
+    FEEDBACK = "feedback"
+    TEMPORAL = "temporal"
+
+
+@dataclass(frozen=True)
+class StructuralWiring:
+    """Protocol-internal intermediate between DFS traversal and IR emission.
+
+    The DFS walk produces these; the wiring emitter callback transforms them
+    into domain-specific IR (e.g. ``WiringIR`` for GDS, flow edges for OGS).
+    """
+
+    source_block: str
+    source_port: str
+    target_block: str
+    target_port: str
+    direction: FlowDirection
+    origin: WiringOrigin
+
+
+# ---------------------------------------------------------------------------
+# Stage 1: flatten_blocks
+# ---------------------------------------------------------------------------
+
+
+def flatten_blocks[B](
+    root: Block,
+    block_compiler: Callable[[AtomicBlock], B],
+) -> list[B]:
+    """Flatten the composition tree and map each leaf through *block_compiler*.
+
+    Args:
+        root: Root of the composition tree.
+        block_compiler: Callback that converts an AtomicBlock into domain IR.
+            For GDS, this produces ``BlockIR``; OGS can produce ``OpenGameIR``.
+
+    Returns:
+        Ordered list of compiled block IR objects.
+    """
+    return [block_compiler(b) for b in root.flatten()]
+
+
+# ---------------------------------------------------------------------------
+# Stage 2: extract_wirings
+# ---------------------------------------------------------------------------
+
+
+def extract_wirings[W](
+    root: Block,
+    wiring_emitter: Callable[[StructuralWiring], W] | None = None,
+) -> list[W]:
+    """Walk the composition tree and emit all wirings through *wiring_emitter*.
+
+    The DFS traversal discovers explicit wirings, auto-wired connections,
+    feedback wirings, and temporal wirings — each tagged with a
+    ``WiringOrigin``. The emitter callback transforms each
+    ``StructuralWiring`` into domain-specific IR.
+
+    Args:
+        root: Root of the composition tree.
+        wiring_emitter: Callback that converts a ``StructuralWiring`` into
+            domain IR. If None, uses the default GDS emitter that produces
+            ``WiringIR``.
+
+    Returns:
+        Ordered list of emitted wiring IR objects.
+    """
+    if wiring_emitter is None:
+        wiring_emitter = _default_wiring_emitter  # type: ignore[assignment]
+
+    structural: list[StructuralWiring] = []
+    _walk_structural_wirings(root, structural)
+    return [wiring_emitter(sw) for sw in structural]
+
+
+# ---------------------------------------------------------------------------
+# Stage 3: extract_hierarchy
+# ---------------------------------------------------------------------------
+
+
+def extract_hierarchy(root: Block) -> HierarchyNodeIR:
+    """Build a ``HierarchyNodeIR`` tree from the composition tree.
+
+    Sequential and parallel chains are flattened from binary trees into
+    n-ary groups for cleaner visualization.
+
+    Args:
+        root: Root of the composition tree.
+
+    Returns:
+        Root ``HierarchyNodeIR`` with flattened chains.
+    """
+    counter = [0]
+    hierarchy = _extract_hierarchy(root, counter)
+    return _flatten_sequential_chains(hierarchy)
+
+
+# ---------------------------------------------------------------------------
+# compile_system — thin wrapper over the three stages
+# ---------------------------------------------------------------------------
+
+
 def compile_system(
     name: str,
     root: Block,
     block_compiler: Callable[[AtomicBlock], BlockIR] | None = None,
+    wiring_emitter: Callable[[StructuralWiring], WiringIR] | None = None,
     composition_type: CompositionType = CompositionType.SEQUENTIAL,
     source: str = "",
+    inputs: list[InputIR] | None = None,
 ) -> SystemIR:
     """Compile a Block tree into a flat SystemIR.
 
@@ -52,34 +174,36 @@ def compile_system(
         root: Root of the composition tree.
         block_compiler: Domain-specific function to convert AtomicBlock → BlockIR.
             If None, uses a default that extracts name + interface.
+        wiring_emitter: Domain-specific function to convert StructuralWiring →
+            WiringIR. If None, uses the default GDS emitter.
         composition_type: Top-level composition type.
         source: Source identifier.
+        inputs: External inputs to include in the SystemIR. Layer 0 never
+            infers inputs — domain packages supply them.
     """
     if block_compiler is None:
         block_compiler = _default_block_compiler
 
-    # 1. Flatten
-    atomic_blocks = root.flatten()
-    block_irs = [block_compiler(b) for b in atomic_blocks]
-
-    # 2. Wire
-    wirings = _extract_wirings(root)
-
-    # 3. Hierarchy
-    counter = [0]
-    hierarchy = _extract_hierarchy(root, counter)
-    hierarchy = _flatten_sequential_chains(hierarchy)
+    blocks = flatten_blocks(root, block_compiler)
+    wirings = extract_wirings(root, wiring_emitter)
+    hierarchy = extract_hierarchy(root)
 
     return SystemIR(
         name=name,
-        blocks=block_irs,
+        blocks=blocks,
         wirings=wirings,
+        inputs=inputs or [],
         composition_type=composition_type,
         hierarchy=hierarchy,
         source=source,
     )
 
 
+# ---------------------------------------------------------------------------
+# Default callbacks
+# ---------------------------------------------------------------------------
+
+
 def _default_block_compiler(block: AtomicBlock) -> BlockIR:
     """Default block compiler — extracts name and interface slots."""
     return BlockIR(
@@ -93,6 +217,18 @@ def _default_block_compiler(block: AtomicBlock) -> BlockIR:
     )
 
 
+def _default_wiring_emitter(sw: StructuralWiring) -> WiringIR:
+    """Default wiring emitter — converts StructuralWiring to WiringIR."""
+    return WiringIR(
+        source=sw.source_block,
+        target=sw.target_block,
+        label=sw.source_port,
+        direction=sw.direction,
+        is_feedback=sw.origin == WiringOrigin.FEEDBACK,
+        is_temporal=sw.origin == WiringOrigin.TEMPORAL,
+    )
+
+
 def _ports_to_sig(ports: tuple[Port, ...]) -> str:
     """Convert a tuple of Ports to the IR signature string format."""
     if not ports:
@@ -101,48 +237,53 @@ def _ports_to_sig(ports: tuple[Port, ...]) -> str:
 
 
 # ---------------------------------------------------------------------------
-# Wiring extraction
+# DFS wiring traversal (produces StructuralWiring intermediates)
 # ---------------------------------------------------------------------------
 
 
-def _extract_wirings(block: Block) -> list[WiringIR]:
-    """Recursively walk the block tree and collect all wirings."""
-    wirings: list[WiringIR] = []
-    _walk_wirings(block, wirings)
-    return wirings
-
-
-def _walk_wirings(block: Block, wirings: list[WiringIR]) -> None:
-    """Recursively walk the composition tree, collecting all wirings."""
+def _walk_structural_wirings(block: Block, out: list[StructuralWiring]) -> None:
+    """Recursively walk the composition tree, collecting StructuralWirings."""
     if isinstance(block, AtomicBlock):
         return
 
     if isinstance(block, StackComposition):
-        _walk_wirings(block.first, wirings)
-        _walk_wirings(block.second, wirings)
+        _walk_structural_wirings(block.first, out)
+        _walk_structural_wirings(block.second, out)
 
         for w in block.wiring:
-            wirings.append(_wiring_to_ir(w))
+            out.append(_wiring_to_structural(w, WiringOrigin.EXPLICIT))
 
         if not block.wiring:
-            _auto_wire_stack(block.first, block.second, wirings)
+            _auto_wire_stack(block.first, block.second, out)
 
     elif isinstance(block, ParallelComposition):
-        _walk_wirings(block.left, wirings)
-        _walk_wirings(block.right, wirings)
+        _walk_structural_wirings(block.left, out)
+        _walk_structural_wirings(block.right, out)
 
     elif isinstance(block, FeedbackLoop):
-        _walk_wirings(block.inner, wirings)
+        _walk_structural_wirings(block.inner, out)
         for fw in block.feedback_wiring:
-            wirings.append(_wiring_to_ir(fw, is_feedback=True))
+            out.append(_wiring_to_structural(fw, WiringOrigin.FEEDBACK))
 
     elif isinstance(block, TemporalLoop):
-        _walk_wirings(block.inner, wirings)
+        _walk_structural_wirings(block.inner, out)
         for w in block.temporal_wiring:
-            wirings.append(_wiring_to_ir(w, is_temporal=True))
+            out.append(_wiring_to_structural(w, WiringOrigin.TEMPORAL))
+
+
+def _wiring_to_structural(wiring: Wiring, origin: WiringOrigin) -> StructuralWiring:
+    """Convert a DSL Wiring to a StructuralWiring intermediate."""
+    return StructuralWiring(
+        source_block=wiring.source_block,
+        source_port=wiring.source_port,
+        target_block=wiring.target_block,
+        target_port=wiring.target_port,
+        direction=wiring.direction,
+        origin=origin,
+    )
 
 
-def _auto_wire_stack(first: Block, second: Block, wirings: list[WiringIR]) -> None:
+def _auto_wire_stack(first: Block, second: Block, out: list[StructuralWiring]) -> None:
     """Auto-wire matching forward_out→forward_in ports in stack compositions."""
     first_leaves = _get_leaf_names(first)
     second_leaves = _get_leaf_names(second)
@@ -156,32 +297,18 @@ def _auto_wire_stack(first: Block, second: Block, wirings: list[WiringIR]) -> No
                 target = (
                     _find_port_owner(second, in_port, "forward_in") or second_leaves[0]
                 )
-                wirings.append(
-                    WiringIR(
-                        source=source,
-                        target=target,
-                        label=out_port.name,
+                out.append(
+                    StructuralWiring(
+                        source_block=source,
+                        source_port=out_port.name,
+                        target_block=target,
+                        target_port=in_port.name,
                         direction=FlowDirection.COVARIANT,
+                        origin=WiringOrigin.AUTO,
                     )
                 )
 
 
-def _wiring_to_ir(
-    wiring: Wiring,
-    is_feedback: bool = False,
-    is_temporal: bool = False,
-) -> WiringIR:
-    """Convert a DSL Wiring to an IR WiringIR."""
-    return WiringIR(
-        source=wiring.source_block,
-        target=wiring.target_block,
-        label=wiring.source_port,
-        direction=wiring.direction,
-        is_feedback=is_feedback,
-        is_temporal=is_temporal,
-    )
-
-
 def _get_leaf_names(block: Block) -> list[str]:
     """Get names of all leaf (atomic) blocks."""
     return [b.name for b in block.flatten()]
@@ -201,16 +328,11 @@ def _find_port_owner(block: Block, target_port: Port, slot: str) -> str | None:
 # ---------------------------------------------------------------------------
 
 
-def _sanitize_id(name: str) -> str:
-    """Convert a name to a valid ID (alphanumeric + underscore only)."""
-    return re.sub(r"[^A-Za-z0-9_]", "_", name)
-
-
 def _extract_hierarchy(block: Block, counter: list[int]) -> HierarchyNodeIR:
     """Recursively build a HierarchyNodeIR from the composition tree."""
     if isinstance(block, AtomicBlock):
         return HierarchyNodeIR(
-            id=f"leaf_{_sanitize_id(block.name)}",
+            id=f"leaf_{sanitize_id(block.name)}",
             name=block.name,
             composition_type=None,
             block_name=block.name,

{gds_framework-0.2.2 → gds_framework-0.2.3}/gds/ir/models.py

@@ -7,6 +7,7 @@ generic models with their own block types and metadata.
 
 from __future__ import annotations
 
+import re
 from enum import StrEnum
 from typing import Any
 
@@ -15,6 +16,18 @@ from pydantic import BaseModel, Field
 from gds.parameters import ParameterSchema
 
 
+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
+
+
 class FlowDirection(StrEnum):
     """Direction of an information flow in a block composition.
 
@@ -60,7 +73,9 @@ class WiringIR(BaseModel):
     """A directed connection (edge) between blocks in the IR.
 
     ``is_feedback`` and ``is_temporal`` flags distinguish special wiring
-    categories for verification.
+    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
@@ -70,6 +85,7 @@ class WiringIR(BaseModel):
     direction: FlowDirection
     is_feedback: bool = False
     is_temporal: bool = False
+    category: str = "dataflow"
 
 
 class HierarchyNodeIR(BaseModel):
@@ -87,6 +103,18 @@ class HierarchyNodeIR(BaseModel):
     exit_condition: str = ""
 
 
+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)
+
+
 class SystemIR(BaseModel):
     """A complete composed system — the top-level IR unit.
 
@@ -97,7 +125,7 @@ class SystemIR(BaseModel):
     name: str
     blocks: list[BlockIR] = Field(default_factory=list)
     wirings: list[WiringIR] = Field(default_factory=list)
-    inputs: list[dict[str, Any]] = Field(default_factory=list)
+    inputs: list[InputIR] = Field(default_factory=list)
     composition_type: CompositionType = CompositionType.SEQUENTIAL
     hierarchy: HierarchyNodeIR | None = None
     source: str = ""

{gds_framework-0.2.2 → gds_framework-0.2.3}/gds/verification/generic_checks.py

@@ -98,27 +98,100 @@ def check_g002_signature_completeness(system: SystemIR) -> list[Finding]:
 
 
 def check_g003_direction_consistency(system: SystemIR) -> list[Finding]:
-    """G-003: Covariant wirings should not be typed as backward;
-    contravariant wirings should not be typed as forward.
+    """G-003: Validate direction flag consistency and contravariant port-slot matching.
 
-    This is a generic structural check — domain packages define their
-    own wiring_type semantics.
+    Two validations:
+
+    A) Flag consistency — ``direction``, ``is_feedback``, ``is_temporal`` must
+       not contradict:
+       - COVARIANT + is_feedback → ERROR (feedback implies contravariant)
+       - CONTRAVARIANT + is_temporal → ERROR (temporal implies covariant)
+
+    B) Contravariant port-slot matching — for CONTRAVARIANT wirings, the label
+       must be a token-subset of the source's backward_out (signature[3]) or
+       the target's backward_in (signature[2]). G-001 already covers the
+       covariant side.
     """
     findings = []
+    block_sigs = {b.name: b.signature for b in system.blocks}
+
     for wiring in system.wirings:
-        # Generic check: just verify the wiring has a direction set
-        findings.append(
-            Finding(
-                check_id="G-003",
-                severity=Severity.INFO,
-                message=(
-                    f"Wiring {wiring.label!r} ({wiring.source} -> {wiring.target}): "
-                    f"direction={wiring.direction.value}"
-                ),
-                source_elements=[wiring.source, wiring.target],
-                passed=True,
+        # A) Flag consistency
+        if wiring.direction == FlowDirection.COVARIANT and wiring.is_feedback:
+            findings.append(
+                Finding(
+                    check_id="G-003",
+                    severity=Severity.ERROR,
+                    message=(
+                        f"Wiring {wiring.label!r} "
+                        f"({wiring.source} -> {wiring.target}): "
+                        f"COVARIANT + is_feedback — contradiction"
+                    ),
+                    source_elements=[wiring.source, wiring.target],
+                    passed=False,
+                )
+            )
+            continue
+
+        if wiring.direction == FlowDirection.CONTRAVARIANT and wiring.is_temporal:
+            findings.append(
+                Finding(
+                    check_id="G-003",
+                    severity=Severity.ERROR,
+                    message=(
+                        f"Wiring {wiring.label!r} "
+                        f"({wiring.source} -> {wiring.target}): "
+                        f"CONTRAVARIANT + is_temporal — contradiction"
+                    ),
+                    source_elements=[wiring.source, wiring.target],
+                    passed=False,
+                )
+            )
+            continue
+
+        # B) Contravariant port-slot matching (G-001 covers covariant)
+        if wiring.direction == FlowDirection.CONTRAVARIANT:
+            if wiring.source not in block_sigs or wiring.target not in block_sigs:
+                # Non-block endpoints — G-004 handles dangling references
+                continue
+
+            src_bwd_out = block_sigs[wiring.source][3]  # backward_out
+            tgt_bwd_in = block_sigs[wiring.target][2]  # backward_in
+
+            if not src_bwd_out and not tgt_bwd_in:
+                findings.append(
+                    Finding(
+                        check_id="G-003",
+                        severity=Severity.ERROR,
+                        message=(
+                            f"Wiring {wiring.label!r} "
+                            f"({wiring.source} -> {wiring.target}): "
+                            f"CONTRAVARIANT but both backward "
+                            f"ports are empty"
+                        ),
+                        source_elements=[wiring.source, wiring.target],
+                        passed=False,
+                    )
+                )
+                continue
+
+            compatible = tokens_subset(wiring.label, src_bwd_out) or tokens_subset(
+                wiring.label, tgt_bwd_in
+            )
+            findings.append(
+                Finding(
+                    check_id="G-003",
+                    severity=Severity.ERROR,
+                    message=(
+                        f"Wiring {wiring.label!r}: "
+                        f"{wiring.source} bwd_out={src_bwd_out!r} -> "
+                        f"{wiring.target} bwd_in={tgt_bwd_in!r}"
+                        + ("" if compatible else " — MISMATCH")
+                    ),
+                    source_elements=[wiring.source, wiring.target],
+                    passed=compatible,
+                )
             )
-        )
 
     return findings
 
@@ -127,10 +200,8 @@ def check_g004_dangling_wirings(system: SystemIR) -> list[Finding]:
     """G-004: Flag wirings whose source or target is not in the system."""
     findings = []
     known_names = {b.name for b in system.blocks}
-    # Also include input names
     for inp in system.inputs:
-        if isinstance(inp, dict) and "name" in inp:
-            known_names.add(inp["name"])
+        known_names.add(inp.name)
 
     for wiring in system.wirings:
         src_ok = wiring.source in known_names

{gds_framework-0.2.2 → gds_framework-0.2.3}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "gds-framework"
-version = "0.2.2"
+dynamic = ["version"]
 description = "Generalized Dynamical Systems — typed compositional specifications for complex systems"
 readme = "README.md"
 license = "Apache-2.0"
@@ -47,6 +47,9 @@ Documentation = "https://blockscience.github.io/gds-core"
 requires = ["hatchling"]
 build-backend = "hatchling.build"
 
+[tool.hatch.version]
+path = "gds/__init__.py"
+
 [tool.hatch.build.targets.wheel]
 packages = ["gds"]