Metadata-Version: 2.5
Name: openstudio-ai
Version: 0.1.8
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<2,>=1.28
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
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: standalone
Requires-Dist: automa-ai>=0.7.3; extra == 'standalone'
Requires-Dist: streamlit>=1.54.0; extra == 'standalone'
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.
- Learning contracts for candidate drafting; host plugins do not persist
  candidate records yet.
- 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,standalone]"
```

Use `.[dev,standalone]` for full local harness development. The `standalone`
extra installs the optional AUTOMA-AI and Streamlit dependencies used by
`agent.py`, `ui.py`, and tests that exercise the local A2A agent path.

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.

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. To run the standalone local AI app, install:

```bash
python -m pip install "openstudio-ai[standalone]"
python agent.py
streamlit run ui.py
```

Standalone mode requires user-provided LLM configuration, such as API keys or
model endpoint settings, in the local environment.

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

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

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