OpenStudio SI Harness
OpenStudio SI Harness packages a local MCP runtime, host adapters, skills, knowledge, and workflow-state tools for SI-assisted building-energy modeling.
The SI rename uses package version 0.4.2, MCP plugin/runtime contract 6.0, and OpenStudio 3.11.0. Install the SI runtime and host plugin together. See the release guide for publication and cutover steps.
Terminal and plant equipment coverage through phases 11–13 is reviewed. See the release review summary for scope and limits.
Current Capabilities
- Boiler, district-capacity, terminal-control, terminal-replacement and tower edits validate initially empty weather metadata against the reviewed companion EPW; changed resources, weather metadata and plan tampering remain rejected.
- OpenStudio MCP server for model lifecycle, simulation, results, SDK lookup, runtime storage, MCP-backed blackboard workflow state, and downloadable self-contained OSM geometry viewers.
- Claude Code plugin export.
- Codex plugin export.
openstudio-hvac-visualizerproduces read-only local JSON, Mermaid and Markdown equipment views of air/plant connections, VRF membership and every thermal zone. Zones are green, air-side equipment blue and water-side equipment orange; SDK routing nodes and controls stay in the detailed JSON. One connected air diagram reads from supply on the left through zones to return/exhaust on the right, with verified outdoor boundary arrows and connected-path fan roles. Water views omit routing-only bypass paths with a note and retain their JSON evidence. VRF indoor units fold contained coils/fans into their labels; shared-zone labels name other serving air/VRF systems. Hidden-only groups produce no empty diagrams. It uses the pinned SDK and bundled model preparation after the existing NLR priority gate. Component ports retain their provenance; embedded paths and legacy port discrepancies warn. Weather and simulation are not required. See the increment D review guide for coverage and commands.- Opt-in, user-local learning evidence and review-gated personal lessons shared by Claude Code and Codex through MCP; the CLI curates candidates and detects repeated scripts as candidate measures. “Opt-in” means explicit learning-tool invocation, not a runtime enable/disable setting.
- HVAC workflow skills with a bundled VAV creation workflow; legacy object-level VAV skills and their generation machinery have been removed.
- VAV and prototype CAV now compose shared equipment scripts in one system transaction. The CAV skill supports a constant-volume supply fan, water heat/ reheat and water or approved DX cooling with VAV-reheat terminals. See the modularization review guide for phases, source trace, supported arrangements and verification. CAV requires an explicit outdoor-air choice and aligns 100% OA operation with coil sizing; approved CAV plans must be regenerated after this correction.
openstudio-district-capacity-editoredits one existing supply-side DistrictHeatingWater or DistrictCooling nominal thermal watts or explicit Autosize in place. Retain schedule, connections, controls and identity. Plans expose the retained capacity-fraction schedule, dispatch sharing, loop conditions and temperature protection (including at fraction 0). Capacity changes are not COP/efficiency or proportional pump-flow savings. Steam needs separate coverage.openstudio-tower-performance-editoredits one condenser-loop variable-speed cooling tower's total design fan watts/Autosize, minimum fan-airflow ratio or free-convection capacity fraction in place. Curves, design conditions, water connections and unrequested inputs stay unchanged. Plans flag airflow sizing, cycling, fan-off cooling and water use. Native evidence separates power-only behavior from low-load controls and reports pump/chiller energy alongside fan electricity; fan-off does not mean pump-off or guaranteed whole-plant savings.openstudio-chiller-performance-editoredits one air- or water-cooled electric EIR chiller's explicit COP, cooling capacity (watts/Autosize), part-load or unloading limits in place. Curves, unrequested sizing/flow inputs, condenser circuits, controls and identities stay unchanged. Capacity affects PLR, dispatch and delivered cooling; plans report reference dispatch limits and flag separate condenser fan power scaling when its retained power ratio is positive. Plans flag autosized condenser pumps/towers whose calculated sizes and energy may change. Heat recovery, thermosiphon and other classes need separate coverage. Reference COP is not seasonal or whole-plant efficiency; changed condenser heat can change calculated condenser sizing.openstudio-boiler-performance-editoredits one heating-plant hot-water boiler's explicit nominal thermal capacity/Autosize, minimum/maximum/optimum part-load ratios, HHV efficiency and electric/fuel parasitics in place. Fuel, flow sizing policy, curves, sizing factor, other controls and identities stay unchanged; unrequested capacity stays exact. Capacity affects dispatch, PLR, curve/parasitic energy and possibly unmet loads, not just a limit. Plans expose curve/EMS/dispatch dependencies and detect configured curves omitted by translation. See the 12a checkpoint.- Explicit Autosize in boiler, chiller, tower and district editors reports design-day/period counts and the effective translated plant-sizing flag. Missing/off/unverified sizing keeps the edit available but marks simulation unready. This is conservative: some fixed-flow cases still size without a plant-sizing run. Multi-boiler Autosize exposes other capacities/factors and warns that each boiler receives the whole design load times its own factor, rather than an automatic share.
openstudio-terminal-replacerconverts one connected single-duct VAV no-reheat terminal to constant-volume no-reheat, or the reverse. Explicit maximum-flow and VAV minimum-fraction choices accompany retained zone service, boundary nodes, availability and zone/system sizing. The terminal gets a new identity; direct references and unsupported controls block conversion. Review overcooling and ventilation before simulation. Plans identify retained fan classes and VRP sizing dependencies; preserved inputs do not promise unchanged calculated OA. Reheat conversions remain separate. See the release review summary.- The VAV creator's
prototype_pvav_v1profile adds packaged VAV with gas central heat, approved two-speed DX cooling, and electric terminal reheat. It uses the same reviewed preflight and saved-model checks as VAV reheat. openstudio-terminal-editoredits one connected VAV reheat/no-reheat terminal's Constant-method minimum fraction or applicable reheat controls in place, including terminals in the prototype CAV recipe. It preserves equipment, references, schedules, connections and unrequested sizing; saved checks verify the requested EnergyPlus fields. Plans expose ventilation, turndown/EMS and sizing dependencies. At the pinned engine, fraction-limit edits require the per-area field at Autocalculate; an Autosize reset must be explicitly chosen. Numeric per-area limits are unsupported and retained ignored limits warn. Terminal replacement and coil-rating changes are separate.- The independent
openstudio-supply-fan-performance-editorskill edits explicit efficiency/pressure values on a selected air loop's direct constant- or variable-volume fan in place. Fan, connection, metadata and reference handles remain stable, including LifeCycleCost and EMS actuators. Saved validation and translation precede publication of a new copy. VAV/CAV creation requires complete performance inputs and shares setters/pressure conversion with this editor.openstudio-supply-fan-replacernow handles genuine constant ↔ variable-volume replacement with explicit curve/performance and terminal/system-sizing choices. It preserves air boundary nodes and translated controls, reports changed fan/ connection identities, and rejects references needing migration. Existing compatible fan-name outputs/custom electricity meters remain intact. An optional explicit end-use label supports reporting changes; stale retained labels warn. Terminals and system sizing remain unchanged; whole-system conversion and embedded fans require separate coverage. openstudio-pump-performance-editoredits one existing single constant- or variable-speed plant pump on either supply or demand side, retaining its identity, connections, metadata and references. Explicit head, motor settings, operating mode, electric-power sizing and variable-speed coefficients use a reviewed copy transaction. Plans expose fixed power, inactive sizing factors and motor feasibility that requires sizing when flow is autosized; saved checks and translation precede publication. Native cases verify actual power under both autosizing methods and fixed power.openstudio-pump-replacerhandles genuine single constant ↔ variable-speed class changes with explicit rated-flow/power policies and variable-speed curve/ minimum flow. It retains plant position, boundary nodes, common controls and compatible reporting references; pump/connection handles change. Native paired runs verify unchanged design sizing and the selected operating-power curve. Constant-speed supply plans expose explicit and translated demand bypasses, warning when the OSM has none while preserving the requested plant topology. Pump banks, pressure/VFD hardware and plant-flow redesign need separate coverage.openstudio-economizer-editorchanges explicit economizer type, lockout and temperature/enthalpy cutoffs in place, preserving OA/MV identities, ventilation, schedules, sizing and equipment. Plans expose retained additive limits and OA overrides and verifies a translated mixed-air temperature setpoint source for enabled economizers; missing control marks simulation unready. Saved checks and translation precede copied publication. VAV/CAV creation shares the canonical setters. Minimum-OA/DCV uses the independent ventilation editor; direct intake/recovery attachment uses the OA connector. Native VAV/CAV pairs verify actual economizer status and OA-flow response on mild design days.openstudio-ventilation-editoredits explicit minimum/maximum OA flow, schedule references and existing ZoneSum DCV in place. Zone OA/People, schedule contents, sizing, economizer, equipment and identities remain protected. The editor preserves OSM flow/fraction settings unless explicitly changed. Plans expose occupancy inputs, nominal OA, schedule ranges, caps and sizing/control warnings. DCV review distinguishes declared and translated OA floors, flags verified blocking floors as ineffective, and explains the SDK's Autosize-to-zero DCV translation; partial floors retain qualified warnings. VAV/CAV share the ventilation setters; saved validation and translation precede copied publication. Native pairs verify occupancy-driven requested and actual OA reductions, with unchanged full-occupancy requests. Other ventilation-method DCV and CO2/IAQ policy need separate coverage.openstudio-outdoor-air-connectorattaches a direct OA intake to a served loop without one, or sensible/latent recovery to empty direct OA/relief streams. Explicit ventilation, effectiveness, power, frost, bypass and outlet-control choices are previewed; both air streams and all new controls/curves are checked after saving. Optional pretreat control requires a verified mixed-air reference.openstudio-heat-recovery-editoredits an existing exchanger in place, retaining curves, nodes, controls and incoming references. Plans explain curve scaling and mark missing temperature control simulation-unready. Uncontrolled recovery on cooled-air loops warns about added cooling load; native comparisons report downstream coil energy alongside recovered heat. Native VAV/CAV cases verify heat transfer, economizer lockout and newly attached intakes. Shared/ dedicated OA, embedded equipment and exchanger replacement need separate coverage.- Independent water-coil skills separate in-place settings edits from new attachment.
openstudio-water-coil-editorchanges explicit ratings, names, availability, autosizing and controller values, preserving coil/controller/connection/reference handles.openstudio-water-coil-connectorattaches only at the supply outlet and finalizes its new controller after plant and air connections. It also migrates existing main-supply water coils to another ready water plant, preserving coil/ controller/air identities while resetting sizing and rebuilding water links. Its review reports remaining source-plant loads and warns when no coils remain; active retained water-temperature mismatches name the editor for follow-up. The connector also relocates a water coil to a selected supply outlet on the same or another main air loop, preserving its plant branch and equipment identities.openstudio-coil-replacerconverts main-supply water heating to electric with explicit efficiency, preserved temperature control, Autosize and reference-policy choices. It reports removed water equipment and the new coil identity. Same-class replacement remains internal. VAV/CAV share the setters; saved validation and EnergyPlus translation precede publication. Heating UA rated temperatures are optional, informational metadata. Missing plant equipment or controls produces a warning for an in-place edit and marks simulation readiness false; attachment requires a ready plant. - Independent bundled plant creation and selective HVAC removal support standalone requests and broader HVAC workflows, including VAV replacement. Air-side skills connect their water coils to the created plants. Plant choices include gas/electric boilers, district heating/cooling, and air- or water-cooled chillers with condenser towers. Removal previews the SDK cascade for selected air loops, VRF systems and zone equipment while protecting existing plants and model loads. Both use reviewed plans and new output copies; native design-day checks cover three plant-to-VAV configurations. See the supported assumptions and verification.
- Unexpected execution failures route to
report-openstudio-failure, which automatically submits sanitized diagnostics topnnl/openstudio-si-harness. Issues are created under your own authenticated GitHub account. Original exception text stays local; public errors use fixed messages and plugin file/function/line locations. Models and companions are excluded; missing authentication/network retains local drafts. Reporting readiness is optional, with a project-level disable policy. See the reporting contract and tests. - Reviewed OpenStudio SDK knowledge packs.
- Skill resource export for both hosts, with one plugin-local
sdk/library and fixed launchers in owning skills. Install or move the complete plugin; no separate shared package is required. Export records size evidence and enforces a 1,114,112-byte (1 MiB + 64 KiB) SDK-resource budget. Shared guides and schemas live once undersdk/; exported skill links stay inside the plugin. Markdown participates in bundle integrity, so documentation edits require a matching full export. See the release review summary. Earlier 0.4.1 exports omitted some declared HVAC guides; regenerate from the updated harness and refresh the complete plugin to repair those links. This package pins OpenStudio 3.11.0 consistently in its dependency, lock metadata and exported compatibility contract. SDK skills include a grouped assumption review with editable inputs and visible fixed controls; declining proposed VAV defaults leads to review/adjust rather than cancellation. SDK skills also include a standalone doctor and shared version guard. The VAV skill includes read-only preflight, reviewed-plan apply, exclusive publication, independent saved-topology and EnergyPlus translation checks, referenced resource relocation through OpenStudio workflow lookup, and bounded summaries with reports written directly by each entrypoint. Scripts run directly through host tools; supported VAV edits require no modeling MCP runtime or per-object code drafting. Outputs use portable references and Application-style companion folders; missing weather warns without blocking VAV editing. External CSV outputs report when they require the companion workflow; model snapshots and simulations retain those resources. Runtime snapshots use absolute CSV references across measure copies; CSV resource failures warn during load so inspection and repair remain available, then block simulation until repaired and reloaded. Weather warnings remain visible and allow an explicit or later-set weather file. Follow-up regressions cover every behavior control and native simulation after moving ScheduleFile resources. Bespoke SDK guidance is a conditional reference. Native hydronic and electric/DX design-day sizing checks cover a five-zone fixture. See Skill-bound SDK development summary. The specified instruction route uses approximately 75% less text; actual agent-token savings remain unmeasured. Configured, compatible NLR OpenStudio MCP has provider priority. After provider selection, use a specific modeling skill; bespoke SDK programming is the fallback for requests those skills do not cover. - Packaging north-star plan for stable
pip installand marketplace agentic installation paths.
Package/plugin releases are tied to their tested OpenStudio SDK release. Updating that release requires a new package/plugin release, coordinated dependency and compatibility changes, and native verification of exported bundles; changing the contract alone is not a supported upgrade. A newer NLR model must remain with a compatible provider or use a matching package release; local scripts never downgrade it. See SDK release requirements.
Development Setup
New contributors can choose a reproducible Python 3.10 Dev Container or a manual standard/full environment. The full path installs the separately locked AUTOMA-AI and Streamlit development project; the standard path is sufficient for harness, MCP, adapter, skill, packaging, and documentation work. Follow the Developer Guide environment setup for the complete onboarding steps.
For a short guide to repository access, folder ownership, plugin exports, and a focused contribution check, see Contributing.
For a manual standard setup from this repository root:
python -m venv .venv
. .venv/bin/activate
python -m pip install -e ".[dev]"
python -m playwright install chromium
The production harness supports Python 3.10 or newer. The dev extra installs
its test and release tools.
Publishing runs fast checks and one paired plugin-export smoke test. Full pull-request/manual CI retains the slower modeling, simulation, browser and packaging checks. See test suite selections for commands and timing reports.
Install the runtime package after it is published:
python -m pip install openstudio-si
openstudio-si install-runtime
openstudio-si doctor
openstudio-si-mcp --transport stdio
OpenStudio SI requires both the PyPI openstudio Python package, installed as
a dependency of openstudio-si, and the native OpenStudio application/CLI. Set
OPENSTUDIO_PATH when the CLI is not on PATH or when selecting a specific
installation. Alternatively, after confirming the executable, save it for
future Claude Code and Codex MCP launches with:
openstudio-si configure-openstudio --path /path/to/openstudio
openstudio-si doctor reports core plugin readiness only when the Python
runtime, MCP command, native OpenStudio executable, and plugin compatibility
are ready for energy modeling. Optional integrations such as NLR OpenStudio-MCP
are reported separately and do not block core readiness. NLR discovery accepts
openstudio-mcp in Codex or Claude project configuration. Detection means
configured; verify NLR status/version through
the connected server before modeling. PNNL’s foundational MCP advertises
openstudio-si-mcp and uses the host connection name openstudio_si.
The base package is the recommended install for Claude Code, Codex, and other marketplace-style host integrations. It intentionally does not install AUTOMA-AI or Streamlit. The standalone local SI app is a separate optional development environment that also supports Python 3.10+:
uv sync --project standalone
uv run --project standalone streamlit run standalone/ui.py --server.port 8504
Standalone mode requires Python 3.10+ and user-provided LLM configuration, such as API keys or model endpoint settings, in the local environment.
For a browser-ready containerized demo, use docker compose --profile standalone up --build standalone and open http://localhost:8504. See
standalone/README.md for the optional host-port
override and environment setup.
Run focused tests:
python -m pytest -q \
tests/test_mcp_openstudio_smoke.py \
tests/test_openstudio_sdk_docs.py \
tests/test_openstudio_learning_pipeline.py \
tests/test_openstudio_codex_adapter.py \
tests/test_openstudio_claude_code_adapter.py
Start the MCP server in stdio mode:
openstudio-si-mcp --transport stdio
Curate local learning outside an active modeling session:
openstudio-si learning curate
openstudio-si learning propose-measures
openstudio-si learning prune-preview
These commands never approve a candidate or delete one without explicit user action.
Export local development plugins:
openstudio-si export claude \
--output-dir /tmp/openstudio-si-claude-plugin \
--runtime-mode local
openstudio-si export codex \
--output-dir /tmp/openstudio-si-codex-plugin \
--runtime-mode local
Export marketplace-oriented plugins that expect an installed runtime command:
openstudio-si export claude \
--output-dir /tmp/openstudio-si-claude-plugin \
--runtime-mode marketplace
openstudio-si export codex \
--output-dir /tmp/openstudio-si-codex-plugin \
--runtime-mode marketplace
Export a publishable repository containing both host packages, generated install guides, and source provenance:
openstudio-si export marketplace \
--output-dir /path/to/openstudio-si-plugins \
--runtime-mode marketplace \
--force
This produces a generated release tree; it validates both exports before completion. Keep the harness repository as the source of truth and do not edit generated plugin files directly.
For development exports from this checkout, use .venv/bin/openstudio-si
(or activate the repository virtualenv) so the command uses the current adapter
code. An older pipx-installed command can combine older generated setup/helpers
with this checkout's skill files; --workspace-root selects assets, not the
installed exporter code. Both exports configure PNNL as openstudio_si launching
openstudio-si-mcp; NLR setup uses openstudio-mcp. PNNL workflow records use
nlr_openstudio as their stable provider identifier, separate from the host
connection name.
After installing the Codex marketplace plugin, add the shared OpenStudio modeler policy to each Codex project that should route plain-language OpenStudio requests through the workflow orchestrator:
openstudio-si install codex --target-dir /path/to/codex-project
This creates AGENTS.md when it does not exist. Use --dry-run to preview;
an existing unmanaged AGENTS.md requires --force before the managed block
is appended.
Key Docs
- SDK Integration and Review Summary
- Contributing
- Multi-lab Assessment and One-month Plan
- Harness Details
- Packaging North Star
- Runtime Installation Contract
- Marketplace Install Guide
- NLR OpenStudio-MCP in Claude Desktop
- PyPI Release Guide
- Developer Guidance
Runtime State
Local runtime state is intentionally ignored by Git:
.openstudio_si_mcp_workspace/.openstudio_si_blackboards/logs/outputs/
The MCP runtime uses local SQLite metadata and filesystem workspaces for large OSM, SQL, and log artifacts.
Bundled SDK operations now gate older or handle-unstable OSMs before planning.
The shared loader also rejects missing air- or plant-loop availability lists.
Their skill-local prepare_model.py creates a stable reported working copy, then
the workflow repeats inventory/preflight with all exact checks intact. See the
increment A contract and local verification commands.
Metadata
Release files for openstudio-si 0.4.2
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| openstudio_si-0.4.2.tar.gz | 10.5 MB | Without provenance | Details for openstudio_si-0.4.2.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| openstudio_si-0.4.2-py3-none-any.whl | Python 3 | none | any | Details for openstudio_si-0.4.2-py3-none-any.whl |
Total release size: 21.0 MB
Release files / openstudio_si-0.4.2.tar.gz
| Download URL | openstudio_si-0.4.2.tar.gz |
|---|---|
| Size | 10.5 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
52a598afa9c68d476246250579e2355fd2bbc6ca5a3a7001c9bc7c5201856bf5
|
|
BLAKE2b-256 checksum How to use checksums |
de4fd5cad3e83af66204283f8a6b7fe7bb68b88524a60d10fdd8b0cbda52cdf9
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Release files / openstudio_si-0.4.2-py3-none-any.whl
| Download URL | openstudio_si-0.4.2-py3-none-any.whl |
|---|---|
| Size | 10.5 MB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
c81b9bae11269c4c09f4bb4c9b538934888e234abf5b5ac7d3b41d02d3c4caa0
|
|
BLAKE2b-256 checksum How to use checksums |
5bcf2d3e0922b0cd4b7a70e5760cfb8a2032cbe594a9247f1b8498f92380a265
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Security for openstudio-si 0.4.2
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.