gw_data 0.3.0__py3-none-any.whl

gw_data/sema/definitions/registry.yaml

@@ -0,0 +1,77 @@
+metadata:
+  registry_version: "1.0"
+  last_updated: "2026-05-14T14:50:00Z"
+  maintainer: "gridworks-energy"
+
+snapshot:
+  built_at: "2026-05-18T22:35:28Z"
+
+formats:
+  left.right.dot:
+    owner: gridworks-energy
+    schema_url: "https://schemas.electricity.works/formats/left.right.dot"
+    created: "2024-09-02T15:00:00Z"
+    description: "Dot-separated hierarchical identifier composed of lowercase alphanumeric segments"
+
+  uuid4.str:
+    owner: gridworks-energy
+    schema_url: "https://schemas.electricity.works/formats/uuid4.str"
+    created: "2024-09-02T15:00:00Z"
+    description: "Canonical lowercase UUIDv4 string (RFC 4122) in 8-4-4-4-12 format"
+
+enums:
+  base.g.node.class:
+    latest_version: "000"
+    owner: gridworks-energy
+    enum_type: "versioned"
+    description: "Universal physical ontology classification for Grid Nodes"
+
+    versions:
+      "000":
+        schema_url: "https://schemas.electricity.works/enums/base.g.node.class/000"
+        created: "2026-02-22T16:43:00Z"
+
+  g.node.status:
+    latest_version: "000"
+    owner: gridworks-energy
+    enum_type: "versioned"
+    description: "Lifecycle status of a Grid Node within the registry"
+
+    versions:
+      "000":
+        schema_url: "https://schemas.electricity.works/enums/g.node.status/000"
+        created: "2026-02-22T16:43:00Z"
+
+types:
+  g.node.gt:
+    latest_version: "004"
+    owner: gridworks-energy
+    versioning_strategy: "literal"
+    description: "Fundamental identity object representing physical and logical grid nodes"
+
+    versions:
+      "004":
+        schema_url: "https://schemas.electricity.works/types/g.node.gt/004"
+        created: "2026-02-24T14:00:00Z"
+        summary: "Baseline runtime version (no prior version tracked)."
+        direct_dependencies:
+          structural:
+            - "base.g.node.class:000"
+            - "g.node.status:000"
+            - "left.right.dot"
+            - "uuid4.str"
+
+  position.point.gt:
+    latest_version: "000"
+    owner: gridworks-energy
+    versioning_strategy: "literal"
+    description: "Geographic position expressed in integer microdegrees (WGS84)"
+
+    versions:
+      "000":
+        schema_url: "https://schemas.electricity.works/types/position.point.gt/000"
+        created: "2026-02-24T15:00:00Z"
+        summary: "Initial Sema version"
+        direct_dependencies:
+          structural:
+            - "uuid4.str"

gw_data/sema/definitions/types/g.node.gt/004.yaml

