Skip to main content

api

Typed wrappers around the Bitfount REST apis.

Classes​

BitfountAM​

class BitfountAM(    session: Optional[BitfountSession] = None, access_manager_url: Optional[str] = None,):

Typed API for communicating with the Bitfount Access Manager.

Arguments

  • session: Bitfount session for authentication.
  • access_manager_url: URL of the access manager.

Methods​

check_oidc_access_request​

def check_oidc_access_request(    self,    pod_identifier: str,    serialized_protocol: SerializedProtocol,    modeller_name: str,    modeller_access_token: str,    project_id: Optional[str] = None,) ‑> AccessCheckResult:

Check access using access token from OIDC request.

Arguments

  • pod_identifier: The pod identifier for the request.
  • serialized_protocol: The protocol received from the modeller.
  • modeller_name: The name of the modeller.
  • modeller_access_token: OAuth access token for the modeller.
  • project_id: Optional. The project ID associated with the task. Used to verify project-based access.

Returns Response code from the Access manager.

Raises

  • RequestException: If there is a problem communicating with the access manager.
  • HTTPError: If it is unable to extract the JSON from the response.
  • InvalidJSONError: If JSON does not match expected format.

check_signature_based_access_request​

def check_signature_based_access_request(    self,    unsigned_task: bytes,    task_signature: bytes,    pod_identifier: str,    serialized_protocol: SerializedProtocol,    modeller_name: str,    project_id: Optional[str] = None,    public_key_id: Optional[str] = None,) ‑> AccessCheckResult:

Check access by verifying the signed task against the unsigned task.

Check that when modeller_name signs the unsigned task it matches the signed version of the task.

Arguments

  • unsigned_task: Unsigned task.
  • task_signature: Task signature.
  • pod_identifier: The pod identifier for the request.
  • serialized_protocol: The protocol received from the modeller.
  • modeller_name: The name of the modeller.
  • modeller_access_token: OAuth access token for the modeller.
  • project_id: Optional. The project ID associated with the task. Used to verify project-based access.
  • public_key_id: Optional. The public key ID associated with the modeller.

Returns Response code from the Access manager.

Raises

  • RequestException: If there is a problem communicating with the access manager.
  • HTTPError: If it is unable to extract the JSON from the response.
  • InvalidJSONError: If JSON does not match expected format.

get_access_manager_key​

def get_access_manager_key(    self,) ‑> cryptography.hazmat.primitives.asymmetric.rsa.RSAPublicKey:

Gets the Access Manager's public key.

Returns The access manager's public key.

Raises

  • RequestException: If there is a problem communicating with the access manager.

BitfountHub​

class BitfountHub(    session: Optional[BitfountSession] = None, url: str = 'https://hub.bitfount.com',):

A typed API for interacting with BitfountHub.

Arguments

  • session: Bitfount session for authentication.
  • url: URL to Bitfount Hub. Defaults to PRODUCTION_HUB_URL.

Static methods​

get_model_from_url​

def get_model_from_url(    model_url: _S3PresignedURL, model_hash: str,) ‑> Optional[type[BitfountModel]]:

Retrieve model code from a pre-defined S3 URL.

Will compare the downloaded model code to the hash provided.

Arguments

  • model_url: The URL to download the model from.
  • model_hash: Hash of the model code to compare the downloaded model code to.

Returns The parsed model class of the downloaded code, or None if the model class could not be parsed.

Raises

  • ModelValidationError: if the provided hash does not match the hash of the downloaded model code.

get_weights_from_url​

def get_weights_from_url(weights_url: _S3PresignedURL) ‑> bytes:

Retrieve model weights from a pre-defined S3 URL.

Methods​

add_dataset_to_project_for_user​

def add_dataset_to_project_for_user(self, project_id: str, dataset_name: str) ‑> None:

Add a dataset to an already existing project.

Only works for projects owned by the authenticated user.

