comcheck-api 1.0.0__tar.gz

comcheck_api-1.0.0/.env.example

@@ -0,0 +1,4 @@
+# COMcheck API Configuration
+
+# Required: Your COMcheck API key
+COM_API_KEY=your-api-key-here

comcheck_api-1.0.0/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,46 @@
+---
+name: Bug Report
+about: Report a bug or issue with the library
+title: '[BUG] '
+labels: bug
+---
+
+## Description
+A clear and concise description of the bug.
+
+## Environment
+- Python version: [e.g., 3.12.1]
+- Library version: [e.g., 0.1.0]
+- Operating System: [e.g., macOS 14.0, Ubuntu 22.04]
+
+## Steps to Reproduce
+1. Step one
+2. Step two
+3. Step three
+
+## Expected Behavior
+What you expected to happen.
+
+## Actual Behavior
+What actually happened.
+
+## Code Example
+```python
+# Minimal code example that reproduces the issue
+from comcheck_api import COMcheckClient
+
+client = COMcheckClient(api_key="...")
+# Your code here
+```
+
+## Error Message
+```
+Paste the full error message and stack trace here
+```
+
+## Additional Context
+Any other information that might be helpful.
+
+---
+
+**Note:** This project does not accept external contributions. Issues are welcome for bug reports and feedback only.

comcheck_api-1.0.0/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,25 @@
+---
+name: Feature Request
+about: Suggest a feature or enhancement
+title: '[FEATURE] '
+labels: enhancement
+---
+
+## Feature Description
+A clear description of the feature you'd like to see.
+
+## Use Case
+Describe the problem this feature would solve or the use case it would enable.
+
+## Proposed Solution
+If you have ideas on how this could be implemented, share them here.
+
+## Alternatives Considered
+Are there alternative solutions or workarounds you've considered?
+
+## Additional Context
+Any other information, examples, or references that might be helpful.
+
+---
+
+**Note:** This project does not accept external contributions. Feature requests are noted for consideration by the internal development team.

comcheck_api-1.0.0/.github/ISSUE_TEMPLATE/question.md

@@ -0,0 +1,27 @@
+---
+name: Question
+about: Ask a question about using the library
+title: '[QUESTION] '
+labels: question
+---
+
+## Question
+Your question here.
+
+## What I've Tried
+Describe what you've already tried or where you've looked for answers:
+- [ ] Checked the README
+- [ ] Reviewed the examples/ directory
+- [ ] Searched existing issues
+
+## Context
+Provide any relevant context about what you're trying to accomplish.
+
+## Code Example (if applicable)
+```python
+# Your code here
+```
+
+---
+
+**Note:** Please check the [examples/](../../examples/) directory. For usage questions, these are often the best resources.

comcheck_api-1.0.0/.github/pull_request_template.md

@@ -0,0 +1,17 @@
+# ⚠️ External Pull Requests Not Accepted
+
+Thank you for your interest in this project!
+
+However, **this project does not accept external contributions or pull requests** at this time. Development is managed internally by the PNNL team.
+
+## Alternative Ways to Help
+
+If you've found a bug or have a suggestion:
+
+1. **Report an Issue**: Open a bug report or feature request instead
+2. **Share Feedback**: Your feedback helps us improve the library
+3. **Use and Share**: Use the library and share your experiences
+
+---
+
+We appreciate your understanding and interest in the COMcheck API Python client!

comcheck_api-1.0.0/.github/workflows/docs.yml

@@ -0,0 +1,49 @@
+name: Deploy Documentation
+
+on:
+  push:
+    branches:
+      - main
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+
+      - name: Set up Python
+        run: uv python install 3.12
+
+      - name: Install dependencies
+        run: uv sync --group docs
+
+      - name: Build documentation
+        run: uv run mkdocs build
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: site
+
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

comcheck_api-1.0.0/.github/workflows/publish.yml

@@ -0,0 +1,34 @@
+name: Publish to PyPI
+
+on:
+  workflow_dispatch:
+    inputs:
+      version:
+        description: "Version to publish (e.g. 1.0.0). Leave empty to use the version in pyproject.toml."
+        required: false
+
+permissions:
+  id-token: write
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+
+      - name: Set version (if provided)
+        if: ${{ inputs.version != '' }}
+        run: sed -i "s/^version = .*/version = \"${{ inputs.version }}\"/" pyproject.toml
+
+      - name: Show version
+        run: grep '^version' pyproject.toml
+
+      - name: Build package
+        run: uv build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

comcheck_api-1.0.0/.gitignore

@@ -0,0 +1,60 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+build/
+*.egg-info/
+.eggs/
+
+# Virtual environments
+venv/
+.env/
+.envrc
+.venv/
+
+# Python tool caches
+pip-log.txt
+pip-delete-this-directory.txt
+__pypackages__/
+
+# uv / hatch virtual environment (if any)
+.uv_env/
+.uv_cache/
+
+# Testing / coverage
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+pytest_cache/
+.pytest_cache/
+htmlcov/
+
+# IDE / editor configs
+.vscode/
+.idea/
+*.sublime-project
+*.sublime-workspace
+
+# MacOS
+.DS_Store
+
+# Logs
+*.log
+
+# Temporary files
+*.tmp
+*.swp
+
+.env
+testprojectJson/
+
+# MkDocs build output
+site/
+
+.claude

