Merge pull request #8 from pnnl/ai-approaches

Ai approaches

Author: yanyanzhu-pnnl

README.md

@@ -41,6 +41,65 @@ pip install comcheckweb-api-python
 
 For detailed usage examples and API reference, see the [documentation](https://pnnl-int.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-int.github.io/comcheckweb-api-python/api/introspection/)
+in the docs for the full reference.
+
+## AI integration: the Claude Skill
+
+A bundled Claude Skill teaches Claude 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.
+
+### Setup in your own repo
+
+Install the bundled Skill into a project-level
+`.claude/skills/comcheck-api/`. Claude Code scans
+`<project>/.claude/skills/` when a session opens against the repo,
+so the guidance kicks in only for projects that actually use this
+SDK — not on every Claude session everywhere.
+
+```bash
+# Run this once in the root of the project that consumes comcheck_api:
+comcheck-api install-skill
+```
+
+Commit `.claude/skills/comcheck-api/`. Teammates get the same
+guidance the moment they open the repo in Claude Code, and Claude
+can pull in the reference docs, examples, and `validate_code.py`
+script on demand — not just the SKILL.md body. Re-run the command
+with `--force` after upgrading the package to refresh the skill.
+
+To install globally for every Claude session instead of per-project,
+pass `--global` (writes to `~/.claude/skills/comcheck-api/`).
+
 ## Development
 
 Clone the repository and follow the commands below to set up developer tooling.
@@ -74,6 +133,26 @@ uv sync
 - 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.

comcheck_api/__init__.py

@@ -60,6 +60,12 @@
     project_envelope_operations,
 )
 
+# Introspection helpers
+from .introspection import list_operations, lookup_type
+
+# Validation helpers
+from .validation import validate_project
+
 # Utilities
 from . import utilities
 
@@ -81,6 +87,11 @@
     # Project Operations
     "project_building_area_operations",
     "project_envelope_operations",
+    # Introspection
+    "list_operations",
+    "lookup_type",
+    # Validation
+    "validate_project",
     # Utilities
     "utilities",
     # Types

comcheck_api/ai/__init__.py

@@ -0,0 +1,30 @@
+"""AI-facing surface for the comcheck_api package.
+
+Ships the canonical Skill folder under ``comcheck_api/ai/skill/``
+(SKILL.md + reference docs + examples + scripts). Use
+:func:`skill_root` to get the on-disk path to the bundled folder —
+useful for installing it into ``<project>/.claude/skills/`` or
+``~/.claude/skills/``.
+
+Introspection and validation helpers live on the SDK itself
+(``comcheck_api.list_operations``, ``comcheck_api.lookup_type``,
+``comcheck_api.validate_project``).
+"""
+
+from __future__ import annotations
+
+from importlib.resources import as_file, files
+from pathlib import Path
+
+
+def skill_root() -> Path:
+    """Return the on-disk path to the bundled Skill folder.
+
+    Uses ``importlib.resources`` so the path resolves correctly
+    whether the package is installed normally or zip-imported.
+    """
+    with as_file(files("comcheck_api.ai.skill")) as p:
+        return Path(p)
+
+
+__all__ = ["skill_root"]

comcheck_api/ai/skill/SKILL.md

