From 8489b2353a8e9eb18aa85d00e2df505e5110a0d6 Mon Sep 17 00:00:00 2001 From: omid-aignostics Date: Tue, 8 Sep 2026 13:03:39 +0200 Subject: [PATCH 01/11] docs: simplify Console guide and focus docs on Console, Library and API Rewrite the "Get started with Console" guide as a minimal tutorial: plain markdown, numbered actions per step, one optional step for copying slides from an existing cloud bucket with rclone. Move Troubleshooting and "Invite your team" to their own pages, linked from "Where to go next". Tighten the shared sign-up and invite partials. Hide the Launchpad and CLI guides, the CLI reference and the API v1 reference from the published docs (files kept, excluded from the build), and repoint README and guide links to Console, the Python Library, and the API Explorer. Co-Authored-By: Claude Opus 5 (1M context) --- README.md | 61 ++++--- docs/partials/README_footer.md | 11 +- docs/partials/README_main.md | 48 ++--- docs/partials/README_platform.md | 2 +- docs/partials/_get_started_signup.md | 15 +- docs/partials/_invite_your_team.md | 14 +- docs/partials/get_started_api.md | 4 +- docs/partials/get_started_console.md | 244 +++++++++++-------------- docs/partials/get_started_launchpad.md | 7 + docs/partials/troubleshooting.md | 25 +++ docs/source/conf.py | 8 +- docs/source/index.rst | 6 +- docs/source/invite_your_team.rst | 2 + docs/source/troubleshooting.rst | 2 + 14 files changed, 222 insertions(+), 227 deletions(-) create mode 100644 docs/partials/troubleshooting.md create mode 100644 docs/source/invite_your_team.rst create mode 100644 docs/source/troubleshooting.rst diff --git a/README.md b/README.md index 23d9eb5ef..e71887d9e 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 @@ -232,7 +236,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 @@ -331,16 +335,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..8a7a6c328 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 diff --git a/docs/partials/README_platform.md b/docs/partials/README_platform.md index 52f1b62a8..ce8d977cd 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 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..8de675583 100644 --- a/docs/partials/get_started_api.md +++ b/docs/partials/get_started_api.md @@ -2,7 +2,7 @@ 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 ``` @@ -221,7 +221,7 @@ 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`. diff --git a/docs/partials/get_started_console.md b/docs/partials/get_started_console.md index 3cabe7feb..9be4d0aa2 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,170 @@ ### 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 your organization's private bucket, 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. +- {doc}`Troubleshooting ` โ€” if something did not work as described. +- **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_launchpad.md b/docs/partials/get_started_launchpad.md index 9a6281a31..fe6aa956b 100644 --- a/docs/partials/get_started_launchpad.md +++ b/docs/partials/get_started_launchpad.md @@ -136,6 +136,13 @@ Your slide appears in QuPath with the analysis annotations layered on top โ€” ti ## Troubleshooting +
+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`. + +
+
How do I find Terminal or PowerShell? diff --git a/docs/partials/troubleshooting.md b/docs/partials/troubleshooting.md new file mode 100644 index 000000000..f3df9b0de --- /dev/null +++ b/docs/partials/troubleshooting.md @@ -0,0 +1,25 @@ +## Troubleshooting + +**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`. + +**The install command failed.** Make sure you copied the whole line, 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 your organization's private storage area on the Aignostics 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 are my slides in?** The folder is named after the user account on your computer โ€” run `whoami` in the terminal if you are unsure. `uvx aignostics bucket find` lists everything in your bucket. Subfolders inside your upload folder are preserved. + +**I don't see a progress bar during the upload.** 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 start an analysis.** Run `uvx aignostics bucket find --detail` to confirm they arrived, and check you are browsing the right folder in Console. 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`. + +**The bucket keys are empty.** If `uvx aignostics user whoami` shows no keys under organization, your organization is not set up for direct bucket access yet. Email support@aignostics.com. + +**A slide failed, or the whole analysis failed.** 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**. + +**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_ From 370bac27de82688046ec16fc70463a099e1ec1c0 Mon Sep 17 00:00:00 2001 From: omid-aignostics Date: Tue, 8 Sep 2026 13:17:21 +0200 Subject: [PATCH 02/11] docs: link "Invite your team" from all guides instead of embedding it Remove the inline invite section from the Library guide and the Platform overview, and give the Library and API guides the same "Where to go next" list as the Console guide, so the invite steps live on one page only. Co-Authored-By: Claude Opus 5 (1M context) --- README.md | 3 +-- docs/partials/README_platform.md | 3 +-- docs/partials/get_started_api.md | 5 +++++ docs/partials/get_started_library.md | 6 ++++-- 4 files changed, 11 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index e71887d9e..501cab9a6 100644 --- a/README.md +++ b/README.md @@ -322,8 +322,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 diff --git a/docs/partials/README_platform.md b/docs/partials/README_platform.md index ce8d977cd..42fb02f3e 100644 --- a/docs/partials/README_platform.md +++ b/docs/partials/README_platform.md @@ -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_api.md b/docs/partials/get_started_api.md index 8de675583..feac2cf10 100644 --- a/docs/partials/get_started_api.md +++ b/docs/partials/get_started_api.md @@ -283,3 +283,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_library.md b/docs/partials/get_started_library.md index 1c4501251..087b3564c 100644 --- a/docs/partials/get_started_library.md +++ b/docs/partials/get_started_library.md @@ -133,5 +133,7 @@ To make whole slide images available to the Aignostics Platform, you provide a s **You must provide the [required credentials](https://cloud.google.com/docs/authentication/application-default-credentials) for the Google Cloud Storage bucket.** -```{include} ../partials/_invite_your_team.md -``` +## Where to go next + +- {doc}`Invite your team ` โ€” add colleagues so they can run analyses too. +- {doc}`Library reference ` โ€” all public classes and functions. From eca66e3c9e5b0f14e1d3c17e00f348933edd037a Mon Sep 17 00:00:00 2001 From: omid-aignostics Date: Tue, 8 Sep 2026 13:19:01 +0200 Subject: [PATCH 03/11] docs: move "We take quality and security seriously" to Operational Excellence MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The paragraph describes how the SDK is built, not how to use it, and already pointed at the Operational Excellence page โ€” make it that page's introduction and take it off the README / docs home page. Co-Authored-By: Claude Opus 5 (1M context) --- OPERATIONAL_EXCELLENCE.md | 16 ++++++++++++++++ README.md | 20 -------------------- docs/partials/README_main.md | 20 -------------------- 3 files changed, 16 insertions(+), 40 deletions(-) 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 501cab9a6..b20726ffc 100644 --- a/README.md +++ b/README.md @@ -98,26 +98,6 @@ Once you've run your first analysis: - **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 diff --git a/docs/partials/README_main.md b/docs/partials/README_main.md index 8a7a6c328..e9beb62dd 100644 --- a/docs/partials/README_main.md +++ b/docs/partials/README_main.md @@ -81,23 +81,3 @@ 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 [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). From ff681cb3181d5d76da0083c9f36b9b3c3e89d130 Mon Sep 17 00:00:00 2001 From: omid-aignostics Date: Tue, 8 Sep 2026 13:19:24 +0200 Subject: [PATCH 04/11] docs: drop Troubleshooting bullet from Console guide's Where to go next The page stays in the Get started sidebar; no other guide links it inline. Co-Authored-By: Claude Opus 5 (1M context) --- docs/partials/get_started_console.md | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/partials/get_started_console.md b/docs/partials/get_started_console.md index 9be4d0aa2..5a9f6c392 100644 --- a/docs/partials/get_started_console.md +++ b/docs/partials/get_started_console.md @@ -168,7 +168,6 @@ That's it: you have analyzed your first slides with Atlas H&E-TME and have the r ## Where to go next - {doc}`Invite your team ` โ€” add colleagues so they can run analyses too. -- {doc}`Troubleshooting ` โ€” if something did not work as described. - **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: ```bash From a1ca3051cbfc0e0f16b6d55614acc86c24592207 Mon Sep 17 00:00:00 2001 From: omid-aignostics Date: Tue, 8 Sep 2026 13:24:08 +0200 Subject: [PATCH 05/11] docs: make Troubleshooting entries self-contained as a standalone page Name the command or Console screen each entry refers to instead of relying on the surrounding guide, and state the page's scope up front. Co-Authored-By: Claude Opus 5 (1M context) --- docs/partials/troubleshooting.md | 14 ++++++++------ 1 file changed, 8 insertions(+), 6 deletions(-) diff --git a/docs/partials/troubleshooting.md b/docs/partials/troubleshooting.md index f3df9b0de..ef2f44103 100644 --- a/docs/partials/troubleshooting.md +++ b/docs/partials/troubleshooting.md @@ -1,22 +1,24 @@ ## Troubleshooting +Common problems when following the {doc}`Console guide `, 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`. -**The install command failed.** Make sure you copied the whole line, 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`. +**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 your organization's private storage area on the Aignostics 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 are my slides in?** The folder is named after the user account on your computer โ€” run `whoami` in the terminal if you are unsure. `uvx aignostics bucket find` lists everything in your bucket. Subfolders inside your upload folder are preserved. +**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 during the upload.** The progress bar only fits in a wide terminal window; otherwise you see the per-file messages alone. The upload is running normally. +**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 start an analysis.** Run `uvx aignostics bucket find --detail` to confirm they arrived, and check you are browsing the right folder in Console. 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`. +**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`. -**The bucket keys are empty.** If `uvx aignostics user whoami` shows no keys under organization, your organization is not set up for direct bucket access yet. 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.** 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**. +**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**. **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. From d15e16665dc7f5d537435bb59c4dcb61a755fdbd Mon Sep 17 00:00:00 2001 From: omid-aignostics Date: Tue, 8 Sep 2026 13:24:56 +0200 Subject: [PATCH 06/11] docs: drop "System health checks" from the Python Library guide A getting-started guide should not explain what the library does not do; the system module remains documented in the Library reference. Co-Authored-By: Claude Opus 5 (1M context) --- docs/partials/get_started_library.md | 20 -------------------- 1 file changed, 20 deletions(-) diff --git a/docs/partials/get_started_library.md b/docs/partials/get_started_library.md index 087b3564c..ba13fecb4 100644 --- a/docs/partials/get_started_library.md +++ b/docs/partials/get_started_library.md @@ -57,26 +57,6 @@ application_run.download_to_folder("path/to/download/folder") See the [library reference](https://aignostics.readthedocs.io/en/latest/lib_reference.html) 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: - -```python -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] From 1b540c02956ae40a3854f9ebfd50a71ae74273f6 Mon Sep 17 00:00:00 2001 From: omid-aignostics Date: Tue, 8 Sep 2026 13:40:37 +0200 Subject: [PATCH 07/11] docs: rewrite Python Library guide to mirror the Console workflow Restructure the guide as the same first analysis as the Console guide, one snippet per step: install, log in (browser or refresh token), upload slides with computed metadata, start Atlas H&E-TME, follow the run state and per-slide outcomes, download results, list/cancel/clean up. Replace the placeholder test-app snippet, and move notebooks to "Where to go next". Also drop the "Step N:" prefixes from the API guide's login headings for consistency with the Console guide. Co-Authored-By: Claude Opus 5 (1M context) --- docs/partials/get_started_api.md | 8 +- docs/partials/get_started_library.md | 146 +++++++++++++-------------- 2 files changed, 76 insertions(+), 78 deletions(-) diff --git a/docs/partials/get_started_api.md b/docs/partials/get_started_api.md index feac2cf10..6f2a7fb8d 100644 --- a/docs/partials/get_started_api.md +++ b/docs/partials/get_started_api.md @@ -20,7 +20,7 @@ The API never sees your password. It accepts a short-lived **access token** โ€” 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 +37,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 +50,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`: @@ -136,7 +136,7 @@ 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 diff --git a/docs/partials/get_started_library.md b/docs/partials/get_started_library.md index ba13fecb4..07cccfde7 100644 --- a/docs/partials/get_started_library.md +++ b/docs/partials/get_started_library.md @@ -1,119 +1,117 @@ # 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 -Add the Aignostics Python SDK to your project. - -**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 +# or +pip install aignostics ``` -**With [pip](https://pip.pypa.io/en/stable/):** +## Log in + +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; the login is cached for future sessions. + +```python +from aignostics import platform + +client = platform.Client() +print(client.me().user.email) +``` + +For scripts that run without a browser โ€” on a server or in CI โ€” set a refresh token instead. Get one 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`: ```shell -pip install aignostics +AIGNOSTICS_REFRESH_TOKEN= ``` -## Usage +## Upload your slides -The following snippet shows how to use the client to submit an application run: +The platform reads each slide from your organization's private bucket, 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 pathlib import Path -# 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, - }, - ) - ], - ), - ], +from aignostics.application import Service as ApplicationService + +APPLICATION = "he-tme" +slides = Path("my-slides") + +metadata = ApplicationService.generate_metadata_from_source_directory( + slides, + APPLICATION, + mappings=[".*:staining_method=H&E,tissue=LUNG,disease=LUNG_CANCER"], ) -# wait for the results and download incrementally as they become available -application_run.download_to_folder("path/to/download/folder") -``` -See the [library reference](https://aignostics.readthedocs.io/en/latest/lib_reference.html) for all classes and methods. -## Example notebooks +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 + -> [!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. +ApplicationService.application_run_upload(APPLICATION, metadata, upload_progress_callable=remember_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): +`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. -```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 +## Start the analysis + +```python +run = ApplicationService().application_run_submit_from_metadata(APPLICATION, metadata, note="My first analysis") +print(run.run_id) ``` -> ๐Ÿ’ก You can also run a notebook inside the Aignostics Launchpad: select the run you want to inspect in the left sidebar and click **Marimo**. +Keep the `run_id`: it is how you find the analysis again later, in Python and in Console. -## Defining the input for an application run +## Follow the analysis -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. +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 +details = run.details() +print(details.state, details.termination_reason) -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: +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) +``` + +The analysis also appears under **My Application Runs** in [Console](https://platform.aignostics.com), where you can review the results in the viewer. + +## Download results ```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, - }, - ) - ], - ), -) +run.download_to_folder("results") ``` -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`. +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. -The `download_url` is a signed URL that allows the Aignostics Platform to download the image data during processing. +## List, cancel, or clean up -## Self-signed URLs for large files +```python +for r in client.runs.list(application_id=APPLICATION): + print(r.run_id, r.details().state) -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)). +run = client.run("") +run.cancel() # stop an analysis that is still running +run.delete() # remove a finished analysis and its results +``` -**You must provide the [required credentials](https://cloud.google.com/docs/authentication/application-default-credentials) for the Google Cloud Storage bucket.** +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. From 5784dce65b9c4330724f2e43b4946f1e163ef923 Mon Sep 17 00:00:00 2001 From: omid-aignostics Date: Tue, 8 Sep 2026 13:47:52 +0200 Subject: [PATCH 08/11] docs: move headless refresh-token setup out of the Library guide's Log in step A first analysis needs a browser login only; running without a browser is an alternative path, so it becomes a Troubleshooting entry instead. Co-Authored-By: Claude Opus 5 (1M context) --- docs/partials/get_started_library.md | 8 +------- docs/partials/troubleshooting.md | 4 +++- 2 files changed, 4 insertions(+), 8 deletions(-) diff --git a/docs/partials/get_started_library.md b/docs/partials/get_started_library.md index 07cccfde7..840d3339c 100644 --- a/docs/partials/get_started_library.md +++ b/docs/partials/get_started_library.md @@ -17,7 +17,7 @@ pip install aignostics ## Log in -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; the login is cached for future sessions. +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 @@ -26,12 +26,6 @@ client = platform.Client() print(client.me().user.email) ``` -For scripts that run without a browser โ€” on a server or in CI โ€” set a refresh token instead. Get one 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`: - -```shell -AIGNOSTICS_REFRESH_TOKEN= -``` - ## Upload your slides The platform reads each slide from your organization's private bucket, 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. diff --git a/docs/partials/troubleshooting.md b/docs/partials/troubleshooting.md index ef2f44103..e457538c2 100644 --- a/docs/partials/troubleshooting.md +++ b/docs/partials/troubleshooting.md @@ -1,6 +1,6 @@ ## Troubleshooting -Common problems when following the {doc}`Console guide `, and what to do about them. +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`. @@ -20,6 +20,8 @@ Common problems when following the {doc}`Console guide `, a **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. From 8d55e4bf1cd15e51cc4bfec117f3e8303e298ee2 Mon Sep 17 00:00:00 2001 From: omid-aignostics Date: Tue, 8 Sep 2026 13:48:24 +0200 Subject: [PATCH 09/11] docs: describe the bucket as provided by Aignostics, not as "private" Co-Authored-By: Claude Opus 5 (1M context) --- docs/partials/get_started_console.md | 2 +- docs/partials/get_started_library.md | 2 +- docs/partials/troubleshooting.md | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/partials/get_started_console.md b/docs/partials/get_started_console.md index 5a9f6c392..1a8d6c4ce 100644 --- a/docs/partials/get_started_console.md +++ b/docs/partials/get_started_console.md @@ -59,7 +59,7 @@ You stay logged in for future sessions. 3. Keep the terminal open until it prints `All files uploaded successfully!`. Slides are large, so this can take a while. -Your slides are now in your organization's private bucket, in a folder named after your computer's user account, for example `jdoe`. +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`. ### 4. (Optional) Copy slides from your own cloud bucket diff --git a/docs/partials/get_started_library.md b/docs/partials/get_started_library.md index 840d3339c..dc446febb 100644 --- a/docs/partials/get_started_library.md +++ b/docs/partials/get_started_library.md @@ -28,7 +28,7 @@ print(client.me().user.email) ## Upload your slides -The platform reads each slide from your organization's private bucket, 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. +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 pathlib import Path diff --git a/docs/partials/troubleshooting.md b/docs/partials/troubleshooting.md index e457538c2..08a1e04d4 100644 --- a/docs/partials/troubleshooting.md +++ b/docs/partials/troubleshooting.md @@ -6,7 +6,7 @@ Common problems when following the getting-started guides, and what to do about **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 your organization's private storage area on the Aignostics 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. +**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. From e2ff24941c86b4930565ca064efbe10d95cf124a Mon Sep 17 00:00:00 2001 From: omid-aignostics Date: Tue, 8 Sep 2026 17:28:39 +0200 Subject: [PATCH 10/11] docs: number the steps in the Library and API guides like the Console guide Same two parts (Upload your slides, Analyze your slides with Atlas H&E-TME) and numbered steps in all three getting-started guides. Co-Authored-By: Claude Opus 5 (1M context) --- docs/partials/get_started_api.md | 28 ++++++++++++++++------------ docs/partials/get_started_library.md | 18 +++++++++++------- 2 files changed, 27 insertions(+), 19 deletions(-) diff --git a/docs/partials/get_started_api.md b/docs/partials/get_started_api.md index 6f2a7fb8d..9f9d38680 100644 --- a/docs/partials/get_started_api.md +++ b/docs/partials/get_started_api.md @@ -7,20 +7,22 @@ This guide covers one full workflow with plain HTTP calls โ€” authenticate, anal ```{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. -### 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). -### 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. -### 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`. @@ -138,7 +140,7 @@ 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 โ€” 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. @@ -225,7 +229,7 @@ A `201` returns `{"run_id": "..."}` โ€” the handle you follow the analysis with, 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 diff --git a/docs/partials/get_started_library.md b/docs/partials/get_started_library.md index dc446febb..4a5f3ec57 100644 --- a/docs/partials/get_started_library.md +++ b/docs/partials/get_started_library.md @@ -5,7 +5,9 @@ The **Aignostics Python Library** lets you use the Aignostics Platform from your ```{include} ../partials/_get_started_signup.md ``` -## Install the library +## Upload your slides + +### 1. Install the library Add the Aignostics Python SDK to your project with [uv](https://docs.astral.sh/uv/) or [pip](https://pip.pypa.io/en/stable/): @@ -15,7 +17,7 @@ uv add aignostics pip install aignostics ``` -## Log in +### 2. Log in 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. @@ -26,7 +28,7 @@ client = platform.Client() print(client.me().user.email) ``` -## Upload your slides +### 3. Upload your slides 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. @@ -56,7 +58,9 @@ ApplicationService.application_run_upload(APPLICATION, metadata, upload_progress `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. -## Start the analysis +## Analyze your slides with Atlas H&E-TME + +### 4. Start the analysis ```python run = ApplicationService().application_run_submit_from_metadata(APPLICATION, metadata, note="My first analysis") @@ -65,7 +69,7 @@ print(run.run_id) Keep the `run_id`: it is how you find the analysis again later, in Python and in Console. -## Follow the analysis +### 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. @@ -83,7 +87,7 @@ for item in run.results(): The analysis also appears under **My Application Runs** in [Console](https://platform.aignostics.com), where you can review the results in the viewer. -## Download results +### 6. Download results ```python run.download_to_folder("results") @@ -91,7 +95,7 @@ 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. -## List, cancel, or clean up +### 7. List, cancel, or clean up ```python for r in client.runs.list(application_id=APPLICATION): From e15082f0c41307b9aa93d5ab768580a269403170 Mon Sep 17 00:00:00 2001 From: omid-aignostics Date: Tue, 8 Sep 2026 17:47:47 +0200 Subject: [PATCH 11/11] docs: drop duplicate FAQ entry from the hidden Launchpad guide The entry now lives on the Troubleshooting page. Co-Authored-By: Claude Opus 5 (1M context) --- docs/partials/get_started_launchpad.md | 7 ------- 1 file changed, 7 deletions(-) diff --git a/docs/partials/get_started_launchpad.md b/docs/partials/get_started_launchpad.md index fe6aa956b..9a6281a31 100644 --- a/docs/partials/get_started_launchpad.md +++ b/docs/partials/get_started_launchpad.md @@ -136,13 +136,6 @@ Your slide appears in QuPath with the analysis annotations layered on top โ€” ti ## Troubleshooting -
-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`. - -
-
How do I find Terminal or PowerShell?