diff --git a/OPERATIONAL_EXCELLENCE.md b/OPERATIONAL_EXCELLENCE.md index 099a2701b..f4df3304f 100644 --- a/OPERATIONAL_EXCELLENCE.md +++ b/OPERATIONAL_EXCELLENCE.md @@ -1,5 +1,21 @@ # Operational Excellence +We know you take **quality** and **security** as seriously as we do. That's why +the Aignostics Python SDK is built following best practices and with full +transparency. This includes (1) making the complete +[source code of the SDK +available on GitHub](https://github.com/aignostics/python-sdk/), maintaining a +(2) +[A-grade code quality](https://sonarcloud.io/summary/new_code?id=aignostics_python-sdk) +with [high test coverage](https://app.codecov.io/gh/aignostics/python-sdk) in +all releases, (3) achieving +[A-grade security](https://sonarcloud.io/summary/new_code?id=aignostics_python-sdk) +with +[active scanning of dependencies](https://github.com/aignostics/python-sdk/issues/4), +and (4) providing +[extensive documentation](https://aignostics.readthedocs.io/en/latest/). Read +more about how we handle [security](https://aignostics.readthedocs.io/en/latest/security.html). + > ๐Ÿง  This project was scaffolded using the template [oe-python-template](https://github.com/helmut-hoffer-von-ankershoffen/oe-python-template) with [copier](https://copier.readthedocs.io/), thereby applying the following toolchain: > 1. Linting with [Ruff](https://github.com/astral-sh/ruff) diff --git a/README.md b/README.md index 23d9eb5ef..b20726ffc 100644 --- a/README.md +++ b/README.md @@ -20,16 +20,7 @@ The **Aignostics Platform** runs computational pathology applications โ€” such a ## Choose your interface -Choose your preferred interface for working with the Aignostics Platform. Each interface is designed for different user roles and use cases: - -### ๐Ÿ–ฅ๏ธ Launchpad (Desktop Application) - -| | | -|---|---| -| **What it is** | Graphical application for analyzing slides and viewing results in QuPath or Python notebooks | -| **Best for** | Pathologists and researchers who want to analyze slides without writing code | -| **Use when** | Running analyses on individual cases or small cohorts (1-20 slides) and exploring results interactively | -| **Get started** | Get started with Launchpad | +Choose your preferred interface for working with the Aignostics Platform: Console if you want to work in your browser, the Python Library or REST API if you want to integrate the Platform into your own code. ### ๐ŸŒ Console (Web Interface) @@ -40,15 +31,6 @@ Choose your preferred interface for working with the Aignostics Platform. Each i | **Use when** | Analyzing slides that are already on your computer or file server (1-100s of slides), without installing a desktop application | | **Get started** | Get started with Console | -### โŒจ๏ธ CLI (Command-Line Interface) - -| | | -|---|---| -| **What it is** | Terminal tool for scripting and automation | -| **Best for** | Bioinformaticians and technical researchers who work with terminal-based workflows | -| **Use when** | Processing large cohorts (10s-100s of slides), automating repetitive analyses, or integrating with computational pipelines | -| **Get started** | Get started with the CLI | - ### ๐Ÿ“š Python Library | | | @@ -67,6 +49,28 @@ Choose your preferred interface for working with the Aignostics Platform. Each i | **Use when** | Building a service or workflow outside Python, or generating your own client from the OpenAPI document | | **Get started** | Get started with the API | + + -> ๐Ÿ’ก Each interface has its own step-by-step guide (linked above) that includes installation. Launchpad and the CLI handle authentication for you; the Python Library guide covers credential setup. +> ๐Ÿ’ก Each interface has its own step-by-step guide (linked above) that includes installation. Console handles authentication for you; the Python Library and API guides cover credential setup. ## Next Steps The best next step is to **run your first analysis** end to end. -New here? Start with the [Get started with Launchpad](https://aignostics.readthedocs.io/en/latest/get_started_launchpad.html) guide โ€” it walks you through signing up, installing, and running [Atlas H&E-TME](https://www.aignostics.com/products/he-tme-profiling-product) on a public example slide, then viewing the results in QuPath, with no coding required. Prefer the terminal or Python? Use the [Get started with the CLI](https://aignostics.readthedocs.io/en/latest/get_started_cli.html) or [Get started with the Python Library](https://aignostics.readthedocs.io/en/latest/get_started_library.html) guide instead. +New here? Start with the [Get started with Console](https://aignostics.readthedocs.io/en/latest/get_started_console.html) guide โ€” it walks you through signing up, uploading your slides, and running [Atlas H&E-TME](https://www.aignostics.com/products/he-tme-profiling-product) on them in your browser, with no coding required. Prefer to work in code? Use the [Get started with the Python Library](https://aignostics.readthedocs.io/en/latest/get_started_library.html) or [Get started with the API](https://aignostics.readthedocs.io/en/latest/get_started_api.html) guide instead. Once you've run your first analysis: - **Understand the platform**: Read the [Aignostics Platform Overview](https://aignostics.readthedocs.io/en/latest/platform_overview.html) for architecture and core concepts. -- **Go deeper**: See the [CLI reference](https://aignostics.readthedocs.io/en/latest/cli_reference.html) and [Python Library reference](https://aignostics.readthedocs.io/en/latest/lib_reference.html). +- **Go deeper**: See the [Python Library reference](https://aignostics.readthedocs.io/en/latest/lib_reference.html) and [API Explorer](https://aignostics.readthedocs.io/en/latest/api_explorer_v1.html). - **Get support**: Contact [support@aignostics.com](mailto:support@aignostics.com) or browse the [full documentation](https://aignostics.readthedocs.io/en/latest/). -## We take quality and security seriously - -We know you take **quality** and **security** as seriously as we do. That's why -the Aignostics Python SDK is built following best practices and with full -transparency. This includes (1) making the complete -[source code of the SDK -available on GitHub](https://github.com/aignostics/python-sdk/), maintaining a -(2) -[A-grade code quality](https://sonarcloud.io/summary/new_code?id=aignostics_python-sdk) -with [high test coverage](https://app.codecov.io/gh/aignostics/python-sdk) in -all releases, (3) achieving -[A-grade security](https://sonarcloud.io/summary/new_code?id=aignostics_python-sdk) -with -[active scanning of dependencies](https://github.com/aignostics/python-sdk/issues/4), -and (4) providing -[extensive documentation](https://aignostics.readthedocs.io/en/latest/). Read -more about how we achieve -[operational excellence](https://aignostics.readthedocs.io/en/latest/operational_excellence.html) and -[security](https://aignostics.readthedocs.io/en/latest/security.html). - ## Platform @@ -232,7 +216,7 @@ For integration with programming languages other than Python, you can use the RE Every WSI processed by the Platform generates a cost. Usage of the "Test Application" is free of charge for any registered user. The cost for other applications is defined in your business agreement with Aignostics. The cost is calculated based on the number of slides processed. When an application run is canceled, either by the system or by the user, only processed images incur a cost. -**[Read the API reference documentation](https://aignostics.readthedocs.io/en/latest/api_reference_v1.html)** or use our **[Interactive API Explorer](https://platform.aignostics.com/explore-api)** to dive into details of all operations and parameters. +**[Browse the API Explorer](https://aignostics.readthedocs.io/en/latest/api_explorer_v1.html)** to dive into details of all operations and parameters, or try them out in the **[Interactive API Explorer](https://platform.aignostics.com/explore-api)** on the Platform. ### Platform workflow @@ -318,8 +302,7 @@ The organization's Google Cloud Storage bucket stores uploaded files with automa - **Cost efficiency**: Pay-per-use GPU provisioning, automatic storage cleanup, no idle infrastructure costs - **Operational simplicity**: Python SDK abstracts all cloud complexity; IT teams manage access through existing identity systems -```{include} ../partials/_invite_your_team.md -``` +Administrators can [invite colleagues](https://aignostics.readthedocs.io/en/latest/invite_your_team.html) onto the Platform so they can run analyses too. ## Further Reading @@ -331,16 +314,13 @@ The organization's Google Cloud Storage bucket stores uploaded files with automa [operational excellence](https://aignostics.readthedocs.io/en/latest/operational_excellence.html) with information on our modern toolchain and software architecture. 2. Check out the - [CLI reference](https://aignostics.readthedocs.io/en/latest/cli_reference.html) - with detailed documentation of all CLI commands and options. -3. Check out the [library reference](https://aignostics.readthedocs.io/en/latest/lib_reference.html) with detailed documentation of public classes and functions. -4. Check out the - [API reference](https://aignostics.readthedocs.io/en/latest/api_reference_v1.html) +3. Check out the + [API Explorer](https://aignostics.readthedocs.io/en/latest/api_explorer_v1.html) with detailed documentation of all API operations and parameters. See as well - the OpenAPI Specification in [JSON](https://github.com/aignostics/python-sdk/blob/main/docs/source/_static/openapi_v1.json) and [YAML](https://github.com/aignostics/python-sdk/blob/main/docs/source/_static/openapi_v1.yaml), and the [API Explorer](https://aignostics.readthedocs.io/en/latest/api_explorer_v1.html). -5. Our + the OpenAPI Specification in [JSON](https://github.com/aignostics/python-sdk/blob/main/docs/source/_static/openapi_v1.json) and [YAML](https://github.com/aignostics/python-sdk/blob/main/docs/source/_static/openapi_v1.yaml). +4. Our [release notes](https://aignostics.readthedocs.io/en/latest/release-notes.html) provide a complete log of recent improvements and changes. 6. We gratefully acknowledge the numerous diff --git a/docs/partials/README_footer.md b/docs/partials/README_footer.md index 26a29209b..d731de210 100644 --- a/docs/partials/README_footer.md +++ b/docs/partials/README_footer.md @@ -7,16 +7,13 @@ [operational excellence](https://aignostics.readthedocs.io/en/latest/operational_excellence.html) with information on our modern toolchain and software architecture. 2. Check out the - [CLI reference](https://aignostics.readthedocs.io/en/latest/cli_reference.html) - with detailed documentation of all CLI commands and options. -3. Check out the [library reference](https://aignostics.readthedocs.io/en/latest/lib_reference.html) with detailed documentation of public classes and functions. -4. Check out the - [API reference](https://aignostics.readthedocs.io/en/latest/api_reference_v1.html) +3. Check out the + [API Explorer](https://aignostics.readthedocs.io/en/latest/api_explorer_v1.html) with detailed documentation of all API operations and parameters. See as well - the OpenAPI Specification in [JSON](https://github.com/aignostics/python-sdk/blob/main/docs/source/_static/openapi_v1.json) and [YAML](https://github.com/aignostics/python-sdk/blob/main/docs/source/_static/openapi_v1.yaml), and the [API Explorer](https://aignostics.readthedocs.io/en/latest/api_explorer_v1.html). -5. Our + the OpenAPI Specification in [JSON](https://github.com/aignostics/python-sdk/blob/main/docs/source/_static/openapi_v1.json) and [YAML](https://github.com/aignostics/python-sdk/blob/main/docs/source/_static/openapi_v1.yaml). +4. Our [release notes](https://aignostics.readthedocs.io/en/latest/release-notes.html) provide a complete log of recent improvements and changes. 6. We gratefully acknowledge the numerous diff --git a/docs/partials/README_main.md b/docs/partials/README_main.md index 985acda85..e9beb62dd 100644 --- a/docs/partials/README_main.md +++ b/docs/partials/README_main.md @@ -4,16 +4,7 @@ The **Aignostics Platform** runs computational pathology applications โ€” such a ## Choose your interface -Choose your preferred interface for working with the Aignostics Platform. Each interface is designed for different user roles and use cases: - -### ๐Ÿ–ฅ๏ธ Launchpad (Desktop Application) - -| | | -|---|---| -| **What it is** | Graphical application for analyzing slides and viewing results in QuPath or Python notebooks | -| **Best for** | Pathologists and researchers who want to analyze slides without writing code | -| **Use when** | Running analyses on individual cases or small cohorts (1-20 slides) and exploring results interactively | -| **Get started** | Get started with Launchpad | +Choose your preferred interface for working with the Aignostics Platform: Console if you want to work in your browser, the Python Library or REST API if you want to integrate the Platform into your own code. ### ๐ŸŒ Console (Web Interface) @@ -24,15 +15,6 @@ Choose your preferred interface for working with the Aignostics Platform. Each i | **Use when** | Analyzing slides that are already on your computer or file server (1-100s of slides), without installing a desktop application | | **Get started** | Get started with Console | -### โŒจ๏ธ CLI (Command-Line Interface) - -| | | -|---|---| -| **What it is** | Terminal tool for scripting and automation | -| **Best for** | Bioinformaticians and technical researchers who work with terminal-based workflows | -| **Use when** | Processing large cohorts (10s-100s of slides), automating repetitive analyses, or integrating with computational pipelines | -| **Get started** | Get started with the CLI | - ### ๐Ÿ“š Python Library | | | @@ -51,6 +33,28 @@ Choose your preferred interface for working with the Aignostics Platform. Each i | **Use when** | Building a service or workflow outside Python, or generating your own client from the OpenAPI document | | **Get started** | Get started with the API | + + -> ๐Ÿ’ก Each interface has its own step-by-step guide (linked above) that includes installation. Launchpad and the CLI handle authentication for you; the Python Library guide covers credential setup. +> ๐Ÿ’ก Each interface has its own step-by-step guide (linked above) that includes installation. Console handles authentication for you; the Python Library and API guides cover credential setup. ## Next Steps The best next step is to **run your first analysis** end to end. -New here? Start with the [Get started with Launchpad](https://aignostics.readthedocs.io/en/latest/get_started_launchpad.html) guide โ€” it walks you through signing up, installing, and running [Atlas H&E-TME](https://www.aignostics.com/products/he-tme-profiling-product) on a public example slide, then viewing the results in QuPath, with no coding required. Prefer the terminal or Python? Use the [Get started with the CLI](https://aignostics.readthedocs.io/en/latest/get_started_cli.html) or [Get started with the Python Library](https://aignostics.readthedocs.io/en/latest/get_started_library.html) guide instead. +New here? Start with the [Get started with Console](https://aignostics.readthedocs.io/en/latest/get_started_console.html) guide โ€” it walks you through signing up, uploading your slides, and running [Atlas H&E-TME](https://www.aignostics.com/products/he-tme-profiling-product) on them in your browser, with no coding required. Prefer to work in code? Use the [Get started with the Python Library](https://aignostics.readthedocs.io/en/latest/get_started_library.html) or [Get started with the API](https://aignostics.readthedocs.io/en/latest/get_started_api.html) guide instead. Once you've run your first analysis: - **Understand the platform**: Read the [Aignostics Platform Overview](https://aignostics.readthedocs.io/en/latest/platform_overview.html) for architecture and core concepts. -- **Go deeper**: See the [CLI reference](https://aignostics.readthedocs.io/en/latest/cli_reference.html) and [Python Library reference](https://aignostics.readthedocs.io/en/latest/lib_reference.html). +- **Go deeper**: See the [Python Library reference](https://aignostics.readthedocs.io/en/latest/lib_reference.html) and [API Explorer](https://aignostics.readthedocs.io/en/latest/api_explorer_v1.html). - **Get support**: Contact [support@aignostics.com](mailto:support@aignostics.com) or browse the [full documentation](https://aignostics.readthedocs.io/en/latest/). - -## We take quality and security seriously - -We know you take **quality** and **security** as seriously as we do. That's why -the Aignostics Python SDK is built following best practices and with full -transparency. This includes (1) making the complete -[source code of the SDK -available on GitHub](https://github.com/aignostics/python-sdk/), maintaining a -(2) -[A-grade code quality](https://sonarcloud.io/summary/new_code?id=aignostics_python-sdk) -with [high test coverage](https://app.codecov.io/gh/aignostics/python-sdk) in -all releases, (3) achieving -[A-grade security](https://sonarcloud.io/summary/new_code?id=aignostics_python-sdk) -with -[active scanning of dependencies](https://github.com/aignostics/python-sdk/issues/4), -and (4) providing -[extensive documentation](https://aignostics.readthedocs.io/en/latest/). Read -more about how we achieve -[operational excellence](https://aignostics.readthedocs.io/en/latest/operational_excellence.html) and -[security](https://aignostics.readthedocs.io/en/latest/security.html). diff --git a/docs/partials/README_platform.md b/docs/partials/README_platform.md index 52f1b62a8..42fb02f3e 100644 --- a/docs/partials/README_platform.md +++ b/docs/partials/README_platform.md @@ -115,7 +115,7 @@ For integration with programming languages other than Python, you can use the RE Every WSI processed by the Platform generates a cost. Usage of the "Test Application" is free of charge for any registered user. The cost for other applications is defined in your business agreement with Aignostics. The cost is calculated based on the number of slides processed. When an application run is canceled, either by the system or by the user, only processed images incur a cost. -**[Read the API reference documentation](https://aignostics.readthedocs.io/en/latest/api_reference_v1.html)** or use our **[Interactive API Explorer](https://platform.aignostics.com/explore-api)** to dive into details of all operations and parameters. +**[Browse the API Explorer](https://aignostics.readthedocs.io/en/latest/api_explorer_v1.html)** to dive into details of all operations and parameters, or try them out in the **[Interactive API Explorer](https://platform.aignostics.com/explore-api)** on the Platform. ### Platform workflow @@ -201,5 +201,4 @@ The organization's Google Cloud Storage bucket stores uploaded files with automa - **Cost efficiency**: Pay-per-use GPU provisioning, automatic storage cleanup, no idle infrastructure costs - **Operational simplicity**: Python SDK abstracts all cloud complexity; IT teams manage access through existing identity systems -```{include} ../partials/_invite_your_team.md -``` +Administrators can [invite colleagues](https://aignostics.readthedocs.io/en/latest/invite_your_team.html) onto the Platform so they can run analyses too. diff --git a/docs/partials/_get_started_signup.md b/docs/partials/_get_started_signup.md index 859e1fcc3..2c5de15f6 100644 --- a/docs/partials/_get_started_signup.md +++ b/docs/partials/_get_started_signup.md @@ -1,16 +1,9 @@ ## 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. +You need an account on the Aignostics Platform. If you already have one, skip this section. -> ๐Ÿ’ก **Already have an account?** Skip to the installation steps below. +1. **Find your invitation email** from support@aignostics.com, with the subject "You've been invited to join your organization's Aignostics account". -1. **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`. +2. **Accept the invitation** in the email, then enter your full name and set a password. -2. **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. - -3. **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](https://play.google.com/store/apps/details?id=com.google.android.apps.authenticator2) - - **iPhone:** [Google Authenticator](https://apps.apple.com/app/google-authenticator/id388497605) - - 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. +3. **Set up [two-factor authentication](https://en.wikipedia.org/wiki/Multi-factor_authentication)**: install Google Authenticator ([Android](https://play.google.com/store/apps/details?id=com.google.android.apps.authenticator2), [iPhone](https://apps.apple.com/app/google-authenticator/id388497605)) or a similar app, scan the code shown in your browser, and enter the six-digit code the app gives you. diff --git a/docs/partials/_invite_your_team.md b/docs/partials/_invite_your_team.md index d7f73b870..6e677da46 100644 --- a/docs/partials/_invite_your_team.md +++ b/docs/partials/_invite_your_team.md @@ -1,18 +1,14 @@ ## Invite your team -If you are your organization's **Administrator**, you can invite colleagues onto the Aignostics Platform so they can run analyses too. +If you are your organization's **Administrator**, you can invite colleagues onto the Aignostics Platform so they can run analyses too. If you are not, ask your administrator to invite you. -> ๐Ÿ’ก **Not an administrator?** Skip this section โ€” ask whoever set up your organization's account to invite you. +1. **Open the members page**: log in to the [Aignostics Console](https://platform.aignostics.com), select **Admin** in the sidebar, then **Members**. -1. **Open the members page.** Log in to the [Aignostics Console](https://platform.aignostics.com), select **Admin** in the sidebar, then open **Members**. - -2. **Add a colleague and choose their role.** At the bottom of the Members page, enter their email address and assign a role: +2. **Enter your colleague's email address** at the bottom of the page โ€” it must use your organization's own domain, the same as yours โ€” 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. - -3. **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. +3. **Click Send.** Your colleague receives the signup email and completes the same signup steps you did. -Return to the Members page any time to review your organization's users and their roles. +The Members page also lists your organization's users and their roles. diff --git a/docs/partials/get_started_api.md b/docs/partials/get_started_api.md index 3183c9da5..9f9d38680 100644 --- a/docs/partials/get_started_api.md +++ b/docs/partials/get_started_api.md @@ -2,25 +2,27 @@ The Aignostics Platform API is a REST API over HTTPS, rooted at `https://platform.aignostics.com/api/v1`. Call it directly when you integrate the platform into another language or into an existing pipeline. -This guide covers one full workflow with plain HTTP calls โ€” authenticate, analyze slides with [Atlas H&E-TME](https://www.aignostics.com/products/he-tme-profiling-product), follow progress, download results. Examples use `curl` and `jq`. The complete contract is in the [API reference](https://aignostics.readthedocs.io/en/latest/api_reference_v1.html). +This guide covers one full workflow with plain HTTP calls โ€” authenticate, analyze slides with [Atlas H&E-TME](https://www.aignostics.com/products/he-tme-profiling-product), follow progress, download results. Examples use `curl` and `jq`. The complete contract is in the [API Explorer](https://aignostics.readthedocs.io/en/latest/api_explorer_v1.html). ```{include} ../partials/_get_started_signup.md ``` -## Authenticate +## Upload your slides + +### 1. Authenticate Authentication is tied to a person, not to a machine: every call acts as a user in an organization, and each analysis records a `submitted_by`. There is no anonymous access and no organization-wide API key. You need two things: - **A platform account**, created by invitation from your organization's administrator (the section above). If your organization is not on the platform yet, talk to `support@aignostics.com`. - **A client ID**, the public identifier of your integration. Ask `support@aignostics.com`; you cannot mint one yourself. There is no matching client *secret*, because a program running on a user's machine cannot keep one safe. -### How it works +#### How it works The API never sees your password. It accepts a short-lived **access token** โ€” issued by Auth0, the identity service behind the platform โ€” which every call carries in an `Authorization: Bearer โ€ฆ` header. You log in once in a browser; from then on your program renews tokens itself with the long-lived **refresh token** it got alongside the first one. When a call returns `401`, renew and retry. This is the standard OAuth 2.0 Device Authorization Grant ([RFC 8628](https://datatracker.ietf.org/doc/html/rfc8628)), so most languages have a library for the three steps below โ€” you supply the endpoints and client ID. -### Step 1: start the login +#### Start the login ```shell CLIENT_ID=your-client-id @@ -37,7 +39,7 @@ curl -s -X POST https://aignostics-platform.eu.auth0.com/oauth/device/code \ The response carries `verification_uri_complete` (the link for you), `user_code` (the code to compare), `device_code` (your program's secret handle), and `interval` (seconds between polls). -### Step 2: approve it, and collect the tokens +#### Approve it, and collect the tokens Open `verification_uri_complete` in a browser, log in, and check the code shown matches the `user_code` your program printed โ€” that comparison is what stops someone else's program from being approved with your account. Meanwhile, poll for the tokens every `interval` seconds while the response says `error: authorization_pending` (or `slow_down`, meaning you are asking too often): @@ -50,7 +52,7 @@ curl -s -X POST https://aignostics-platform.eu.auth0.com/oauth/token \ Once you approve, the same call returns `access_token` and `refresh_token`. Store the refresh token as a secret โ€” it is what makes the next step possible โ€” and never log or commit either token. -### Step 3: renew without a browser +#### Renew without a browser This is what CI and long-running services do whenever a call returns `401`: @@ -63,7 +65,7 @@ curl -s -X POST https://aignostics-platform.eu.auth0.com/oauth/token \ Because the refresh token belongs to the person who logged in, an unattended service acts as that user โ€” and stops working if that account does. If you need a true machine identity, ask support; these flows are what the API supports today. -### Check that it worked +#### Check that it worked ```shell export TOKEN=your-access-token @@ -74,7 +76,7 @@ curl -s "$API/me" -H "Authorization: Bearer $TOKEN" | jq . `GET /v1/me` returns your user and your organization โ€” including `aignostics_bucket_name`, the bucket used below. -### Hello world, end to end +#### Hello world, end to end All of the above in one script, with your client ID as the only input. It needs `curl` and `jq`. @@ -136,9 +138,9 @@ Got an access token, and a refresh token to store as a secret (64 chars). } ``` -Keep the refresh token in your secret manager and later runs skip the browser entirely โ€” Step 3 is the whole renewal. +Keep the refresh token in your secret manager and later runs skip the browser entirely โ€” the renewal call above is all they need. -## Find out what the application expects +### 2. Find out what the application expects Two calls: one to see which applications your organization can run, one to read the contract of the version you intend to use. @@ -153,7 +155,7 @@ The version response tells you exactly what to send in the next step: - `input_artifacts[].metadata_schema` โ€” a JSON Schema for the per-slide `metadata`. Validate against it locally instead of guessing; it is versioned with the application, so it is the source of truth for required fields. - `output_artifacts[]` โ€” the result files a successful slide produces, with their MIME types. -## Give the platform access to your slides +### 3. Give the platform access to your slides The platform fetches each slide from a URL you provide, so that URL has to work without your credentials and keep working while the analysis is queued. @@ -187,6 +189,8 @@ Treat the secret like any other credential: it grants access to your organizatio ## Analyze your slides with Atlas H&E-TME +### 4. Start the analysis + > โš ๏ธ **This example is specific to Atlas H&E-TME `1.3.0`.** Artifact names, metadata, and outputs differ per application and change between versions, so read the version's own contract โ€” *Find out what the application expects*, above โ€” instead of copying this payload. One `POST` describes the whole analysis: which application, which version, and one entry per slide. The API calls those entries **items**, and the files attached to them **artifacts** โ€” here a single input artifact, your slide. Give each item your own `external_id` so you can match results back to your records. Omit `version_number` for the latest version, or pin it as below so a repeat analysis behaves identically. @@ -221,11 +225,11 @@ curl -s -X POST "$API/runs" \ }' | jq . ``` -A `201` returns `{"run_id": "..."}` โ€” the handle you follow the analysis with, so keep it. `custom_metadata` and `scheduling` are optional; the [API reference](https://aignostics.readthedocs.io/en/latest/api_reference_v1.html) lists what your API version accepts. +A `201` returns `{"run_id": "..."}` โ€” the handle you follow the analysis with, so keep it. `custom_metadata` and `scheduling` are optional; the [API Explorer](https://aignostics.readthedocs.io/en/latest/api_explorer_v1.html) lists what your API version accepts. A `422` means nothing ran and `detail` names the offending field โ€” usually metadata that fails `metadata_schema`, a download URL the platform cannot fetch, or two slides sharing an `external_id`. -## Follow the analysis +### 5. Follow the analysis Ask about the analysis as a whole: @@ -248,7 +252,7 @@ curl -s "$API/runs/$RUN_ID/items?state=TERMINATED" -H "Authorization: Bearer $TO Per slide, `termination_reason` is `SUCCEEDED`, `USER_ERROR` (your input โ€” bad file, wrong metadata), `SYSTEM_ERROR` (ours; `error_code` and `error_message` say more), or `SKIPPED`. Every 30 seconds is a plenty frequent poll for analyses taking minutes to hours. -## Download results +### 6. Download results Every succeeded slide lists its result files under `output_artifacts`, each with a `download_url` you can fetch directly. Those URLs expire; if one has gone stale, ask for a fresh one: @@ -260,7 +264,7 @@ Since slides finish one by one, the efficient pattern is a loop: poll `/items`, > โš ๏ธ **Results are kept for 30 days** from the day you started the analysis. After that, re-analyzing the slides is the only way to get them back. -## List, cancel, or clean up +### 7. List, cancel, or clean up ```shell # list your analyses, filtered and paginated @@ -283,3 +287,8 @@ curl -s -X DELETE "$API/runs/$RUN_ID/artifacts" -H "Authorization: Bearer $TOKEN - **Status.** Live platform status is at [status.platform.aignostics.com](https://status.platform.aignostics.com). Questions about the API, or something behaving differently from this guide? Email `support@aignostics.com`. + +## Where to go next + +- {doc}`Invite your team ` โ€” add colleagues so they can run analyses too. +- {doc}`API Explorer ` โ€” all operations and parameters. diff --git a/docs/partials/get_started_console.md b/docs/partials/get_started_console.md index 3cabe7feb..1a8d6c4ce 100644 --- a/docs/partials/get_started_console.md +++ b/docs/partials/get_started_console.md @@ -1,8 +1,8 @@ # Get started with Console -[Console](https://platform.aignostics.com) is the web interface of the Aignostics Platform. This guide walks you through running [Atlas H&E-TME](https://www.aignostics.com/products/he-tme-profiling-product) โ€” which analyzes the tumor microenvironment in H&E-stained tissue โ€” on your own slides: you upload the slides with one command, then analyze them, review the results, and download them in your browser. You do not need any programming experience, and the setup takes about 15 minutes plus the time your slides take to upload. Results stay available in Console for 30 days. +[Console](https://platform.aignostics.com) is the web interface of the Aignostics Platform. This guide takes you through your first analysis with [Atlas H&E-TME](https://www.aignostics.com/products/he-tme-profiling-product), which profiles the tumor microenvironment on H&E slides: you upload your slides with one command, then start the analysis and download the results in your browser. It takes about 15 minutes plus upload time, and you don't need to know how to code. -**What you need:** a Mac, Windows (Windows 10 or later), or Linux (Ubuntu) computer, a web browser, a mobile phone for the login security step, and your whole slide images in a supported format โ€” `.svs`, `.tif`, `.tiff`, or DICOM (`.dcm`). No slides at hand? [Step 4](#optional-get-an-example-slide) downloads a public example slide for you. +You need a Mac, Windows, or Linux computer, a phone for the login code, and your slides as `.svs`, `.tif`, `.tiff`, or DICOM `.dcm` files. ```{include} ../partials/_get_started_signup.md ``` @@ -11,206 +11,169 @@ ### 1. Install the Aignostics Python SDK -The SDK runs in a terminal โ€” a text window where you type commands. You only need it for the upload; everything after that happens in your browser. If a command does not work, see [Troubleshooting](#troubleshooting). +1. Open a terminal. On macOS, press `Cmd+Space`, type `Terminal`, and press `Enter`. On Windows, open the Start menu, type `PowerShell`, and press `Enter`. -**On macOS or Linux:** open the **Terminal** app โ€” on macOS, press `Cmd` + `Space`, type `Terminal`, and press `Enter`. Paste this command and press `Enter`: +2. Paste the install command for your system into the terminal and press Enter: -```bash -curl -LsSf https://astral.sh/uv/install.sh | sh -``` + ```bash + # macOS or Linux + curl -LsSf https://astral.sh/uv/install.sh | sh + ``` -**On Windows:** open **PowerShell** โ€” click the Start menu, type `PowerShell`, and press `Enter`. Paste this command and press `Enter`: + ```powershell + # Windows + powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex" + ``` -```powershell -powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex" -``` +3. Close the terminal and open a new one. -When it finishes, **close that window and open a new one.** Then check the install worked by pasting this command and pressing `Enter`: +4. Check the install by running in your terminal: -```bash -uvx aignostics --help -``` + ```bash + uvx aignostics --help + ``` -The first run takes a minute to get ready. A list of command groups (`application`, `bucket`, `dataset`, and more) means the install worked. If you see an error instead, see [Troubleshooting](#troubleshooting). + You should see a list of commands. ### 2. Log in -In the same window, paste this command and press `Enter`: - -```bash -uvx aignostics user login -``` +1. Log in by running in your terminal: -A browser window opens at `platform.aignostics.com`. Enter your email and password, then the six-digit code from your authenticator app, and return to your terminal. You stay logged in for future sessions. + ```bash + uvx aignostics user login + ``` -### 3. Prepare your slides for upload +2. In the browser window that opens, log in with your email, password, and the six-digit code from your authenticator app. -Collect the slides you want to analyze in a single folder on your computer โ€” for example a folder called `my-slides`. Subfolders are fine; they are preserved during upload. +You stay logged in for future sessions. -Only files of the supported formats (`.svs`, `.tif`, `.tiff`, `.dcm`) can be analyzed. Other files in the folder are uploaded but will not appear as slides when you start the analysis. +### 3. Upload your slides from your local disk -### 4. (Optional) Get an example slide - -To try the workflow before using your own data, download a public example slide โ€” a TCGA lung adenocarcinoma case from the NCI Image Data Commons. - -The target folder has to exist before you download into it, so create it first. Paste these commands and press `Enter` after each: - -```bash -mkdir my-slides -uvx aignostics dataset idc download 1.3.6.1.4.1.5962.99.1.1069745200.1645485340.1637452317744.2.0 my-slides/ -``` +1. Put the slides you want to upload in one folder on your local disk. -Skip the first command if you already created `my-slides` in Step 3 โ€” and if you named your folder something else, use that name in both commands. Downloading a folder that does not exist stops with `Invalid value for 'target': Directory 'my-slides/' does not exist`. +2. Upload the folder by running the following, replacing `./my-slides` with its path: -The download takes a few minutes and puts the slide in `my-slides/tcga_luad`, ready for the next step. + ```bash + uvx aignostics bucket upload ./my-slides + ``` -### 5. Run the upload +3. Keep the terminal open until it prints `All files uploaded successfully!`. Slides are large, so this can take a while. -Your organization has a private storage area on the Aignostics Platform โ€” your **bucket**. Only you and the other members of your organization can see what is in it. Uploading a slide does not start an analysis; it just puts the slide where Console can find it. +Your slides are now in the bucket Aignostics provides for your organization, in a folder named after your computer's user account, for example `jdoe`. -Paste this command and press `Enter`, replacing `./my-slides` with the path to your folder: +### 4. (Optional) Copy slides from your own cloud bucket -```bash -uvx aignostics bucket upload ./my-slides -``` +If your slides are already stored in AWS S3, Azure Blob Storage, or Google Cloud Storage, you can copy them directly from there into your Aignostics bucket. -The command first reports how many files it found and their total size, then names each slide as it goes up. When it is finished it lists what it uploaded and prints `All files uploaded successfully!`. A progress bar is part of that output, but it only shows up if your terminal window is wide enough โ€” in a standard-width window there is no room for it, so you see the messages alone. +1. Install rclone, a tool for managing cloud storage, by following the [rclone installation guide](https://rclone.org/install/). -**Keep the terminal open and your computer awake until then** โ€” a single whole slide image is often 1โ€“4 GB, so this can take a while. If the upload is interrupted, run the same command again. +2. Log in to your own cloud provider account (`aws sso login`, `az login`, or `gcloud auth application-default login`). -Your slides are filed in a folder named after the user account you are logged in with on your computer, so they stay separate from your colleagues' slides. If that account is `jdoe`, then `my-slides/slide1.svs` becomes `jdoe/slide1.svs`. Run `whoami` if you are unsure what your account is called โ€” you will need the folder name in the next step. +3. Log in to your Aignostics account if you haven't already and get the access keys for your Aignostics bucket by running: -To list what arrived in your bucket: + ```bash + uvx aignostics user whoami --no-mask-secrets + ``` -```bash -uvx aignostics bucket find -``` + Note `aignostics_bucket_name`, `aignostics_bucket_hmac_access_key_id`, and `aignostics_bucket_hmac_secret_access_key` โ€” these are your access credentials. Treat them like a password. -## Analyze your slides with Atlas H&E-TME +4. Use the access credentials from the previous step to register both your own cloud bucket and your Aignostics bucket with rclone by running: -### 6. Start the analysis + ```bash + rclone config create aignx s3 provider=GCS endpoint=https://storage.googleapis.com \ + access_key_id= secret_access_key= no_check_bucket=true -Open [platform.aignostics.com](https://platform.aignostics.com) and log in. Select **Analyze** โ†’ **My Application Runs** in the sidebar, then click **Create run** in the top right. + # and one of these, depending on your cloud: + rclone config create mycloud s3 provider=AWS env_auth=true region= + rclone config create mycloud azureblob env_auth=true account= + rclone config create mycloud "google cloud storage" env_auth=true + ``` -![The My Application Runs page with the Create run button in the top right](../source/_static/console/01-analyze-create-run.png) +5. Copy your slides from your own bucket into a folder in your Aignostics bucket (for example, `jdoe`), by running: -Fill in the **Create run** form: + ```bash + rclone copy mycloud:/ aignx:/jdoe/ --progress + ``` -- **Slides.** You see the contents of your organization's bucket. Use the breadcrumb (**Bucket ยป โ€ฆ**) to open the folder named after your computer account, then tick the slides you want to analyze. Your selection is listed under the table, so you can check it before you continue. + Keep the process running and your machine awake until the copy finishes. - ![The Create run form with the bucket contents listed and one slide ticked](../source/_static/console/02-select-slides.png) +## Analyze your slides with Atlas H&E-TME -- **Version.** Pick the entry starting with `he-tme` โ€” that is Atlas H&E-TME. Unless you need to reproduce an earlier analysis, use the highest version number. -- **Staining method.** Already fixed to `H&E` for Atlas H&E-TME, so there is nothing to choose. -- **Indication.** The disease your slides relate to โ€” for the example slide, `Lung cancer`. -- **Tissue.** The tissue your slides were taken from โ€” for the example slide, `Lung`. -- **Name.** A name of your choice, which makes the analysis easier to recognise later. +### 5. Start the analysis -Your entries apply to every slide you selected, so all slides you analyze together must share the same staining method, indication, and tissue. Click **Run now** to start the analysis. +1. Open [platform.aignostics.com](https://platform.aignostics.com) and select **Analyze** โ†’ **My Application Runs** in the sidebar. -![The lower half of the Create run form with Version, Staining method, Indication, Tissue and Name filled in](../source/_static/console/03-metadata.png) +2. Click **Create run** in the top right. -Your analysis now appears at the top of **My Application Runs**. +3. Under **Slides**, open your folder (**Bucket ยป jdoe**) and tick the slides to analyze. -### 7. Wait for results + ```{figure} ../source/_static/console/02-select-slides.png + :alt: The Create run form with the bucket contents listed and one slide ticked + :figclass: guide-screenshot + :target: ../source/_static/console/02-select-slides.png -The analysis runs on Aignostics servers, so you can close your browser and switch off your computer. How long it takes depends on the size and number of your slides โ€” anywhere from a few minutes to several hours. Return to **My Application Runs** any time: the **Status** column shows how far the analysis has got, and **Completed** means it has finished. + Pick your slides from the bucket. Click to view full size. + ``` -### 8. Review your results in the viewer +4. Under **Version**, pick the he-tme entry with the highest version number. -Select your analysis in **My Application Runs** to open **Run Details**, then click a slide name to open it in the built-in viewer. +5. Under **Indication** and **Tissue**, pick what matches your slides, for example Lung cancer and Lung. They apply to all slides you selected. -The **Overlays** panel on the right switches the results on and off on top of your slide: **Tissue Segmentation** colours the tissue regions that were found, **Cell Classification** colours the individual cells by type โ€” with a legend of the cell types and a slider to make the colours more or less transparent โ€” and **Tissue QC** shows areas flagged during quality control. Use the zoom buttons at the top right (`0.4ร—` to `40ร—`) to look at an area closely. +6. Under **Name**, enter anything that helps you recognize the analysis later. -![A slide in the viewer with tissue and cell overlays switched on and the Overlays panel open](../source/_static/console/04-viewer-overlays.png) + ```{figure} ../source/_static/console/03-metadata.png + :alt: The lower half of the Create run form with Version, Staining method, Indication, Tissue and Name filled in + :figclass: guide-screenshot + :target: ../source/_static/console/03-metadata.png -### 9. Download your results + The rest of the form, filled in for a lung slide. Click to view full size. + ``` -On **Run Details**, click **Download Available Results** for all your slides, or use the download icon in the **Actions** column to get a single slide. For each slide you get the tissue regions that were found, the individual cells that were detected and classified by type, and a spreadsheet of measurements such as cell counts and densities. +7. Click **Run now**. -![The Run Details page with the Download Available Results button and per-slide download icons](../source/_static/console/05-download-results.png) +Your analysis appears at the top of **My Application Runs**. -> โš ๏ธ **Results are kept for 30 days**, counting from the day you started the analysis. After that they can no longer be viewed or downloaded, and the only way to get them back is to analyze the slides again โ€” so download whatever you want to keep in time. +### 6. Wait for results -**Congratulations** โ€” you have run your first analysis, reviewed it in the viewer, and downloaded the results. +The analysis runs on Aignostics servers, so you can close your browser. It takes anywhere from minutes to hours depending on the number and size of your slides. The **Status** column on **My Application Runs** shows **Completed** when it is done. -### (Optional) Clean up your bucket +### 7. Review your results in the viewer -Your slides stay in your bucket until you delete them, so analyzing the same slides again needs no new upload. Deletion works on patterns and is a dry run by default. Replace `jdoe` with your own folder name from step 5: +1. Open your analysis and click a slide name to open it in the viewer. -```bash -uvx aignostics bucket delete "jdoe/.*" # shows how many objects would be deleted -uvx aignostics bucket delete "jdoe/.*" --no-dry-run # actually deletes them -``` +2. Use the **Overlays** panel on the right to show the tissue regions, classified cells, and quality-control flags on top of your slide. -> โš ๏ธ Deleting objects from your bucket cannot be undone. It does not affect results you have already downloaded. +```{figure} ../source/_static/console/04-viewer-overlays.png +:alt: A slide in the viewer with tissue and cell overlays switched on and the Overlays panel open +:figclass: guide-screenshot +:target: ../source/_static/console/04-viewer-overlays.png -```{include} ../partials/_invite_your_team.md +The viewer with tissue and cell overlays on. Click to view full size. ``` -## Troubleshooting - -
-The install command failed - -First, make sure you copied the whole command, including everything from the start of the line to the end. Paste it again and press `Enter`. - -If `uvx aignostics --help` did not work right after installing, close that terminal window, open a new one, and try again. The install command is only fully active in a freshly opened window. - -If it still fails, copy the error message and email it to `support@aignostics.com`. +### 8. Download your results -
+On **Run Details**, click **Download Available Results**. For each slide you get the tissue regions, the classified cells, and a spreadsheet of measurements such as cell counts and densities. Results are kept for 30 days, so download what you want to keep. -
-My upload was interrupted +```{figure} ../source/_static/console/05-download-results.png +:alt: The Run Details page with the Download Available Results button and per-slide download icons +:figclass: guide-screenshot +:target: ../source/_static/console/05-download-results.png -Run the same `uvx aignostics bucket upload` command again. Files that were already uploaded are simply uploaded again and replace the earlier copy, so nothing is duplicated and nothing is lost. - -If uploads are interrupted repeatedly, check that your computer does not go to sleep while the upload runs, and that your network connection is stable. - -
- -
-My slides don't show up when I start an analysis - -1. Confirm the upload arrived by running `uvx aignostics bucket find --detail` and looking for your files. -2. Check that you are browsing the right folder in Console โ€” the one named after your computer account, or the one you passed to `--destination-prefix`. -3. Check the file format. Only `.svs`, `.tif`, `.tiff`, and `.dcm` files can be analyzed. For DICOM slides, the complete set of `.dcm` files belonging to the slide must be uploaded together, so upload the whole folder rather than individual files. - -If your slides are in the bucket, in the right format, and still not selectable, email `support@aignostics.com`. - -
- -
-A slide failed, or the whole analysis failed - -Open the analysis on **My Application Runs** to see which slides failed โ€” the **Status** column on **Run Details** shows the outcome per slide. Results for the slides that succeeded are unaffected โ€” you can review and download them as usual. - -A single failed slide usually points at the slide itself: an unsupported or incomplete file, or metadata that does not match the tissue on the slide. Check the file opens on your computer, then analyze that slide on its own. - -If the whole analysis failed, or a slide fails again on a second attempt, email `support@aignostics.com` with the name or ID shown on **Run Details** and we will look into it. - -
- -
-I can't log in, or my six-digit code is rejected - -The six-digit code from your authenticator app changes every 30 seconds. If yours was rejected, wait for the app to show a new code and enter that one promptly. - -Make sure your phone's clock is set to update automatically โ€” if it is wrong by even a minute, the codes will not match. - -If you have forgotten your password, use the "Forgot password" link on the login page. If you still can't get in, email `support@aignostics.com`. - -
+**Run Details** โ€” download everything at once, or one slide at a time. Click to view full size. +``` -
-I want to upload and analyze hundreds of slides +That's it: you have analyzed your first slides with Atlas H&E-TME and have the results on your computer. -The upload command handles large folders, but for larger cohorts you may prefer to script the whole workflow โ€” including submission and result download โ€” instead of clicking through Console for every batch. See [Get started with the CLI](https://aignostics.readthedocs.io/en/latest/get_started_cli.html) and [Get started with the Python Library](https://aignostics.readthedocs.io/en/latest/get_started_library.html), or email `support@aignostics.com` and we will help you choose an approach. +## Where to go next -
+- {doc}`Invite your team ` โ€” add colleagues so they can run analyses too. +- **Clean up your bucket** โ€” your slides stay in your bucket until you delete them, so analyzing them again needs no new upload. Deletion cannot be undone but does not affect results you have downloaded. It is a dry run by default; replace `jdoe` with the folder your slides are in: -Still stuck? Email `support@aignostics.com` and describe what you were doing and what you saw. + ```bash + uvx aignostics bucket delete "jdoe/.*" # shows what would be deleted + uvx aignostics bucket delete "jdoe/.*" --no-dry-run # deletes it + ``` diff --git a/docs/partials/get_started_library.md b/docs/partials/get_started_library.md index 1c4501251..4a5f3ec57 100644 --- a/docs/partials/get_started_library.md +++ b/docs/partials/get_started_library.md @@ -1,137 +1,115 @@ # 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. +The **Aignostics Python Library** lets you use the Aignostics Platform from your own scripts, notebooks, and pipelines. This guide takes you through the same first analysis as the Console guide โ€” upload your slides, run [Atlas H&E-TME](https://www.aignostics.com/products/he-tme-profiling-product) on them, follow the analysis, and download the results โ€” in Python. ```{include} ../partials/_get_started_signup.md ``` -## Install the library +## Upload your slides -Add the Aignostics Python SDK to your project. +### 1. Install the library -**With [uv](https://docs.astral.sh/uv/):** +Add the Aignostics Python SDK to your project with [uv](https://docs.astral.sh/uv/) or [pip](https://pip.pypa.io/en/stable/): ```shell uv add aignostics -``` - -**With [pip](https://pip.pypa.io/en/stable/):** - -```shell +# or pip install aignostics ``` -## Usage +### 2. Log in -The following snippet shows how to use the client to submit an application run: +Create a client. The first time, your browser opens for you to log in with your email, password, and the six-digit code from your authenticator app. You stay logged in for future sessions. ```python 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="", - 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") +print(client.me().user.email) ``` -See the [library reference](https://aignostics.readthedocs.io/en/latest/lib_reference.html) for all classes and methods. - -## System health checks +### 3. Upload your slides -The library does **not** perform automated health checks before operations. If you need health verification, implement it in your application logic: +The platform reads each slide from the bucket Aignostics provides for your organization, together with its checksum, size, resolution, staining method, tissue, and disease. The library computes the technical values from the files; the medical ones you set per slide โ€” here the same for all slides in the folder. ```python -from aignostics import platform -from aignostics.system import Service as SystemService +from pathlib import Path -# Check system health before submitting runs -health = SystemService().health() -if not health: - raise RuntimeError(f"System is unhealthy: {health.reason}") +from aignostics.application import Service as ApplicationService -# Proceed with run submission -client = platform.Client() -run = client.runs.submit(...) -``` +APPLICATION = "he-tme" +slides = Path("my-slides") -This gives you full control over health-check behavior โ€” custom retry logic, logging, and graceful handling of unhealthy states. +metadata = ApplicationService.generate_metadata_from_source_directory( + slides, + APPLICATION, + mappings=[".*:staining_method=H&E,tissue=LUNG,disease=LUNG_CANCER"], +) -## 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](https://platform.aignostics.com/getting-started/quick-start) -> and follow the steps in the `Use in Python Notebooks` section. +def remember_bucket_url(_bytes_uploaded: int, source: Path, bucket_url: str) -> None: + for row in metadata: + if row["external_id"] == str(source): + row["platform_bucket_url"] = bucket_url -The SDK includes ready-to-use [Marimo](https://marimo.io/) 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): -```shell -# 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 +ApplicationService.application_run_upload(APPLICATION, metadata, upload_progress_callable=remember_bucket_url) ``` -> ๐Ÿ’ก You can also run a notebook inside the Aignostics Launchpad: select the run you want to inspect in the left sidebar and click **Marimo**. +`mappings` match slide paths by regular expression, so a folder with mixed cases takes one mapping per group, for example `"lung/.*:tissue=LUNG,disease=LUNG_CANCER"`. If your slides are already in a cloud bucket, you can skip the upload and hand the platform signed URLs instead โ€” see {doc}`Give the platform access to your slides ` in the API guide. + +## Analyze your slides with Atlas H&E-TME + +### 4. Start the analysis -## Defining the input for an application run +```python +run = ApplicationService().application_run_submit_from_metadata(APPLICATION, metadata, note="My first analysis") +print(run.run_id) +``` -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. +Keep the `run_id`: it is how you find the analysis again later, in Python and in Console. -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: +### 5. Follow the analysis + +The analysis runs on Aignostics servers, so your script can exit and pick it up later with `client.run(run_id)`. The run's state goes `PENDING` โ†’ `PROCESSING` โ†’ `TERMINATED`; each slide has its own state and outcome. ```python -( - platform.InputItem( - external_id="1", - input_artifacts=[ - platform.InputArtifact( - name="whole_slide_image", # defined by the application version's input artifact schema - download_url="", - 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, - }, - ) - ], - ), -) +details = run.details() +print(details.state, details.termination_reason) + +s = details.statistics +failed = s.item_user_error_count + s.item_system_error_count +print(f"{s.item_succeeded_count} of {s.item_count} slides succeeded, {failed} failed") + +for item in run.results(): + print(item.external_id, item.state, item.termination_reason) ``` -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 analysis also appears under **My Application Runs** in [Console](https://platform.aignostics.com), where you can review the results in the viewer. -The `download_url` is a signed URL that allows the Aignostics Platform to download the image data during processing. +### 6. Download results -## Self-signed URLs for large files +```python +run.download_to_folder("results") +``` + +This waits for the analysis to finish and downloads each slide's results as soon as they are ready: the tissue regions, the classified cells, and a spreadsheet of measurements such as cell counts and densities. Results are kept for 30 days, so download what you want to keep. -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](https://github.com/aignostics/python-sdk/blob/main/src/aignostics/platform/_utils.py)). +### 7. List, cancel, or clean up -**You must provide the [required credentials](https://cloud.google.com/docs/authentication/application-default-credentials) for the Google Cloud Storage bucket.** +```python +for r in client.runs.list(application_id=APPLICATION): + print(r.run_id, r.details().state) -```{include} ../partials/_invite_your_team.md +run = client.run("") +run.cancel() # stop an analysis that is still running +run.delete() # remove a finished analysis and its results ``` + +Your slides stay in your bucket until you delete them; see {doc}`Clean up your bucket ` in the Console guide. + +## Where to go next + +- {doc}`Invite your team ` โ€” add colleagues so they can run analyses too. +- {doc}`Library reference ` โ€” all public classes and functions. +- [Example notebooks](https://github.com/aignostics/python-sdk/tree/main/examples) โ€” ready-to-use [Marimo](https://marimo.io/) and Jupyter notebooks in the repository. diff --git a/docs/partials/troubleshooting.md b/docs/partials/troubleshooting.md new file mode 100644 index 000000000..08a1e04d4 --- /dev/null +++ b/docs/partials/troubleshooting.md @@ -0,0 +1,29 @@ +## Troubleshooting + +Common problems when following the getting-started guides, and what to do about them. + +**I can't find my invitation email.** Check your spam folder. If it isn't there either, ask your organization's administrator to invite you, or email `support@aignostics.com`. + +**Installing the Aignostics Python SDK failed.** Make sure you copied the whole install command from the guide, then paste it again. If `uvx aignostics --help` fails right after installing, close the terminal and try again in a new one โ€” the install is only active in a fresh window, and the first run takes a minute to get ready. If it still fails, email the error message to `support@aignostics.com`. + +**What is a bucket, and who can see my slides?** Your bucket is the storage area Aignostics provides for your organization on the Platform. Only members of your organization can see what is in it. Uploading a slide does not start an analysis; it just puts the slide where Console can find it. + +**Which folder in the bucket are my slides in?** `uvx aignostics bucket upload` puts them in a folder named after the user account on your computer โ€” run `whoami` in the terminal if you are unsure. Subfolders inside the folder you uploaded are preserved. `uvx aignostics bucket find` lists everything in your bucket. + +**I don't see a progress bar while `uvx aignostics bucket upload` runs.** The progress bar only fits in a wide terminal window; otherwise you see the per-file messages alone. The upload is running normally. + +**My upload was interrupted.** Run the same `uvx aignostics bucket upload` command again. Files already uploaded are replaced, so nothing is duplicated or lost. If it keeps happening, make sure your computer does not go to sleep and your network connection is stable. + +**My slides don't show up when I create a run in Console.** Run `uvx aignostics bucket find --detail` to confirm they arrived, and check you are browsing the right folder in the **Create run** form. Only `.svs`, `.tif`, `.tiff`, and `.dcm` files appear as slides; other files are uploaded but not shown. For DICOM, the complete set of `.dcm` files belonging to a slide must be uploaded together, so upload the whole folder. If your slides are there, in the right format, and still not selectable, email `support@aignostics.com`. + +**`uvx aignostics user whoami` shows no bucket keys.** If the `aignostics_bucket_hmac_*` fields under `organization` are empty, your organization is not yet set up for direct bucket access, which copying slides from your own cloud bucket requires. Email `support@aignostics.com`. + +**A slide failed, or the whole analysis failed.** In Console, the **Status** column on **Run Details** shows the outcome per slide; results for slides that succeeded are unaffected. A single failed slide usually points at the file itself โ€” unsupported or incomplete, or metadata that does not match the tissue. Check the file opens on your computer, then analyze it on its own. If the whole analysis failed, or a slide fails twice, email `support@aignostics.com` with the name or ID shown on **Run Details**. + +**My script runs on a server or in CI, where no browser can open.** Set a refresh token and the library logs in without one. Get it from the `Use in Python Notebooks` section of [your quick-start page in Console](https://platform.aignostics.com/getting-started/quick-start) and put it in the environment or in `~/.aignostics/.env` as `AIGNOSTICS_REFRESH_TOKEN=`. It belongs to your user account, so treat it like a password. + +**I can't log in, or my six-digit code is rejected.** The code changes every 30 seconds โ€” wait for a new one and enter it promptly. Make sure your phone's clock is set automatically; if it is off by a minute, the codes will not match. Use "Forgot password" on the login page if needed, and email `support@aignostics.com` if you still can't get in. + +**I want to analyze hundreds of slides.** For larger cohorts you may prefer to script the whole workflow instead of clicking through Console for every batch. If you copy slides from your own cloud with rclone, run it on a virtual machine in that cloud rather than on your laptop โ€” the data passes through the machine running rclone. See [Get started with the Python Library](https://aignostics.readthedocs.io/en/latest/get_started_library.html) or [Get started with the API](https://aignostics.readthedocs.io/en/latest/get_started_api.html), or email `support@aignostics.com` and we will help you choose. + +Still stuck? Email `support@aignostics.com` and describe what you were doing and what you saw. diff --git a/docs/source/conf.py b/docs/source/conf.py index c558d3cd9..19d45a8cc 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -90,7 +90,13 @@ templates_path = ["_templates"] # Hidden from the published documentation for now: the MCP server is not yet usable # for customers. The guide is kept in the repository, excluded only from the build. -exclude_patterns = ["get_started_mcp.rst"] +exclude_patterns = [ + "get_started_launchpad.rst", + "get_started_cli.rst", + "get_started_mcp.rst", + "cli_reference.rst", + "api_reference_v1.rst", +] html_theme = "furo" html_static_path = ["_static"] diff --git a/docs/source/index.rst b/docs/source/index.rst index 5b6e154f4..861da3a1a 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -13,11 +13,11 @@ :hidden: :caption: Get started - get_started_launchpad get_started_console - get_started_cli get_started_library get_started_api + invite_your_team + troubleshooting .. toctree:: :maxdepth: 1 @@ -25,10 +25,8 @@ :caption: Reference platform_overview - cli_reference lib_reference api_explorer_v1 - api_reference_v1 operational_excellence security release-notes diff --git a/docs/source/invite_your_team.rst b/docs/source/invite_your_team.rst new file mode 100644 index 000000000..aa9e6df67 --- /dev/null +++ b/docs/source/invite_your_team.rst @@ -0,0 +1,2 @@ +.. include:: ../partials/_invite_your_team.md + :parser: myst_parser.sphinx_ diff --git a/docs/source/troubleshooting.rst b/docs/source/troubleshooting.rst new file mode 100644 index 000000000..04be8ea01 --- /dev/null +++ b/docs/source/troubleshooting.rst @@ -0,0 +1,2 @@ +.. include:: ../partials/troubleshooting.md + :parser: myst_parser.sphinx_