comcheck-api 1.0.0__py3-none-any.whl

comcheck_api/cli.py

@@ -0,0 +1,136 @@
+"""``comcheck-api`` console-script entry point.
+
+Subcommands:
+
+* ``install-skill`` — install the bundled Skill so an AI coding agent
+  picks it up. The Skill follows the open agent-skills standard
+  (``SKILL.md`` + ``reference/`` + ``scripts/``), so the same folder
+  works for both Claude Code and OpenAI Codex; only the install
+  location differs:
+
+  - Claude Code → ``.claude/skills/comcheck-api/`` (or
+    ``~/.claude/skills/`` with ``--global``).
+  - OpenAI Codex → ``.agents/skills/comcheck-api/`` (or
+    ``~/.agents/skills/`` with ``--global``). Codex scans
+    ``.agents/skills`` from the working directory up to the repo root.
+
+  By default both are installed. Pass ``--claude`` to install only the
+  Claude Code Skill, or ``--codex`` to install only the Codex Skill.
+"""
+
+from __future__ import annotations
+
+import argparse
+import shutil
+import sys
+from pathlib import Path
+
+from comcheck_api import ai
+
+# (agent label, skills dir) for each supported target.
+_TARGETS = {
+    "claude": ("Claude", ".claude"),
+    "codex": ("Codex", ".agents"),
+}
+
+
+def _install_one(
+    src: Path, base_dir: Path, agent_dir: str, force: bool, dry_run: bool
+) -> tuple[bool, Path]:
+    """Install the Skill for one agent. Returns (installed, target)."""
+    target_root = base_dir / agent_dir / "skills" / "comcheck-api"
+
+    if dry_run:
+        print(f"[dry-run] would copy {src} → {target_root}")
+        return True, target_root
+
+    if target_root.exists() and not force:
+        print(f"{target_root} already exists. Re-run with --force to overwrite.")
+        return False, target_root
+
+    if target_root.exists():
+        shutil.rmtree(target_root)
+    target_root.parent.mkdir(parents=True, exist_ok=True)
+    shutil.copytree(src, target_root)
+    print(f"Installed Skill into {target_root}")
+    return True, target_root
+
+
+def _cmd_install_skill(args: argparse.Namespace) -> int:
+    if args.global_install:
+        base_dir = Path.home()
+    else:
+        base_dir = Path(args.path).resolve()
+        if not base_dir.is_dir():
+            print(f"ERROR: {base_dir} is not a directory.")
+            return 1
+
+    # No agent flag → install both. Otherwise install only the
+    # selected agents.
+    if args.claude or args.codex:
+        agents = [k for k in _TARGETS if getattr(args, k)]
+    else:
+        agents = list(_TARGETS)
+
+    src = ai.skill_root()
+    any_installed = False
+    for key in agents:
+        label, agent_dir = _TARGETS[key]
+        installed, _ = _install_one(src, base_dir, agent_dir, args.force, args.dry_run)
+        if installed and not args.dry_run:
+            print(f"Restart {label} to pick up the new Skill.")
+        any_installed = any_installed or installed
+
+    return 0 if any_installed else 1
+
+
+def build_parser() -> argparse.ArgumentParser:
+    common = argparse.ArgumentParser(add_help=False)
+    common.add_argument(
+        "--dry-run", action="store_true", help="Show actions without applying"
+    )
+    common.add_argument(
+        "--force", action="store_true", help="Overwrite existing files/configs"
+    )
+
+    parser = argparse.ArgumentParser(prog="comcheck-api")
+    sub = parser.add_subparsers(dest="cmd", required=True)
+
+    p_skill = sub.add_parser(
+        "install-skill",
+        parents=[common],
+        help="Install the Skill for Claude Code and/or Codex (both by default)",
+    )
+    p_skill.add_argument(
+        "path", nargs="?", default=".", help="Project directory (default: cwd)"
+    )
+    p_skill.add_argument(
+        "--global",
+        dest="global_install",
+        action="store_true",
+        help="Install into the user-global skills dir (~/.claude/skills/ "
+        "and/or ~/.agents/skills/) instead of project-level",
+    )
+    p_skill.add_argument(
+        "--claude",
+        action="store_true",
+        help="Install only the Claude Code Skill (.claude/skills/)",
+    )
+    p_skill.add_argument(
+        "--codex",
+        action="store_true",
+        help="Install only the Codex Skill (.agents/skills/)",
+    )
+    p_skill.set_defaults(func=_cmd_install_skill)
+
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    return args.func(args)
+
+
+if __name__ == "__main__":  # pragma: no cover
+    sys.exit(main())

