Metadata-Version: 2.4
Name: openstudio-ai
Version: 0.4.0
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.10.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.

## 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.
- 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 and generated child skills.
- Reviewed OpenStudio SDK knowledge packs.
- Packaging north-star plan for stable `pip install` and marketplace agentic
  installation paths.

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

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