comcheck-api 1.0.0__py3-none-any.whl

comcheck_api/ai/skill/reference/types.md

@@ -0,0 +1,90 @@
+# Types Reference
+
+All types are Pydantic models. Import from `comcheck_api.types`.
+
+## Top-level project model
+
+`ComBuilding` is the root project model. **All top-level fields are
+lowercase camelCase** (no `Project`/`Control`/`Envelope` PascalCase
+aliases exist).
+
+| Field | Type | Purpose |
+|---|---|---|
+| `project` | `Project` | Project metadata. Title is `project.project.projectTitle`; address fields use `projectAddress` / `projectCity` / etc. |
+| `location` | `Location` | State, city, climate zone. |
+| `envelope` | `Envelope` | Roofs (`roof[]`), AG walls (`agWall[]`), BG walls (`bgWall[]`), floors, windows, doors, skylights. |
+| `lighting` | `Lighting` | Holds `wholeBldgUse[]` — the **building areas / zones**. `wholeBldgUse[]` (including each area's `interiorLightingSpace` singleton) is operable; `activityUse[]`, `exteriorUse[]`, and `fixtureSchedule[]` have no operations. |
+| `hvac` | `HVAC` | Mechanical systems — no operations; not editable via this SDK. |
+| `renewable` | `Renewable` | Renewable energy systems — no operations; not editable via this SDK. |
+| `control` | `Control` | Energy code (`control.code`, e.g. `CEZ_IECC2018`, `CEZ_90_1_2022`). |
+
+Building areas (`WholeBldgUse`) are **not top-level** — they live
+under `lighting.wholeBldgUse[]`. Use
+`ba_ops.get_building_area_keys_from_project(project)` to enumerate
+them.
+
+## Envelope component models
+
+| Model | Notes |
+|---|---|
+| `Envelope` | Container for all envelope components. |
+| `Roof` | Skylights nest inside. |
+| `AgWall` (above-grade) | Windows, doors, thermal bridges nest inside. |
+| `BgWall` (below-grade) | Same nesting as AgWall. |
+| `Floor` | Top-level. |
+| `Skylight` | Standalone or nested under a `Roof`. |
+| `Window` | Standalone or nested under a wall. |
+| `Door` | Standalone or nested under a wall. |
+| `ThermalBridge` | Nested under a wall. |
+
+## Building area / lighting
+
+| Model | Purpose |
+|---|---|
+| `WholeBldgUse` | One building area / zone. Lives in `project.lighting.wholeBldgUse[]`. Has `key`, `areaDescription`, `floorArea`, `ceilingHeight`, `interiorLightingSpace`, etc. |
+| `InteriorLightingSpace` | Lighting configuration for one area. The singleton attached directly to a `WholeBldgUse` is editable via `update_building_area_in_project`; the same model nested under `activityUse[]` is **not** operable (interior-lighting fixtures live there). |
+
+Every envelope component has a `bldgUseKey` field that ties it to
+one of these area keys.
+
+## HVAC
+
+⚠️ Documented for shape only — no add/update/remove operations exist
+for any of these models. Leave `project.hvac` at its template default.
+
+| Model | Purpose |
+|---|---|
+| `HVAC` | Container. |
+| `HVACSystem` | One HVAC system definition. |
+| `HVACPlant` | Central plant equipment. |
+| `Fan` / `FanSystem` | Fan and fan-system models. |
+| `ServiceWaterHeatingSystem` (SWH) | Service water heating. |
+
+## Enums (StrEnum)
+
+Always set typed fields with members from the matching `*Options`
+enum imported from `comcheck_api.types`. Setting them as raw strings
+"works" but emits `PydanticSerializationUnexpectedValue` warnings
+on every serialize.
+
+Common ones:
+
+| Enum | Examples |
+|---|---|
+| `EnergyCodeOptions` | `CEZ_IECC2018`, `CEZ_IECC2021`, `CEZ_90_1_2019`, `CEZ_90_1_2022` |
+| `OrientationOptions` | `NORTH`, `EAST`, `SOUTH`, `WEST`, plus diagonals and `UNSPECIFIED_ORIENTATION` |
+| `WallTypeOptions` | (see source for full set) |
+| `SimulationStatus` | Known: `INITIALIZING`, `GENERATING_BASELINE`, `GENERATING_PROPOSED`, `RUNNING_SIMULATIONS`, `CALCULATING_RESULTS`, `EVALUATING`, `SUCCESS`, `FAILED`. Catalog is **not exhaustive** — only `SUCCESS`/`FAILED` are guaranteed terminal. |
+
+For exhaustive enum values, use
+`comcheck_api.lookup_type("WallTypeOptions")` (or any other enum
+name) — that's the live source of truth and stays in sync with the
+installed SDK.
+
+## Tips
+
+- Pydantic models accept dicts in their constructors and produce
+  validated instances — useful when interop with JSON.
+- Models export to JSON with `.model_dump_json()`.
+- The SDK accepts dicts for inputs but always returns validated
+  Pydantic models — that asymmetry is intentional.

comcheck_api/ai/skill/scripts/__init__.py

@@ -0,0 +1 @@
+"""Helper scripts bundled with the Skill (importable as a Python module)."""

comcheck_api/ai/skill/scripts/validate_code.py

@@ -0,0 +1,210 @@
+"""Validate generated Python that uses comcheck_api against a mocked client.
+
+Usage:
+    python -m comcheck_api.ai.skill.scripts.validate_code <path-to-script>
+    cat script.py | python -m comcheck_api.ai.skill.scripts.validate_code -
+
+Runs the user's code in a subprocess with the network layer mocked.
+Prints structured errors to stdout and exits non-zero if validation
+fails.
+
+This script is invoked by the Skill so Claude can run it via shell
+tools to self-check generated code.
+
+Security: the calling layer is responsible for sandboxing — running
+this script from an untrusted source still executes arbitrary Python.
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+from pathlib import Path
+
+
+def _read_input(arg: str) -> str:
+    if arg == "-":
+        return sys.stdin.read()
+    return Path(arg).read_text()
+
+
+UNSUPPORTED_PROJECT_ATTRS = {"hvac", "renewable"}
+UNSUPPORTED_LIGHTING_ATTRS = {
+    "activityUse",
+    "exteriorUse",
+    "fixtureSchedule",
+}
+
+
+def _supported_operation_names() -> set[str]:
+    """Live set of supported operation function names from the SDK."""
+    try:
+        from comcheck_api import list_operations
+    except Exception:  # noqa: BLE001
+        return set()
+    return {op.name for op in list_operations()}
+
+
+def _is_attr_chain(node, head: str, tail: str) -> bool:
+    """True if `node` is `<head>.<tail>` — e.g. `project.hvac`."""
+    import ast
+
+    return (
+        isinstance(node, ast.Attribute)
+        and node.attr == tail
+        and isinstance(node.value, ast.Name)
+        and node.value.id == head
+    )
+
+
+def _is_lighting_chain(node, attr: str) -> bool:
+    """True if `node` is `project.lighting.<attr>`."""
+    import ast
+
+    return (
+        isinstance(node, ast.Attribute)
+        and node.attr == attr
+        and isinstance(node.value, ast.Attribute)
+        and node.value.attr == "lighting"
+        and isinstance(node.value.value, ast.Name)
+        and node.value.value.id == "project"
+    )
+
+
+def validate(code: str) -> dict:
+    """Compile-check the provided code and report errors as a dict.
+
+    Runs three passes:
+    1. Syntax check via :func:`compile`.
+    2. Import check on every imported module name.
+    3. Scope check that the code only uses operations actually exposed
+       by the SDK and does not mutate the unsupported `hvac`,
+       `renewable`, or non-`wholeBldgUse` lighting subtrees.
+    """
+    errors: list[dict] = []
+
+    # 1. Syntax check via compile().
+    try:
+        compile(code, "<generated>", "exec")
+    except SyntaxError as e:
+        errors.append(
+            {
+                "kind": "syntax",
+                "line": e.lineno,
+                "col": e.offset,
+                "message": e.msg,
+            }
+        )
+        return {"ok": False, "errors": errors}
+
+    # 2. Import check: parse import statements and try importing each
+    #    module name without executing the user's code.
+    import ast
+
+    tree = ast.parse(code)
+    for node in ast.walk(tree):
+        modules: list[str] = []
+        if isinstance(node, ast.Import):
+            modules = [alias.name for alias in node.names]
+        elif isinstance(node, ast.ImportFrom) and node.module:
+            modules = [node.module]
+        for mod in modules:
+            try:
+                __import__(mod)
+            except ImportError as e:
+                errors.append({"kind": "import", "module": mod, "message": str(e)})
+
+    # 3. Scope check: cross-reference symbols against list_operations()
+    #    so the guard auto-tracks SDK growth, and forbid direct mutation
+    #    of the unsupported subtrees.
+    supported_ops = _supported_operation_names()
+
+    # Collect the local names that resolve into the operation modules.
+    op_module_aliases: set[str] = set()
+    for node in ast.walk(tree):
+        if isinstance(node, ast.ImportFrom) and node.module == "comcheck_api":
+            for alias in node.names:
+                if alias.name in {
+                    "project_envelope_operations",
+                    "project_building_area_operations",
+                }:
+                    op_module_aliases.add(alias.asname or alias.name)
+        elif isinstance(node, ast.ImportFrom) and node.module == (
+            "comcheck_api.project_operations"
+        ):
+            for alias in node.names:
+                if alias.name in {
+                    "project_envelope_operations",
+                    "project_building_area_operations",
+                }:
+                    op_module_aliases.add(alias.asname or alias.name)
+
+    for node in ast.walk(tree):
+        # Forbid `project.hvac` / `project.renewable` access in any context.
+        if isinstance(node, ast.Attribute) and any(
+            _is_attr_chain(node, "project", attr) for attr in UNSUPPORTED_PROJECT_ATTRS
+        ):
+            errors.append(
+                {
+                    "kind": "unsupported-scope",
+                    "line": node.lineno,
+                    "message": (
+                        f"`project.{node.attr}` has no operations in this SDK; "
+                        "leave it at template defaults."
+                    ),
+                }
+            )
+
+        # Forbid `project.lighting.<unsupported>`.
+        if isinstance(node, ast.Attribute) and any(
+            _is_lighting_chain(node, attr) for attr in UNSUPPORTED_LIGHTING_ATTRS
+        ):
+            errors.append(
+                {
+                    "kind": "unsupported-scope",
+                    "line": node.lineno,
+                    "message": (
+                        f"`project.lighting.{node.attr}` has no operations; "
+                        "only `lighting.wholeBldgUse[]` is editable."
+                    ),
+                }
+            )
+
+        # Calls of the form `<op_module>.<name>(...)` must hit a real op.
+        if (
+            supported_ops
+            and isinstance(node, ast.Call)
+            and isinstance(node.func, ast.Attribute)
+            and isinstance(node.func.value, ast.Name)
+            and node.func.value.id in op_module_aliases
+        ):
+            fn_name = node.func.attr
+            if fn_name not in supported_ops and not fn_name.startswith("_"):
+                errors.append(
+                    {
+                        "kind": "unknown-operation",
+                        "line": node.lineno,
+                        "operation": fn_name,
+                        "message": (
+                            f"`{node.func.value.id}.{fn_name}` is not a supported "
+                            "operation. Run comcheck_api.list_operations() for the "
+                            "current set."
+                        ),
+                    }
+                )
+
+    return {"ok": not errors, "errors": errors}
+
+
+def main() -> int:
+    if len(sys.argv) != 2:
+        print("usage: validate_code.py <path|->", file=sys.stderr)
+        return 2
+    code = _read_input(sys.argv[1])
+    result = validate(code)
+    print(json.dumps(result, indent=2))
+    return 0 if result["ok"] else 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

comcheck_api/api/__init__.py

@@ -0,0 +1 @@
+from comcheck_api.api.api_services import COMCheckApiService

comcheck_api/api/api_services.py

@@ -0,0 +1,273 @@
+"""COMCheck API service module for making HTTP requests to the COMCheck API."""
+
+"""Note: Service layer accepts raw data types (dicts) as inputs to stay simple and
+HTTP-library-friendly, but returns validated Pydantic models to provide type safety
+and catch API schema mismatches at the boundary."""
+
+import logging
+import os
+from typing import Any, Dict, NoReturn, Optional
+
+import httpx
+
+from comcheck_api.exceptions import (
+    COMCheckHTTPError,
+    COMCheckConnectionError,
+    COMCheckValidationError,
+)
+from comcheck_api.types.api_types import (
+    RunSimulationResponse,
+    SimulationStatusResponse,
+    SimulationResultResponse,
+)
+
+
+class COMCheckApiService:
+    """Low-level HTTP service for the COMcheck Web API.
+
+    Handles authentication, request construction, response parsing, and
+    error mapping.  Methods accept raw dicts as inputs and return either
+    raw dicts or validated Pydantic response models.
+
+    Can be used as a context manager::
+
+        with COMCheckApiService(api_key="key") as svc:
+            data = svc.get_project("123")
+    """
+
+    def __init__(self, api_key: str) -> None:
+        """Initialize COMCheck API service.
+
+        Args:
+            api_key: API key for authentication
+
+        Raises:
+            ValueError: If API key is not provided
+        """
+        if not api_key:
+            raise ValueError(
+                "COM_API_KEY is not set. Please provide it as a constructor parameter "
+                "or set it in your environment variables."
+            )
+        self.api_key = api_key
+        self.base_url: str = os.getenv(
+            "COMCHECK_API_URL", "https://comcheck.energycode.pnl.gov/checkweb-api/COM"
+        )
+        self._client: Optional[httpx.Client] = None
+
+    def _get_client(self) -> httpx.Client:
+        """Get or create HTTP client instance.
+
+        Returns:
+            Configured httpx.Client instance
+        """
+        if self._client is None:
+            self._client = httpx.Client(
+                base_url=self.base_url,
+                headers=self._prepare_headers(),
+                timeout=30.0,
+            )
+        return self._client
+
+    def _prepare_headers(self) -> Dict[str, str]:
+        """Prepare headers for API requests.
+
+        Returns:
+            HTTP headers dictionary
+        """
+        return {
+            "x-api-key": self.api_key,
+            "Content-Type": "application/json",
+            "Accept": "application/json",
+        }
+
+    def _handle_api_error(self, error: Exception) -> NoReturn:
+        """Handle API errors with detailed logging and raise custom exceptions.
+
+        Args:
+            error: The error object to handle
+
+        Raises:
+            COMCheckHTTPError: For HTTP status errors
+            COMCheckConnectionError: For connection/request errors
+            COMCheckValidationError: For validation errors
+        """
+        logger = logging.getLogger(__name__)
+
+        if isinstance(error, httpx.HTTPStatusError):
+            logger.error(
+                "HTTP error occurred: %s (Status: %s)",
+                error,
+                error.response.status_code,
+                exc_info=True,
+                extra={
+                    "response_data": error.response.text,
+                    "response_headers": dict(error.response.headers),
+                },
+            )
+            raise COMCheckHTTPError(
+                status_code=error.response.status_code,
+                message=error.response.reason_phrase,
+                response_data=error.response.text,
+            ) from error
+        elif isinstance(error, httpx.RequestError):
+            logger.error(
+                "Request error occurred: %s",
+                error,
+                exc_info=True,
+                extra={"request": str(error.request)},
+            )
+            raise COMCheckConnectionError(
+                f"Failed to connect to COMcheck API: {str(error)}"
+            ) from error
+        else:
+            logger.error("Unexpected error: %s", error, exc_info=True)
+            raise
+
+    def get_project(self, project_id: str) -> Dict[str, Any]:
+        """Get a single project by ID.
+
+        Args:
+            project_id: The project ID to retrieve
+
+        Returns:
+            API response data as dictionary
+
+        Raises:
+            COMCheckHTTPError: If the API returns an error status
+            COMCheckConnectionError: If the request fails
+        """
+        try:
+            client = self._get_client()
+            response = client.get(f"/project/{project_id}")
+            response.raise_for_status()
+            return response.json()
+        except Exception as error:
+            self._handle_api_error(error)
+
+    def get_project_list(self) -> Dict[str, Any]:
+        """Get a list of all projects.
+
+        Returns:
+            API response data as dictionary
+
+        Raises:
+            COMCheckHTTPError: If the API returns an error status
+            COMCheckConnectionError: If the request fails
+        """
+        try:
+            client = self._get_client()
+            response = client.get("/projects")
+            response.raise_for_status()
+            return response.json()
+        except Exception as error:
+            self._handle_api_error(error)
+
+    def update_project(
+        self, project_id: str, project_data: Dict[str, Any]
+    ) -> Dict[str, Any]:
+        """Update a project by ID.
+
+        Args:
+            project_id: The project ID to update
+            project_data: The project data to send in the request body
+
+        Returns:
+            API response data as dictionary
+
+        Raises:
+            COMCheckHTTPError: If the API returns an error status
+            COMCheckConnectionError: If the request fails
+        """
+        try:
+            client = self._get_client()
+            response = client.put(f"/project/{project_id}", json=project_data)
+            response.raise_for_status()
+            return response.json()
+        except Exception as error:
+            self._handle_api_error(error)
+
+    def start_run_simulation(
+        self, project_data: Dict[str, Any]
+    ) -> RunSimulationResponse:
+        """Start a simulation.
+
+        Args:
+            project_data: The project data to send in the request body
+
+        Returns:
+            RunSimulationResponse with session information
+
+        Raises:
+            COMCheckHTTPError: If the API returns an error status
+            COMCheckConnectionError: If the request fails
+        """
+        try:
+            client = self._get_client()
+            response = client.post(
+                f"/compliance/start-run-simulation", json=project_data
+            )
+            response.raise_for_status()
+            return RunSimulationResponse.model_validate(response.json())
+        except Exception as error:
+            self._handle_api_error(error)
+
+    def get_simulation_status(self, session_id: str) -> SimulationStatusResponse:
+        """Get status of a simulation.
+
+        Args:
+            session_id: The session ID of the simulation
+
+        Returns:
+            SimulationStatusResponse with status information
+
+        Raises:
+            COMCheckHTTPError: If the API returns an error status
+            COMCheckConnectionError: If the request fails
+        """
+        try:
+            client = self._get_client()
+            response = client.get(
+                f"/compliance/get-status-simulation?sessionId={session_id}"
+            )
+            response.raise_for_status()
+            return SimulationStatusResponse.model_validate(response.json())
+        except Exception as error:
+            self._handle_api_error(error)
+
+    def get_simulation_result(self, session_id: str) -> SimulationResultResponse:
+        """Get result of a simulation.
+
+        Args:
+            session_id: The session ID of the simulation
+
+        Returns:
+            SimulationResultResponse with simulation results
+
+        Raises:
+            COMCheckHTTPError: If the API returns an error status
+            COMCheckConnectionError: If the request fails
+        """
+        try:
+            client = self._get_client()
+            response = client.get(
+                f"/compliance/get-result-simulation?sessionId={session_id}"
+            )
+            response.raise_for_status()
+            return SimulationResultResponse.model_validate(response.json())
+        except Exception as error:
+            self._handle_api_error(error)
+
+    def close(self) -> None:
+        """Close the HTTP client connection."""
+        if self._client is not None:
+            self._client.close()
+            self._client = None
+
+    def __enter__(self) -> "COMCheckApiService":
+        """Context manager entry."""
+        return self
+
+    def __exit__(self, exc_type: Any, exc_val: Any, exc_tb: Any) -> None:
+        """Context manager exit."""
+        self.close()