cimhub_chat

Natural language chat interface for CIMHub power system models. Load any CIMHub-supported model (DSS, GLM, RAW, MATPOWER, CIM XML) and query or edit it in plain English.

Features

• Query — "How many loads are on bus 634?" / "What is the total MW?"
• Edit — "Change load L1 to 500 kW" / "Add a new line from 632 to 645"
• Cross-format awareness — "Show me the DSS command for this EnergyConsumer"
• Write-back — Saves edits to native format files or CIM XML
• Schema-aware — Introspects LinkML-generated dataclasses at runtime so the LLM knows valid field names, types, and relationships without hard-coded prompts

Usage

# Start the chat CLI with a DSS model
cimhub-chat ieee13/Master.dss

# Start with a PSS/E RAW model
cimhub-chat network.raw

# Start with a CIM XML file
cimhub-chat ieee13.xml --cim-profile cimhub_2026

Or from Python:

from cimhub_chat.cli import start_chat

start_chat("ieee13/Master.dss")

Architecture

CLI / REPL
    ↓
ModelService   (loads + manages the active CIM model)
    ↓
Agent          (LLM-backed reasoning loop via LangGraph)
    ↓
MCP Server     (exposes CIM graph as tools via Model Context Protocol)
    ↓
CIMHub converters  (cimhub_opendss, cimhub_raw, cimhub_gridlabd, ...)

The MCP server (mcp_server/) provides typed tools (list_buses, get_load, set_load_power, etc.) backed by runtime introspection of the loaded model's LinkML schema. The agent calls these tools rather than generating raw Python.

Supported LLMs

Configured via environment variables or --model flag:

Running Tests

uv run pytest cimhub_chat/tests/ -v