comcheck_api-1.0.0/.pre-commit-config.yaml

@@ -0,0 +1,8 @@
+repos:
+  - repo: https://github.com/psf/black
+    rev: 26.1.0  # latest Black release
+    hooks:
+      - id: black
+        language_version: python3
+        exclude: ^comcheck_api/types/core_types\.py$
+

comcheck_api-1.0.0/.python-version

@@ -0,0 +1 @@
+3.13

comcheck_api-1.0.0/CHANGELOG.md

@@ -0,0 +1,123 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Fixed
+- Made BASE_URL configurable via COMCHECK_API_URL environment variable
+
+### To Be Added
+- Logging implementation to replace print statements
+- Custom exception classes for better error handling
+- Comprehensive API documentation
+- Additional examples and tutorials
+
+### To Be Fixed
+- Fix import path documentation in __init__.py
+- Security: Remove .env from version control
+
+## [0.1.0] - 2025-03-XX
+
+### Added
+- Initial release of COMcheck Web API Python client
+- Core API service layer with httpx HTTP client
+- High-level client interface (COMcheckClient)
+- Project CRUD operations (get, list, update)
+- Building component management:
+  - Envelope operations (walls, roofs, windows, doors, skylights)
+  - Building area operations
+  - Lighting, HVAC, and control systems
+- Energy simulation support:
+  - Start simulation
+  - Check simulation status
+  - Retrieve simulation results
+- Compliance checking before simulation
+- Type-safe Pydantic models for all data structures
+- Context manager support for automatic resource cleanup
+- Project template and default constants
+- Data managers for building areas and envelope components
+- Utility functions for project operations
+- Comprehensive examples:
+  - Client operations (simulation, user functions)
+  - Data manager usage
+  - Project operations
+- Development tooling:
+  - Black code formatter
+  - MyPy type checking
+  - Pre-commit hooks
+  - pytest test framework
+- Schema generation from COMcheck API
+- Package management with uv
+
+### Dependencies
+- httpx >= 0.27.0 (HTTP client)
+- pydantic >= 2.12.5 (data validation)
+- jsonschema >= 4.23.0 (schema validation)
+- python-dotenv >= 1.0.0 (environment configuration)
+- types-jsonschema >= 4.23.0 (type stubs)
+
+### Development Dependencies
+- black >= 26.1.0 (code formatting)
+- datamodel-code-generator >= 0.54.1 (type generation)
+- mypy >= 1.19.1 (type checking)
+- pre-commit >= 4.5.1 (git hooks)
+- pytest >= 9.0.2 (testing)
+
+### Requirements
+- Python >= 3.12
+
+### Known Issues
+- API key must be provided manually (no OAuth flow yet)
+- Some print() statements used instead of proper logging
+- Limited error handling with custom exceptions
+
+### Breaking Changes
+None (initial release)
+
+---
+
+## Release Notes
+
+### Version 0.1.0 - Initial Alpha Release
+
+This is the first alpha release of the COMcheck Web API Python client. The library provides a clean, type-safe interface for interacting with the COMcheck Web API to perform building energy code compliance checks.
+
+**Key Features:**
+- Easy-to-use client interface
+- Full project lifecycle management
+- Building component operations
+- Energy simulation and compliance checking
+- Type-safe with Pydantic models
+- Well-documented with examples
+
+**Not Yet Stable:**
+This is an alpha release. The API may change in future versions. Not recommended for production use without thorough testing.
+
+**What's Next:**
+- API stabilization for v1.0.0
+- Enhanced documentation
+- More examples and tutorials
+- Performance optimizations
+- Better error handling
+
+---
+
+## Migration Guides
+
+### Upgrading to 0.1.0
+Initial release - no migration needed.
+
+---
+
+## Deprecation Notices
+
+None yet.
+
+---
+
+*For detailed technical improvements and roadmap, see [docs/IMPROVEMENTS.md](docs/IMPROVEMENTS.md)*
+*For version control strategy, see [docs/VERSION_CONTROL.md](docs/VERSION_CONTROL.md)*

comcheck_api-1.0.0/DISCLAIMER.md

@@ -0,0 +1,24 @@
+DISCLAIMER
+
+This material was prepared as an account of work sponsored by an agency of the
+United States Government.  Neither the United States Government nor the United
+States Department of Energy, nor Battelle, nor any of their employees, nor any
+jurisdiction or organization that has cooperated in the development of these
+materials, makes any warranty, express or implied, or assumes any legal
+liability or responsibility for the accuracy, completeness, or usefulness or
+any information, apparatus, product, software, or process disclosed, or
+represents that its use would not infringe privately owned rights.
+
+Reference herein to any specific commercial product, process, or service by
+trade name, trademark, manufacturer, or otherwise does not necessarily
+constitute or imply its endorsement, recommendation, or favoring by the United
+States Government or any agency thereof, or Battelle Memorial Institute. The
+views and opinions of authors expressed herein do not necessarily state or
+reflect those of the United States Government or any agency thereof.
+
+                 PACIFIC NORTHWEST NATIONAL LABORATORY
+                              operated by
+                                BATTELLE
+                                for the
+                   UNITED STATES DEPARTMENT OF ENERGY
+                    under Contract DE-AC05-76RL01830

comcheck_api-1.0.0/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.

comcheck_api-1.0.0/PKG-INFO

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