infrared-sdk 0.4.0__tar.gz

infrared_sdk-0.4.0/.env.example

@@ -0,0 +1,2 @@
+INFRARED_API_KEY="your_api_key_here"
+INFRARED_BASE_URL="https://api.infrared.city"

infrared_sdk-0.4.0/.github/CODEOWNERS

@@ -0,0 +1 @@
+* @Infrared-city/sdk-maintainers

infrared_sdk-0.4.0/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,54 @@
+name: Bug Report
+description: Report a bug in the Infrared SDK
+labels: ["bug"]
+body:
+  - type: input
+    id: sdk-version
+    attributes:
+      label: SDK Version
+      placeholder: "0.2.0"
+    validations:
+      required: true
+  - type: input
+    id: python-version
+    attributes:
+      label: Python Version
+      placeholder: "3.12"
+    validations:
+      required: true
+  - type: input
+    id: os
+    attributes:
+      label: Operating System
+      placeholder: "macOS 15, Ubuntu 24.04, Windows 11"
+    validations:
+      required: true
+  - type: textarea
+    id: description
+    attributes:
+      label: Description
+      description: What happened?
+    validations:
+      required: true
+  - type: textarea
+    id: steps
+    attributes:
+      label: Steps to Reproduce
+      description: Minimal code or steps to reproduce the issue.
+      render: python
+    validations:
+      required: true
+  - type: textarea
+    id: expected
+    attributes:
+      label: Expected Behavior
+      description: What did you expect to happen?
+    validations:
+      required: true
+  - type: textarea
+    id: actual
+    attributes:
+      label: Actual Behavior
+      description: What actually happened? Include error messages or tracebacks.
+    validations:
+      required: true

infrared_sdk-0.4.0/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,5 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Questions & Discussions
+    url: https://github.com/Infrared-city/infrared-sdk-python/discussions
+    about: Ask questions and discuss ideas

infrared_sdk-0.4.0/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,25 @@
+name: Feature Request
+description: Suggest a new feature or improvement
+labels: ["enhancement"]
+body:
+  - type: textarea
+    id: use-case
+    attributes:
+      label: Use Case
+      description: What problem are you trying to solve?
+    validations:
+      required: true
+  - type: textarea
+    id: proposed-solution
+    attributes:
+      label: Proposed Solution
+      description: How would you like this to work?
+    validations:
+      required: true
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives Considered
+      description: What workarounds or alternatives have you tried?
+    validations:
+      required: false

infrared_sdk-0.4.0/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,10 @@
+## Summary
+
+<!-- Brief description of the changes -->
+
+## Checklist
+
+- [ ] Tests added/updated
+- [ ] `ruff check .` and `ruff format --check .` pass
+- [ ] `mypy src/infrared_sdk/` passes
+- [ ] CHANGELOG.md updated under `[Unreleased]`

infrared_sdk-0.4.0/.github/workflows/ci.yml

@@ -0,0 +1,42 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v4
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: uv sync --group dev
+      - run: uv run pytest --cov=infrared_sdk -v
+
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v4
+        with:
+          python-version: "3.13"
+      - run: uv sync --group dev
+      - run: uv run ruff check .
+      - run: uv run ruff format --check .
+
+  typecheck:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v4
+        with:
+          python-version: "3.13"
+      - run: uv sync --group dev
+      - run: uv run pyright src/infrared_sdk/

infrared_sdk-0.4.0/.github/workflows/publish.yml

@@ -0,0 +1,21 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - "v*"
+
+permissions:
+  id-token: write
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v4
+        with:
+          python-version: "3.13"
+      - run: uv build
+      - uses: pypa/gh-action-pypi-publish@release/v1

infrared_sdk-0.4.0/.github/workflows/pypi-publish.yml

@@ -0,0 +1,50 @@
+name: Upload to PyPI
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  release-build:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v8.0.0
+
+      - name: Build release distributions
+        run: uv build
+
+      - name: Upload distributions
+        uses: actions/upload-artifact@v7
+        with:
+          name: release-dists
+          path: dist/
+
+  pypi-publish:
+    runs-on: ubuntu-latest
+    needs:
+      - release-build
+    permissions:
+      id-token: write
+
+    environment:
+      name: pypi
+
+    steps:
+      - name: Retrieve release distributions
+        uses: actions/download-artifact@v8
+        with:
+          name: release-dists
+          path: dist/
+
+      - name: Publish release distributions to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          packages-dir: dist/

infrared_sdk-0.4.0/.github/workflows/pypi-test-publish.yml