@@ -0,0 +1,143 @@
+---
+name: comcheck-api
+description: Use this skill when the user is writing Python code that uses
+  the comcheck_api package to build COMcheck project JSON, run compliance
+  simulations against the PNNL COMcheck Web API, or work with envelope,
+  lighting, mechanical, or building-area operations. Triggers on imports
+  of `comcheck_api`, mentions of COMcheck/ASHRAE 90.1/IECC compliance,
+  or requests to validate building energy code compliance.
+---
+
+# COMcheck API Python Client Skill
+
+## When to use this skill
+
+Triggers:
+- The user imports `comcheck_api` or asks for help with it.
+- The user mentions COMcheck, ASHRAE 90.1, IECC, or commercial building
+  energy code compliance.
+- The user wants to build, update, or run a simulation on a COMcheck
+  project from Python.
+
+## Core concepts
+
+- **Single entry point**: `COMcheckClient` is the only client class
+  users instantiate. Construct with `api_key=...` or rely on the
+  `COM_API_KEY` env var.
+- **Project shape**: a project is a `ComBuilding` Pydantic model. It
+  contains: `Project` (metadata), `Location`, `Envelope`, `WholeBldgUse[]`
+  (building areas), `HVAC`, `Lighting`, `Renewable`, and `Control`.
+- **Operation classes (functional)**: building areas and envelope
+  components are added/updated/removed via free functions in
+  `project_building_area_operations` and `project_envelope_operations`.
+  Each function takes a `ComBuilding` and returns a new `ComBuilding`.
+- **Defaults**: `comcheck_api.defaults` has `get_default_*_template()`
+  functions that return Pydantic models filled with sensible defaults.
+  Always start from these.
+- **Simulation flow is async**: `start_run_simulation` returns a
+  session ID. Poll `get_simulation_status` until status is `complete`,
+  then call `get_simulation_result`.
+
+## Quick start
+
+```python
+from comcheck_api import COMcheckClient
+from comcheck_api.defaults import get_default_project_template
+
+client = COMcheckClient(api_key="your-key")
+
+# Build a project from a default template
+project = get_default_project_template()
+project.Project.title = "5,000 sqft office in Seattle"
+
+# Save it (creates server-side project, returns ID via list)
+# Update if you have an existing ID:
+# updated = client.update_project(project_id="123", project_data=project)
+
+# Run a simulation
+session_id = client.start_run_simulation(project)
+
+# Poll until complete
+import time
+while True:
+    status = client.get_simulation_status(session_id)
+    if status["status"] == "complete":
+        break
+    time.sleep(5)
+
+result = client.get_simulation_result(session_id)
+print(result["performanceRating"])
+```
+
+## Conventions (do)
+
+- Use `get_default_*_template()` to start any new component, then
+  customize. Don't construct `ComBuilding` from scratch.
+- Use the operation classes (e.g.,
+  `project_envelope_operations.add_ag_wall_to_project(project, wall)`)
+  to mutate project structure. Don't manipulate nested dicts directly.
+- Read the API key from `COM_API_KEY` env var by default; let users
+  pass `api_key=...` to override.
+- Wrap network calls in try/except and catch `COMCheckHTTPError`,
+  `COMCheckConnectionError`, `COMCheckValidationError`,
+  `COMCheckSimulationError`, `COMCheckProjectNotFoundError`.
+- The package uses `httpx`, not `requests`.
+
+## Conventions (don't)
+
+- Don't construct project JSON by hand — use templates + operation
+  functions.
+- Don't suggest `requests` — the SDK is `httpx`-based.
+- Don't import private modules (anything starting with `_`).
+- Don't poll `get_simulation_status` faster than every 5 seconds.
+- Don't put the API key in source code; use env var or argument.
+
+## Common patterns
+
+### Adding an above-grade wall
+
+```python
+from comcheck_api import project_envelope_operations as envelope_ops
+from comcheck_api.defaults import get_default_ag_wall_template
+
+wall = get_default_ag_wall_template()
+wall.name = "South wall"
+wall.area = 4800.0
+project = envelope_ops.add_ag_wall_to_project(project, wall)
+```
+
+### Listing the user's projects and updating one
+
+```python
+projects = client.list_projects()
+target = next(p for p in projects if p["title"] == "My office")
+project_obj = client.get_project(target["id"])
+project_obj.Project.title = "My office (revised)"
+client.update_project(project_id=target["id"], project_data=project_obj)
+```
+
+### Polling a simulation with a timeout
+
+```python
+import time
+session_id = client.start_run_simulation(project)
+deadline = time.time() + 300  # 5 min
+while time.time() < deadline:
+    status = client.get_simulation_status(session_id)
+    if status["status"] == "complete":
+        result = client.get_simulation_result(session_id)
+        break
+    time.sleep(5)
+else:
+    raise TimeoutError(f"Simulation {session_id} did not complete in 5 min")
+```
+
+## When you need more detail
+
+- For envelope assemblies (roof, walls, floor, windows, doors,
+  skylights, thermal bridges) → read `reference/operations.md`.
+- For Pydantic model field-level details → read `reference/types.md`.
+- For the simulation start/poll/fetch flow → read
+  `reference/simulation.md`.
+- To validate generated code against a mocked client → run
+  `scripts/validate_code.py`.

