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,) ‑> bitfount.federated.types._PodResponseType:

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,) ‑> bitfount.federated.types._PodResponseType:

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.

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.

get_saml_challenge​

def get_saml_challenge(self) ‑> Tuple[str, str]:

Gets a fresh SAML challenge for a user.

Returns A tuple of: - The SAML Request (Challenge). - A request ID that the Pod should keep.

Raises

  • RequestException: If there is a problem communicating with the access manager.
  • HTTPError: If it is unable to extract the SAML challenge from the response.

validate_saml_response​

def validate_saml_response(    self,    saml_response: _SAMLResponse,    saml_request_id: str,    pod_identifier: str,    modeller_name: str,    serialized_protocol: SerializedProtocol,    project_id: Optional[str] = None,) ‑> bitfount.federated.types._PodResponseType:

Check if modeller task should be accepted.

This sends the SAML Response from a modeller, along with details about their training request to the access manager so that it can inform the pod whether or not to accept the job.

Arguments

  • saml_response: SAML Response from Modeller
  • saml_request_id: The ID of the original SAML request. The pod should have stored this.
  • pod_identifier: The pod identifier of the pod that the task is for
  • modeller_name: The username of the modeller that has sent the task
  • serialized_protocol: The serialized protocol to use for the task received from 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.

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.

Methods​

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.

do_pod_heartbeat​

def do_pod_heartbeat(self, pod_name: 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_name: The name of the pod.
  • pod_public_key: The public key of the pod.

get_all_models​

def get_all_models(self) ‑> List[bitfount.hub.types._MultiModelDetailsResponseJSON]:

Returns a list of all registered models.

Returns A list of JSON details for each model or a empty list if unable to retrieve them.

get_all_pods​

def get_all_pods(self) ‑> List[bitfount.hub.types._MultiPodDetailsResponseJSON]:

Returns a list of all registered and visible pods.

Returns A list of JSON details for each visible pod or a empty list if unable to retrieve them.

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: (Optional) The version of the model. Defaults to latest.

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).
  • pod_namespace: Pod namespace name.
  • pod_name: Pod name.

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).
  • pod_namespace: Pod namespace name.
  • pod_name: Pod name.

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.

Returns The BitfountSchema for that pod.

Raises

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

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: (Optional) The version of the model. Defaults to latest.

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]
  • static schema : Dict[str, Any]