@@ -0,0 +1,49 @@
+name: Upload to TestPyPI
+
+on:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  release-build:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v8.0.0
+
+      - name: Build release distributions
+        run: uv build
+
+      - name: Upload distributions
+        uses: actions/upload-artifact@v7
+        with:
+          name: release-dists
+          path: dist/
+
+  testpypi-publish:
+    runs-on: ubuntu-latest
+    needs:
+      - release-build
+    permissions:
+      id-token: write
+
+    environment:
+      name: testpypi
+
+    steps:
+      - name: Retrieve release distributions
+        uses: actions/download-artifact@v8
+        with:
+          name: release-dists
+          path: dist/
+
+      - name: Publish release distributions to TestPyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          repository-url: https://test.pypi.org/legacy/
+          packages-dir: dist/

infrared_sdk-0.4.0/.gitignore

@@ -0,0 +1,234 @@
+# Created by https://gitignore.org
+# Python.gitignore
+
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[codz]
+*$py.class
+
+# C extensions
+*.so
+
+.flow
+.claude
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#   Usually these files are written by a python script from a template
+#   before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py.cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+model_payloads/*
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+# Pipfile.lock
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+# uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+# poetry.lock
+# poetry.toml
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#   pdm recommends including project-wide configuration in pdm.toml, but excluding .pdm-python.
+#   https://pdm-project.org/en/latest/usage/project/#working-with-version-control
+# pdm.lock
+# pdm.toml
+.pdm-python
+.pdm-build/
+
+# pixi
+#   Similar to Pipfile.lock, it is generally recommended to include pixi.lock in version control.
+# pixi.lock
+#   Pixi creates a virtual environment in the .pixi directory, just like venv module creates one
+#   in the .venv directory. It is recommended not to include this directory in version control.
+.pixi
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# Redis
+*.rdb
+*.aof
+*.pid
+
+# RabbitMQ
+mnesia/
+rabbitmq/
+rabbitmq-data/
+
+# ActiveMQ
+activemq-data/
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.envrc
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#   JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#   be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#   and can be added to the global gitignore or merged into this file.  For a more nuclear
+#   option (not recommended) you can uncomment the following to ignore the entire idea folder.
+# .idea/
+
+# Abstra
+#   Abstra is an AI-powered process automation framework.
+#   Ignore directories containing user credentials, local state, and settings.
+#   Learn more at https://abstra.io/docs
+.abstra/
+
+# Visual Studio Code
+#   Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore 
+#   that can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
+#   and can be added to the global gitignore or merged into this file. However, if you prefer, 
+#   you could uncomment the following to ignore the entire vscode folder
+# .vscode/
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+# Marimo
+marimo/_static/
+marimo/_lsp/
+__marimo__/
+
+# Streamlit
+.streamlit/secrets.toml
+
+.DS_Store
+.osgrep/
+.osgrep
+demo.db
+demo.db-*
+demos/areas_demo_async/outputs/
+demos/areas_demo_async/cache/
+demos/*.html
+public-demos/_outputs_*/

infrared_sdk-0.4.0/.pre-commit-config.yaml

@@ -0,0 +1,18 @@
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v5.0.0
+    hooks:
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: check-yaml
+      - id: check-toml
+      - id: check-added-large-files
+        args: ["--maxkb=500"]
+      - id: debug-statements
+
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.11.6
+    hooks:
+      - id: ruff
+        args: [--fix]
+      - id: ruff-format

infrared_sdk-0.4.0/.vscode/settings.json

@@ -0,0 +1,14 @@
+{
+    "python.testing.pytestArgs": [
+        "tests"
+    ],
+    "python.testing.unittestEnabled": false,
+    "python.testing.pytestEnabled": true,
+    "python-envs.pythonProjects": [
+        {
+            "path": ".",
+            "envManager": "ms-python.python:venv",
+            "packageManager": "ms-python.python:pip"
+        }
+    ]
+}

infrared_sdk-0.4.0/CHANGELOG.md