comcheck_api/client/__init__.py

@@ -0,0 +1 @@
+from comcheck_api.client.comcheck_client import COMcheckClient

comcheck_api/client/comcheck_client.py

@@ -0,0 +1,335 @@
+"""COMcheck Client module for simplified API interactions."""
+
+"""Note: Client layer provides user-friendly methods that accept Pydantic models as inputs
+and return either Pydantic models, primitives, or raw dicts depending on the operation."""
+
+import logging
+from typing import Any, Dict, List, Literal, Optional, Union, overload
+
+from comcheck_api.api import COMCheckApiService
+from comcheck_api.constants.building_area_constants import DEFAULT_BUILDING_AREA
+from comcheck_api.exceptions import (
+    COMCheckProjectNotFoundError,
+    COMCheckSimulationError,
+)
+from comcheck_api.types.core_types import ComBuilding, InteriorLightingSpace
+
+Mode = Literal["python", "json"]
+
+
+class COMcheckClient:
+    """High-level client for the COMcheck Web API.
+
+    Provides user-friendly methods that accept Pydantic models as inputs
+    and return either :class:`~comcheck_api.types.core_types.ComBuilding`
+    models, primitives, or raw dicts depending on the operation.
+
+    Can be used as a context manager to ensure the underlying HTTP
+    connection is closed::
+
+        with COMcheckClient(api_key="your-key") as client:
+            project = client.get_project("123")
+
+    Example:
+        ```python
+        client = COMcheckClient(api_key="your-key")
+        projects = client.list_projects()
+        project = client.get_project(projects[0]["projectId"])
+        client.close()
+        ```
+    """
+
+    def __init__(self, api_key: Optional[str] = None) -> None:
+        """Initialize COMcheck client.
+
+        Args:
+            api_key: Optional API key for authentication. Can be set later with set_api_key()
+        """
+        self._api_service: Optional[COMCheckApiService] = None
+        if api_key:
+            self.set_api_key(api_key)
+
+    def set_api_key(self, api_key: str) -> None:
+        """Set the API key and initialize the API service.
+
+        Args:
+            api_key: API key for authentication
+
+        Raises:
+            ValueError: If API key is not provided
+        """
+        if not api_key:
+            raise ValueError("API key is required.")
+        self._api_service = COMCheckApiService(api_key)
+
+    @property
+    def _service(self) -> COMCheckApiService:
+        """Get the API service instance.
+
+        Returns:
+            COMCheckApiService instance
+
+        Raises:
+            RuntimeError: If API key has not been set
+        """
+        if self._api_service is None:
+            raise RuntimeError(
+                "API key not set. Call set_api_key() before using the client."
+            )
+        return self._api_service
+
+    @overload
+    def get_project(
+        self,
+        project_id: str,
+        mode: Literal["python"] = "python",
+    ) -> Optional["ComBuilding"]: ...
+
+    @overload
+    def get_project(
+        self,
+        project_id: str,
+        mode: Literal["json"],
+    ) -> Optional[Dict[str, Any]]: ...
+
+    def get_project(
+        self,
+        project_id: str,
+        mode: Literal["python", "json"] = "python",
+    ) -> Optional[Union["ComBuilding", Dict[str, Any]]]:
+        """Fetch a single project by ID.
+
+        Args:
+            project_id: The project ID to retrieve.
+            mode: ``"python"`` returns a ``ComBuilding`` model; ``"json"`` returns a raw dict.
+
+        Returns:
+            The project as a ``ComBuilding`` or dict, or ``None`` if not found.
+        """
+        resp = self._service.get_project(project_id)
+        data = resp.get("data")
+        if data is not None:
+            for building_area in data["lighting"]["wholeBldgUse"]:
+                building_area["interiorLightingSpace"] = {
+                    **DEFAULT_BUILDING_AREA.interiorLightingSpace.model_dump(
+                        mode="json", exclude_unset=True
+                    )
+                }
+
+        return self._parse_data(data, mode)
+
+    def list_projects(self) -> List[Dict[str, Any]]:
+        """Get a list of all projects.
+
+        Returns:
+            API response data as list of project dictionaries
+        """
+        return self._service.get_project_list().get("data", [])
+
+    # TODO: return of update_project should be ComBuilding
+    def update_project(
+        self,
+        project_id: str,
+        project_data: ComBuilding,
+        mode: Literal["python", "json"] = "python",
+    ) -> ComBuilding | dict[str, Any] | None:
+        """Update a project by ID.
+
+        The existing project is fetched first to preserve server-assigned IDs
+        and the ``userProject`` reference.  Envelope component IDs that are
+        ``None`` (auto-generated by Pydantic) are stripped before submission.
+
+        Args:
+            project_id: The project ID to update.
+            project_data: A ``ComBuilding`` model with the desired state.
+            mode: ``"python"`` returns a ``ComBuilding`` model;
+                ``"json"`` returns a raw dict.
+
+        Returns:
+            The refreshed project after the update, in the requested format.
+
+        Raises:
+            COMCheckProjectNotFoundError: If the project does not exist.
+        """
+        # Get existing project
+        old_project = self.get_project(project_id, mode="json")
+
+        if not old_project:
+            raise COMCheckProjectNotFoundError(project_id)
+
+        project_data_json = project_data.model_dump(mode="json", exclude_unset=True)
+
+        # Preserve user project reference
+        user_project = old_project["userProject"]
+        project_data_json["userProject"] = user_project
+
+        # Preserve IDs from existing project
+        for section in [
+            "envelope",
+            "lighting",
+            "hvac",
+            "control",
+            "project",
+            "location",
+            "renewable",
+        ]:
+            project_data_json[section]["id"] = old_project[section]["id"]
+        project_data_json["id"] = old_project["id"]
+
+        # Ensure each building area has interiorLightingSpace initialized
+        for building_area in project_data_json["lighting"]["wholeBldgUse"]:
+            building_area["interiorLightingSpace"] = {
+                **DEFAULT_BUILDING_AREA.interiorLightingSpace.model_dump(
+                    mode="json", exclude_unset=True
+                )
+            }
+
+        # TODO: need to verify if other componets also need to remove None IDs (auto-generated through pydantic )
+        # Remove None IDs from envelope components
+        if "envelope" in project_data_json:
+            envelope = project_data_json["envelope"]
+            for component_type in [
+                "roof",
+                "agWall",
+                "bgWall",
+                "floor",
+                "skylight",
+                "window",
+                "door",
+            ]:
+                if component_type in envelope and isinstance(
+                    envelope[component_type], list
+                ):
+                    for component in envelope[component_type]:
+                        if isinstance(component, dict) and component.get("id") is None:
+                            component.pop("id", None)
+                        # Also remove None IDs from nested components (skylights in roofs, windows/doors in walls)
+                        if component_type == "roof" and "skylight" in component:
+                            for skylight in component.get("skylight", []):
+                                if (
+                                    isinstance(skylight, dict)
+                                    and skylight.get("id") is None
+                                ):
+                                    skylight.pop("id", None)
+                        elif component_type in ["agWall", "bgWall"]:
+                            for nested_type in ["window", "door", "thermalBridge"]:
+                                if nested_type in component:
+                                    for nested in component.get(nested_type, []):
+                                        if (
+                                            isinstance(nested, dict)
+                                            and nested.get("id") is None
+                                        ):
+                                            nested.pop("id", None)
+
+        self._service.update_project(project_id, project_data_json).get("data")
+
+        # It's necessary that we call return get_project instead of what's returned from
+        # the service's update project due to interiorLightingSpace not being updated correctly
+        # when returned from the update call
+        return self.get_project(project_id=project_id, mode=mode)
+
+    def _parse_data(self, data, mode):
+        """Convert raw API data to the requested output format.
+
+        Args:
+            data: Raw dict from the API response, or ``None``.
+            mode: ``"python"`` wraps data in a ``ComBuilding``; ``"json"`` returns it as-is.
+
+        Returns:
+            A ``ComBuilding``, a raw dict, or ``None`` if ``data`` is ``None``.
+        """
+        if data is None:
+            return None
+        if mode == "python":
+            return ComBuilding(**data)
+        return data
+
+    def start_run_simulation(
+        self, project: ComBuilding, project_id: Optional[int] = None
+    ) -> str:
+        """Start a compliance simulation run for a project.
+
+        If *project_id* is supplied the project is persisted via
+        :meth:`update_project` before the simulation is launched.
+
+        Args:
+            project: The project data to simulate.
+            project_id: Optional server-side project ID.  When given, the
+                project is saved before the simulation starts.
+
+        Returns:
+            The simulation session ID that can be passed to
+            :meth:`get_simulation_status` and :meth:`get_simulation_result`.
+
+        Raises:
+            COMCheckSimulationError: If the API returns no session data.
+        """
+        logger = logging.getLogger(__name__)
+
+        if project_id:
+            logger.info("Updating project: %s", project_id)
+            self.update_project(str(project_id), project)
+
+        project_data = project.model_dump(mode="json", exclude_unset=True)
+        run_result = self._service.start_run_simulation(project_data)
+        if run_result.data is None:
+            raise COMCheckSimulationError(
+                "Simulation start failed: no session data returned"
+            )
+        return run_result.data.sessionId
+
+    def get_simulation_status(self, session_id: str) -> Dict[str, Any]:
+        """Get the status of a running or completed simulation.
+
+        Args:
+            session_id: The session ID returned by :meth:`start_run_simulation`.
+
+        Returns:
+            A dict containing ``sessionId``, ``status``, and optional
+            ``message``. ``status`` is one of the values defined in
+            :class:`comcheck_api.types.SimulationStatus`. Terminal
+            values are ``"SUCCESS"`` and ``"FAILED"``.
+
+        Raises:
+            COMCheckSimulationError: If the status cannot be retrieved.
+        """
+        status_response = self._service.get_simulation_status(session_id)
+        if status_response.data is None:
+            raise COMCheckSimulationError(
+                f"Failed to get simulation status for session {session_id}"
+            )
+        return status_response.data.model_dump(mode="json")
+
+    def get_simulation_result(self, session_id: str) -> Dict[str, Any]:
+        """Get the result metrics of a completed simulation.
+
+        Args:
+            session_id: The session ID returned by :meth:`start_run_simulation`.
+
+        Returns:
+            A dict containing ``sessionId``, ``performanceRating``,
+            ``energyCreditPerformanceRating``, ``proposedBpf``, and
+            ``baselineBpf``.
+
+        Raises:
+            COMCheckSimulationError: If the result cannot be retrieved.
+        """
+        result_response = self._service.get_simulation_result(session_id)
+        if result_response.data is None:
+            raise COMCheckSimulationError(
+                f"Failed to get simulation result for session {session_id}"
+            )
+        return result_response.data.model_dump(mode="python")
+
+    def close(self) -> None:
+        """Close the API service connection."""
+        if self._api_service is not None:
+            self._api_service.close()
+
+    def __enter__(self) -> "COMcheckClient":
+        """Context manager entry."""
+        return self
+
+    def __exit__(self, exc_type: Any, exc_val: Any, exc_tb: Any) -> None:
+        """Context manager exit."""
+        self.close()