Arguments

  • project_id: The ID of the project to add the dataset to.
  • dataset_name: The name of the dataset to add.

check_public_key_registered_and_active​

def check_public_key_registered_and_active(    self, key_id: str, username: Optional[str] = None,) ‑> Optional[bitfount.hub.types._ActivePublicKey]:

Return key details from hub if key is registered.

create_project​

def create_project(self, name: str) ‑> str:

Creates a project and returns the ID.

do_pod_heartbeat​

def do_pod_heartbeat(self, pod_names: list[str], pod_public_key: RSAPublicKey) ‑> None:

Makes a "heartbeat" update to the hub.

This takes the form of a PATCH request to the /api/pods endpoint.

Arguments

  • pod_names: The names of the pods.
  • pod_public_key: The public key of the pod.

get_model​

def get_model(    self,    username: str,    model_name: str,    model_version: Optional[int] = None,    project_id: Optional[str] = None,) ‑> Optional[type[BitfountModel]]:

Gets model code corresponding to model_name from user username.

Arguments

  • username: The model's owner.
  • model_name: The name of the model.
  • model_version: The version of the model. Defaults to latest. Optional.
  • project_id: The project ID to search for the model in. Optional.

Returns The loaded Bitfount model class or None if unable to retrieve it.

get_pod​

def get_pod(    self,    pod_identifier: Optional[str] = None,    pod_namespace: Optional[str] = None,    pod_name: Optional[str] = None,    project_id: Optional[str] = None,) ‑> Optional[bitfount.hub.types._PodDetailsResponseJSON]:

Gets the details of a pod.

Either pod_identifier or pod_namespace and pod_name can be provided.

Arguments

  • pod_identifier: Full pod identifier (i.e. pod_namespace/pod_name). Optional.
  • pod_namespace: Pod namespace name. Optional.
  • pod_name: Pod name. Optional.
  • project_id: The project ID to search for the pod in. Optional.

Returns The pod details JSON or None if unable to retrieve them.

get_pod_key​

def get_pod_key(    self,    pod_identifier: Optional[str] = None,    pod_namespace: Optional[str] = None,    pod_name: Optional[str] = None,    project_id: Optional[str] = None,) ‑> Optional[str]:

Gets the public key of a pod.

Either pod_identifier or pod_namespace and pod_name can be provided.

Arguments

  • pod_identifier: Full pod identifier (i.e. pod_namespace/pod_name). Optional.
  • pod_namespace: Pod namespace name. Optional.
  • pod_name: Pod name. Optional.
  • project_id: The project ID to search for the pod in. Optional.

Returns The pod key or None if no key can be found.

Raises

  • HTTPError: If the response from the hub is malformed.

get_pod_schema​

def get_pod_schema(    self, pod_identifier: str, project_id: Optional[str] = None,) ‑> BitfountSchema:

Retrieves the schema for a given pod.

Arguments

  • pod_identifier: The pod to retrieve the schema of.
  • project_id: The project ID to retrieve the schema from.

Returns The BitfountSchema for that pod.

Raises

  • HTTPError: If there is an issue in the response.

get_projects​

def get_projects(    self, offset: Optional[int] = 0, limit: Optional[int] = 12,) ‑> Optional[bitfount.hub.types._GetProjectsPagedResponseJSON]:

Gets a page of projects.

Arguments

  • offset: Starting point
  • limit: Max number of projects to retrieve

Returns A page of projects

get_usage_limits​

def get_usage_limits(    self,    project_id: str,    model_id: Optional[str] = None,) ‑> Union[list[bitfount.hub.types._SimpleUsageJSON], bitfount.hub.types._ProjectModelLimitsJSON]:

Get usage/limits information in a project for the current user.

If model_id is provided, will return the usage for that model+user+project combination.

If it is not provided, will return the simple usages for each model associated with the project task for user+project combination.

get_weights​

