comcheck-api 1.0.0__py3-none-any.whl

comcheck_api/constants/envelope_constants.py

@@ -0,0 +1,250 @@
+"""Envelope constants for COMcheck projects."""
+
+from uuid import uuid4
+
+from comcheck_api.types.core_types import (
+    AgWall,
+    BgWall,
+    Door,
+    Envelope,
+    Floor,
+    Roof,
+    Skylight,
+    ThermalBridge,
+    Window,
+)
+from comcheck_api.utilities.common import get_random_number
+
+DEFAULT_WINDOW: Window = Window.model_validate(
+    {
+        "adjacentSpaceBuildingType": "WHOLE_BUILDING_OFFICE",
+        "adjacentSpaceType": "ADJACENT_SPACE_EXTERIOR",
+        "allowanceType": "ENV_ALLOWANCE_NONE",
+        "altExemptType": None,
+        "assemblyType": "Window:Default Window",
+        "bldgUseKey": str(uuid4()),
+        "constructionType": "NON_RESIDENTIAL",
+        "description": "",
+        "exemptionType": "ENV_EXEMPTION_NONE",
+        "frameType": "METAL",
+        "glazingMaterialType": "GLASS_GLAZING_MAT",
+        "glazingType": "TRIPLE_PANE",
+        "grossArea": 300,
+        "isSiteShading": False,
+        "orientation": "NORTH",
+        "perfDataType": "PERF_TYPE_NFRC",
+        "preAltPropShgc": 0.25,
+        "preAltPropUval": 0.35,
+        "productId": "WIN-001",
+        "productType": "FACTORY_ASSEMBLED_WINDOW",
+        "propProjectionFactor": 0.5,
+        "propShgc": 0.25,
+        "propUValue": 0.35,
+        "propVt": 0.65,
+        "solarType": "CLEAR",
+        "windowOpenType": "NON_OPERABLE_WINDOW",
+        "cavityRValue": 0,
+        "continuousRValue": 0,
+    }
+)
+
+DEFAULT_DOOR: Door = Door.model_validate(
+    {
+        "adjacentSpaceBuildingType": None,
+        "adjacentSpaceType": None,
+        "allowanceType": None,
+        "altExemptType": None,
+        "assemblyType": "Door:Default Door",
+        "bldgUseKey": str(uuid4()),
+        "cavityRValue": 0,
+        "continuousRValue": 0,
+        "constructionType": None,
+        "description": None,
+        "doorEntranceType": "ENTRANCE_DOOR",
+        "doorOpenType": "SWINGING_DOOR",
+        "doorType": "INSUL_METAL_DOOR",
+        "exemptionType": None,
+        "frameType": None,
+        "glazingMaterialType": None,
+        "glazingType": None,
+        "grossArea": 23,
+        "isSiteShading": None,
+        "orientation": "UNSPECIFIED_ORIENTATION",
+        "perfDataType": None,
+        "preAltPropShgc": 0,
+        "preAltPropUval": None,
+        "productId": None,
+        "productType": None,
+        "propProjectionFactor": 0,
+        "propShgc": 0,
+        "propUValue": 0.37,
+        "propVt": None,
+        "solarType": None,
+    }
+)
+
+DEFAULT_SKYLIGHT: Skylight = Skylight.model_validate(
+    {
+        "adjacentSpaceType": None,
+        "allowanceType": None,
+        "assemblyType": "Skylight:Default Skylight",
+        "bldgUseKey": "",
+        "curbType": "NO_CURB_SKYLIGHT",
+        "description": "",
+        "exemptionType": None,
+        "frameType": "METAL",
+        "glazingMaterialType": "GLASS_GLAZING_MAT",
+        "glazingType": "DOUBLE_PANE_LOWE",
+        "grossArea": 100,
+        "isSiteShading": None,
+        "orientation": "UNSPECIFIED_ORIENTATION",
+        "perfDataType": None,
+        "preAltPropShgc": 0,
+        "productId": None,
+        "productType": None,
+        "propProjectionFactor": 0,
+        "propShgc": 0.6,
+        "propUValue": 0.55,
+        "propVt": None,
+        "solarType": "TINTED",
+    }
+)
+
+DEFAULT_ROOF: Roof = Roof.model_validate(
+    {
+        "adjacentSpaceType": None,
+        "allowanceType": None,
+        "assemblyType": "Roof:Default Roof",
+        "bldgUseKey": str(uuid4()),
+        "cavityRValue": 0,
+        "continuousRValue": 37,
+        "description": "",
+        "exemptionType": None,
+        "grossArea": 6000,
+        "highAlbedoRoofReqType": "HA_ROOF_EXEMPTION_VEGETATED",
+        "orientation": "UNSPECIFIED_ORIENTATION",
+        "propUValue": 0.26,
+        "purlinSpacing": 0,
+        "roofInsulType": None,
+        "roofType": "ABOVE_DECK_ROOF",
+        "skylight": [],
+        "solarReflectance": 0,
+        "solarReflectanceIndex": 0,
+        "thermalEmittance": 0,
+    }
+)
+
+DEFAULT_FLOOR: Floor = Floor.model_validate(
+    {
+        "adjacentSpaceType": None,
+        "allowanceType": None,
+        "altExemptType": None,
+        "assemblyType": "Floor:Default Floor",
+        "bldgUseKey": str(uuid4()),
+        "cavityRValue": 0,
+        "constructionType": None,
+        "continuousRValue": 15,
+        "depthOfInsulation": 4,
+        "description": "",
+        "exemptionType": None,
+        "floorExposedFrameType": None,
+        "floorType": "HEATED_SLAB_ON_GRADE",
+        "grossArea": 320,
+        "hasEdgeInsul": None,
+        "insulationPosition": "VERTICAL",
+        "orientation": "UNSPECIFIED_ORIENTATION",
+        "propUValue": 0.72,
+        "slabFullInsulBelowMinRValue": 0,
+    }
+)
+
+DEFAULT_AG_WALL: AgWall = AgWall.model_validate(
+    {
+        "adjacentSpaceType": None,
+        "agWallConstructionDetailsType": "NONE",
+        "agWallExteriorFinishDetailsType": None,
+        "allowanceType": None,
+        "assemblyType": "Ext Wall:Default Exterior Wall",
+        "bldgUseKey": str(uuid4()),
+        "cavityRValue": 20,
+        "cmuType": None,
+        "concreteDensity": 0,
+        "concreteThickness": 0,
+        "continuousRValue": 10,
+        "description": "",
+        "door": [],
+        "effectiveUFactor": 0.054,
+        "exemptionType": None,
+        "furringType": None,
+        "grossArea": 4800,
+        "heatCapacity": 0,
+        "insulationPosition": None,
+        "nextToUncondSpace": None,
+        "orientation": "NORTH",
+        "otherWallType": "NONE",
+        "propUValue": 0.048,
+        "thermalBridge": [],
+        "thermalBridgeAdjustmentFactor": None,
+        "thermalBridgeExceptionType": "THERMAL_BRIDGE_EXCEPTION_NONE",
+        "wallType": "METAL_FRAME_24_AG_WALL",
+        "window": [],
+    }
+)
+
+DEFAULT_THERMAL_BRIDGE: ThermalBridge = ThermalBridge.model_validate(
+    {
+        "chiFactor": 0,
+        "id": get_random_number(),
+        "numberOfPoints": 0,
+        "psiFactor": 0.177,
+        "thermalBridgeCategory": "THERMAL_BRIDGE_LINEAR",
+        "thermalBridgeComplianceType": "THERMAL_BRIDGE_PRESCRIPTIVE",
+        "thermalBridgeLength": 100,
+        "thermalBridgeType": "THERMAL_BRIDGE_FLOOR_TO_WALL_INTERSECTION",
+    }
+)
+
+DEFAULT_BG_WALL: BgWall = BgWall.model_validate(
+    {
+        "adjacentSpaceBuildingType": None,
+        "adjacentSpaceType": None,
+        "allowanceType": None,
+        "altExemptType": None,
+        "assemblyType": "Basement:Default Basement",
+        "bldgUseKey": "",
+        "cavityRValue": 20,
+        "cmuType": None,
+        "concreteDensity": 95,  # TODO: Generated value
+        "concreteThickness": 6,  # TODO: Generated value, type is not correct in coreTypes
+        "constructionType": None,
+        "continuousRValue": 10,
+        "description": "",
+        "door": [],
+        "exemptionType": None,
+        "furringType": "WOOD_FURRING",
+        "grossArea": 3000,
+        "heatCapacity": 0,
+        "insulationPosition": None,
+        "orientation": "NORTH",
+        "propUValue": 0.037,
+        "wallHeight": 9,
+        "wallHeightBelowGrade": 6,
+        "wallType": "CONCRETE_BG_WALL",
+        "window": [],
+    }
+)
+
+DEFAULT_ENVELOPE: Envelope = Envelope(
+    agWall=[], bgWall=[], roof=[], floor=[], door=[], window=[], skylight=[]
+)
+
+# TODO: add values to other assemblies
+DEFAULT_ASSEMBLIES = {
+    "Window": DEFAULT_WINDOW,
+    "Roof": DEFAULT_ROOF,
+    "Skylight": DEFAULT_SKYLIGHT,
+    "AgWall": DEFAULT_AG_WALL,
+    "BgWall": DEFAULT_BG_WALL,
+    "Door": DEFAULT_DOOR,
+    "Floor": DEFAULT_FLOOR,
+}

