Package: aide-sdk
AIDE SDKIntroductionThis library allows you to build AI inference models to be run on the AIDE platform.Table of contentsQuickstartPackaging a modelThe Manifest fileAccessing study dataSaving outputLogging & Model FailuresQuickstartTo get started:fromaide_sdk.applicationimportAideApplicationfromaide_sdk.inference.aideoperatorimportAideOperatorfromaide_sdk.model.operatorcontextimportOperatorContextfromaide_sdk.model.resourceimportResourcefromaide_sdk.utils.file_storageimportFileStorageclassMyModel(AideOperator):defprocess(self,context:OperatorContext):origin_dicom=context.originresult=my_cool_stuff(origin_dicom)# Your magic goes herefile_manager=FileStorage(context)path=file_manager.save_dicom("my_results",result)result_dicom=Resource(format="dicom",content_type="result",file_path=path)context.add_resource(result_dicom)returncontextAideApplication.start(operator=MyModel())What we just didThe main application class isAideApplication. Once started, it will connect to the model's input queue and listen for new messages.
The single parameter required by Aide is theoperator- this can be any object that implements the following method:process(context: OperatorContext)- This is the operation method, it receives an OperatorContext as input, and should return it as output. The context object is a special object which allows access to input resources.Packaging & PublishingOnce your model is ready, it will need to be published onto the platform.
In order to do that, it'll need to be Dockerized.Docker image requirementsThe SDK needs to be installed on the image (usingpip install aide-sdkor similar)The entrypoint to the container needs to runAideApplication.start.The following environment variables need to be set:MANIFEST_PATH - the path to amanifestfile.Manifest FileThe manifest file provides the AIDE platform with the details it needs to use the model. It includes the following information:model_name- stringmodel_version- stringmodel_description- string, The description of your model.predicate- string, a validpredicate string.mode- string, a validmode string.Model modesThe model mode determines how it'll be used by AIDE.
The mode string can have one of the following values:QA- QA mode, when the model is still being tested.R- Research mode.CU- Clinical use.Predicate StringThe predicate string determines which inputs will be sent to the model.
It's a logical expression, evaluating to a boolean,It's possible to use any comparison operator (<,>,==,>=,<=,!=) and combine usingANDorOR.The predicate supports evaluation against DICOM image metadata tags. Any DICOM tags that are wished to be evaluated against should be prefixed with the following:DICOM_.For example:DICOM_Modality=="MR"ANDDICOM_SliceThickness<=10The above string will evaluate to true if the input DICOM "Modality" tag value is "MR" and the "SliceThickness" tag value is 10 or lower.It is also possible to request specific resource types. For example:DICOM_Modality=="MR"ANDDICOM_SliceThickness<=10ANDresource.type=="nifty/origin"Resource types are defined as format/content-type.Manifest example{"model_name":"test_model","model_version":"1.0.0","model_description":"This is a test model","mode":"QA","predicate":"tetststs"}Accessing ResourcesTheprocessmethod is called with an instance ofOperatorContext, the reference for that object is shown below.Object ReferenceOperatorContextPropertiesPropertyTypeDescriptionoriginOriginThe origin object contains the initial input information to this pipeline.resourcesList[Resource]The resources added by previous operators in the pipeline.MethodsMethodReturn typeDescriptionget_resources_by_type(format: str, content_type: str)List[Resource]Returns the resources of a specific type.add_resource(resource: Resource)NoneAdd a newResourceto the resources list. This resource will be available to the next operators.set_error(error: str)NoneSets an error message in case the operator can't complete its operation. The execution will be marked as a failure.ResourcePropertiesPropertyTypeDescriptionformatstrThe file format (e.g. nifti/dicom/etc)content_typestrThe content within this resource (eg "brain_scan", "white_matter")file_pathstrThe file path of this resource. Returned by the file manager when saving.namespacestrThe UID of the operator that created this resource. Added automatically when saving resources.Origin(Resource)The origin object is a special resource. It contains everything any resource contains, and additional information.PropertiesPropertyTypeDescriptionformatstrThe file format (e.g. "dicom")content_typestrThe content within this resource (eg "origin")file_pathstrThe path of this object.namespacestrThe UID of the operator that created this resource. Added automatically when saving resources.received_timestampdatetimeThe time and date on which the origin object was first received by AIDE.patient_idstrThe patient ID this data refers to.DicomOrigin(Origin)This origin object is used when the original input data is a DICOM study.PropertiesPropertyTypeDescriptionformatstrThe file format (e.g. "dicom")content_typestrThe content within this resource (eg "origin")file_pathstrThe path of this object.namespacestrThe UID of the operator that created this resource. Added automatically when saving resources.received_timestampdatetimeThe time and date on which the origin object was first received by AIDE.patient_idstrThe patient ID this data refers to.study_uidstrThe DICOM Study ID.seriesList[DicomSeries]The DICOM series in this study.MethodsMethodReturn typeDescriptionget_series_by_id()DicomSeriesReads the dicom file and instantiates a pydicomDatasetfrom it.DicomSeriesA DicomSeries object refers to a specific series of images.PropertiesPropertyTypeDescriptionseries_idstrThe UID of this series.metadatadictA dictionary containing series metadata.imagesList[DicomImage]A list of dicom images included in this series.DicomImageThis is a wrapper object around a PyDicomDatasetobject.PropertiesPropertyTypeDescriptioncontext_metadatadictA dictionary containing the image metadata.image_pathstrThe path to the .dcm file.MethodsMethodReturn typeDescriptionload_dataset()pydicom.DatasetReads the dicom file and instantiates a pydicomDatasetfrom it.get_filename()strReturns the dicom filename (e.g. "filename.dcm")get_context_metadata()strReturns the image metadata, loading it if hasn't been loaded.reload_context_metadata()strReloads the context metadata from the file.Saving output DataFileStorageThis helper class allows you to save files, with convenience methods to help save DICOM images and PDF files.
To use it, instantiate it with anOperatorContextobject.It is recommended to include the source DICOM study/series id in the output/final report, this helps the end user to validate that the output was produced using the expected source dataMethodsMethodReturn typeDescriptionsave_file(file_bytes: bytes, file_name: str)strSaves binary data to disk, and returns a path string with its location on disk. Requires binary data and a file name.load_file(file_path: str)bytesLoads a file from disk, using a path string.save_dicom(folder_name: str, dataset: pydicom.Dataset)strSaves a PyDicomDatasetto disk, and returns a path string with its location on disk. Requires a container folder name and the pydicomDataset.save_encapsulated_pdf(folder_name: str, dataset: Dataset, pdf_file_path: str)strSave a PDF file, encapsulated within a DICOM file. This function require a folder name, theDatasetthe PDF relates to, and the pdf file path. Returns the dicom path.LoggingLogging is possible using theaide_sdk.logger.logger.LogManagerclass:fromaide_sdk.logger.loggerimportLogManagerlogger=LogManager.get_logger()logger.info("info message")logger.warn("warn message")logger.error("error message")logger.exception("exception message")Failures vs ErrorsThere are two ways in which operators can fail - either a response can't be reached, for example because of a lack of statistical significance, or an error occurred while attempting to run the operator.Failures are still a valid result. To log an error response, use theOperatorContextset_failuremethod:context.set_failure("Couldn't reach conclusion")returncontextHowever, unexpected errors should raise an exception. It is possible to use theModelErrorexception for this:fromaide_sdk.utils.exceptionsimportModelErrortry:something()exceptException:LogManager.get_logger().exception("Failed")raiseModelError("Unknown error while running model")