comcheck_api/constants/building_area_constants.py

@@ -0,0 +1,35 @@
+"""Building area constants for COMcheck projects."""
+
+from uuid import uuid4
+
+from comcheck_api.types.core_types import WholeBldgUse
+
+# Default building area structure with interior lighting space
+DEFAULT_BUILDING_AREA: WholeBldgUse = WholeBldgUse.model_validate(
+    {
+        "key": str(uuid4()),
+        "wholeBldgType": "WHOLE_BUILDING_AUTOMOTIVE",  # TODO: wholeBldgType is a list of enum, need to define the enum type
+        "areaDescription": "Automotive Facility",
+        "constructionType": "NON_RESIDENTIAL",
+        "floorArea": 1000,
+        "internalLoad": 0,
+        "powerDensity": 0.71,  # TODO: power density is automatically calculated based on wholeBldgType
+        "isTenantSpace": False,  # TODO: space conditioning is a list of enum, need to define the enum type
+        "activityUse": [],
+        "interiorLightingSpace": {
+            "altExemptType": "EXEMPT_NOT_SET",
+            "description": "",
+            "numFixturesAlteredOrAdded": 0,
+            "postAltTotalWattage": 0,
+            "preAltNumberFixtures": 0,
+            "preAltTotalWattage": 0,
+            "allowanceType": None,
+            "exemptionType": None,
+            "allowanceFloorArea": 0,
+            "rcrFloorToWorkplaneHeight": 0,
+            "rcrPerimeter": 0,
+            "rcrWorkplaneToLuminaireHeight": 0,
+            "fixture": [],
+        },  # redundant data, but need it for backend call
+    }
+)