comcheck_api/defaults.py

@@ -0,0 +1,150 @@
+"""Module for project default templates/values."""
+
+import copy
+
+from comcheck_api.constants.building_area_constants import DEFAULT_BUILDING_AREA
+from comcheck_api.constants.envelope_constants import (
+    DEFAULT_AG_WALL,
+    DEFAULT_BG_WALL,
+    DEFAULT_DOOR,
+    DEFAULT_FLOOR,
+    DEFAULT_ROOF,
+    DEFAULT_SKYLIGHT,
+    DEFAULT_THERMAL_BRIDGE,
+    DEFAULT_WINDOW,
+)
+
+from comcheck_api.constants.common_constants import PROJECT_TEMPLATE
+
+# from comcheck_api.constants.lighting_constants import DEFAULT_FIXTURE_SCHEDULE
+
+
+def get_default_project_template():
+    """Return a deep copy of the default :class:`~comcheck_api.types.core_types.ComBuilding` template.
+
+    The template is pre-populated with sensible defaults for location
+    (Boulder, CO), envelope, lighting, HVAC, and other required sections.
+
+    Returns:
+        A new ``ComBuilding`` instance ready to be customized.
+    """
+    return copy.deepcopy(PROJECT_TEMPLATE)
+
+
+def get_default_building_area_template():
+    """Return a deep copy of the default :class:`~comcheck_api.types.core_types.WholeBldgUse` template.
+
+    Defaults to an *Automotive Facility* with 1 000 sq ft floor area
+    and interior lighting space initialized.
+
+    Returns:
+        A new ``WholeBldgUse`` instance.
+    """
+    return copy.deepcopy(DEFAULT_BUILDING_AREA)
+
+
+def get_default_roof_template():
+    """Return a deep copy of the default :class:`~comcheck_api.types.core_types.Roof` template.
+
+    Defaults to an above-deck roof with 6 000 sq ft gross area and
+    R-37 continuous insulation.
+
+    Returns:
+        A new ``Roof`` instance.
+    """
+    return copy.deepcopy(DEFAULT_ROOF)
+
+
+def get_default_ag_wall_template():
+    """Return a deep copy of the default :class:`~comcheck_api.types.core_types.AgWall` template.
+
+    Defaults to a metal-frame 24-inch above-grade wall with 4 800 sq ft
+    gross area, R-20 cavity / R-10 continuous insulation.
+
+    Returns:
+        A new ``AgWall`` instance.
+    """
+    return copy.deepcopy(DEFAULT_AG_WALL)
+
+
+def get_default_floor_template():
+    """Return a deep copy of the default :class:`~comcheck_api.types.core_types.Floor` template.
+
+    Defaults to a heated slab-on-grade floor with 320 sq ft gross area
+    and R-15 continuous insulation.
+
+    Returns:
+        A new ``Floor`` instance.
+    """
+    return copy.deepcopy(DEFAULT_FLOOR)
+
+
+def get_default_bg_wall_template():
+    """Return a deep copy of the default :class:`~comcheck_api.types.core_types.BgWall` template.
+
+    Defaults to a concrete below-grade wall with 3 000 sq ft gross area,
+    R-20 cavity / R-10 continuous insulation, and wood furring.
+
+    Returns:
+        A new ``BgWall`` instance.
+    """
+    return copy.deepcopy(DEFAULT_BG_WALL)
+
+
+def get_default_skylight_template():
+    """Return a deep copy of the default :class:`~comcheck_api.types.core_types.Skylight` template.
+
+    Defaults to a no-curb, double-pane low-E skylight with 100 sq ft
+    gross area.
+
+    Returns:
+        A new ``Skylight`` instance.
+    """
+    return copy.deepcopy(DEFAULT_SKYLIGHT)
+
+
+def get_default_window_template():
+    """Return a deep copy of the default :class:`~comcheck_api.types.core_types.Window` template.
+
+    Defaults to a triple-pane, non-operable, metal-frame window with
+    300 sq ft gross area and NFRC performance data.
+
+    Returns:
+        A new ``Window`` instance.
+    """
+    return copy.deepcopy(DEFAULT_WINDOW)
+
+
+def get_default_door_template():
+    """Return a deep copy of the default :class:`~comcheck_api.types.core_types.Door` template.
+
+    Defaults to a swinging, insulated metal entrance door with 23 sq ft
+    gross area.
+
+    Returns:
+        A new ``Door`` instance.
+    """
+    return copy.deepcopy(DEFAULT_DOOR)
+
+
+def get_default_thermal_bridge_template():
+    """Return a deep copy of the default :class:`~comcheck_api.types.core_types.ThermalBridge` template.
+
+    Defaults to a prescriptive linear floor-to-wall intersection thermal
+    bridge with a psi factor of 0.177 and 100 ft length.
+
+    Returns:
+        A new ``ThermalBridge`` instance.
+    """
+    return copy.deepcopy(DEFAULT_THERMAL_BRIDGE)
+
+
+def get_default_fixture_schedule_template():
+    """Return a default fixture schedule template with a unique key.
+
+    .. warning::
+        Not yet implemented — raises :exc:`NotImplementedError`.
+    """
+    # TODO: Implement when DEFAULT_FIXTURE_SCHEDULE constant is available
+    # return {**DEFAULT_FIXTURE_SCHEDULE, "scheduleFixtureKey": str(uuid4())}
+    raise NotImplementedError("DEFAULT_FIXTURE_SCHEDULE constant not yet implemented")

