Metadata-Version: 2.4
Name: cimhub_core
Version: 2.0.0a1
Summary: CIMHub Core Library — shared foundation for all CIMHub converter packages
Author-email: Pacific Northwest National Laboratory <gridappsd@pnnl.gov>
License: BSD-2-Clause
Project-URL: Homepage, https://github.com/PNNL-CIM-Tools/CIMHub_2_0
Project-URL: Bug Tracker, https://github.com/PNNL-CIM-Tools/CIMHub_2_0/issues
Project-URL: Documentation, https://pnnl-cim-tools.github.io/CIMHub_2_0/cimhub_core/
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Classifier: Environment :: Console
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: BSD License
Classifier: Topic :: Scientific/Engineering
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: cim-graph>=0.5.0a7
Requires-Dist: linkml-runtime~=1.9.5

# 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.

```python
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

```python
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 |