@@ -0,0 +1,169 @@
+$schema: "https://json-schema.org/draft/2020-12/schema"
+$id: "https://schemas.electricity.works/types/g.node.gt/004"
+
+title: "g.node.gt"
+type: object
+description: >
+  A GNode (“Grid Node”) is the fundamental identity object in the GridWorks 
+  ecosystem. Every physical location, metered unit, device, service, or actor 
+  interacting with the transactive system is represented as a GNode.
+
+properties:
+
+  GNodeId:
+    $ref: "https://schemas.electricity.works/formats/uuid4.str"
+    description: >
+      Globally unique identifier for this GNode. Immutable for the lifetime
+      of the GNode.
+
+  Alias:
+    $ref: "https://schemas.electricity.works/formats/left.right.dot"
+    description: >
+      Human-readable hierarchical identifier. Forms the basis of the
+      GNodeTree topology. Alias may change over time as the physical
+      or conceptual topology is refined.
+
+  BaseClass:
+    $ref: "https://schemas.electricity.works/enums/base.g.node.class/000"
+    description: >
+      Universal structural ontology classification for the GNode.
+      Defines the physical or logical topology role used for
+      interoperability, copper-tree construction, and market
+      coordination across organizations.
+
+  GNodeClass:
+    type: string
+    description: >
+      Functional or role-based classification for the GNode. Interpreted
+      according to the namespace of the registering organization. This field is a
+      free-form string, not a universal enum. 
+
+  Status:
+    $ref: "https://schemas.electricity.works/enums/g.node.status/000"
+    description: >
+      Lifecycle status of the GNode within the registry.
+
+  PrevAlias:
+    $ref: "https://schemas.electricity.works/formats/left.right.dot"
+    description: >
+      Previous Alias value during alias transitions. Required only when
+      Alias changes. Must be null if Alias has not changed.
+
+  PositionPointId:
+    $ref: "https://schemas.electricity.works/formats/uuid4.str"
+    description: >
+      Reference to a PositionPoint GT type giving physical location
+      (WGS84 microdegrees). Required for physical GNodes; null for
+      logical/service nodes.
+
+  DisplayName:
+    type: "string"
+    description: >
+      Optional human-friendly label for UI or documentation.
+
+  TypeName:
+    const: "g.node.gt"
+
+  Version:
+    const: "004"
+
+required:
+  - GNodeId
+  - Alias
+  - BaseClass
+  - GNodeClass
+  - Status
+  - TypeName
+  - Version
+
+additionalProperties: false
+
+examples:
+  - |
+    {
+      "GNodeId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
+      "Alias": "d1.isone.me.versant.keene.beech",
+      "BaseClass": "LeafTransactiveNode",
+      "GNodeClass": "LeafTransactiveNode",
+      "Status": "Active",
+      "PositionPointId": "198ca6af-5a4b-43a2-a8a9-7546deabc731",
+      "DisplayName": "Beech Street Meter",
+      "TypeName": "g.node.gt",
+      "Version": "004"
+    }
+  - |
+    {
+      "GNodeId": "dcb05390-5bca-40ef-b63d-7908ccb33d9b",
+      "Alias": "d1.isone.me.ws",
+      "BaseClass": "Logical",
+      "GNodeClass": "WeatherForecastService",
+      "Status": "Active",
+      "DisplayName": "New England Weather Forecast Service",
+      "TypeName": "g.node.gt",
+      "Version": "004"
+    }
+
+x-gridworks:
+  owner: "gridworks-energy"
+
+  axioms:
+
+    - number: 1
+      name: "ClassConsistency"
+      statement: >
+        a. If BaseClass is not Logical, GNodeClass SHALL equal the string value of BaseClass.
+        b. If BaseClass is Logical, GNodeClass SHALL NOT equal any value of base.g.node.class other than Logical.
+
+    - number: 2
+      name: "PhysicalGNodeLocations"
+      statement: >
+        If BaseClass != Logical, PositionPointId SHALL NOT be null.
+
+    - number: 3
+      name: "AliasTransitionConsistency"
+      statement: >
+        If PrevAlias is not null, it SHALL differ from Alias.
+
+    - number: 4
+      name: "GNodeClassNamespacing"
+      statement: >
+        GNodeClass SHALL be a non-empty string containing no whitespace
+
+    - number: 5
+      name: "AliasSuffixSemantics"
+      statement: >
+        a. Alias SHALL end with ".ta" if and only if GNodeClass is "TerminalAsset".
+        b. Alias SHALL end with ".scada" if and only if GNodeClass is "Scada".
+
+  extended_description: >
+    Grid Nodes (GNodes) provide the stable identity layer for distributed
+    coordination in the GridWorks ecosystem. Each GNode participates in a
+    hierarchical alias structure that encodes topology, routing semantics,
+    and coordination scope.
+
+    GNodes may represent physical grid structure (e.g., metered boundaries,
+    connectivity nodes, constraint points) or logical and service roles
+    (e.g., SCADA agents, forecasting services, market participants).
+    BaseClass defines the universal structural ontology required for
+    interoperability. GNodeClass expresses organization-specific
+    functional roles and does not alter structural semantics.
+
+    `g.node.gt` is an immutable serialized snapshot of declared node state.
+    Any change to a GNode (alias updates, status changes, relocations,
+    or classification changes) SHALL be represented by publishing a new
+    `g.node.gt` message rather than mutating a previously published instance.
+    This preserves durable identity (GNodeId) while allowing controlled
+    evolution of descriptive attributes.
+
+    GNode is designed as the atomic unit of coordination in a recursively
+    composable grid architecture. Systems of arbitrary scale are formed by
+    composing GNodes into hierarchical or heterarchical structures. This
+    allows optimal power flow (OPF), market clearing, and constraint
+    coordination mechanisms to operate centrally, regionally, or in
+    distributed configurations without altering the underlying identity model.
+
+    Conceptually, GNode aligns with node abstractions in IEC 61970/61968
+    CIM (e.g., ConnectivityNode and TopologicalNode), while unifying
+    physical and logical coordination entities within a single identity
+    abstraction suitable for graph-based modeling and transactive
+    coordination.