def get_weights(    self,    username: str,    model_name: str,    model_version: int,    project_id: Optional[str] = None,) ‑> Optional[bytes]:

Gets weights byte stream corresponding to model_name from user username.

Arguments

  • username: The model's owner.
  • model_name: The name of the model.
  • model_version: The version of the model. Defaults to latest.
  • project_id: The project ID to search for the model in. Optional.

Returns The loaded weights as a byte stream or None if one has not been uploaded.

register_pod​

def register_pod(    self,    public_metadata: PodPublicMetadata,    pod_public_key: RSAPublicKey,    access_manager_key: RSAPublicKey,) ‑> None:

Registers a pod with the hub.

The pod's schema will be uploaded to S3.

Arguments

  • public_metadata: Details about the pod (name, etc) to register.
  • pod_public_key: The public key to use for this pod.
  • access_manager_key: The public key of the Access Manager.

Raises

  • RequestException: If unable to connect to the hub.
  • HTTPError: If the response is not successful.

register_user_public_key​

def register_user_public_key(self, key: RSAPublicKey) ‑> Union[str, int]:

Register a public key for the signed-in user.

Arguments

  • key: The public key to register.

send_model​

def send_model(    self, model_code_path: Path, private_model: bool = False,) ‑> bitfount.hub.types._ModelUploadResponseJSON:

Sends the provided model_code to Hub, associated to session username.

The name of the model is taken from the name of the file.

Arguments

  • model_code_path: The path to the file containing the model code.
  • private_model: Whether the model is private or publically accessible.
  • Returns: The response JSON from the Hub.

Raises

  • ModelUploadError: If the model upload fails. Specific subclasses of ModelUploadError are used to indicate different failure conditions.

send_monitor_update​

def send_monitor_update(self, update: _MonitorPostJSON) ‑> None:

Send an update to the monitor service.

Arguments

  • update: The monitor service update to send as a JSON dict.

Raises

  • RequestException: If unable to connect to the hub.
  • HTTPError: If the response is not successful.

send_weights​

def send_weights(    self, model_name: str, model_version: int, pretrained_file_path: Path,) ‑> None:

Sends the provided model_weights to Hub.

Save trained model weights associated to session username, model_name and model_version.

Arguments

  • model_name: The name of the model to associate the weights with.
  • model_version: The version of the model to associate the weights with.
  • pretrained_file_path: The path to the pretrained model file.

Raises

  • ModelUploadError: If the model upload fails. Specific subclasses of ModelUploadError are used to indicate different failure conditions.

PodPublicMetadata​

class PodPublicMetadata(    name: str,    display_name: str,    description: str,    schema: _JSONDict,    number_of_records: Optional[int] = None,):

Data about the Pod which is publicly visible on BitfountHub.

Variables​

  • static description : str
  • static display_name : str
  • static name : str
  • static number_of_records : Optional[int]

SMARTOnFHIR​

class SMARTOnFHIR(    session: Optional[BitfountSession] = None,    smart_on_fhir_url: Optional[str] = None,    resource_server_url: Optional[str] = None,):

API for SMART on FHIR pairing and session management.

Create API client for SMART on FHIR pairing and session management.

Arguments

  • session: The BitfountSession to use for API calls. If not provided, a default one is created.
  • smart_on_fhir_url: URL for the SMART on FHIR service. If not provided the URL will either be pulled from configuration or failing that set depending on the BITFOUNT_ENVIRONMENT we are running in.
  • resource_server_url: URL for the SMART on FHIR resource server (i.e. the NextGen server that the pairings should correspond to). If not provided the URL will be pulled from configuration if provided.

Methods​

get_access_token​

def get_access_token(self) ‑> SMARTOnFHIRAccessToken:

Get a SMART on FHIR access token for the logged-in user.

Returns the access token string and the nextgen context for that token.

Returns A SMARTOnFHIRAccessToken instance containing the token string and additional context.