comcheck_api/ai/skill/__init__.py

@@ -0,0 +1,5 @@
+"""Canonical Skill folder for the comcheck_api package.
+
+Hand-authored content. Use ``comcheck_api.ai.skill_root()`` to get
+the on-disk path.
+"""

comcheck_api/ai/skill/reference/operations.md

@@ -0,0 +1,86 @@
+# Project Operations Reference
+
+Operation functions are free functions in two modules:
+
+- `comcheck_api.project_operations.project_building_area_operations`
+- `comcheck_api.project_operations.project_envelope_operations`
+
+Each function takes a `ComBuilding` and a payload, and returns a new
+`ComBuilding`. Treat them as immutable transformations.
+
+## Building area operations
+
+```python
+from comcheck_api import project_building_area_operations as ba_ops
+```
+
+| Function | Purpose |
+|---|---|
+| `add_building_area_to_project(project, new_building_area)` | Add a `WholeBldgUse` building area to the project. |
+| `update_building_area_in_project(project, building_area_key, updates)` | Update fields of an existing building area by key. |
+| `remove_building_area_from_project(project, building_area_key)` | Remove a building area by key. |
+| `get_building_area_keys_from_project(project)` | List `[{key, areaDescription}, …]` for the project. |
+
+## Envelope operations
+
+```python
+from comcheck_api import project_envelope_operations as env_ops
+```
+
+Each envelope component has a consistent triplet:
+`add_*_to_project`, `update_*_in_project`, `remove_*_from_project`.
+Plus the special `add_thermal_bridge_to_project` (no
+update/remove yet).
+
+| Component | Add | Update | Remove |
+|---|---|---|---|
+| Roof | `add_roof_to_project` | `update_roof_in_project` | `remove_roof_from_project` |
+| Above-grade wall | `add_ag_wall_to_project` | `update_ag_wall_in_project` | `remove_ag_wall_from_project` |
+| Below-grade wall | `add_bg_wall_to_project` | `update_bg_wall_in_project` | `remove_bg_wall_from_project` |
+| Floor | `add_floor_to_project` | `update_floor_in_project` | `remove_floor_from_project` |
+| Skylight | `add_skylight_to_project` | `update_skylight_in_project` | `remove_skylight_from_project` |
+| Window | `add_window_to_project` | `update_window_in_project` | `remove_window_from_project` |
+| Door | `add_door_to_project` | `update_door_in_project` | `remove_door_from_project` |
+| Thermal bridge | `add_thermal_bridge_to_project` | — | — |
+
+## Nesting rules
+
+- Skylights nest under a `Roof`.
+- Windows, doors, thermal bridges nest under an above-grade or
+  below-grade wall.
+- Floors are top-level.
+
+The `add_*_to_project` functions accept the parent component
+identifier (or auto-place under the first matching parent) — see
+the existing `examples/project_operations/envelope_operations.py`
+for current calling conventions.
+
+## Working with templates
+
+Always start from `comcheck_api.defaults`:
+
+```python
+from comcheck_api.defaults import (
+    get_default_project_template,
+    get_default_roof_template,
+    get_default_ag_wall_template,
+    get_default_bg_wall_template,
+    get_default_floor_template,
+    get_default_window_template,
+    get_default_door_template,
+    get_default_skylight_template,
+    get_default_thermal_bridge_template,
+    get_default_building_area_template,
+)
+```
+
+Each returns a fully-populated Pydantic model with sensible defaults
+(Boulder, CO; metal-frame walls; double-pane low-E glazing; etc.).
+Customize fields after construction:
+
+```python
+roof = get_default_roof_template()
+roof.area = 6000.0
+roof.cavityRValue = 38.0
+project = env_ops.add_roof_to_project(project, roof)
+```