Get started with the Python Library¶

The Aignostics Python Library lets you call the Aignostics Platform programmatically from your own scripts, notebooks, and applications. It is well suited to building custom analysis pipelines and processing large datasets in Python.

Sign up for the Aignostics Platform¶

Before you can run an analysis, you need an account on the Aignostics Platform. These account steps are the same whichever interface you use.

💡 Already have an account? Skip to the installation steps below.

Find your invitation email. Look in your inbox for a message from support@aignostics.com, with a subject like “You’ve been invited to join your organization’s Aignostics account”. If you can’t find it, check your spam folder. If it isn’t there either, ask your organization’s administrator or email support@aignostics.com.
Accept the invitation. Open the email and click Accept Invitation. A page opens in your browser where you enter your full name and set a password.
Set up two-factor authentication. Next, you are asked to set up two-factor authentication. This is a second login step that uses a code from your phone. Install one of these free authenticator apps, then scan the code shown in your browser and enter the six-digit code it gives you:
- Android: Google Authenticator
- iPhone: Google Authenticator
You are done when you see “Welcome to the Console of the Aignostics Platform”. From now on, each time you log in you enter your password and then a fresh six-digit code from the app.

Install the library¶

Add the Aignostics Python SDK to your project.

With uv:

uv add aignostics

With pip:

pip install aignostics

Usage¶

The following snippet shows how to use the client to submit an application run:

from aignostics import platform

# initialize the client
client = platform.Client()
# submit an application run
application_run = client.runs.submit(
    application_id="test-app",
    items=[
        platform.InputItem(
            external_id="slide-1",
            input_artifacts=[
                platform.InputArtifact(
                    name="whole_slide_image",
                    download_url="<a signed url to download the data>",
                    metadata={
                        "checksum_base64_crc32c": "AAAAAA==",
                        "resolution_mpp": 0.25,
                        "width_px": 1000,
                        "height_px": 1000,
                    },
                )
            ],
        ),
    ],
)
# wait for the results and download incrementally as they become available
application_run.download_to_folder("path/to/download/folder")

See the library reference for all classes and methods.

System health checks¶

The library does not perform automated health checks before operations. If you need health verification, implement it in your application logic:

from aignostics import platform
from aignostics.system import Service as SystemService

# Check system health before submitting runs
health = SystemService().health()
if not health:
    raise RuntimeError(f"System is unhealthy: {health.reason}")

# Proceed with run submission
client = platform.Client()
run = client.runs.submit(...)

This gives you full control over health-check behavior — custom retry logic, logging, and graceful handling of unhealthy states.

Example notebooks¶

[!IMPORTANT] Before you start, set up your authentication credentials if you have not done so. Visit your personal dashboard on the Aignostics Platform website and follow the steps in the Use in Python Notebooks section.

The SDK includes ready-to-use Marimo notebooks that demonstrate platform interaction patterns — ideal for learning the API, prototyping workflows, and integrating with data science pipelines. They use the “Test Application” (free for all users):

# clone the python-sdk repository
git clone https://github.com/aignostics/python-sdk.git
# within the cloned repository, install the SDK and all dependencies
uv sync --all-extras
# open the example notebook in your browser
uv run marimo edit examples/notebook.py

💡 You can also run a notebook inside the Aignostics Launchpad: select the run you want to inspect in the left sidebar and click Marimo.

Defining the input for an application run¶

The following details apply to advanced use cases. These examples use the “Test Application” — a free application available to all users for testing and development.

When creating a run, you specify the application_id and optionally the application_version. If you omit the version, the latest is used automatically. You then define the input items to process:

(
    platform.InputItem(
        external_id="1",
        input_artifacts=[
            platform.InputArtifact(
                name="whole_slide_image",  # defined by the application version's input artifact schema
                download_url="<a signed url to download the data>",
                metadata={  # defined by the application version's input artifact schema
                    "checksum_base64_crc32c": "N+LWCg==",
                    "resolution_mpp": 0.46499982,
                    "width_px": 3728,
                    "height_px": 3640,
                },
            )
        ],
    ),
)

For each item you process, provide a unique external_id string — it is used to match results back to your inputs. The input_artifacts field is a list of InputArtifact objects defining the data and metadata for each item. The required artifacts depend on the application version; for the test application there is a single artifact, named whole_slide_image.

The download_url is a signed URL that allows the Aignostics Platform to download the image data during processing.

Self-signed URLs for large files¶

To make whole slide images available to the Aignostics Platform, you provide a signed URL the platform can download from. Signed URLs for files in Google Cloud Storage buckets can be generated with generate_signed_url (code).

You must provide the required credentials for the Google Cloud Storage bucket.

Invite your team¶

If you are your organization’s Administrator, you can invite colleagues onto the Aignostics Platform so they can run analyses too.

💡 Not an administrator? Skip this section — ask whoever set up your organization’s account to invite you.

Open the members page. Log in to the Aignostics Console, select Admin in the sidebar, then open Members.
Add a colleague and choose their role. At the bottom of the Members page, enter their email address and assign a role:
- Member — can run applications and manage their own runs.
- Admin — everything a member can do, plus inviting and managing other users.
⚠️ The email address must use your organization’s own domain — the same domain as yours.
Send the invitation. Click Send. Your colleague receives a signup email from support@aignostics.com and completes the same signup steps you did — accepting the invitation, setting a password, and configuring two-factor authentication.

Return to the Members page any time to review your organization’s users and their roles.