comcheck-api 1.0.0__py3-none-any.whl

comcheck_api-1.0.0.dist-info/METADATA

@@ -0,0 +1,244 @@
+Metadata-Version: 2.4
+Name: comcheck_api
+Version: 1.0.0
+Summary: COMcheck Web API Python Client
+Project-URL: Homepage, https://pnnl.github.io/comcheckweb-api-python/
+Project-URL: Documentation, https://pnnl.github.io/comcheckweb-api-python/
+Project-URL: Repository, https://github.com/pnnl/comcheckweb-api-python
+Author-email: Yanyan Zhu <yanyan.zhu@pnnl.gov>
+Maintainer-email: Yanyan Zhu <yanyan.zhu@pnnl.gov>, Weili Xu <weili.xu@pnnl.gov>
+License-Expression: BSD-3-Clause
+License-File: LICENSE
+Keywords: IECC,ashrae 90.1,building,comcheck,compliance,simulation
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: jsonschema>=4.23.0
+Requires-Dist: pydantic>=2.12.5
+Requires-Dist: python-dotenv>=1.0.0
+Requires-Dist: types-jsonschema>=4.23.0
+Description-Content-Type: text/markdown
+
+# COMcheckWeb API — Python Package
+
+This repository contains the COMcheckWeb API Python package. It provides tools and scripts for working with the COMcheckWeb API and is intended to be used as a Python package maintained with `uv` for package management.
+
+**Requirements:**
+- Python: `>=3.12`
+
+**Package management:**
+- This project uses `uv` (configured in `pyproject.toml`) for dependency and workspace management. The `tool.uv` settings in `pyproject.toml` control workspace members and local sources.
+
+Quickly useful notes:
+- If you reference this package from other workspace packages, keep the `tool.uv.sources` entry that maps `comcheck_api = { workspace = true }` so `uv` resolves it to the local workspace copy.
+- For a single-package repo you can also rely on `members = ["."]` and omit additional sources, but leaving the explicit source entry is harmless and makes intent clear.
+
+## Usage
+
+### 1. Obtain an API Key
+
+Get a Personal Access Token from the new
+[COMcheck Web site](https://comcheck.energycode.pnl.gov):
+
+1. Log in (or register a new account if you don't have one).
+2. Click your **username** in the left-side navigation.
+3. From the menu that appears, choose **Settings**.
+4. Click **Developer Setting** to open the Personal Access Token
+   page.
+5. Click **Generate**, then immediately copy the token.
+
+> **Important:** the token is shown **only once**. Save it somewhere
+> safe (a password manager, your `.env`, etc.) before leaving the
+> page. If you lose it, generate a new one — the old one will stop
+> working.
+
+### 2. Configure the API Key
+
+Create a `.env` file at the root of your project and add:
+
+```
+COM_API_KEY=<your-api-key-here>
+```
+
+The SDK does **not** auto-load this — you read it yourself and pass
+it to the client. With `python-dotenv` this is two lines:
+
+```python
+import os
+from dotenv import load_dotenv
+from comcheck_api import COMcheckClient
+
+load_dotenv()
+client = COMcheckClient(api_key=os.environ["COM_API_KEY"])
+```
+
+(`client.set_api_key(api_key)` is the equivalent post-construction
+setter if you'd rather defer.)
+
+For more detail, see the
+[Getting Started](https://pnnl.github.io/comcheckweb-api-python/getting-started/)
+guide.
+
+### 3. Install the Package
+
+```bash
+pip install comcheck-api
+```
+
+### 4. Start Using the Package
+
+- **Simulation only:** You can use the simulation features directly without creating a project on COMcheck Web.
+- **Updating a project:** You must first create the project under your account on [COMcheck Web](https://comcheck.energycode.pnl.gov) before using this package to update it. Project creation is not yet supported through this package.
+
+For detailed usage examples and API reference, see the [documentation](https://pnnl.github.io/comcheckweb-api-python/).
+
+## Introspection helpers
+
+The package ships typed helpers for discovering what the SDK exposes
+and for validating project data — useful from notebooks, IDE plugins,
+and AI agents alike. All return Pydantic models; call `.model_dump()`
+when you need JSON.
+
+```python
+import comcheck_api as cc
+
+# What operation functions does the SDK ship?
+for op in cc.list_operations():
+    print(op.group, op.signature)
+
+# What does the ComBuilding model look like?
+schema = cc.lookup_type("ComBuilding")
+for field in schema.fields:
+    print(field.name, field.type, field.required)
+
+# Does this dict satisfy the SDK schema?
+result = cc.validate_project(project_dict)
+if not result.ok:
+    for err in result.errors:
+        print(err.loc, err.msg)
+```
+
+See [`api/introspection`](https://pnnl.github.io/comcheckweb-api-python/api/introspection/)
+in the docs for the full reference.
+
+## AI integration: the bundled Skill
+
+A bundled Skill teaches AI coding agents how to use this SDK correctly —
+operation modules, default templates, the simulation polling loop,
+common pitfalls. The Skill folder lives at
+[`comcheck_api/ai/skill/`](comcheck_api/ai/skill/) and ships in the
+wheel. It follows the open agent-skills standard (`SKILL.md` plus
+`reference/` and `scripts/`), so the same folder works for both
+**Claude Code** and **OpenAI Codex** — only the install location
+differs.
+
+### Setup in your own repo
+
+Run the installer once in the root of the project that consumes
+`comcheck_api`. By default it installs the Skill for **both** agents:
+
+```bash
+comcheck-api install-skill
+```
+
+This writes:
+
+- `.claude/skills/comcheck-api/` — Claude Code scans
+  `<project>/.claude/skills/` when a session opens against the repo.
+- `.agents/skills/comcheck-api/` — Codex scans `.agents/skills` from
+  the working directory up to the repository root.
+
+So the guidance kicks in only for projects that actually use this SDK,
+not on every session everywhere. Commit both folders; teammates get the
+same guidance the moment they open the repo, and the agent can pull in
+the reference docs and `validate_code.py` script on demand — not just
+the `SKILL.md` body.
+
+To install for only one agent, pass `--claude` or `--codex`:
+
+```bash
+comcheck-api install-skill --claude   # Claude Code only
+comcheck-api install-skill --codex    # Codex only
+```
+
+Re-run with `--force` after upgrading the package to refresh the Skill.
+Pass `--global` to install into the user-global skills dirs
+(`~/.claude/skills/` and/or `~/.agents/skills/`) for every session
+instead of per-project.
+
+## Development
+
+Clone the repository and follow the commands below to set up developer tooling.
+
+```bash
+git clone https://github.com/pnnl/comcheckweb-api-python.git
+cd comcheckweb-api-python
+uv sync
+```
+
+## Common commands
+
+- Setup pre-commit (run once after cloning):
+	`uv run pre-commit install`
+
+- Fetch the latest COMcheck schema and regenerate types:
+	`./tools/fetch_comcheck_schema.sh`
+
+- Regenerate types from existing schema (without fetching):
+	`uv run tools/generate_core_types.py`
+
+- Run a file from `examples/`:
+	`uv run examples/<script>`
+
+- Run tests:
+	`uv run pytest`
+
+- Format the repository with Black:
+	`uv run black comcheck_api tests examples`
+
+- Run type checking:
+	`uv run mypy comcheck_api`
+
+## Running the docs locally
+
+The documentation site is built with MkDocs (Material theme +
+mkdocstrings). The dependencies live in the optional `docs` group
+defined in `pyproject.toml`.
+
+```bash
+# Install the docs group (mkdocs, mkdocs-material, mkdocstrings).
+uv sync --group docs
+
+# Serve with live reload at http://127.0.0.1:8000
+uv run mkdocs serve
+
+# One-shot build into ./site/
+uv run mkdocs build
+
+# Fail on warnings (good before committing)
+uv run mkdocs build --strict
+```
+
+## Support
+
+This is a publicly available library maintained by PNNL. While the code is open source and free to use, **external contributions are not accepted** at this time.
+
+### Reporting Issues
+
+If you encounter bugs or have questions:
+- Open an issue on GitHub for bug reports
+- Check the [examples/](examples/) directory for usage guidance
+- Review the [documentation](docs/) for detailed information
+
+**Note:** Issues are welcome, but pull requests from external contributors will not be accepted.
+
+## License
+
+See the `LICENSE` file at the repository root for license details.

comcheck_api-1.0.0.dist-info/RECORD

@@ -0,0 +1,54 @@
+comcheck_api/__init__.py,sha256=rvfYAeE1eScktBFFSM_4JTd3fy4HAa-XJWoCDMlJ1YI,2369
+comcheck_api/cli.py,sha256=YBXrXE1_y2x_EOJappWJWObxDXCswXMYlCZqZYXqTUc,4288
+comcheck_api/defaults.py,sha256=VSVTokh_-VR5sQiZDktETlOskVyviKIcY5TCpEmh9v4,4550
+comcheck_api/exceptions.py,sha256=-vd-_bdknvj0xSOpMF6p3EqQaaadMWnc0l-ZPX2eZJA,1577
+comcheck_api/introspection.py,sha256=7gFuZ5_-BZCJ8GlFkUanr9avnLhFa3fOeEdWIBvI2bg,5064
+comcheck_api/validation.py,sha256=42cuY1z8r5K52q5oRTsW0xDR_FCE4qybihIffF9hzR4,1739
+comcheck_api/ai/__init__.py,sha256=_M_b7zKKUNIUlyQ7z-O3zMAtKAzmqfPfMr52eH89TJY,931
+comcheck_api/ai/skill/SKILL.md,sha256=W_q8nYuzeVezBLeA2XPw5ZYYtb5dC3BJc8cQyvfwV10,12612
+comcheck_api/ai/skill/__init__.py,sha256=sJyMmuuCEy01zKAomzupTnrIFeM6dGu6zrtQsacjJmo,146
+comcheck_api/ai/skill/reference/operations.md,sha256=ktTM02dDuBEVVGzmm3EcZ5iNq7ZKzFkg15F3SWDcpv8,4033
+comcheck_api/ai/skill/reference/simulation.md,sha256=enSLcNY6BauIQOUjnqHIX6F0dkTDyn566FTqzznJrp8,4196
+comcheck_api/ai/skill/reference/types.md,sha256=Issvt-Lcrg2NJEtX0S8Qo18qiz4NPrcG1bggJwbZmmw,4155
+comcheck_api/ai/skill/scripts/__init__.py,sha256=feMXCGSxtzsfkcpIxkUGQDL59auJK7ICdVch3-9WLjY,77
+comcheck_api/ai/skill/scripts/validate_code.py,sha256=E4nq_k0VVVS-r8YVjFvUm9tlZ_86NDcHv0e9FhUZGf0,7054
+comcheck_api/api/__init__.py,sha256=08pWupzr9ROTFTnQc1ur3ijbEPMU3VHyTVz9sTp9h0E,60
+comcheck_api/api/api_services.py,sha256=hrLBuQ5FSpeHvFKAuqgV9YD4nDIwpaZgrPr9RZ9jOWw,8860
+comcheck_api/client/__init__.py,sha256=-YeuOolE8awh4e5iRMyocNEbmvryN25fyuKcs-mRqek,62
+comcheck_api/client/comcheck_client.py,sha256=0FyFehYA-CgyK6uL8wNdMNtY45u674q16SO0bZNaMQI,12480
+comcheck_api/constants/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+comcheck_api/constants/building_area_constants.py,sha256=xzS3biZALxXbVB3Ebzb1VGfNrrbolhurfDcBmDIgSbM,1409
+comcheck_api/constants/common_constants.py,sha256=WTNr936sCeFK_9hWeuDEfbPUySLbqoTQ9hp0gevbgQM,4101
+comcheck_api/constants/envelope_constants.py,sha256=5aY55tZRzp9TmR0T4uq2yaC8bJxUMl96H88Om5Jjfhk,7498
+comcheck_api/managers/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+comcheck_api/managers/data_manager.py,sha256=n2Q2C3HgwVImnWs1cr6YQfvryfjpgOiedqUQTFgCNo4,12079
+comcheck_api/managers/components/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+comcheck_api/managers/components/building_area.py,sha256=5wR3LUba37UDdXjPAW6aSmHzCQpXw31VhSdOQdVFDwY,343
+comcheck_api/managers/components/envelope/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+comcheck_api/managers/components/envelope/ag_wall.py,sha256=ubqYStMhmY-75DSVfPsjNjX3LHFNWzgkJgjNI7o0WkE,3301
+comcheck_api/managers/components/envelope/bg_wall.py,sha256=ezNUds12BbSf3svoibay2GtLii4ThpjCo_NZDfmqWSQ,1153
+comcheck_api/managers/components/envelope/door.py,sha256=-J4ffHjuLtqf_Ml5qh0YpajK3IHkSbpwyuHghQbJXLM,282
+comcheck_api/managers/components/envelope/floor.py,sha256=oEwOtL4PsCdx8wiO9iJaTcFssWoVD3v3ptEtbw1E9Ys,288
+comcheck_api/managers/components/envelope/roof.py,sha256=PpQgxkEpXh51sOPx5BRo-74W0ugkUxvglBZsBUcpyCU,913
+comcheck_api/managers/components/envelope/skylight.py,sha256=ukJNqPgaKo-8fQ7vd9DsKcEn1elkoC7vJzx2TEGjT1s,307
+comcheck_api/managers/components/envelope/window.py,sha256=kIc3J9BKlyaj-uADIr3wUK1IaHRx1phajjKO6ZCWXQY,294
+comcheck_api/project_operations/__init__.py,sha256=4JST01vNBx9gILUk1LSTnFIXqTfrxZulAzxum8XvSuY,200
+comcheck_api/project_operations/project_building_area_operations.py,sha256=4WLtOGpqT_rWq_tZwWE-eeIqNXASZjqb9OgcIFU9dZc,3491
+comcheck_api/project_operations/project_envelope_operations.py,sha256=0fjnjDxg0xIf-yCxOwKR2pbLQ-TI9HtKwSP4do6oYOQ,30025
+comcheck_api/schemas/comCheck.schema.json,sha256=e3XLXznluuDB4unBNDJHP3REi43uvrCkk4LyHt8N6rM,292455
+comcheck_api/types/__init__.py,sha256=FgsNKPFFGAGxTNXe-GqDASO5kfs30lbuIFJ6DGqfNj8,1379
+comcheck_api/types/api_types.py,sha256=591y39iokXn6_My3IvYC20abzjx3qVbDI3hO33NBHRk,4054
+comcheck_api/types/common_types.py,sha256=-CNWKzJ5a0kDcKnICC9SDQRFwhFfqoU7lBGj_5V07CU,780
+comcheck_api/types/core_types.py,sha256=8Myca-KkUlLfqRmCc3nfBTdAQfpGHREtV2aXmLe0mic,167389
+comcheck_api/types/custom_base_model.py,sha256=i0IozkQCCqzITzFcrzbRuyNUf4NzcHuOfnEExCvGrqs,11208
+comcheck_api/utilities/__init__.py,sha256=dR0r3GORwgYDzSSmZZhtzBc-ip_56plGkjqnO3po1YQ,98
+comcheck_api/utilities/common.py,sha256=fIa1-RZc-2-5qYlUN67xMem-H-Om-EKwVNNzwtSZN44,1412
+comcheck_api/utilities/envelope_utilities.py,sha256=BYOutg4zKFYVf-Cr0MBH-95pI7R1QSfmiFNet0m3WqM,1338
+comcheck_api/utilities/id_registry.py,sha256=gGKc2k90726AxafUTtUICeasu2Wf7mvpWkElCbyF1Ic,2244
+comcheck_api/utilities/project_utilities.py,sha256=SpXsMeDMhNkNNPi2DjeP15Wd7Wc4EWOee1bYLiJKMN8,1957
+comcheck_api/DISCLAIMER.md,sha256=0eBTxQiTBPWvv3AbKOcm13O-LNdXdHW9-ygqDR0GlBw,1348
+comcheck_api-1.0.0.dist-info/METADATA,sha256=-T5wGcmsSVfbdrIcvdSt6aCL7e--JRzCL2LJgknntoI,8252
+comcheck_api-1.0.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+comcheck_api-1.0.0.dist-info/entry_points.txt,sha256=ddgK3Qw_NvaitnyavNa4L9YQTZMHmndpOuH1BcuIejk,55
+comcheck_api-1.0.0.dist-info/licenses/LICENSE,sha256=C6PeRixx39RBUkf6qLRWptgzH3IyWzvpzOrXadXsCeA,1302
+comcheck_api-1.0.0.dist-info/RECORD,,

comcheck_api-1.0.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

comcheck_api-1.0.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+comcheck-api = comcheck_api.cli:main

comcheck_api-1.0.0.dist-info/licenses/LICENSE

@@ -0,0 +1,24 @@
+BSD 3-Clause License
+
+Copyright Battelle Memorial Institute 2026
+
+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.
+
+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.