comcheck_api/exceptions.py

@@ -0,0 +1,54 @@
+"""Custom exceptions for COMcheck API client."""
+
+
+class COMCheckAPIError(Exception):
+    """Base exception for COMcheck API errors."""
+
+    pass
+
+
+class COMCheckHTTPError(COMCheckAPIError):
+    """HTTP request failed."""
+
+    def __init__(self, status_code: int, message: str, response_data: str = ""):
+        """Initialize with the HTTP status code, message, and optional response body.
+
+        Args:
+            status_code: The HTTP status code returned by the API.
+            message: Human-readable error description.
+            response_data: Raw response body text (empty string if unavailable).
+        """
+        self.status_code = status_code
+        self.response_data = response_data
+        super().__init__(f"HTTP {status_code}: {message}")
+
+
+class COMCheckValidationError(COMCheckAPIError):
+    """Raised when request or response data fails Pydantic or schema validation."""
+
+    pass
+
+
+class COMCheckConnectionError(COMCheckAPIError):
+    """Raised when the HTTP client cannot reach the COMcheck API server."""
+
+    pass
+
+
+class COMCheckSimulationError(COMCheckAPIError):
+    """Raised when a simulation request fails or returns unexpected data."""
+
+    pass
+
+
+class COMCheckProjectNotFoundError(COMCheckAPIError):
+    """Project not found."""
+
+    def __init__(self, project_id: str):
+        """Initialize with the ID of the project that was not found.
+
+        Args:
+            project_id: The project ID that could not be located.
+        """
+        self.project_id = project_id
+        super().__init__(f"Project with ID '{project_id}' not found")

