Skip to content

gds_business.common

Shared types, errors, and compilation utilities.

Diagram Kinds

Bases: StrEnum

The three business dynamics diagram types.

Source code in packages/gds-business/gds_business/common/types.py 
 6
 7
 8
 9
10
11
class BusinessDiagramKind(StrEnum):
    """The three business dynamics diagram types."""

    CLD = "cld"
    SUPPLY_CHAIN = "supply_chain"
    VSM = "vsm"

Errors

Bases: GDSError

Base exception for business dynamics DSL errors.

Source code in packages/gds-business/gds_business/common/errors.py 
6
7
class BizError(GDSError):
    """Base exception for business dynamics DSL errors."""

Bases: BizError

Raised when a business dynamics model fails structural validation.

Source code in packages/gds-business/gds_business/common/errors.py 
10
11
class BizValidationError(BizError):
    """Raised when a business dynamics model fails structural validation."""

Bases: BizError

Raised when compilation of a business dynamics model fails.

Source code in packages/gds-business/gds_business/common/errors.py 
14
15
class BizCompilationError(BizError):
    """Raised when compilation of a business dynamics model fails."""

Compilation Utilities

Compose a list of blocks in parallel.

Source code in packages/gds-business/gds_business/common/compile_utils.py 
17
18
19
20
21
22
def parallel_tier(blocks: list[Block]) -> Block:
    """Compose a list of blocks in parallel."""
    tier: Block = blocks[0]
    for b in blocks[1:]:
        tier = tier | b
    return tier

Build explicit wirings between two tiers based on port token overlap.

For each output port in the first tier, find matching input ports in the second tier (by token intersection). This replaces auto-wiring so we can use explicit StackComposition and bypass the token overlap validator.

Source code in packages/gds-business/gds_business/common/compile_utils.py 
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
def build_inter_tier_wirings(
    first_tier_blocks: list[Block],
    second_tier_blocks: list[Block],
) -> list[Wiring]:
    """Build explicit wirings between two tiers based on port token overlap.

    For each output port in the first tier, find matching input ports in the
    second tier (by token intersection). This replaces auto-wiring so we can
    use explicit StackComposition and bypass the token overlap validator.
    """
    wirings: list[Wiring] = []
    for first_block in first_tier_blocks:
        for out_port in first_block.interface.forward_out:
            for second_block in second_tier_blocks:
                for in_port in second_block.interface.forward_in:
                    if out_port.type_tokens & in_port.type_tokens:
                        wirings.append(
                            Wiring(
                                source_block=first_block.name,
                                source_port=out_port.name,
                                target_block=second_block.name,
                                target_port=in_port.name,
                            )
                        )
    return wirings

Compose two tiers sequentially with explicit wiring.

Uses StackComposition directly to bypass the auto-wire token overlap check. If no wirings found, falls back to auto-wiring via >>.

Source code in packages/gds-business/gds_business/common/compile_utils.py 
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
def sequential_with_explicit_wiring(
    first: Block,
    second: Block,
    wiring: list[Wiring],
) -> Block:
    """Compose two tiers sequentially with explicit wiring.

    Uses StackComposition directly to bypass the auto-wire token overlap check.
    If no wirings found, falls back to auto-wiring via >>.
    """
    if wiring:
        return StackComposition(
            name=f"{first.name} >> {second.name}",
            first=first,
            second=second,
            wiring=wiring,
        )
    return first >> second