comcheck_api/constants/common_constants.py

@@ -0,0 +1,116 @@
+"""Default project template used to bootstrap new COMcheck projects.
+
+The :data:`PROJECT_TEMPLATE` constant is a fully validated :class:`ComBuilding`
+instance pre-populated with sensible defaults for all required sections
+(envelope, lighting, HVAC, location, etc.).
+"""
+
+from comcheck_api.types.core_types import ComBuilding
+
+PROJECT_TEMPLATE = ComBuilding.model_validate(
+    {
+        "control": {
+            "code": "CEZ_IECC2018",
+            "complianceMode": "UA",
+            "version": "",
+        },
+        "envelope": {
+            "useVltDetails": False,
+            "useCoolRoofPerformanceDetails": False,
+            "postAltWindowWallPct": None,
+            "postAltSkylightRoofPct": None,
+            "altPctGlazingAreaReplaced": None,
+            "altPctSkylightAreaReplaced": None,
+            "applyWindowPctAllowanceForDaylighting": False,
+            "applySkylightPctAllowanceForDaylighting": False,
+            "agWall": [],
+            "bgWall": [],
+            "roof": [],
+            "floor": [],
+            "door": [],
+            "window": [],
+            "skylight": [],
+            "useOrientDetails": True,
+            "airBarrierComplianceType": "AIR_BARRIER_OPTION_UNKNOWN",
+        },
+        "project": {
+            "projectTitle": "Default Project",
+            "projectPermitNumber": "",
+            "projectPermitDate": "",
+            "projectTaxMap": None,
+            "projectLotNumber": None,
+            "projectAddress": "",
+            "projectAddress2": None,
+            "projectCity": "",
+            "projectState": "",
+            "projectZipCode": "",
+            "projectComplete": None,
+            "ownerFirstName": "",
+            "ownerLastName": "",
+            "ownerCompany": "",
+            "ownerAddress": "",
+            "ownerAddress2": None,
+            "ownerCity": "",
+            "ownerState": "",
+            "ownerZipCode": "",
+            "ownerPhone": "",
+            "ownerEmail": "",
+            "developerFirstName": "",
+            "developerLastName": "",
+            "developerCompany": "",
+            "developerAddress": "",
+            "developerAddress2": None,
+            "developerCity": "",
+            "developerState": "",
+            "developerZipCode": "",
+            "developerPhone": "",
+            "developerEmail": "",
+            "notes": "",
+        },
+        "lighting": {
+            "exteriorLightingZoneType": "EXT_ZONE_UNSPECIFIED",
+            "exteriorUse": [],
+            "wholeBldgUse": [],
+            "fixtureSchedule": [],
+        },
+        "renewable": {
+            "renewableException": "RENEWABLE_ONSITE_EXCEPTION_NONE",
+            "numberOfFloors": 1,
+            "largestThreeFloorArea": 0,
+            "requiredCapacity": 0,
+            "proposedCapacity": 0,
+            "roofAreaForRenewable": 0,
+            "requiredOffsiteRenewableEnergy": 0,
+            "proposedOffsiteRenewableEnergy": 0,
+            "renewableSystem": [],
+            "offsiteRenewableProcurement": [],
+        },
+        "location": {"state": "Colorado", "city": "Boulder", "climateZone": 5},
+        "semiheated": None,
+        "hvac": {"hvacPlant": [], "hvacSystem": [], "fanSystem": []},
+        "swhSystem": [],
+        "requirements": [],
+        "isNonresidentialConditioning": True,
+        "isResidentialConditioning": False,
+        "isSemiheatedConditioning": False,
+        "isHistoricBuilding": False,
+        "feetBldgHeight": None,
+        "constructionType": "NONE",
+        "projectType": "NEW_CONSTRUCTION",
+        "projectSubType": "CONSTRUCTION_COMPLETE",
+        "projectMechanicalType": "PROJECT_HVAC_WITH_CENTRAL",
+        "projectCoreAndShellCredit": 0,
+        "efficiencyPackages": [],
+        "performanceRating": 0,
+        "energyCreditPerformanceRating": 0,
+        "buildingUseType": "ACTIVITY",
+        "conditioningType": "HEATING_AND_COOLING",
+        "heatingFuelType": "UNKNOWN_FUEL",
+        "userProject": None,
+        "allElectric": None,
+        "isRenewable": None,
+        "hasBattery": None,
+        "hasCharger": None,
+        "hasHeatPump": None,
+    }
+)