Metadata-Version: 2.4
Name: cimhub-chat
Version: 0.1.0a0
Summary: Natural language chat interface for CIMHub power system models
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
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Classifier: Environment :: Console
Requires-Python: <3.14,>=3.10
Description-Content-Type: text/markdown
Requires-Dist: cimhub-core<2.1,>=2.0.0a2
Requires-Dist: cimhub-raw<2.1,>=2.0.0a2
Requires-Dist: cimhub-opendss<2.1,>=2.0.0a2
Requires-Dist: mcp>=1.0.0
Requires-Dist: pydantic>=2.0
Requires-Dist: anthropic
Requires-Dist: langchain>=1.3.12
Requires-Dist: langchain_mcp_adapters
Requires-Dist: langchain-anthropic
Requires-Dist: langchain-openai
Requires-Dist: langchain-ollama
Requires-Dist: langgraph
Requires-Dist: a2a-python
Requires-Dist: streamlit

# 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

```bash
# 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:

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

| Provider | Models |
|---|---|
| Anthropic | `claude-sonnet-5`, `claude-opus-4-8` |
| OpenAI | `gpt-4o`, `gpt-4-turbo` |
| Ollama | any locally-served model |

## Running Tests

```bash
uv run pytest cimhub_chat/tests/ -v
```
