hero-sdk 0.14.0__tar.gz

hero_sdk-0.14.0/.github/workflows/docs.yml

@@ -0,0 +1,68 @@
+# This workflow will publish pdoc to Github Pages on each published release
+
+# How it works:
+# This workflow runs pdoc.sh which generates the documentation
+# The static documentation pages gets bundled up into an artifact as a tarball
+# In the deploy phase the artifact gets uploaded to Github Pages
+
+name: pdoc to Github Pages
+
+# build the documentation whenever a pull request is made
+# on:
+#     pull_request:
+
+# build the documentation whenever there are new commits on main
+# on:
+    # push:
+    #   branches:
+        # - main
+      # Alternative: only build for tags.
+      # tags:
+      #   - '*'
+
+# build the documentation whenever a release is created, edited, or published
+on:
+  push:
+    branches:
+      - main
+
+# security: restrict permissions for CI jobs.
+permissions:
+    contents: read
+
+jobs:
+    # Build the documentation and upload the static HTML files as an artifact.
+    build:
+      runs-on: [ hero-runners ]
+      steps:
+        - uses: actions/checkout@v4
+        - uses: actions/setup-python@v5
+          with:
+            python-version: '3.11'
+
+        # ADJUST THIS: install all dependencies (including pdoc)
+        - run: pip install .
+        - run: pip install pdoc
+        # ADJUST THIS: build your documentation into docs/.
+        # We use a custom build script for pdoc itself, ideally you just run `pdoc -o docs/ ...` here.
+        - run: pdoc ./hero --template-dir ./pdoc/templates --output-dir docs
+        # - run: PUT COMMAND TO MOVE FILES UP A DIR HERE <- we don't need this anymore
+
+        - uses: actions/upload-pages-artifact@v3
+          with:
+            path: docs
+
+    # Deploy the artifact to GitHub pages.
+    # This is a separate job so that only actions/deploy-pages has the necessary permissions.
+    deploy:
+      needs: build
+      runs-on: ubuntu-latest
+      permissions:
+        pages: write
+        id-token: write
+      environment:
+        name: github-pages
+        url: ${{ steps.deployment.outputs.page_url }}
+      steps:
+        - id: deployment
+          uses: actions/deploy-pages@v4

hero_sdk-0.14.0/.github/workflows/release.yml

@@ -0,0 +1,19 @@
+name: GitHub Release
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+
+    permissions:
+      contents: write
+
+    steps:
+      - name: Create GitHub Release
+        uses: softprops/action-gh-release@v2
+        with:
+          generate_release_notes: true

hero_sdk-0.14.0/.gitignore

@@ -0,0 +1,14 @@
+*.egg-info
+env.sh
+env
+__pycache__
+.pytest_cache
+.python-version
+docs
+build
+dist
+
+test/download.json
+test/example.json
+
+.DS_Store

hero_sdk-0.14.0/.pre-commit-config.yaml

@@ -0,0 +1,11 @@
+repos:
+-   repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v2.3.0
+    hooks:
+    -   id: check-yaml
+    -   id: end-of-file-fixer
+    -   id: trailing-whitespace
+-   repo: https://github.com/psf/black
+    rev: 24.8.0
+    hooks:
+    -   id: black

hero_sdk-0.14.0/LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2026 Alliance for Energy Innovation, LLC
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

hero_sdk-0.14.0/PKG-INFO

