cimhub-core 2.0.0a1

CIMHub Core Library — shared foundation for all CIMHub converter packages

cimhub_core

Shared foundation for all CIMHub converter packages. Provides the base classes, data model, and utilities that every spoke in the hub-and-spoke architecture depends on.

What's in here

Module	Purpose
base.py	ABCs: FormatReader, FormatWriter, FormatImporter, FormatExporter
graph_model.py	GraphModel — typed in-memory store for LinkML dataclasses
registry.py	ConverterRegistry — decorator-based dispatch for import/export functions
scaffold.py	Code generator that scaffolds a new converter package from a template
serialization.py	Shared serialization helpers (CSV, YAML round-trips)
connectivity/	Topology helpers (bus lookups, connectivity node resolution)
transformations/	CIM-to-CIM geometry transforms (wire spacings, coordinate systems)
get_utils/	get_or_create helpers for common CIM objects (BaseVoltage, Substation, etc.)
mcp/	MCP server tools for LLM-assisted model introspection

Architecture

Every CIMHub converter follows the same four-layer pipeline:

LinkML YAML schemas   →   Generated dataclasses   →   GraphModel   →   FormatReader / FormatWriter
                                                            ↕
                                                    FormatImporter / FormatExporter
                                                    (native ↔ CIM conversion)

cimhub_core owns the bottom two layers (GraphModel + ABCs). Each spoke package owns its own LinkML schema, generated dataclasses, and converter implementations.

GraphModel

The central data container. A sorted dictionary keyed by class then by identifier.

from cimhub_core import GraphModel

model = GraphModel()
model.add_to_graph(obj)

# Retrieve all objects of a class (sorted by identifier)
buses = model.list_by_class(schema.BusRecord)

# Search by attribute value
gen = model.find_by_attribute(schema.GeneratorRecord, "bus_number", 101)

# Counts and membership
model.count(schema.BusRecord)
schema.BusRecord in model
len(model)

Converter ABCs

from cimhub_core import FormatImporter, FormatExporter

class MyImporter(FormatImporter):
    def to_cim(self, source, **kwargs):
        ...

class MyExporter(FormatExporter):
    def to_format(self, cim_model, **kwargs):
        ...

See cimhub_core/src/cimhub_core/development/CONVERTER_API.md for the full contract.

Development Docs

The development/ directory contains the canonical references for all converter authors:

Doc	What it covers
CONVERTER_API.md	Public API every converter must expose
READER_WRITER_GUIDE.md	FormatReader / FormatWriter implementation guide
LINKML_TEMPLATE.md	How to write LinkML schemas for native formats
UNITS.md	CIMUnit usage — never manually multiply by 1e3/1e6
STYLE_GUIDE.md	Coding rules (KISS → DRY → Readable → Maintainable)
ARCHITECTURE.md	Full sub-package architecture diagram
TEST_FIXTURE_ARCHITECTURE.md	4-tier test strategy
CONDUCTOR_GEOMETRY_ANTI_PATTERNS.md	Line/cable geometry export rules