gw_data/sema/definitions/types/position.point.gt/000.yaml

@@ -0,0 +1,86 @@
+$schema: "https://json-schema.org/draft/2020-12/schema"
+$id: "https://schemas.electricity.works/types/position.point.gt/000"
+
+title: "position.point.gt"
+type: object
+description: >
+  A geographic position for a physical Grid Node. Coordinates are stored in
+  integer microdegrees (degrees × 1,000,000). This type is conceptually aligned
+  with the IEC 61970/61968 CIM `PositionPoint` class, but simplified for
+  GridWorks use cases, which require only a single latitude/longitude point.
+
+properties:
+
+  Id:
+    $ref: "https://schemas.electricity.works/formats/uuid4.str"
+    description: >
+      Globally unique identifier for this PositionPoint. Serves as the
+      primary key in the Grid Node Registry.
+
+  LatitudeMicroDeg:
+    type: integer
+    description: >
+      Latitude in microdegrees. Must fall between -90,000,000 and
+      90,000,000 inclusive (corresponding to -90.0° to +90.0° in WGS84).
+
+  LongitudeMicroDeg:
+    type: integer
+    description: >
+      Longitude in microdegrees. Must fall between -180,000,000 and
+      180,000,000 inclusive (corresponding to -180.0° to +180.0° in WGS84).
+
+  TypeName:
+    const: "position.point.gt"
+
+  Version:
+    const: "000"
+
+required:
+  - Id
+  - LatitudeMicroDeg
+  - LongitudeMicroDeg
+  - TypeName
+  - Version
+
+additionalProperties: false
+
+examples:
+  - |
+    {
+      "Id": "198ca6af-5a4b-43a2-a8a9-7546deabc731",
+      "LatitudeMicroDeg": 45657842,
+      "LongitudeMicroDeg": -68708913,
+      "TypeName": "position.point.gt",
+      "Version": "000"
+    }
+
+x-gridworks:
+  owner: "gridworks-energy"
+
+  axioms:
+    - number: 1
+      name: "ValidEarthCoordinates"
+      statement: >
+        LatitudeMicroDeg SHALL be between -90,000,000 and 90,000,000 inclusive.
+        LongitudeMicroDeg SHALL be between -180,000,000 and 180,000,000 inclusive.
+
+  extended_description: >
+    PositionPoint represents the physical location of a GNode that has
+    spatial meaning within the electric grid, such as TerminalAssets,
+    LeafTransactiveNodes, MarketMaker constraint points, and ConnectivityNodes.
+    Coordinates are expressed in WGS84 (EPSG:4326), the standard global
+    geodetic reference system used by GPS and commonly adopted in utility
+    GIS, mapping, and DERMS integrations.
+
+    This type corresponds to a simplified form of the IEC 61970/61968 CIM
+    `PositionPoint` class. The CIM model supports elevation, coordinate-system
+    definitions, and collections of points for geometric shapes. GridWorks
+    intentionally restricts this type to a single latitude/longitude pair
+    to provide a deterministic and minimal spatial anchor for coordination.
+
+    Position accuracy is not prescribed by this type. The microdegree
+    representation provides sufficient precision to distinguish
+    distribution-level assets (e.g., residential footprints, poles,
+    transformers, substations). The actual positional accuracy of a
+    PositionPoint depends entirely on the source of the underlying
+    geographic data.

gw_data/sema/enums/__init__.py

@@ -0,0 +1,7 @@
+from gw_data.sema.enums.base_g_node_class import BaseGNodeClass
+from gw_data.sema.enums.g_node_status import GNodeStatus
+
+__all__ = [
+    "BaseGNodeClass",
+    "GNodeStatus",
+]

gw_data/sema/enums/base_g_node_class.py