@@ -0,0 +1,98 @@
+Metadata-Version: 2.4
+Name: hero-sdk
+Version: 0.14.0
+Summary: Python client for HERO
+Project-URL: Homepage, https://github.nrel.gov/Hero/hero
+Project-URL: Documentation, https://github.nrel.gov/Hero/hero
+Project-URL: Repository, https://github.nrel.gov/Hero/hero
+Project-URL: Bug Tracker, https://github.nrel.gov/Hero/hero/issues
+Author-email: Monte Lunacek <monte.lunacek@nrel.gov>, Nick Wunder <nick.wunder@nrel.gov>
+Maintainer-email: Monte Lunacek <monte.lunacek@nrel.gov>, Nick Wunder <nick.wunder@nrel.gov>, Joseph Smith <joseph.smith@nrel.gov>
+License: Proprietary
+License-File: LICENSE
+Keywords: data repo,hero,search,task engine
+Classifier: Development Status :: 4 - Beta
+Classifier: Programming Language :: Python
+Requires-Python: <=3.12,>=3.10
+Requires-Dist: cryptography>=44.0.3
+Requires-Dist: pyjwt>=2.8.0
+Requires-Dist: requests>=2.32.3
+Requires-Dist: tenacity>=8.3.0
+Requires-Dist: tqdm>=4.66.4
+Provides-Extra: dev
+Requires-Dist: black>=24.8.0; extra == 'dev'
+Requires-Dist: pre-commit>=3.8.0; extra == 'dev'
+Requires-Dist: pytest>=8.3.5; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# HERO Python SDK
+
+This is the Python SDK for HERO.
+
+## Installation
+
+The HERO team recommends using [uv](https://docs.astral.sh/uv/) to install and manage project dependencies.
+
+### Using uv
+
+```
+uv add https://github.nrel.gov/Hero/hero/archive/refs/tags/v0.14.0.zip
+```
+
+### Using pip
+
+```
+pip install git+https://github.nrel.gov/Hero/hero@v0.14.0#egg=hero
+```
+
+## Development Installation and Release
+
+First, clone this repo locally. Then install dependencies and pre-commit hooks:
+
+```
+uv sync
+uv run pre-commit install
+```
+
+To run the tests:
+
+```
+./run_test.sh
+```
+
+To link the local HERO codebase into a consuming project for feature development:
+
+- Checkout the target branch in this repo
+- In your consuming project, run `uv add --editable THE-PATH-TO-THE-NEWLY-CLONED-HERO-REPO`
+
+### Releasing a New Version
+
+Once development is complete on a given feature/bugfix/etc, pleaes do the following to tag a new release.
+- Update the version in `pyproject.toml`.
+- Update the version in the Installation section(s) in the `README.md` (this file).
+- Add and commit the changes made in the above two steps.
+- Perform a non fast-forward the working branch into main
+    - `git checkout main`
+    - `git merge --no-ff THE-BRANCH-NAME-YOU-ARE-MERGING`.
+- Tag the main branch with the new version via `git tag THE-NEW-VERSION-NUMBER`
+- Push with tags `git push && git push --tags`
+
+
+## Usage
+
+You need to have the following environment variables defined.
+
+```
+export HERO_ENV=["dev", "stage", "prod"]
+export HERO_PROJECT="aeroportal-app"
+export HERO_CLIENT_ID="*******************************"
+export HERO_CLIENT_SECRET="*******************************"
+```
+
+### Examples
+
+Please check out the [HERO examples](https://github.com/nrel-hero/hero-examples).
+
+Additionally, the tests in the `test` directory of this repo may also prove useful for basic usage examples.
+
+SWR 26-024

hero_sdk-0.14.0/README.md

@@ -0,0 +1,71 @@
+# HERO Python SDK
+
+This is the Python SDK for HERO.
+
+## Installation
+
+The HERO team recommends using [uv](https://docs.astral.sh/uv/) to install and manage project dependencies.
+
+### Using uv
+
+```
+uv add https://github.nrel.gov/Hero/hero/archive/refs/tags/v0.14.0.zip
+```
+
+### Using pip
+
+```
+pip install git+https://github.nrel.gov/Hero/hero@v0.14.0#egg=hero
+```
+
+## Development Installation and Release
+
+First, clone this repo locally. Then install dependencies and pre-commit hooks:
+
+```
+uv sync
+uv run pre-commit install
+```
+
+To run the tests:
+
+```
+./run_test.sh
+```
+
+To link the local HERO codebase into a consuming project for feature development:
+
+- Checkout the target branch in this repo
+- In your consuming project, run `uv add --editable THE-PATH-TO-THE-NEWLY-CLONED-HERO-REPO`
+
+### Releasing a New Version
+
+Once development is complete on a given feature/bugfix/etc, pleaes do the following to tag a new release.
+- Update the version in `pyproject.toml`.
+- Update the version in the Installation section(s) in the `README.md` (this file).
+- Add and commit the changes made in the above two steps.
+- Perform a non fast-forward the working branch into main
+    - `git checkout main`
+    - `git merge --no-ff THE-BRANCH-NAME-YOU-ARE-MERGING`.
+- Tag the main branch with the new version via `git tag THE-NEW-VERSION-NUMBER`
+- Push with tags `git push && git push --tags`
+
+
+## Usage
+
+You need to have the following environment variables defined.
+
+```
+export HERO_ENV=["dev", "stage", "prod"]
+export HERO_PROJECT="aeroportal-app"
+export HERO_CLIENT_ID="*******************************"
+export HERO_CLIENT_SECRET="*******************************"
+```
+
+### Examples
+
+Please check out the [HERO examples](https://github.com/nrel-hero/hero-examples).
+
+Additionally, the tests in the `test` directory of this repo may also prove useful for basic usage examples.
+
+SWR 26-024

hero_sdk-0.14.0/hero/__init__.py

@@ -0,0 +1,9 @@
+import os
+import json
+
+from . lib import errors
+from . lib.config import set_environment
+from . lib.event_trigger import event_trigger
+from . lib.loaders import get_env_variable, load_environment, load_runtime_config
+
+from .client import HeroClient

hero_sdk-0.14.0/hero/client.py

@@ -0,0 +1,194 @@
+import jwt
+import base64
+from requests import Session
+from jwt import (
+    PyJWKClient,
+    ExpiredSignatureError,
+    InvalidTokenError,
+    InvalidSignatureError,
+    DecodeError,
+)
+
+from .url_map import URL_MAP
+from .lib import (
+    get_conf_from_collection,
+    get_env,
+    get_client_credentials,
+)
+from .services import (
+    AuthService,
+    DataRepoService,
+    TaskEngineService,
+    MLModelRegistry,
+    AssistantService,
+)
+from .services import SearchService
+
+from .lib.errors import (
+    TokenDecodeError,
+    TokenInvalidSignatureError,
+    TokenInvalidError,
+    TokenGeneralError,
+)
+
+
+class HeroClient:
+    """
+    Primary client for interfacing with the HERO API. Provides access to all services.
+    """
+
+    def __init__(self, client_id: str = None, client_secret: str = None):
+        """
+        Creates the Hero client.
+        """
+        self._scopes = []
+
+        self.env = get_env()
+        self.api = Session()
+        region = "us-west-2"
+
+        if client_id is None or client_secret is None:
+            client_id, client_secret = get_client_credentials()
+
+        self._client_id = client_id
+        self._client_secret = client_secret
+        self._cognito_api_url = get_conf_from_collection(
+            URL_MAP, "HERO_COGNITO_API_URL"
+        )
+        self._cognito_user_pool_id = get_conf_from_collection(URL_MAP, "USER_POOL_ID")
+        self._cognito_auth_url = f"https://cognito-idp.{region}.amazonaws.com/{region}_{self._cognito_user_pool_id}"
+        self._jwks_url = f"{self._cognito_auth_url}/.well-known/jwks.json"
+        self._jwk_client = PyJWKClient(self._jwks_url)
+        self._access_token = None
+
+    def _fetch_token(self):
+        """
+        Login to the Cognito user pool. Requires a client with a client secret and authorization to assign requested scopes.
+
+        Returns a JWT access token.
+        """
+        app_client_id_secret = f"{self._client_id}:{self._client_secret}".encode(
+            "utf-8"
+        )
+        # Request access_token following client credentials grant flow
+        basic_auth = f"Basic {base64.urlsafe_b64encode(app_client_id_secret).decode()}"
+
+        response = self.api.post(
+            self._cognito_api_url,
+            data=f'grant_type=client_credentials&scope={" ".join(self._scopes)}&client_id={self._client_id}',
+            headers={
+                "Authorization": basic_auth,
+                "Content-Type": "application/x-www-form-urlencoded",
+            },
+            verify=False,
+        )
+
+        if response.status_code != 200:
+            raise Exception(
+                f"Failed to fetch access token: {response.status_code} - {response.text}, {self._scopes}"
+            )
+
+        self._access_token = response.json()["access_token"]
+
+    def _decode_token(self, token):
+        """
+        Decodes a JWT token and returns the payload, verifying its signature and expiration.
+
+        Raises TokenInvalidSignatureError if the signature is invalid.
+        Raises TokenDecodeError if the token is malformed.
+        Raises TokenInvalidError if the token is invalid.
+        Raises TokenGeneralError for any other unexpected errors.
+        """
+        try:
+            signing_key = self._jwk_client.get_signing_key_from_jwt(token).key
+            # Token is valid and not expired
+            return jwt.decode(
+                token,
+                key=signing_key,
+                algorithms=["RS256"],
+                options={"verify_exp": True, "verify_iat": False},
+            )
+        except ExpiredSignatureError:
+            # token expired, we need to refresh it
+            self._fetch_token()
+            # try to decode again
+            return jwt.decode(
+                token, algorithms=["RS256"], options={"verify_signature": False}
+            )
+        except InvalidSignatureError:
+            # The signature doesn't match — token could be tampered with
+            raise TokenInvalidSignatureError("Invalid token signature")
+        except DecodeError:
+            # Token is malformed (e.g., bad base64, wrong structure)
+            raise TokenDecodeError("Malformed token")
+        except InvalidTokenError as e:
+            # Other invalid token cases
+            raise TokenInvalidError(f"Invalid token: {str(e)}")
+        except Exception as e:
+            # Any other unexpected errors
+            raise TokenGeneralError("Unexpected error")
+
+    def add_scope(self, scope):
+        """
+        Adds a scope to the client.
+        """
+        if scope in self._scopes:
+            return
+        self._scopes.append(scope)
+
+    def authenticate(self):
+        """
+        Authenticates the client with the Cognito user pool.
+        """
+        self._fetch_token()
+
+    def get_token(self):
+        """
+        Returns the access token if it is valid.
+
+        Note: we could add re-auth capabilities here Or manage elsewhere
+        (i.e. resilient sessions, etc)
+        """
+        access_token_decoded = self._decode_token(self._access_token)
+        if access_token_decoded:
+            return self._access_token
+        else:
+            self._fetch_token()
+            return self._access_token
+
+    def Auth(self):
+        """
+        Returns a AuthService instance.
+        """
+        return AuthService(self)
+
+    def DataRepo(self, application_id=None):
+        """
+        Returns a DataRepoService instance.
+        """
+        return DataRepoService(self, application_id)
+
+    def TaskEngine(self, application_id=None):
+        """
+        Returns a TaskEngineService instance.
+        """
+        return TaskEngineService(self, application_id)
+
+    def MLModelRegistry(self, application_id=None):
+        """
+        Returns a MLModelRegistry instance.
+        """
+        self.authInstance = self.Auth()
+        return MLModelRegistry(self, application_id)
+
+    def Search(self):
+        """
+        Returns a SearchService instance.
+        """
+        return SearchService(self)
+
+    def Assistant(self, application_id):
+        """
+        Returns a AssistantService instance.
+        """
+        return AssistantService(self, application_id)

hero_sdk-0.14.0/hero/lib/__init__.py

@@ -0,0 +1,19 @@
+from .service_base import ServiceBase
+from .config import (
+    get_resilient_session,
+    get_client_credentials,
+    get_service_id,
+    get_conf_from_collection,
+    get_env,
+    set_environment,
+)
+from .decorators import (
+    decorate_all,
+    log_errors,
+    track_calls,
+    retry_method,
+)
+from .errors import HeroRetryError
+from .helpers import set_log_level_from_env
+from .attr_mapper import HeroObject
+from .credentials import HeroCredentialsProvider

hero_sdk-0.14.0/hero/lib/attr_mapper.py

@@ -0,0 +1,82 @@
+from collections.abc import MutableMapping
+
+
+def _to_attr(value):
+    if isinstance(value, dict):
+        return HeroObject(value)
+    if isinstance(value, list):
+        return [_to_attr(v) for v in value]
+    if isinstance(value, tuple):
+        return tuple(_to_attr(v) for v in value)
+    return value
+
+
+class HeroObject(MutableMapping):
+    """
+    Mapping that supports attribute-style access and recursive wrapping.
+    Example:
+        run = HeroObject({"info": {"run_id": "123"}, "data": {"tags": [{"key": "k","value": "v"}]}})
+        run.info.run_id -> "123"
+        run["info"]["run_id"] -> "123"
+    """
+
+    __slots__ = ("_store",)
+
+    def __init__(self, data=None, **kwargs):
+        object.__setattr__(self, "_store", {})
+        if data:
+            for k, v in data.items():
+                self._store[k] = _to_attr(v)
+        for k, v in kwargs.items():
+            self._store[k] = _to_attr(v)
+
+    # Mapping protocol
+    def __getitem__(self, key):
+        return self._store[key]
+
+    def __setitem__(self, key, value):
+        self._store[key] = _to_attr(value)
+
+    def __delitem__(self, key):
+        del self._store[key]
+
+    def __iter__(self):
+        return iter(self._store)
+
+    def __len__(self):
+        return len(self._store)
+
+    # Attribute access
+    def __getattr__(self, name):
+        try:
+            return self._store[name]
+        except KeyError as e:
+            raise AttributeError(name) from e
+
+    def __setattr__(self, name, value):
+        # keep internal slot private; everything else goes in the mapping
+        if name == "_store":
+            object.__setattr__(self, name, value)
+        else:
+            self._store[name] = _to_attr(value)
+
+    def __delattr__(self, name):
+        try:
+            del self._store[name]
+        except KeyError as e:
+            raise AttributeError(name) from e
+
+    def to_dict(self):
+        def _to_plain(v):
+            if isinstance(v, HeroObject):
+                return {k: _to_plain(v[k]) for k in v}
+            if isinstance(v, list):
+                return [_to_plain(i) for i in v]
+            if isinstance(v, tuple):
+                return tuple(_to_plain(i) for i in v)
+            return v
+
+        return {k: _to_plain(v) for k, v in self._store.items()}
+
+    def __repr__(self):
+        return f"HeroObject({self.to_dict()!r})"

hero_sdk-0.14.0/hero/lib/config.py

@@ -0,0 +1,71 @@
+import os
+import pathlib
+import json
+import logging
+import pathlib
+
+log = logging.getLogger("hero:config")
+
+
+def get_env():
+    return os.environ.get("HERO_ENV", "dev")
+
+
+def get_service_id(key):
+    env = get_env()
+    return f"{env}-{os.environ[key]}"
+
+
+def get_conf_from_collection(collection, key):
+    return os.environ.get(key, collection[get_env()][key])
+
+
+def get_resilient_session():
+    return os.environ.get("HERO_RESILIENT_SESSION", "False").lower() in ("true")
+
+
+def get_client_credentials():
+    """Returns the client credentials tuple (client_id, client_secret) from the environment variables HERO_CLIENT_ID and HERO_CLIENT_SECRET"""
+    client_credentials = (
+        os.environ["HERO_CLIENT_ID"],
+        os.environ["HERO_CLIENT_SECRET"],
+    )
+    return client_credentials
+
+
+def set_environment(application_id, path=None):
+    """
+    This function will set the HERO environment variables from a file stored in ~/.hero/.credentials.json
+
+    Ensure you have your hero credentials saved in `~/.hero/credentials.json` format.
+
+        {
+            "dev-aeroportal": {
+                "HERO_CLIENT_ID": "1c5ngb6o6lvtdfkus0sflstdq4",
+                "HERO_CLIENT_SECRET": "******",
+                "[ANOTHER_KEY]": "***"
+            }
+        }
+
+
+    Parameters
+    ----------
+    application_id: name in the credentials.json file (e.g. dev-aeroportal)
+
+    """
+    if path is None:
+        path = str(pathlib.Path(os.environ.get("HOME")) / ".hero" / "credentials.json")
+
+    try:
+        credentials = json.loads(open(path, "r").read())
+        these_credentials = credentials[application_id]
+        for key, value in these_credentials.items():
+            os.environ[key] = value
+
+    except FileNotFoundError as e:
+        log.error(f"Unable to load {path}")
+    except KeyError as e:
+        log.error(f"Unable to read key {e}")
+    except Exception as e:
+        log.error(str(e))
+        log.error(f"Unable to set credentials from {path}")