comcheck-api 1.0.0__py3-none-any.whl

comcheck_api/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/__init__.py

@@ -0,0 +1,99 @@
+"""COMcheckWeb API - Python client for programmatic building energy code compliance.
+
+This package provides a type-safe, automated interface to the U.S. Department of
+Energy's COMcheck Web API for building energy code compliance verification.
+
+Quick Start:
+    >>> from comcheck_api import COMcheckClient
+    >>> client = COMcheckClient(api_key="your-api-key")
+    >>> project = client.get_project("123")
+    >>> session_id = client.start_run_simulation(project)
+
+Basic Usage:
+    from comcheck_api import (
+        COMcheckClient,
+        COMCheckHTTPError,
+        export_to_json,
+    )
+
+    client = COMcheckClient(api_key="your-key")
+
+    try:
+        projects = client.list_projects()
+        export_to_json(projects, "projects.json")
+    except COMCheckHTTPError as e:
+        print(f"HTTP error: {e.status_code}")
+
+Advanced Usage:
+    from comcheck_api import (
+        COMcheckClient,
+        project_envelope_operations,
+    )
+    from comcheck_api.types import AgWall, ComBuilding
+
+    # For type imports, use the types submodule
+    # from comcheck_api.types import ...
+
+    # For advanced utilities, use the utilities submodule
+    # from comcheck_api.utilities import ...
+"""
+
+# Client
+from .client import COMcheckClient
+
+# Exceptions
+from .exceptions import (
+    COMCheckAPIError,
+    COMCheckHTTPError,
+    COMCheckConnectionError,
+    COMCheckValidationError,
+    COMCheckSimulationError,
+    COMCheckProjectNotFoundError,
+)
+
+# Project Defaults
+from . import defaults
+
+# Project Operations
+from .project_operations import (
+    project_building_area_operations,
+    project_envelope_operations,
+)
+
+# Introspection helpers
+from .introspection import list_operations, lookup_type
+
+# Validation helpers
+from .validation import validate_project
+
+# Utilities
+from . import utilities
+
+# Types
+from . import types
+
+__all__ = [
+    # Client
+    "COMcheckClient",
+    # Exceptions
+    "COMCheckAPIError",
+    "COMCheckHTTPError",
+    "COMCheckConnectionError",
+    "COMCheckValidationError",
+    "COMCheckSimulationError",
+    "COMCheckProjectNotFoundError",
+    # Project Defaults
+    "defaults",
+    # Project Operations
+    "project_building_area_operations",
+    "project_envelope_operations",
+    # Introspection
+    "list_operations",
+    "lookup_type",
+    # Validation
+    "validate_project",
+    # Utilities
+    "utilities",
+    # Types
+    "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,285 @@
+---
+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
+  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=...`. The client does
+  **not** auto-read any environment variable — read it yourself and
+  pass it: `COMcheckClient(api_key=os.environ["COM_API_KEY"])`.
+- **Project shape**: a project is a `ComBuilding` Pydantic model with
+  lowercase top-level fields: `project` (metadata), `location`,
+  `envelope`, `lighting` (which contains `wholeBldgUse[]` — the
+  building areas), `hvac`, `renewable`, and `control` (energy code).
+  No `Project`/`Control` PascalCase aliases exist.
+  The fields `hvac`, `renewable`, and the **interior-lighting fixtures
+  inside `activityUse[]`**, plus exterior lighting (`exteriorUse[]`)
+  and the shared `fixtureSchedule[]`, exist on the model but have
+  **no operation functions** — leave them at template defaults. Only
+  `lighting.wholeBldgUse[]` (building areas, including each area's
+  own `interiorLightingSpace` singleton) is mutable, via
+  `project_building_area_operations`.
+- **Operation modules (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`.
+- **Envelope items attach to a building-area key**: every
+  `add_*_to_project` envelope function takes
+  `(project, building_area_key, new_component)`. Look up the key
+  with `ba_ops.get_building_area_keys_from_project(project)` first.
+  Default projects have **no** building areas — add one with
+  `ba_ops.add_building_area_to_project(...)` before any envelope
+  work.
+- **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
+  `"SUCCESS"` (terminal-ok) or `"FAILED"` (terminal-error), then call
+  `get_simulation_result`. See `comcheck_api.types.SimulationStatus`
+  for known lifecycle values (the catalog isn't exhaustive — only
+  the terminal pair is guaranteed stable).
+
+## Quick start
+
+```python
+import os
+import time
+
+from comcheck_api import COMcheckClient
+from comcheck_api.defaults import get_default_project_template
+from comcheck_api.types import SimulationStatus
+
+# Client does NOT auto-read COM_API_KEY — pass it in.
+client = COMcheckClient(api_key=os.environ["COM_API_KEY"])
+
+# Build a project from a default template
+project = get_default_project_template()
+project.project.projectTitle = "5,000 sqft office in Seattle"
+
+# Run a simulation
+session_id = client.start_run_simulation(project)
+
+# Poll until terminal — SUCCESS or FAILED
+while True:
+    status = client.get_simulation_status(session_id)
+    if status["status"] == SimulationStatus.SUCCESS:
+        break
+    if status["status"] == SimulationStatus.FAILED:
+        raise RuntimeError(f"Simulation failed: {status.get('message')}")
+    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 modules (e.g.,
+  `env_ops.add_ag_wall_to_project(project, area_key, wall)`) to
+  mutate project structure. Don't manipulate nested dicts directly.
+- For envelope items, look up the building-area key first via
+  `ba_ops.get_building_area_keys_from_project(project)`. The key
+  goes between `project` and the new component in every
+  `add_*_to_project` envelope call.
+- Set enum-typed fields (`orientation`, `wallType`, `code`, etc.)
+  with members from the matching `*Options` enum imported from
+  `comcheck_api.types` — not raw strings, which trigger
+  Pydantic serialization warnings.
+- Pass `api_key=` explicitly to `COMcheckClient(...)`. The SDK does
+  **not** auto-load any env var — read it yourself:
+
+  ```python
+  from dotenv import load_dotenv
+  load_dotenv()
+  client = COMcheckClient(api_key=os.environ["COM_API_KEY"])
+  ```
+
+  `client.set_api_key(api_key)` is the equivalent post-construction
+  setter. Users get a Personal Access Token from the COMcheck Web
+  site (Settings → Developer Setting); see the
+  [GitHub README](https://github.com/pnnl/comcheckweb-api-python#1-obtain-an-api-key)
+  or the
+  [Getting Started page](https://pnnl.github.io/comcheckweb-api-python/getting-started/)
+  for the full walkthrough.
+- 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.
+- Don't use `comcheck_api.managers.*` (e.g. `AgWallListManager`,
+  `RoofListManager`). Those are internal list-mutation helpers; they
+  bypass the validation logic in the operation modules. Always go
+  through `project_envelope_operations` and
+  `project_building_area_operations` instead.
+- Don't add, update, or remove interior lighting (the
+  `activityUse[]` fixtures), exterior lighting (`exteriorUse[]`,
+  `fixtureSchedule[]`), HVAC/mechanical, or renewable-energy
+  components — no operations exist for them. The whole-building
+  `interiorLightingSpace` singleton on each `WholeBldgUse` *is*
+  editable through `project_building_area_operations`; the per-
+  activity lighting nested under `activityUse[]` is not. The
+  `COMcheckClient` user methods (`list_projects`, `get_project`,
+  `update_project`, `start_run_simulation`, `get_simulation_status`,
+  `get_simulation_result`, `set_api_key`) are fully supported and
+  fine to use. If asked for an unsupported mutation area, tell the
+  user it's not implemented and offer building-area / envelope /
+  simulation instead. Confirm operation scope with
+  `comcheck_api.list_operations()` (only `building_area` and
+  `envelope` groups exist).
+
+## Common patterns
+
+### Adding a building area, then an above-grade wall
+
+`get_default_project_template()` starts with **zero building
+areas** — add one before attaching any envelope component.
+
+```python
+from comcheck_api import (
+    project_envelope_operations as env_ops,
+    project_building_area_operations as ba_ops,
+)
+from comcheck_api.defaults import (
+    get_default_building_area_template,
+    get_default_ag_wall_template,
+)
+from comcheck_api.types import OrientationOptions
+
+# 1. Add the building area (no areas exist by default).
+area = get_default_building_area_template()
+area.areaDescription = "Open office"
+project = ba_ops.add_building_area_to_project(project, area)
+
+# 2. Look up its key.
+area_key = ba_ops.get_building_area_keys_from_project(project)[0]["key"]
+
+# 3. Attach the wall to that area.
+wall = get_default_ag_wall_template()
+wall.description = "South wall"
+wall.orientation = OrientationOptions.SOUTH   # use the enum, not "SOUTH"
+wall.grossArea = 4800.0                        # field is grossArea, not area
+project = env_ops.add_ag_wall_to_project(project, area_key, wall)
+```
+
+### Listing the user's projects and updating one
+
+```python
+projects = client.list_projects()
+target = next(p for p in projects if p["name"] == "My office")  # key is "name", not "title"
+project_obj = client.get_project(target["_id"])     # note the underscore
+project_obj.project.projectTitle = "My office (revised)"
+client.update_project(project_id=target["_id"], project_data=project_obj)
+```
+
+`list_projects()` returns **raw, untyped dicts** straight from the API
+(no TypedDict enforces the shape). Each entry looks like:
+`{"_id", "name", "energyCode", "status", "sharing", "ownedByMe",
+"lastUpdated"}`. The display name is under `"name"` — there is **no
+`"title"` key** (matching on `"title"` silently fails with
+`StopIteration`/`KeyError`).
+
+`get_project(project_id, mode="json")` returns a raw dict instead of
+a `ComBuilding` model — handy when you just need the JSON shape.
+
+### Polling a simulation with a timeout
+
+```python
+import time
+from comcheck_api.types import SimulationStatus
+
+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"] == SimulationStatus.SUCCESS:
+        result = client.get_simulation_result(session_id)
+        break
+    if status["status"] == SimulationStatus.FAILED:
+        raise RuntimeError(f"Simulation failed: {status.get('message')}")
+    time.sleep(5)
+else:
+    raise TimeoutError(f"Simulation {session_id} did not complete in 5 min")
+```
+
+## Gotchas
+
+- **Field names are lowercase camelCase**, not PascalCase.
+  `project.project.projectTitle`, `project.control.code`,
+  `project.lighting.wholeBldgUse[0].areaDescription`. There is no
+  `Project`, `Control`, `WholeBldgUse` (top-level), or `.title`.
+- **AG/BG wall area field is `grossArea`**, not `area`. Same for
+  roofs/floors/windows/doors. Setting `.area` silently does nothing
+  because Pydantic models reject unknown attributes only in strict
+  mode.
+- **Use enum members for typed fields**: `OrientationOptions.NORTH`,
+  `WallTypeOptions.WOOD_FRAME_16_AG_WALL`,
+  `EnergyCodeOptions.CEZ_90_1_2022`. Setting them to raw strings
+  works at runtime but emits `PydanticSerializationUnexpectedValue`
+  warnings every time the model serializes.
+- **There is no `STEEL_FRAME` wall type — steel framing maps to
+  `METAL_FRAME_*`.** `WallTypeOptions` members are `WOOD_FRAME_16/24`,
+  `METAL_FRAME_16/24`, `METAL_WALL_WO_TB`, `METAL_BLDG`, `CONCRETE`,
+  `MASONRY`, `OTHER` (each suffixed `_AG_WALL`). A user asking for a
+  "steel-frame wall" wants `WallTypeOptions.METAL_FRAME_16_AG_WALL`
+  (or `_24_`).
+- **`COMcheckClient(api_key=...)` does not auto-read env vars.** No
+  `COM_API_KEY` fallback exists in `__init__`. Pass it explicitly.
+- **`SimulationStatus` is a known-values catalog, not an exhaustive
+  contract.** The server may emit lifecycle values not yet in the
+  enum (e.g. `EVALUATING` was added in a later version). The
+  `status` field comes back as a plain `str` so unknown values
+  don't crash polling. Only `SUCCESS` and `FAILED` are guaranteed
+  terminal — break/raise on those, keep polling for everything
+  else (don't enumerate non-terminals).
+- **A 500 from `start_run_simulation` usually means bad project
+  data, not a server outage.** All HTTP errors surface as the same
+  `COMCheckHTTPError` — there is no validation-specific exception, so
+  a payload the engine rejects (e.g. a malformed shape like assigning
+  a list to an object field, or project state the engine won't
+  accept) comes back as a bare HTTP 500, indistinguishable from a
+  real outage. To tell them apart, simulate a fresh
+  `get_default_project_template()` project: if that succeeds, the 500
+  is your project data, not the server. Inspect
+  `COMCheckHTTPError.status_code` / `.response_data` for detail.
+
+## When you need more detail
+
+- For the authoritative list of what's implemented → call
+  `comcheck_api.list_operations()`. Only operations it returns are
+  supported.
+- 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,101 @@
+# 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
+```
+
+Every envelope `add_*_to_project` call attaches the new component to
+a building-area key. Default projects have no areas — add one first:
+
+```python
+from comcheck_api.defaults import get_default_building_area_template
+
+area = get_default_building_area_template()
+area.areaDescription = "Open office"
+project = ba_ops.add_building_area_to_project(project, area)
+
+area_key = ba_ops.get_building_area_keys_from_project(project)[0]["key"]
+```
+
+| Component | Add signature | Update / Remove key |
+|---|---|---|
+| Roof | `add_roof_to_project(project, building_area_key, new_roof)` | `assemblyType` |
+| Above-grade wall | `add_ag_wall_to_project(project, building_area_key, new_ag_wall)` | `assemblyType` |
+| Below-grade wall | `add_bg_wall_to_project(project, building_area_key, new_bg_wall)` | `assemblyType` |
+| Floor | `add_floor_to_project(project, building_area_key, new_floor)` | `assemblyType` |
+| Skylight | `add_skylight_to_project(project, building_area_key, new_skylight, roof=None)` | `assemblyType` |
+| Window | `add_window_to_project(project, building_area_key, new_window, wall=None)` | `assemblyType` |
+| Door | `add_door_to_project(project, building_area_key, new_door, wall=None)` | `assemblyType` |
+| Thermal bridge | `add_thermal_bridge_to_project(project, building_area_key, ag_wall, ...)` | (no update/remove yet) |
+
+The `update_*_in_project` and `remove_*_from_project` functions take
+the component's `assemblyType` string, e.g.
+`update_ag_wall_in_project(project, ag_wall_assembly_type, updates)`.
+
+## Nesting rules
+
+- Skylights live inside a `Roof`. Pass `roof=` to
+  `add_skylight_to_project` to attach to a specific roof; otherwise
+  it goes on the first one in the area.
+- Windows and doors live inside an above-grade or below-grade wall.
+  Pass `wall=` to target a specific wall.
+- Thermal bridges always require an `ag_wall=` argument.
+- Floors and walls live directly under the building area.
+
+## 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, then attach to a building area:
+
+```python
+from comcheck_api.types import OrientationOptions
+
+area_key = ba_ops.get_building_area_keys_from_project(project)[0]["key"]
+
+roof = get_default_roof_template()
+roof.grossArea = 6000.0          # field is grossArea, not area
+roof.cavityRValue = 38.0
+roof.orientation = OrientationOptions.UNSPECIFIED_ORIENTATION
+project = env_ops.add_roof_to_project(project, area_key, roof)
+```

comcheck_api/ai/skill/reference/simulation.md

@@ -0,0 +1,99 @@
+# Simulation Flow Reference
+
+Simulations are asynchronous on the server side. Three-step pattern:
+
+1. **Start** — submit the project, receive a session ID.
+2. **Poll** — repeatedly check status until it reports `SUCCESS`
+   (terminal-ok) or `FAILED` (terminal-error).
+3. **Fetch** — retrieve the result by session ID.
+
+## Status values
+
+`get_simulation_status(...)["status"]` is a string. Known values are
+enumerated in `comcheck_api.types.SimulationStatus` (a `StrEnum`),
+but **the catalog is not exhaustive** — the server may emit values
+the SDK doesn't yet enumerate. The status field is typed as `str`
+specifically so unknown values pass through without crashing the
+polling loop. Only the terminal pair (`SUCCESS` / `FAILED`) is
+guaranteed stable; treat anything else as "still in progress."
+
+| Value | Terminal? | Meaning |
+|---|---|---|
+| `INITIALIZING` | no | Server is preparing the run |
+| `GENERATING_BASELINE` | no | Building the baseline (code-minimum) model |
+| `GENERATING_PROPOSED` | no | Building the proposed (user) model |
+| `RUNNING_SIMULATIONS` | no | Energy simulations are executing |
+| `CALCULATING_RESULTS` | no | Post-processing performance metrics |
+| `EVALUATING` | no | Evaluating compliance results |
+| `SUCCESS` | **yes** | Result is ready; call `get_simulation_result` |
+| `FAILED` | **yes** | Simulation failed; check the `message` field |
+| (any other value) | no | Future / unknown server state — keep polling |
+
+Because `SimulationStatus` is a `StrEnum`, `==` works against both
+the enum member and the raw string:
+``status == SimulationStatus.SUCCESS`` and
+``status == "SUCCESS"`` are equivalent.
+
+## Methods
+
+```python
+from comcheck_api import COMcheckClient
+client = COMcheckClient(api_key="...")
+```
+
+| Method | Returns | Purpose |
+|---|---|---|
+| `client.start_run_simulation(project, project_id=None)` | `str` (session ID) | Kick off the simulation. If `project_id` is provided, the project is also saved/updated. |
+| `client.get_simulation_status(session_id)` | `dict` | Current status. Fields: `sessionId`, `status` (see the Status values table above), optional `message`. |
+| `client.get_simulation_result(session_id)` | `dict` | Final result. Fields: `sessionId`, `performanceRating`, `energyCreditPerformanceRating`, `proposedBpf`, `baselineBpf`. |
+
+### Loading an existing project to simulate
+
+| Method | Returns | Notes |
+|---|---|---|
+| `client.list_projects()` | `list[dict]` | Each project dict uses **`_id`** (with the underscore), not `id`. |
+| `client.get_project(project_id, mode="python")` | `ComBuilding` | Default. Returns a Pydantic model you can pass straight into `start_run_simulation`. |
+| `client.get_project(project_id, mode="json")` | `dict` | Returns the raw project JSON instead of a parsed model. |
+
+## Polling pattern
+
+Always include a timeout. 5 minutes is a safe default for a typical
+small/medium project.
+
+```python
+import time
+from comcheck_api.types import SimulationStatus
+
+session_id = client.start_run_simulation(project)
+deadline = time.time() + 300
+
+while time.time() < deadline:
+    status = client.get_simulation_status(session_id)
+    if status["status"] == SimulationStatus.SUCCESS:
+        break
+    if status["status"] == SimulationStatus.FAILED:
+        raise RuntimeError(f"Simulation failed: {status.get('message')}")
+    time.sleep(5)
+else:
+    raise TimeoutError(f"Simulation {session_id} did not complete in 5 minutes")
+
+result = client.get_simulation_result(session_id)
+```
+
+## Result interpretation
+
+- `performanceRating` is the primary pass/fail metric — typically
+  expressed as a percentage margin against the baseline. Positive =
+  better than baseline = pass.
+- `proposedBpf` / `baselineBpf` are Building Performance Factors for
+  the proposed and baseline (code-minimum) buildings.
+- `energyCreditPerformanceRating` is the credit rating used when
+  optional measures (renewables, advanced controls, etc.) are
+  included.
+
+## Don't
+
+- Don't poll faster than every 5 seconds — the backend rate-limits.
+- Don't run multiple concurrent simulations from the same API key
+  unless you've confirmed your quota allows it.
+- Don't drop the `session_id` — there's no recovery without it.