@@ -0,0 +1,29 @@
+from enum import auto
+
+from gw_data.sema.enums.gw_str_enum import SemaEnum
+
+
+class BaseGNodeClass(SemaEnum):
+    """Sema: https://schemas.electricity.works/enums/base.g.node.class/000"""
+
+    TerminalAsset = auto()
+    LeafTransactiveNode = auto()
+    ConnectivityNode = auto()
+    MarketMaker = auto()
+    Logical = auto()
+
+    @classmethod
+    def default(cls) -> "BaseGNodeClass":
+        return cls.Logical
+
+    @classmethod
+    def values(cls) -> list[str]:
+        return [elt.value for elt in cls]
+
+    @classmethod
+    def enum_name(cls) -> str:
+        return "base.g.node.class"
+
+    @classmethod
+    def enum_version(cls) -> str:
+        return "000"

gw_data/sema/enums/g_node_status.py

@@ -0,0 +1,28 @@
+from enum import auto
+
+from gw_data.sema.enums.gw_str_enum import SemaEnum
+
+
+class GNodeStatus(SemaEnum):
+    """Sema: https://schemas.electricity.works/enums/g.node.status/000"""
+
+    Pending = auto()
+    Active = auto()
+    Suspended = auto()
+    PermanentlyDeactivated = auto()
+
+    @classmethod
+    def default(cls) -> "GNodeStatus":
+        return cls.Pending
+
+    @classmethod
+    def values(cls) -> list[str]:
+        return [elt.value for elt in cls]
+
+    @classmethod
+    def enum_name(cls) -> str:
+        return "g.node.status"
+
+    @classmethod
+    def enum_version(cls) -> str:
+        return "000"

gw_data/sema/enums/gw_str_enum.py

@@ -0,0 +1,97 @@
+from enum import StrEnum
+from typing import Any, Self
+
+
+class GwStrEnum(StrEnum):
+    """
+    Mimics fastapi-utils use of StrEnum, which diverges from the
+    python-native StrEnum for python 3.11+.  Also, fills in with default
+    value if a string does not exist in the enum.
+
+    Specifically (re difference with python StrEnum) if
+
+    class Foo(Enum):
+        Bar = auto()
+
+    then
+
+    Foo.Bar.value is 'Bar' (instead of 'bar')
+
+    """
+
+    @staticmethod
+    def _generate_next_value_(
+        name: str,
+        start: int,  # noqa: ARG004
+        count: int,  # noqa: ARG004
+        last_values: list[Any],  # noqa: ARG004
+    ) -> str:
+        return name
+
+    @classmethod
+    def values(cls) -> list[str]:
+        return [str(elt) for elt in cls]
+
+    @classmethod
+    def _init_index_maps(cls) -> None:
+        if hasattr(cls, "_index_to_value"):
+            return
+
+        values = [m.value for m in cls]
+        cls._index_to_value = values
+        cls._value_to_index = {v: i for i, v in enumerate(values)}
+
+    @classmethod
+    def to_index(cls, value: str) -> int:
+        cls._init_index_maps()
+        return cls._value_to_index[value]
+
+    @classmethod
+    def from_index(cls, idx: int) -> str:
+        cls._init_index_maps()
+        return cls._index_to_value[idx]
+
+    @classmethod
+    def default(cls) -> Self | None:
+        return None
+
+    @classmethod
+    def _missing_(cls, value: str) -> Self:
+        default = cls.default()
+        if default is None:
+            raise ValueError(f"'{value}' is not valid {cls.__name__}")
+        return default
+
+class SemaEnum(GwStrEnum):
+    """
+    Base for enums published in Sema.
+    Requires enum_name(). Version is optional (return None for stable enums).
+    """
+
+    @classmethod
+    def enum_name(cls) -> str:
+        """Sema identifier (e.g., 'gw1.relay.state')"""
+        raise NotImplementedError(
+            f"{cls.__name__} must implement enum_name() for Sema"
+        )
+
+    @classmethod
+    def enum_version(cls) -> str:
+        """Sema identifier (e.g., '000')"""
+        raise NotImplementedError(
+            f"{cls.__name__} must implement enum_name() for Sema"
+        )
+
+
+class SymbolizedEnum(SemaEnum):
+    @classmethod
+    def symbol_to_value(cls, symbol: str) -> str:
+        raise NotImplementedError
+
+    @classmethod
+    def value_to_symbol(cls, value: str) -> str:
+        raise NotImplementedError
+
+    @classmethod
+    def symbols(cls) -> list[str]:
+        raise NotImplementedError

gw_data/sema/indexes/dependency_closure.yaml

