Fix missing api_utils module and mitigate dependency confusion risk in HeAR demo

[ashutoshjoshi23]

https://github.com/ashutoshjoshi23/MedGemma-Nexus-AI-Powered-Clinical-System/blob/c5c8bb7616ad1fe6327472a4f657331098e2d9e5/hear_api_fix.py

Description

Overview

This PR resolves a critical usability and security issue in the HeAR repository by providing a complete implementation of the missing api_utils module referenced in hear_demo.ipynb.

Currently, the notebook imports api_utils, but no such module exists in the repository. This leads users to install an unrelated third-party package from PyPI, resulting in runtime errors and exposing users to potential dependency confusion risks.

---

Problem

api_utils is referenced but not present in the repository

Users may install a third-party api_utils package from PyPI

This results in:

AttributeError: module 'api_utils' has no attribute 'make_prediction'

Potential execution of untrusted code (supply chain risk)

---

Solution

This PR introduces a fully functional replacement for api_utils with:

A HeARAnalyzer class implementing:

Vertex AI prediction integration

Token-based authentication using google.auth

Support for both raw audio arrays and GCS URIs

Drop-in compatibility with existing notebook usage:

make_prediction

make_prediction_with_exponential_backoff

initial_token_refresh

Exponential backoff retry logic for robustness

Environment variable support for endpoint configuration

---

Key Features

Compatible with existing hear_demo.ipynb without modifications

Eliminates dependency confusion risk

Improves reliability with retry handling

Supports production-ready usage with Vertex AI endpoints

---

Implementation Details

Adds a new module implementing:

Authentication via google.auth.default()

Prediction requests to Vertex AI endpoints

Automatic token refresh

Uses environment variables:

HEAR_RAW_AUDIO_ENDPOINT

HEAR_GCS_URI_ENDPOINT

Converts NumPy inputs to JSON-compatible format

Handles GCS URI formatting when required

---

Security Impact

Prevents unintended installation of third-party api_utils packages

Eliminates a dependency confusion attack vector

Ensures users execute only intended logic

---

Testing

Verified compatibility with existing notebook flow

Confirmed resolution of AttributeError

Successfully tested prediction calls with Vertex AI endpoints

Validated retry behavior under failure conditions

---

Backward Compatibility

Fully backward compatible with existing demo usage

No changes required in hear_demo.ipynb

---

Additional Notes

This implementation is designed as a minimal, self-contained fix

Future improvements could include:

Official packaging under a namespaced module (e.g., google_hear_utils)

Integration into the core repository structure

[google-cla]

Thanks for your pull request! It looks like this may be your first contribution to a Google open source project. Before we can look at your pull request, you'll need to sign a Contributor License Agreement (CLA).

View this failed invocation of the CLA check for more information.

For the most up to date status, view the checks section at the bottom of the pull request.

[sonali-kumari1]

Hi @ashutoshjoshi23 - This PR requires a signed CLA. Could you please sign the CLA so the review process can proceed. Thanks!

[ashutoshjoshi23]

Hi @sonali-kumari1 , thanks for pointing that out. I’ve already signed the Google Individual CLA (Apr 20, 2026). Could you please check if it’s now reflecting correctly on your end? Let me know if anything else is needed. Thanks!

[sonali-kumari1]

Hi @sonali-kumari1 , thanks for pointing that out. I’ve already signed the Google Individual CLA (Apr 20, 2026). Could you please check if it’s now reflecting correctly on your end? Let me know if anything else is needed. Thanks!

@ashutoshjoshi23, The CLA check is still failing, as shown below. Could you please verify that the CLA was signed with the same email linked to this PR? Thanks!

[ashutoshjoshi23]

**sonali-kumari1 ** c

Hi! I’ve already signed the Google Open Source Contributor License Agreement using the same account linked to this PR ([[email protected]] It shows as signed on Apr 21, 2026. Could you please recheck on your end or let me know if anything else is needed from my side? Thanks!