openstudio-ai 0.1.0__tar.gz

openstudio_ai-0.1.0/.gitignore

@@ -0,0 +1,38 @@
+# Python
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+dist/
+build/
+*.egg-info/
+
+# Local environments
+.venv/
+venv/
+.env
+
+# macOS / editor
+.DS_Store
+.idea/
+.vscode/
+
+# OpenStudio AI runtime state
+.openstudio_mcp_workspace/
+.openstudio_ai_blackboards/
+.sdk_doc_index.json
+logs/*
+!logs/.gitkeep
+outputs/*
+!outputs/.gitkeep
+state/candidate_assets/*
+state/sessions/*
+state/snapshots/*
+state/workflow_runs/*
+
+# Generated local package exports
+openstudio-ai-claude-plugin/
+openstudio-ai-codex-plugin/

openstudio_ai-0.1.0/HANDOFF.md

@@ -0,0 +1,88 @@
+# OpenStudio AI Harness Handoff
+
+## Current Status
+
+The initial standalone repository migration has started. The OpenStudio AI
+example from `BEM-AI/examples/openstudio_ai` now lives in a flattened,
+root-level harness layout in this repository.
+
+Migrated components:
+
+- OpenStudio MCP runtime and tools.
+- Claude Code and Codex plugin adapters.
+- Skills, generated HVAC child skills, knowledge packs, and SDK index modules.
+- Learning pipeline modules, policies, prompts, and docs.
+- Local blackboard modules and MCP-backed blackboard tools.
+- Focused regression tests from the BEM-AI repository.
+
+First packaging phase completed:
+
+- Runtime installation contract documented in `docs/RUNTIME_INSTALLATION_CONTRACT.md`.
+- Claude and Codex adapters support `--runtime-mode local`, `installed`, and
+  `marketplace`.
+- Installed and marketplace exports point `.mcp.json` at `openstudio-ai-mcp`.
+- Marketplace exports include setup/doctor/repair command files and
+  `installers/install_runtime.py` plus `installers/doctor_runtime.py`.
+- Energy-modeler marketplace setup guide added in `docs/MARKETPLACE_INSTALL_GUIDE.md`.
+
+Pip release baseline completed:
+
+- Distribution name set to `openstudio-ai`.
+- `openstudio>=3.10.0` is a required runtime dependency because the MCP server
+  depends on the OpenStudio Python package.
+- `openstudio-ai` CLI added with `doctor`, `paths`, `version`,
+  `install-runtime`, `repair`, `export`, and `validate-export`.
+- `openstudio-ai-mcp` console script remains the MCP runtime entrypoint.
+- Runtime assets, skills, knowledge, prompts, resources, and docs are included
+  in the wheel while local folders such as `.venv`, `.git`, `.idea`, and
+  runtime workspaces are excluded.
+- PyPI/TestPyPI release instructions added in `docs/RELEASE.md`.
+
+Documentation cleanup completed:
+
+- Long-form docs and diagrams moved under `docs/`.
+- Root `blackboard_schema.json` removed because active exported schemas live in
+  `blackboard/schemas/`.
+- `docs/README.md` documents the current docs map and schema decision.
+
+## Verification
+
+Last verified from this repository root with the BEM-AI development virtual
+environment:
+
+```bash
+/Users/xuwe123/github/BEM-AI/.venv/bin/python -m py_compile $(find . -name '*.py' -print)
+/Users/xuwe123/github/BEM-AI/.venv/bin/python -m pytest -q tests
+```
+
+Result:
+
+- `py_compile`: passed.
+- `pytest`: `54 passed, 2 skipped, 5 warnings`.
+- The skipped tests require `OPENSTUDIO_PATH` to point to a valid OpenStudio
+  executable.
+- `python -m build`: produced `dist/openstudio_ai-0.1.0.tar.gz` and
+  `dist/openstudio_ai-0.1.0-py3-none-any.whl`.
+- `twine check dist/*`: passed in a temporary smoke-test environment.
+- Fresh wheel install smoke test: `openstudio-ai`, `openstudio-ai-mcp`, and
+  marketplace plugin exports worked.
+
+## Notes
+
+- `pyproject.toml` is a first standalone package scaffold. It explicitly
+  includes the harness tree so skills, prompts, resources, knowledge files, and
+  diagrams are distributed with the package.
+- Runtime state and generated caches are ignored by Git.
+- The root README now describes the migrated standalone harness and the current
+  developer commands.
+
+## Next Steps
+
+1. Decide the long-term dependency source for `automa_ai` before publishing.
+2. Add CI that runs `py_compile` and the focused pytest suite.
+3. Test `pip install -e ".[dev]"` in a fresh environment once package
+   dependencies are settled.
+4. Add an OpenStudio-installed verification pass with `OPENSTUDIO_PATH`
+   configured.
+5. Continue packaging work for MCP distribution and marketplace-oriented
+   agentic installation.

openstudio_ai-0.1.0/LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2026, Battelle Memorial Institute
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its contributors
+   may be used to endorse or promote products derived from this software
+   without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT INCLUDING NEGLIGENCE OR OTHERWISE ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

openstudio_ai-0.1.0/PKG-INFO

@@ -0,0 +1,129 @@
+Metadata-Version: 2.4
+Name: openstudio-ai
+Version: 0.1.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.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering
+Requires-Python: >=3.12
+Requires-Dist: jinja2>=3.1.0
+Requires-Dist: mcp>=1.0.0
+Requires-Dist: openstudio>=3.10.0
+Requires-Dist: pydantic>=2.12.3
+Requires-Dist: python-dotenv>=1.0.0
+Requires-Dist: pyyaml>=6.0.2
+Provides-Extra: automa
+Requires-Dist: automa-ai>=0.7.3; extra == 'automa'
+Provides-Extra: dev
+Requires-Dist: black>=25.9.0; extra == 'dev'
+Requires-Dist: build>=1.2.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'
+Provides-Extra: ui
+Requires-Dist: streamlit>=1.54.0; extra == 'ui'
+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, and MCP-backed blackboard workflow state.
+- Claude Code plugin export.
+- Codex plugin export.
+- Runtime learning schemas and candidate folders.
+- 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
+
+From this repository root:
+
+```bash
+python -m pip install -e ".[dev]"
+```
+
+Install the runtime package after it is published:
+
+```bash
+python -m pip install openstudio-ai
+openstudio-ai doctor
+openstudio-ai-mcp --transport stdio
+```
+
+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
+```
+
+Export local development plugins:
+
+```bash
+python -m adapters.claude_code_adapter export-plugin \
+  --output-dir /tmp/openstudio-ai-claude-plugin
+
+python -m adapters.codex_adapter export-plugin \
+  --output-dir /tmp/openstudio-ai-codex-plugin
+```
+
+Export marketplace-oriented plugins that expect an installed runtime command:
+
+```bash
+python -m adapters.claude_code_adapter export-plugin \
+  --output-dir /tmp/openstudio-ai-claude-plugin \
+  --runtime-mode marketplace
+
+python -m adapters.codex_adapter export-plugin \
+  --output-dir /tmp/openstudio-ai-codex-plugin \
+  --runtime-mode marketplace
+```
+
+## Key Docs
+
+- [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)
+- [PyPI Release Guide](docs/RELEASE.md)
+- [Developer Guidance](docs/DEVELOPER_GUIDANCE.md)
+
+## Runtime State
+
+Local runtime state is intentionally ignored by Git:
+
+- `.openstudio_mcp_workspace/`
+- `.openstudio_ai_blackboards/`
+- `logs/`
+- `outputs/`
+
+The MCP runtime uses local SQLite metadata and filesystem workspaces for large
+OSM, SQL, and log artifacts.

openstudio_ai-0.1.0/README.md

@@ -0,0 +1,92 @@
+# 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, and MCP-backed blackboard workflow state.
+- Claude Code plugin export.
+- Codex plugin export.
+- Runtime learning schemas and candidate folders.
+- 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
+
+From this repository root:
+
+```bash
+python -m pip install -e ".[dev]"
+```
+
+Install the runtime package after it is published:
+
+```bash
+python -m pip install openstudio-ai
+openstudio-ai doctor
+openstudio-ai-mcp --transport stdio
+```
+
+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
+```
+
+Export local development plugins:
+
+```bash
+python -m adapters.claude_code_adapter export-plugin \
+  --output-dir /tmp/openstudio-ai-claude-plugin
+
+python -m adapters.codex_adapter export-plugin \
+  --output-dir /tmp/openstudio-ai-codex-plugin
+```
+
+Export marketplace-oriented plugins that expect an installed runtime command:
+
+```bash
+python -m adapters.claude_code_adapter export-plugin \
+  --output-dir /tmp/openstudio-ai-claude-plugin \
+  --runtime-mode marketplace
+
+python -m adapters.codex_adapter export-plugin \
+  --output-dir /tmp/openstudio-ai-codex-plugin \
+  --runtime-mode marketplace
+```
+
+## Key Docs
+
+- [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)
+- [PyPI Release Guide](docs/RELEASE.md)
+- [Developer Guidance](docs/DEVELOPER_GUIDANCE.md)
+
+## Runtime State
+
+Local runtime state is intentionally ignored by Git:
+
+- `.openstudio_mcp_workspace/`
+- `.openstudio_ai_blackboards/`
+- `logs/`
+- `outputs/`
+
+The MCP runtime uses local SQLite metadata and filesystem workspaces for large
+OSM, SQL, and log artifacts.

openstudio_ai-0.1.0/adapters/README.md

@@ -0,0 +1,183 @@
+# OpenStudio AI Agent Adapters
+
+This folder defines the host-specific adapter layer for packaging OpenStudio AI
+into agent shells such as Codex or Claude Code.
+
+Adapters are responsible for:
+
+- loading the harness system prompt and prompt contracts;
+- exposing the skill directory to the host agent;
+- connecting the OpenStudio MCP server;
+- wiring the blackboard state store;
+- recording learning events from host-agent activity.
+
+Adapters should stay thin. Product behavior belongs in `harness/`,
+`blackboard/`, `learning/`, `skills/`, and `openstudio_mcp/`.
+
+## Claude Code Plugin Export
+
+Export a Claude plugin-style package:
+
+```bash
+.venv/bin/python -m adapters.claude_code_adapter export-plugin \
+  --output-dir /tmp/openstudio-ai-plugin
+```
+
+Preview package files without writing:
+
+```bash
+.venv/bin/python -m adapters.claude_code_adapter export-plugin \
+  --output-dir /tmp/openstudio-ai-plugin \
+  --dry-run
+```
+
+Runtime modes:
+
+- `--runtime-mode local`: development mode; `.mcp.json` starts the MCP server
+  from this source checkout.
+- `--runtime-mode installed`: assumes `openstudio-ai-mcp` is already installed.
+- `--runtime-mode marketplace`: assumes `openstudio-ai-mcp` is the runtime
+  command and adds setup/doctor/repair commands plus installer helper scripts.
+
+Marketplace export:
+
+```bash
+.venv/bin/python -m adapters.claude_code_adapter export-plugin \
+  --output-dir /tmp/openstudio-ai-plugin \
+  --runtime-mode marketplace
+```
+
+The exported package has this shape:
+
+```text
+openstudio-ai-plugin/
+├── .claude-plugin/marketplace.json
+├── INSTALL.md
+└── openstudio-ai/
+    ├── .claude-plugin/plugin.json
+    ├── .mcp.json
+    ├── README.md
+    ├── CONNECTORS.md
+    ├── commands/
+    ├── installers/
+    ├── skills/
+    ├── knowledge/
+    ├── instructions/
+    ├── learning/
+    └── blackboard/schemas/
+```
+
+Skills and knowledge are exported as separate files and folders. They are not
+flattened into one large `CLAUDE.md`.
+
+Install the exported plugin from inside Claude Code:
+
+```text
+/plugin marketplace add /tmp/openstudio-ai-plugin
+/plugin install openstudio-ai@openstudio-ai-local
+/reload-plugins
+```
+
+Then use the namespaced commands:
+
+```text
+/openstudio-ai:add-vav-reheat
+/openstudio-ai:simulate
+/openstudio-ai:query-results
+/openstudio-ai:propose-measure
+/openstudio-ai:setup-openstudio-ai
+```
+
+## Claude Code Project Install
+
+Preview the files that would be installed into a Claude Code project:
+
+```bash
+.venv/bin/python -m adapters.claude_code_adapter install \
+  --target-dir /path/to/claude/project \
+  --dry-run
+```
+
+Install into a Claude Code project:
+
+```bash
+.venv/bin/python -m adapters.claude_code_adapter install \
+  --target-dir /path/to/claude/project
+```
+
+The installer writes:
+
+- `.mcp.json`
+  Project-scoped MCP server registration for `openstudio_ai`.
+- `.claude/CLAUDE.md`
+  Project instructions containing OpenStudio AI harness paths, prompt
+  contracts, and runtime skill references.
+
+If `.claude/CLAUDE.md` already exists and is not managed by OpenStudio AI, the
+installer stops unless `--force` is provided. With `--force`, it appends a
+generated OpenStudio AI block.
+
+Project install is mainly useful for local development and debugging. The
+plugin export command is the intended distributable path.
+
+## Codex Plugin Export
+
+Export a Codex plugin-style package and repo-local marketplace:
+
+```bash
+.venv/bin/python -m adapters.codex_adapter export-plugin \
+  --output-dir /tmp/openstudio-ai-codex-plugin
+```
+
+Preview package files without writing:
+
+```bash
+.venv/bin/python -m adapters.codex_adapter export-plugin \
+  --output-dir /tmp/openstudio-ai-codex-plugin \
+  --dry-run
+```
+
+Marketplace export:
+
+```bash
+.venv/bin/python -m adapters.codex_adapter export-plugin \
+  --output-dir /tmp/openstudio-ai-codex-plugin \
+  --runtime-mode marketplace
+```
+
+The exported package has this shape:
+
+```text
+openstudio-ai-codex-plugin/
+├── .agents/plugins/marketplace.json
+├── INSTALL.md
+└── plugins/
+    └── openstudio-ai/
+        ├── .codex-plugin/plugin.json
+        ├── .mcp.json
+        ├── README.md
+        ├── CONNECTORS.md
+        ├── commands/
+        ├── installers/
+        ├── skills/
+        ├── knowledge/
+        ├── instructions/
+        ├── learning/
+        └── blackboard/schemas/
+```
+
+Validate the plugin:
+
+```bash
+python -m json.tool \
+  /tmp/openstudio-ai-codex-plugin/plugins/openstudio-ai/.codex-plugin/plugin.json
+```
+
+Install the marketplace in Codex:
+
+```bash
+codex plugin marketplace add /tmp/openstudio-ai-codex-plugin
+```
+
+Then install or view `openstudio-ai` from the `openstudio-ai-local` marketplace
+in the Codex plugin UI.

openstudio_ai-0.1.0/adapters/__init__.py

@@ -0,0 +1,2 @@
+"""Host adapter contracts for the OpenStudio AI harness."""
+

openstudio_ai-0.1.0/adapters/base.py

@@ -0,0 +1,17 @@
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+
+from adapters.contracts import HostAdapterConfig, HostLaunchPlan
+
+
+class OpenStudioAiHostAdapter(ABC):
+    """Thin interface implemented by each supported agent host."""
+
+    def __init__(self, config: HostAdapterConfig):
+        self.config = config
+
+    @abstractmethod
+    def build_launch_plan(self) -> HostLaunchPlan:
+        """Return the files and entrypoints the host should load."""
+