@@ -0,0 +1,19 @@
+# GENERATED FILE - DO NOT EDIT
+# Generated from definitions/registry.yaml
+
+types:
+  g.node.gt:
+    '004':
+      enums:
+      - base.g.node.class:000
+      - g.node.status:000
+      formats:
+      - left.right.dot
+      - uuid4.str
+      types: []
+  position.point.gt:
+    '000':
+      enums: []
+      formats:
+      - uuid4.str
+      types: []

gw_data/sema/indexes/local_names.yaml

@@ -0,0 +1,6 @@
+enums:
+  base.g.node.class: base.g.node.class
+  g.node.status: g.node.status
+types:
+  g.node.gt: g.node.gt
+  position.point.gt: position.point.gt

gw_data/sema/indexes/lookup.yaml

@@ -0,0 +1,35 @@
+# GENERATED FILE - DO NOT EDIT
+# Generated from definitions/registry.yaml
+#
+# ------------------------------------------------------------------
+# LOCAL LOOKUP (NON-AUTHORITATIVE)
+#
+# This file provides local resolution from Sema vocabulary words
+# to schema files within this snapshot.
+# ------------------------------------------------------------------
+
+types:
+  g.node.gt:
+    latest_version: '004'
+    versioning_strategy: literal
+    versions:
+      '004': definitions/types/g.node.gt/004.yaml
+  position.point.gt:
+    latest_version: '000'
+    versioning_strategy: literal
+    versions:
+      '000': definitions/types/position.point.gt/000.yaml
+enums:
+  base.g.node.class:
+    enum_type: versioned
+    latest_version: '000'
+    versions:
+      '000': definitions/enums/base.g.node.class/000.yaml
+  g.node.status:
+    enum_type: versioned
+    latest_version: '000'
+    versions:
+      '000': definitions/enums/g.node.status/000.yaml
+formats:
+  left.right.dot: definitions/formats/left.right.dot.yaml
+  uuid4.str: definitions/formats/uuid4.str.yaml

gw_data/sema/indexes/reverse_dependencies.yaml

@@ -0,0 +1,21 @@
+# GENERATED FILE - DO NOT EDIT
+# Generated from definitions/registry.yaml
+
+types: {}
+enums:
+  base.g.node.class:
+    '000':
+      used_by:
+      - g.node.gt:004
+  g.node.status:
+    '000':
+      used_by:
+      - g.node.gt:004
+formats:
+  left.right.dot:
+    used_by:
+    - g.node.gt:004
+  uuid4.str:
+    used_by:
+    - g.node.gt:004
+    - position.point.gt:000

gw_data/sema/indexes/seed_expanded.yaml

@@ -0,0 +1,29 @@
+metadata:
+  generated_from: indexes/public_registry.yaml
+  generated_at: '2026-05-18T22:35:28Z'
+  note: Transitive closure of initial_targets
+initial_targets:
+- position.point.gt:000
+- g.node.gt:004
+- base.g.node.class:000
+- g.node.status:000
+worklist:
+  formats:
+    left.right.dot:
+      path: definitions/formats/left.right.dot.yaml
+    uuid4.str:
+      path: definitions/formats/uuid4.str.yaml
+  enums:
+    base.g.node.class:
+      '000':
+        path: definitions/enums/base.g.node.class/000.yaml
+    g.node.status:
+      '000':
+        path: definitions/enums/g.node.status/000.yaml
+  types:
+    g.node.gt:
+      '004':
+        path: definitions/types/g.node.gt/004.yaml
+    position.point.gt:
+      '000':
+        path: definitions/types/position.point.gt/000.yaml

gw_data/sema/indexes/versions.yaml

@@ -0,0 +1,31 @@
+# GENERATED FILE - DO NOT EDIT
+# Generated from definitions/registry.yaml
+
+
+types:
+  g.node.gt:
+    latest_version: "004"
+    versioning_strategy: "literal"
+    versions:
+      "004":
+        summary: "Baseline runtime version (no prior version tracked)."
+
+  position.point.gt:
+    latest_version: "000"
+    versioning_strategy: "literal"
+    versions:
+      "000":
+        summary: "Initial Sema version"
+
+enums:
+  base.g.node.class:
+    enum_type: "versioned"
+    note: "This enum is versioned; new versions are additive only."
+    versions:
+      "000": {}
+
+  g.node.status:
+    enum_type: "versioned"
+    note: "This enum is versioned; new versions are additive only."
+    versions:
+      "000": {}