comcheck_api/introspection.py

@@ -0,0 +1,188 @@
+"""Introspection helpers over the installed SDK.
+
+Discoverable from the package root:
+
+    >>> from comcheck_api import list_operations, lookup_type
+    >>> ops = list_operations()
+    >>> schema = lookup_type("ComBuilding")
+
+``list_operations`` enumerates the public functions in the project
+operation modules. ``lookup_type`` reflects a Pydantic model or enum
+from :mod:`comcheck_api.types`. Both return Pydantic models with
+typed fields so IDEs and type checkers can see the shape.
+"""
+
+from __future__ import annotations
+
+import inspect
+from typing import Any, Literal, get_args, get_origin
+
+import pydantic
+from pydantic import BaseModel, ConfigDict
+
+from comcheck_api import (
+    project_building_area_operations,
+    project_envelope_operations,
+)
+
+_OP_MODULES = {
+    "building_area": project_building_area_operations,
+    "envelope": project_envelope_operations,
+}
+
+
+class OperationInfo(BaseModel):
+    """One public function in a project-operation module."""
+
+    group: str
+    module: str
+    name: str
+    signature: str
+    summary: str
+
+
+class FieldSchema(BaseModel):
+    """One field of a Pydantic model."""
+
+    model_config = ConfigDict(arbitrary_types_allowed=True)
+
+    name: str
+    type: str
+    required: bool
+    default: Any | None
+    description: str
+
+
+class EnumMember(BaseModel):
+    name: str
+    value: str
+
+
+class TypeSchema(BaseModel):
+    """Reflected schema of a Pydantic model or StrEnum."""
+
+    name: str
+    kind: Literal["model", "enum"]
+    doc: str
+    fields: list[FieldSchema] = []
+    members: list[EnumMember] = []
+
+
+def list_operations() -> list[OperationInfo]:
+    """Discover public functions in the project operation modules.
+
+    Discovered live via :mod:`inspect` so the list always matches the
+    installed SDK version.
+    """
+    out: list[OperationInfo] = []
+    for group, mod in _OP_MODULES.items():
+        for name, fn in inspect.getmembers(mod, inspect.isfunction):
+            if name.startswith("_"):
+                continue
+            if fn.__module__ != mod.__name__:
+                continue  # skip re-exports
+            doc = inspect.getdoc(fn) or ""
+            summary = doc.split("\n", 1)[0]
+            out.append(
+                OperationInfo(
+                    group=group,
+                    module=fn.__module__,
+                    name=name,
+                    signature=f"{name}{inspect.signature(fn)}",
+                    summary=summary,
+                )
+            )
+    return out
+
+
+def lookup_type(name: str) -> TypeSchema | None:
+    """Reflect a Pydantic model or enum from :mod:`comcheck_api.types`.
+
+    Returns ``None`` if no matching type is found. Lookup is
+    case-insensitive as a fallback.
+    """
+    from comcheck_api import types as cc_types
+
+    obj = getattr(cc_types, name, None)
+    if obj is None:
+        lower = name.lower()
+        for cand in dir(cc_types):
+            if cand.lower() == lower:
+                obj = getattr(cc_types, cand)
+                name = cand
+                break
+
+    if obj is None:
+        return None
+
+    if isinstance(obj, type) and issubclass(obj, pydantic.BaseModel):
+        return _describe_model(name, obj)
+
+    if isinstance(obj, type):
+        members = [
+            EnumMember(name=member.name, value=str(member.value))
+            for member in getattr(obj, "__members__", {}).values()
+        ]
+        if members:
+            return TypeSchema(
+                name=name,
+                kind="enum",
+                doc=inspect.getdoc(obj) or "",
+                members=members,
+            )
+
+    return None
+
+
+def _describe_model(name: str, model: type[pydantic.BaseModel]) -> TypeSchema:
+    fields = [
+        FieldSchema(
+            name=fname,
+            type=_render_type(finfo.annotation),
+            required=finfo.is_required(),
+            default=_render_default(finfo),
+            description=finfo.description or "",
+        )
+        for fname, finfo in model.model_fields.items()
+    ]
+    return TypeSchema(
+        name=name,
+        kind="model",
+        doc=inspect.getdoc(model) or "",
+        fields=fields,
+    )
+
+
+def _render_type(annotation: Any) -> str:
+    if annotation is None or annotation is type(None):
+        return "None"
+    origin = get_origin(annotation)
+    if origin is None:
+        return getattr(annotation, "__name__", str(annotation))
+    args = ", ".join(_render_type(a) for a in get_args(annotation))
+    origin_name = getattr(origin, "__name__", str(origin))
+    return f"{origin_name}[{args}]"
+
+
+def _render_default(finfo: pydantic.fields.FieldInfo) -> Any:
+    if finfo.is_required():
+        return None
+    default = finfo.default
+    if default is pydantic.fields.PydanticUndefined:
+        return None
+    try:
+        if isinstance(default, pydantic.BaseModel):
+            return default.model_dump(mode="json")
+        return default
+    except Exception:  # noqa: BLE001
+        return repr(default)
+
+
+__all__ = [
+    "OperationInfo",
+    "FieldSchema",
+    "EnumMember",
+    "TypeSchema",
+    "list_operations",
+    "lookup_type",
+]

comcheck_api/managers/components/building_area.py

@@ -0,0 +1,11 @@
+"""Building area list manager for COMcheck projects."""
+
+from typing import Any
+
+from comcheck_api.types.core_types import WholeBldgUse
+from comcheck_api.managers.data_manager import DataManager
+
+
+class BuildingAreaListManager(DataManager[WholeBldgUse]):
+    """Manager for WholeBldgUse (building area) items."""
+    model_type = WholeBldgUse