Metadata-Version: 2.4
Name: openstudio-ai
Version: 0.4.1
Summary: OpenStudio AI harness with MCP runtime, host adapters, skills, and knowledge.
Project-URL: Homepage, https://gitlab.pnnl.gov/building-energy-modeling/openstudio-ai-harness
Project-URL: Repository, https://gitlab.pnnl.gov/building-energy-modeling/openstudio-ai-harness
Project-URL: Documentation, https://gitlab.pnnl.gov/building-energy-modeling/openstudio-ai-harness
Author: PNNL
License-Expression: BSD-3-Clause
License-File: LICENSE
Keywords: ai,building-energy-modeling,mcp,openstudio,simulation
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: BSD License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering
Requires-Python: >=3.10
Requires-Dist: jinja2>=3.1.0
Requires-Dist: mcp<3,>=2
Requires-Dist: openstudio==3.11.0
Requires-Dist: platformdirs>=4.0.0
Requires-Dist: pydantic>=2.12.3
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: pyyaml>=6.0.2
Requires-Dist: tomli>=2.0.0; python_version < '3.11'
Provides-Extra: dev
Requires-Dist: black>=25.9.0; extra == 'dev'
Requires-Dist: build>=1.2.0; extra == 'dev'
Requires-Dist: playwright>=1.50.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=1.2.0; extra == 'dev'
Requires-Dist: pytest>=8.4.2; extra == 'dev'
Requires-Dist: twine>=5.0.0; extra == 'dev'
Description-Content-Type: text/markdown

# OpenStudio AI Harness

OpenStudio AI Harness packages a local MCP runtime, host adapters, skills,
knowledge, and workflow-state tools for AI-assisted building-energy modeling.

Release preparation: **0.4.1**, using MCP plugin/runtime contract **6.0** and
OpenStudio **3.11.0**. Refresh both the runtime and exported host plugin together;
contract compatibility requires an exact match. See the
[release guide](docs/RELEASE.md) for validation and publication steps.

## Current Capabilities

- 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-visualizer` produces 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](docs/SDK_INTEGRATION_SUMMARY.md#d--read-only-hvac-visualization) 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](docs/HVAC_MODULARIZATION_WORK.md) 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.
- The independent `openstudio-supply-fan-performance-editor` skill 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-replacer` now 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-editor` edits 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-replacer` handles 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-editor` changes 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-editor` edits 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-connector` attaches 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-editor` edits 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-editor` changes explicit ratings, names, availability,
  autosizing and controller values, preserving coil/controller/connection/reference
  handles. `openstudio-water-coil-connector` attaches 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-replacer` converts 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](docs/SKILL_BOUND_SDK_SUMMARY.md#plant-creation-and-hvac-removal-extension).
- Unexpected execution failures route to `report-openstudio-failure`, which
  automatically submits sanitized diagnostics to `pnnl/openstudio-ai-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](docs/SDK_INTEGRATION_SUMMARY.md#c--automatic-failure-reporting).
- 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 MiB SDK-resource budget. See the [packaging contract and review commands](docs/SDK_INTEGRATION_SUMMARY.md#b--shared-sdk-packaging).
  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](docs/SKILL_BOUND_SDK_SUMMARY.md). 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 install` and 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](docs/SKILL_BOUND_SDK_SUMMARY.md#decisions-and-architecture).

## 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](docs/DEVELOPER_GUIDANCE.md#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](CONTRIBUTING.md).

For a manual standard setup from this repository root:

```bash
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.

Install the runtime package after it is published:

```bash
python -m pip install openstudio-ai
openstudio-ai install-runtime
openstudio-ai doctor
openstudio-ai-mcp --transport stdio
```

OpenStudio AI requires both the PyPI `openstudio` Python package, installed as
a dependency of `openstudio-ai`, 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:

```bash
openstudio-ai configure-openstudio --path /path/to/openstudio
```

`openstudio-ai 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-ai-mcp` and uses the host connection name `openstudio_ai`.

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 AI app is a separate optional
development environment that also supports Python 3.10+:

```bash
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](http://localhost:8504). See
[`standalone/README.md`](standalone/README.md) for the optional host-port
override and environment setup.

Run focused tests:

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

```bash
openstudio-ai-mcp --transport stdio
```

Curate local learning outside an active modeling session:

```bash
openstudio-ai learning curate
openstudio-ai learning propose-measures
openstudio-ai learning prune-preview
```

These commands never approve a candidate or delete one without explicit user
action.

Export local development plugins:

```bash
openstudio-ai export claude \
  --output-dir /tmp/openstudio-ai-claude-plugin \
  --runtime-mode local

openstudio-ai export codex \
  --output-dir /tmp/openstudio-ai-codex-plugin \
  --runtime-mode local
```

Export marketplace-oriented plugins that expect an installed runtime command:

```bash
openstudio-ai export claude \
  --output-dir /tmp/openstudio-ai-claude-plugin \
  --runtime-mode marketplace

openstudio-ai export codex \
  --output-dir /tmp/openstudio-ai-codex-plugin \
  --runtime-mode marketplace
```

Export a publishable repository containing both host packages, generated install
guides, and source provenance:

```bash
openstudio-ai export marketplace \
  --output-dir /path/to/openstudio-ai-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-ai`
(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_ai` launching
`openstudio-ai-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:

```bash
openstudio-ai 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](docs/SDK_INTEGRATION_SUMMARY.md#status-and-development-rules)
- [Contributing](CONTRIBUTING.md)
- [Multi-lab Assessment and One-month Plan](docs/MULTILAB_ONE_MONTH_PLAN.md)
- [Harness Details](docs/HARNESS_DETAILS.md)
- [Packaging North Star](docs/PACKAGING_NORTHSTAR.md)
- [Runtime Installation Contract](docs/RUNTIME_INSTALLATION_CONTRACT.md)
- [Marketplace Install Guide](docs/MARKETPLACE_INSTALL_GUIDE.md)
- [NLR OpenStudio-MCP in Claude Desktop](docs/CLAUDE_DESKTOP_NLR_OPENSTUDIO_MCP.md)
- [PyPI Release Guide](docs/RELEASE.md)
- [Developer Guidance](docs/DEVELOPER_GUIDANCE.md)

## Runtime State

Local runtime state is intentionally ignored by Git:

- `.openstudio_ai_mcp_workspace/`
- `.openstudio_ai_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](docs/SDK_INTEGRATION_SUMMARY.md#a--deterministic-inputs-and-explicit-preparation).