@@ -0,0 +1,93 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.4.0] - 2026-04-29
+
+### Breaking
+- `DEFAULT_BASE_URL` is now `https://api.infrared.city/v2` (was `https://api.infrared.city`). The previous default returned `403 {"message":"Forbidden"}` on every call because the AWS API Gateway custom domain `api.infrared.city` only has `/v2`, `/v1`, and `/v1.1` base-path mappings — there is no no-prefix mapping. Users who pinned the old default explicitly (constructor arg or `INFRARED_BASE_URL` env var) need to add `/v2`; users who relied on the default are unaffected (silently changes from "always 403" to "works"). The `/v2` mapping points at the production REST API; `/v1` and `/v1.1` continue to route to the older API for callers that explicitly opt in. (#98)
+- `merge_area_jobs` (and therefore `run_area_and_wait`) now raises a new `AreaRunError` when every job in an area run terminates without producing a usable tile. Previously it returned an `AreaResult` with `succeeded_jobs=0` and an all-NaN merged grid — visually indistinguishable from a successful run unless the caller manually inspected `succeeded_jobs`. Callers that did not check `succeeded_jobs` will see exceptions in this scenario; wrap calls in `try ... except AreaRunError` to handle. Partial failures (≥1 success + ≥N failures) still return an `AreaResult` so callers don't lose the data they did get; jobs still pending also still return a result. The exception carries `failed_jobs`, `skipped_jobs`, `total_jobs`. The "no usable output" gate covers four paths: every job's server status was Failed; every download permanently errored; every grid was the wrong shape; every grid extractor raised. (#95)
+
+### Added
+- `AreaRunError` exception — exported from the top-level package alongside `AreaTimeoutError` and `TiledRunError`. (#95)
+- `AreaBuildings.failed_tiles: list[dict]` — partial-tile failures from `client.buildings.get_area(...)` are now surfaced on the returned object (each entry: `tile_id`, `row`, `col`, `error`). Empty list when every tile succeeded. The pre-existing log warning is unchanged. Same structural fix is recommended for `AreaVegetation` / `AreaGroundMaterials` next; tracked separately. (#95)
+
+### Fixed
+- README weather example: replaced the obsolete `{"identifier": ..., "name": ...}` station-dict shape with the actual response (`uuid`, `fileName`, `location_data`) and updated the `filter_weather_data(identifier=locations[0]["uuid"], ...)` call accordingly. (#95)
+- README quick-start examples for UTCI / TCS / PWC switched from a multi-month `TimePeriod` (which currently fails server-side with `DNI length 828 != sun_vectors 270`) to single-month windows that round-trip cleanly. Each affected snippet has a callout explaining the constraint. (#97)
+- README Output Reference and AreaResult sections gained a `None`-fallback note for `min_legend` / `max_legend` — the API does not currently emit these for any analysis, so naive `zmin=result.min_legend` plotting passes `None` to matplotlib/Plotly. Snippets now use `np.nanmin/np.nanmax(merged_grid)` as the fallback. (#97)
+- README `Error Handling` section now lists `AreaRunError`, `AreaTimeoutError`, and `TiledRunError` alongside the job-level error table; previously these area-level exceptions had no documented surface despite being raisable from the headline `run_area_and_wait` example. (#95)
+- README "Install from source" block removed (referenced the private SDK source repo). `CONTRIBUTING.md` removed entirely (private repo, no external contributors). (#99, follow-ups)
+
+### CI / dev infrastructure
+- CI pipeline finally green: `ruff check`, `ruff format --check`, `pyright`, and `pytest --cov` all pass on Python 3.11/3.12/3.13. Previously every PR for ~3 days landed on a red pipeline (both v0.3.0 and v0.3.1 release merges shipped on red CI). Causes were structural lint debt (`E402` in `buildings/service.py`), 37 files drifted from the formatter, missing dev deps (`pytest-cov`), and the workflow calling `mypy` while the project configures `pyright`. (#102)
+- `pytest-cov>=5.0` added to the `dev` dependency group.
+- Workflow typecheck step switched from `mypy` to `pyright` to match the configured tool.
+- Latent pyright errors fixed by widening 7 over-narrow signatures in `_area/_submission.py` and `tiling/tiles.py` (no behaviour change).
+
+## [0.3.1] - 2026-04-29
+
+### Added
+- `infrared_sdk.preflight.estimate_sun_context_loss(...)` — client-side pre-flight check that flags `direct-sun-hours` / daylight / solar / thermal-comfort configurations whose low-sun shadows exceed the per-tile geometry buffer. Returns a `SunContextResult` (`info` / `ok` / `marginal` / `warning` / `critical`) with a human-readable message. Pure math; no API calls; never raises (`#86`).
+- `CLAUDE.md` — onboarding guide for AI assistants and human contributors covering repo layout, branching, conventions, and the PyPI release recipe.
+
+### Fixed
+- README: cookbook notebook URLs now point at `cookbook/notebooks/` in `Infrared-city/infrared-skills` (previously 404'd at the repo root) (#90).
+- README: top-of-file link bar to https://infrared.city/docs/sdk/, the skills repo, and the knowledge base. Dropped CI badge that pointed at a non-existent repo (#92).
+
+## [0.3.0] - 2026-04-28
+
+### Added
+- `TimePeriod` now validates calendar inputs: end-before-start, zero-length windows, and impossible day-of-month combinations (April 31, February 30, June 31, September 31, November 31) raise `ValidationError`. February 29 is accepted because `TimePeriod` carries no year context. Year-wrap windows (e.g. Nov→Feb) are not supported — split them into two periods.
+- Typed exception hierarchy mirrored across service clients: `WeatherServiceError`, `BuildingsServiceError`, plus subclasses, and the `JobsServiceClient` hierarchy under `InfraredJobError` (#79). Response bodies live on `.response_body`, kept out of `args[0]` so they are not captured in default error-tracking message fields.
+- HTTP timeouts on every outbound call across the 5 service clients (`(10, 300)` for control plane, `(10, 600)` for S3 downloads) (#79).
+- `Retry-After` header is honored across the area orchestration path (submission, polling, result download) — when present on a 429/503, the SDK sleeps for the advertised duration instead of using jittered backoff. The header value is propagated through the typed exception hierarchy (`JobSubmitError.retry_after`, `JobPollError.retry_after`, `ResultsDownloadError.retry_after`) so the area path retries against the typed exceptions it actually catches. HTTP-date format is intentionally not parsed; only delta-seconds are honored.
+
+### Changed
+- **Breaking**: `AreaState.from_job_states({})` now returns status `"empty"` instead of `"completed"`. Code that branches on `state.status == "completed"` for empty schedules will silently stop matching (#76). Migrate to either `state.is_complete` or `state.status in {"completed", "empty"}`.
+- **Breaking**: error response bodies that previously could be reached via `exc.args[1]` now live exclusively on the typed `.response_body` attribute (#79).
+- `AreaSchedule.jobs` is now a frozen `MappingProxyType` rather than a mutable dict. Direct mutation raises `TypeError`; rebuild a new schedule instead (#76).
+- `TilingConfig.from_dict()` tolerates unknown keys, so newer configs from the server roll forward without breaking older clients (#78).
+- `api_key` is wrapped in a `pydantic.SecretStr` to prevent plaintext leakage in logs and repr output (#72).
+
+### Fixed
+- Continent-scale polygons are pre-capped before tile materialization to avoid OOM (#75).
+- Numpy polygon coordinates are canonicalized for dtype-stable tile IDs across float32/float64 inputs (#77).
+- Zero-area polygons now raise `PolygonValidationError` instead of producing empty schedules silently (#74).
+- `"nan"` strings in API responses are coerced to `None` rather than producing string fields where floats are expected (#74).
+- `AreaResult.to_dict()` always emits `min_legend` and `max_legend` keys (set to `None` when no legend bounds are available) for stable downstream consumers (#73).
+
+### Known limitations
+- 100k-vertex polygons hit an O(n²) self-intersection check that can hang. Batch polygons through a simplifier first or split into smaller pieces. A sweep-line replacement is on the v0.3.x backlog.
+
+## [0.2.0] - 2025-04-15
+
+### Added
+- Area orchestration API (`run_area`, `run_area_multi`, `run_area_and_wait`) for multi-tile polygon analysis
+- Automatic polygon tiling with 512m tiles and 256m overlap blending
+- `get_buildings_in_area()` for fetching, deduplicating, and transforming buildings across tiles
+- Model-grouped tiling configuration for wind and solar analyses
+- `gen_grid_image()` parameters: `analysis_type`, `criteria`, `subtype`
+- Python 3.11 support with strict type checking
+- Vegetation and ground materials pipeline (fetch, dedup, tile assignment)
+- `x-infrared-application: sdk` header on all API requests
+
+### Fixed
+- Type errors for Python 3.11 strict type checking
+- Single-line f-strings for Python 3.11 compatibility
+
+## [0.1.0] - 2024-12-01
+
+### Added
+- Core analysis types: wind speed, pedestrian wind comfort, daylight availability, direct sun hours, sky view factors, solar radiation, thermal comfort index, thermal comfort statistics
+- Async job system with exponential backoff polling
+- Webhook integration for job status notifications
+- Buildings API with DotBim, GeoJSON, and Mesh output formats
+- Weather data API (search stations, fetch data, filter by time period)
+- Grid image generation utility
+- Context manager support for HTTP session lifecycle