hopprai 2026.23.2

SDK for interacting with the HOPPR API

HOPPR Python SDK

The HOPPR Python SDK allows you to interact with the HOPPR API for managing studies, adding images, and performing model inferences.

Installation

To install the HOPPR SDK, you can use pip:

pip install -U hopprai

This will install the HOPPR SDK along with its dependencies.

Initialization

To start using the HOPPR SDK, you need to initialize it with your API key:

Note: Do not place your API key directly in your code. Instead, use environment variables or other secure methods to manage your API key. This helps prevent accidental exposure of sensitive information.

import os
from hopprai import HOPPR

api_key = os.getenv("HOPPR_API_KEY")
hoppr = HOPPR(api_key)

Make sure to set the HOPPR_API_KEY environment variable with your actual API key.

Error Handling

To handle errors more effectively, the HOPPR SDK includes a custom HOPPRError type that provides the status code and an error message, allowing users to respond accordingly to specific error situations.

Here's an example of how to handle errors:

from hopprai import HOPPR

api_key = os.getenv("HOPPR_API_KEY")
hoppr = HOPPR(api_key)

try:
  study = hoppr.create_study("example_study_reference")
except Exception as e:
  print(f"Error occurred: Status code: {e.status_code}, Message: {e.message}")

Examples

Create a Study

To create a new study, use the create_study method:

reference = "example_study_reference"
study = hoppr.create_study(reference)
print(f"Created study with id: {study.id}")

Retrieve a Study

To retrieve an existing study by its id:

study_id = "a3f1d5c2-41d4-4c9a-8b8f-8e5f9a4e8f9a"
study = hoppr.get_study(study_id)
if study:
  print(f"Study id: {study.id}, Reference: {study.reference}")
else:
  print("Study not found.")

Delete a Study

To delete a study by its id:

study_id = "a3f1d5c2-41d4-4c9a-8b8f-8e5f9a4e8f9a"
if hoppr.delete_study(study_id):
  print("Study deleted successfully.")
else:
  print("Failed to delete study.")

Add an Image to a Study

To add an image to a study:

study_id = "a3f1d5c2-41d4-4c9a-8b8f-8e5f9a4e8f9a"
reference = "1.2.840.113619.2.312.4120.793348.11111.1586342345.233"
image_data = open("path/to/your/image.dcm", "rb").read()

image = hoppr.add_study_image(study_id, reference, image_data)
print(f"Added image with id: {image.id}")

Delete an Image from a Study

To delete an image from a study:

study_id = "a3f1d5c2-41d4-4c9a-8b8f-8e5f9a4e8f9a"
image_id = "1.2.840.113619.2.312.4120.793348.11111.1586342345.233"
if hoppr.delete_study_image(study_id, image_id):
  print("Image deleted successfully.")
else:
  print("Failed to delete image.")

Prompt a Model for Inference

To prompt a model for inference and wait for the response:

study_id = "a3f1d5c2-41d4-4c9a-8b8f-8e5f9a4e8f9a"
model = "model"
prompt = "What findings are present in this study?"
organization = "your_org" # optional

response = hoppr.prompt_model(study_id=study_id, model=model, prompt=prompt, organization=organization)
if response:
  print(f"Model response: {response.response}")
else:
  print("Model inference timed out or failed.")

Prompt a Model for Inference Asynchronously

To prompt a model for inference asynchronously:

study_id = "a3f1d5c2-41d4-4c9a-8b8f-8e5f9a4e8f9a"
model = "model"
prompt = "What findings are present in this study?"
organization = "your_org" # optional

inference_id = hoppr.prompt_model_async(study_id=study_id, model=model, prompt=prompt, organization=organization)
print(f"Inference queued with id: {inference_id}")

To retrieve the response later:

timeout = 180
response = hoppr.retrieve_prompt_response(study_id, inference_id, timeout)
if response:
  print(f"Model response: {response.response}")
else:
  print("Model inference timed out or failed.")

Datasets and Training Jobs

List Datasets

To retrieve all datasets:

datasets = hoppr.get_datasets()
for ds in datasets:
  print(f"Dataset id: {ds['id']}, Name: {ds['name']}")

Retrieve a Dataset

To retrieve a dataset:

dataset_id = "your_dataset_id"
dataset = hoppr.get_dataset(dataset_id)
print(f"Dataset: {dataset}")

Create a Dataset

To create a new dataset (expects a .jsonl file):

dataset_name = "my_dataset"
description = "A test dataset."
file_path = "path/to/dataset.jsonl"
dataset = hoppr.create_dataset(dataset_name, description, file_path)
print(f"Created dataset with id: {dataset['id']}")

Create a Training Job

To create a new training job:

training_job = {
  "dataset_id": "your_dataset_id",
  "model": "hoppr_model:1.0.0",
  # Add other required fields as needed
}
job = hoppr.create_training_job(training_job)
print(f"Created training job with id: {job['id']}")

Retrieve a Training Job

To get the status or details of a training job:

training_job_id = "your_training_job_id"
job = hoppr.get_training_job(training_job_id)
print(f"Training job status: {job['status']}")

Cancel a Training Job

To cancel a running training job:

training_job_id = "your_training_job_id"
result = hoppr.cancel_training_job(training_job_id)
print(f"Cancel result: {result}")

Download Training Manifest

To download the training/validation manifest for a training job:

training_job_id = "your_training_job_id"
csv_content = hoppr.download_training_manifest(training_job_id)
print(csv_content)

To save it directly to a file:

hoppr.download_training_manifest(training_job_id, output_path="manifest.csv")

The manifest CSV contains one row per image with columns: study_id, series_id, instance_id, classification, and train/val.

Map Manifest IDs to Original Identifiers

After downloading a manifest, use map_manifest_ids to replace HOPPR de-identified IDs with your original DICOM identifiers. This runs entirely on your local machine — no data is sent to HOPPR.

result = hoppr.map_manifest_ids(
  manifest_path="manifest.csv",
  jsonl_path="path/to/your/dataset.jsonl",
  organization="your_organization",
)
print(result)

To write the remapped manifest to a file:

hoppr.map_manifest_ids(
  manifest_path="manifest.csv",
  jsonl_path="path/to/your/dataset.jsonl",
  organization="your_organization",
  output_path="remapped_manifest.csv",
)

The jsonl_path should point to the original JSONL file you uploaded when creating the dataset. Each row must contain one of StudyInstanceUID, SeriesInstanceUID, or SOPInstanceUID as the identifier key.