diff --git a/CLAUDE.md b/CLAUDE.md index bec4072bf..444b96412 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -516,7 +516,7 @@ Some modules have conditional loading based on dependencies: * 5-minute refresh buffer before expiry * OAuth 2.0 device flow -### SDK Metadata System (ENHANCED - Run v0.0.4, Item v0.0.3) +### SDK Metadata System (ENHANCED - Run v0.0.6, Item v0.0.3) **Automatic Run & Item Tracking**: Every application run and item submitted through the SDK automatically includes comprehensive metadata about the execution context, with support for tags and timestamps. @@ -526,7 +526,7 @@ Some modules have conditional loading based on dependencies: * **Environment Detection**: Automatically detects script/CLI/GUI and user/test/bridge contexts * **CI/CD Integration**: Captures GitHub Actions workflow information and pytest test context * **User Information**: Includes authenticated user and organization details -* **Schema Validation**: Pydantic-based validation with JSON Schema (Run: v0.0.4, Item: v0.0.3) +* **Schema Validation**: Pydantic-based validation with JSON Schema (Run: v0.0.6, Item: v0.0.3) * **Versioned Schema**: Published JSON Schema at `docs/source/_static/sdk_{run|item}_custom_metadata_schema_*.json` * **Tags Support** (NEW): Associate runs and items with searchable tags * **Timestamps** (NEW): Track creation and update times (`created_at`, `updated_at`) @@ -577,7 +577,7 @@ aignostics application run list --tags experiment-1,batch-A * Integration: Automatic in `platform.resources.runs.submit()` * User Agent: Enhanced `utils.user_agent()` with CI/CD context * Tests: Comprehensive test suite in `tests/aignostics/platform/sdk_metadata_test.py` -* **Schema Files**: `sdk_run_custom_metadata_schema_v0.0.4.json` and `sdk_item_custom_metadata_schema_v0.0.3.json` +* **Schema Files**: `sdk_run_custom_metadata_schema_v0.0.6.json` and `sdk_item_custom_metadata_schema_v0.0.3.json` See `platform/CLAUDE.md` for detailed documentation. diff --git a/README.md b/README.md index b728aa1cc..148702ff5 100644 --- a/README.md +++ b/README.md @@ -13,177 +13,10 @@ [![Coverage](https://codecov.io/gh/aignostics/python-sdk/graph/badge.svg?token=SX34YRP30E)](https://codecov.io/gh/aignostics/python-sdk) [![Uptime](https://uptime.betterstack.com/status-badges/v2/monitor/1wbqa.svg)](https://aignostics.betteruptime.com) -## Introduction - -The **Aignostics Python SDK** provides multiple ways to interact with the **Aignostics Platform** for running advanced computational pathology applications like [Atlas H&E-TME](https://www.aignostics.com/products/he-tme-profiling-product), which analyzes tumor microenvironments in H&E-stained tissue samples. - -### 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). - -## Installation - -The **Aignostics Python SDK** can be installed via the [uv package manager](https://docs.astral.sh/uv/). The installation process sets up the SDK along with the necessary dependencies, including the **uv** package manager itself if not already present. - -Before proceeding, ensure you have an **Aignostics Platform account**. You can get access either through your organization admin (if your organization has an Aignostics account) or directly from Aignostics. Check your email for an invitation before proceeding. - -### Requirements - -- **Python 3.11, 3.12, 3.13, or 3.14** -- **macOS 11.0+, Linux, or Windows** -- **Homebrew** (only if you previously installed `uv` via Homebrew) - -### Installation Steps - -The installation will: - -1. Install or update **uv** (Python package installer) -2. Install the **Aignostics Python SDK** (includes Launchpad, CLI, and Python Library) - -Copy and paste the appropriate command below into your terminal (macOS/Linux) or PowerShell (Windows): - -**Linux/macOS:** - -```bash -if ! command -v uv &> /dev/null; then - echo "uv not found, installing..." - curl -LsSf https://astral.sh/uv/install.sh | sh - source $HOME/.local/bin/env -else - UV_VERSION=$(uv --version | cut -d' ' -f2) - if [ "$(printf '%s\n' "0.6.17" "$UV_VERSION" | sort -V | head -n1)" != "0.6.17" ]; then - echo "Updating uv to the latest version..." - UV_PATH=$(which uv) - if [[ "$UV_PATH" == *"brew"* ]]; then - echo "Updating uv using Homebrew..." - brew upgrade uv - else - echo "Updating uv using the installer..." - uv self update - fi - else - echo "uv is up to date" - fi -fi -``` - -**Windows (PowerShell):** - -```powershell -winget install --id=Microsoft.VCRedist.2015+.x64 -e -powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex" -``` - -Verify your installation by running: - -```bash -uvx aignostics --help -``` - -You should see the Aignostics CLI help output. - -You can then proceed by choosing your preferred user interface below. - -## Platform Workflow Overview - -The Aignostics Platform delivers enterprise-grade computational pathology through a secure, scalable cloud architecture. Organizations subscribe to the platform, and their users interact through three interfaces - all part of the Python SDK - to leverage advanced AI/ML models running on dedicated NVIDIA® GPU infrastructure. - -**Key architectural components:** - -- **Python SDK**: Provides three user interfaces (Launchpad desktop app, CLI, and Client Library) with unified functionality -- **Enterprise authentication**: Powered by Auth0, supporting Single Sign-On (SSO) and existing identity management systems -- **Organization storage**: Dedicated Google Cloud Storage bucket per organization with automatic 30-day cleanup -- **Aignostics Platform API**: Orchestrates application discovery, run submission, status monitoring, and results delivery -- **NVIDIA® GPU clusters**: Dedicated compute provisioned per application run for maximum security and compliance - -```mermaid -%%{init: {'theme':'dark', 'themeVariables': { 'fontSize':'18px', 'fontFamily':'arial', 'darkMode':'true', 'background':'#1e1e1e', 'primaryColor':'#4a4a4a', 'primaryTextColor':'#ffffff', 'primaryBorderColor':'#ffffff', 'lineColor':'#ffffff', 'secondaryColor':'#3a3a3a', 'tertiaryColor':'#2a2a2a', 'actorBkg':'#4a4a4a', 'actorBorder':'#ffffff', 'actorTextColor':'#ffffff', 'actorLineColor':'#ffffff', 'signalColor':'#ffffff', 'signalTextColor':'#ffffff', 'labelBoxBkgColor':'#3a3a3a', 'labelBoxBorderColor':'#ffffff', 'labelTextColor':'#ffffff', 'noteBkgColor':'#4a4a4a', 'noteTextColor':'#ffffff', 'noteBorderColor':'#ffffff', 'sequenceNumberColor':'#000000'}}}%% -sequenceDiagram - autonumber - actor User as User
(Organization Member) - participant SDK as Python SDK
(Launchpad/CLI/Client Library) - participant Auth0 as Auth0
(Enterprise Identity) - participant Bucket as Organization Bucket
(Google Cloud Storage) - participant API as Aignostics Platform API - participant GPU as NVIDIA® GPU Cluster
(per-run isolation) - - Note over User,GPU: Authentication & Authorization - User->>SDK: Launch interface - SDK->>Auth0: Authenticate user - Auth0-->>SDK: Access token - SDK->>API: Validate token - API-->>SDK: User authorized - - Note over User,GPU: Application Selection - User->>SDK: Browse applications - SDK->>API: List applications & versions - API-->>SDK: Application catalog - SDK-->>User: Display options - - Note over User,GPU: Data Upload - User->>SDK: Select WSIs + metadata - SDK->>Bucket: Upload files - Note over Bucket: 30-day auto-cleanup - Bucket-->>SDK: Upload complete - SDK->>SDK: Generate signed download URLs - - Note over User,GPU: Run Submission - SDK->>API: Submit run (app, metadata, signed URLs) - API-->>SDK: Run ID + queue position - SDK-->>User: Confirm submission - - Note over User,GPU: GPU Processing - API->>GPU: Provision dedicated NVIDIA® cluster - GPU->>Bucket: Download WSIs via signed URLs - GPU->>GPU: Process slides incrementally - GPU->>API: Upload results per slide - Note over GPU: Deprovision after completion - - Note over User,GPU: Status Monitoring & Results - User->>SDK: Check status - SDK->>API: Poll run status - API-->>SDK: Progress (e.g., "3 of 10 complete") - SDK-->>User: Display progress - User->>SDK: Download results - SDK->>API: Request result URLs - API-->>SDK: Signed download URLs - SDK->>API: Download files (GeoJSON, CSV, TIFF) - SDK-->>User: Results ready for inspection -``` - -**How it works:** - -Organizations subscribe to the Aignostics Platform and receive dedicated infrastructure including a Google Cloud Storage bucket and API access. Users within the organization authenticate through Auth0, which integrates with enterprise identity management systems for seamless Single Sign-On (SSO). - -The Python SDK - available as a desktop application (Launchpad), command-line interface (CLI), or programmable library (Client Library) - handles all complexity of authentication, data upload, run orchestration, and results delivery. Users simply select an application, provide whole slide images with metadata, and submit. - -Behind the scenes, the Aignostics Platform API provisions dedicated NVIDIA® GPU clusters for each application run, ensuring data isolation and compliance with healthcare regulations. Processing occurs incrementally (slide-by-slide), allowing users to monitor progress and download results as they become available rather than waiting for entire cohorts. +## Introduction -The organization's Google Cloud Storage bucket stores uploaded files with automatic 30-day cleanup, optimizing costs while maintaining data availability throughout processing. All data transfers use time-limited signed URLs, eliminating credential management complexity and security risks. - -**Enterprise benefits:** - -- **Security & compliance**: Per-run GPU isolation, enterprise SSO integration, zero-trust architecture with signed URLs -- **Scalability**: Handles single exploratory slides through thousand-slide clinical studies with identical user experience -- **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 +The **Aignostics Platform** runs computational pathology applications — such as [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 whole slide images. The **Aignostics Python SDK** is how you work with it, through the interfaces below. ## Choose your interface @@ -196,7 +29,7 @@ Choose your preferred interface for working with the Aignostics Platform. Each i | **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** | Install and run your first analysis | +| **Get started** | Get started with Launchpad | ### ⌨️ CLI (Command-Line Interface) @@ -205,7 +38,7 @@ Choose your preferred interface for working with the Aignostics Platform. Each i | **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** | Manage datasets and application runs from your terminal | +| **Get started** | Get started with the CLI | ### 📚 Python Library @@ -214,7 +47,7 @@ Choose your preferred interface for working with the Aignostics Platform. Each i | **What it is** | Python library for programmatic access in scripts, notebooks, and applications | | **Best for** | Data scientists and developers who want to integrate the platform into Python-based workflows | | **Use when** | Building custom analysis pipeline in Python for repeated usage and processing large datasets (10s-1000s of slides) | -| **Get started** | Run example notebooks or call the Aignostics Platform API from your Python scripts | +| **Get started** | Get started with the Python Library | ### 🤖 MCP Server (AI Agent Integration) @@ -223,454 +56,41 @@ Choose your preferred interface for working with the Aignostics Platform. Each i | **What it is** | Model Context Protocol server that exposes SDK functionality to AI agents like Claude | | **Best for** | Users who want AI assistants to help with platform operations | | **Use when** | Working with Claude Desktop or other MCP-compatible AI tools to manage datasets, submit runs, or query results | -| **Get started** | Configure Claude Desktop for MCP integration | - -> 💡 Launchpad and CLI handle authentication automatically. Python Library requires manual setup (see [authentication section](#example-notebooks-interact-with-the-aignostics-platform-from-your-python-notebook-environment)). - -## Launchpad: Run your first computational pathology analysis in 10 minutes from your desktop - -The **Aignostics Launchpad** is a graphical desktop application that allows you to run applications on whole slide images (WSIs) from your computer, and inspect results with QuPath and Python Notebooks with one click. It is designed to be user-friendly and intuitive, for use by Research Pathologists and Data Scientists. - -**New to Launchpad?** See Installation section above to get started. - -### Running Your First Analysis - -This tutorial uses [Atlas H&E-TME](https://www.aignostics.com/products/he-tme-profiling-product) with a public lung cancer dataset from the NCI Image Data Commons. - -**Step 1: Start Aignostics Launchpad** - -1. Open a terminal or command prompt -2. Run the command: `uvx aignostics launchpad` -This starts the Launchpad application. - -**Step 2: Download a Sample Dataset** +| **Get started** | Get started with the MCP Server | -1. Click the menu icon (☰) in the top right corner -2. Click "Download Datasets". The system displays the dataset download interface. -3. Click "EXAMPLE DATASET". The system populates the dataset ID field with a TCGA lung adenocarcinoma sample. -4. Click "DATA". The system shows a folder selection dialog. -5. Click "OK" -6. Click "DOWNLOAD". The system downloads the DICOM dataset. A progress indicator shows download status. -7. Click the menu icon and select "Run Applications" - -**Step 3: Select Atlas H&E-TME** - -1. Click "Atlas H&E-TME" in the left sidebar. The system displays the application workflow with six steps. -2. Click the version dropdown to view available versions. The system shows all available versions with release notes accessible via the "RELEASE NOTES" button. -3. Keep the default version (latest) -4. Click "NEXT" - -**Step 4: Select Slides and Provide Metadata** - -1. Click "DATA". The system opens a folder selection dialog showing the Launchpad datasets directory. -2. Navigate to the downloaded dataset folder (e.g., `/datasets/idc/tcga_luad/`) -3. Click "OK". The system displays the selected folder path and scans the folder, showing a table with all compatible slides. Each row shows thumbnail preview, technical metadata (file size, MPP resolution, dimensions), and status indicators. -4. The system automatically extracts technical file metadata. You must provide the required medical metadata by double-clicking the red cells in the "Tissue" column. The system displays a dropdown menu with tissue types. -5. Select the tissue type (e.g., "LUNG") and disease (e.g., "LUNG_CANCER") by double-clicking in the red cells and selecting the value from the dropdown. The system marks these cells green indicating valid metadata. -6. Review the "Staining" column. The system shows "H&E" if this information was extracted from the DICOM file. -7. Click "NEXT" - -**Step 5: Add Notes and Tags (Optional)** - -1. The system displays the notes and tags screen. -2. Enter an optional note in the text field (e.g., "TCGA lung sample analysis") -3. Add optional tags by typing and pressing Enter (e.g., "TCGA", "lung") -4. Click "NEXT" - -**Step 6: Set Schedule (Optional)** - -1. The system displays scheduling options with soft due date and hard deadline pickers. -2. Click "NEXT" to leave the default settings. - -The soft due date indicates when the platform will attempt to complete processing. The hard deadline is when the platform may cancel the run if resources are unavailable. - -**Step 7: Submit Your Run** - -1. The system displays the submission screen showing number of slides to be analyzed, full file paths, and upload and submit button. -2. Review the slide information -3. Click "UPLOAD AND SUBMIT". The system uploads your slides to the Aignostics Platform and submits the analysis run. A progress indicator shows upload status. - -The left sidebar now shows your submitted run with application name and version, submission timestamp, running status icon (🏃), and any tags you added. - -**Step 8: Monitor Your Run** - -Atlas H&E-TME processing time depends on slide size and system load. Depending on the file size and the number of files, processing can take minutes to many hours. - -Click on your run in the sidebar to view run details and metadata, slide thumbnails, and processing status for each slide. The status icon updates as processing progresses. - -### Understanding Your Results - -When processing completes, Atlas H&E-TME provides comprehensive tumor microenvironment analysis results for each processed slide: - -**What You'll Receive:** - -- **Tissue analysis**: Identification of tissue regions (tumor, stroma, necrosis, etc.) with quality assessment in GeoJSON format -- **Cell analysis**: Individual cells detected and classified by type (tumor cells, immune cells, stromal cells, etc.) in GeoJSON format -- **Visual segmentation maps**: Color-coded images showing spatial distribution of tissue and cell types -- **Quantitative measurements**: Cell counts, densities, spatial relationships, and statistical summaries provided in CSV format - -**Downloading Results:** - -When processing completes, the status icon changes to show completion. To download results: - -1. Click the "Download Results" button -2. The system downloads a ZIP file containing all outputs to your computer - -**Inspecting Results in QuPath:** - -QuPath integration provides the most powerful way to visualize and interact with your results: - -1. Click "Open in QuPath" (requires QuPath extension - see Advanced Setup below) -2. The system automatically creates a QuPath project with your slides and annotations loaded -3. In QuPath, you can: - - View tissue and cell annotations overlaid on your slides - - Explore cell classifications and measurements - - Analyze spatial relationships between different cell types - - Export annotations or perform additional analysis - -**Congratulations!** You have successfully downloaded a public dataset, submitted an Atlas H&E-TME analysis run, and learned how to access and inspect your results. - -### System Health Checks - -The Launchpad automatically monitors system health before allowing run submissions. If the system is unhealthy (e.g., network connectivity issues, authentication problems, or platform unavailability), the submission workflow is blocked: - -- A tooltip displays "System is unhealthy, you cannot prepare a run at this time." -- The "Next" button in the application workflow is disabled. -- The health status is shown in the footer bar at the bottom of the Launchpad. - -To resolve health issues: - -1. Check the health status indicator in the footer bar -2. Click "Info and Settings" in the menu to see detailed health information -3. Verify your network connection and authentication status -4. Check the [Aignostics Platform Status](https://status.aignostics.com) page - -### Advanced Setup: Extensions - -> 💡 The Launchpad features a growing ecosystem of extensions that seamlessly integrate with standard digital pathology tools. To use the Launchpad with all available extensions, run `uvx --from "aignostics[qupath,marimo]" aignostics launchpad`. Currently available extensions are: -> -> 1. **QuPath extension**: View your application results in [QuPath](https://qupath.github.io/) with a single click. The Launchpad creates QuPath projects on-the-fly. -> 2. **Marimo extension**: Analyze your application results using [Marimo](https://marimo.io/) notebooks embedded in the Launchpad. You don't have to leave the Launchpad to do real data science. - -## CLI: Manage datasets and application runs from your terminal - -The Python SDK includes the **Aignostics CLI**, a Command-Line Interface (CLI) that allows you to -interact with the Aignostics Platform directly from your terminal or shell script. - -**New to CLI?** See Installation section above to get started. - -**Common workflows:** - -- Download public datasets from NCI Image Data Commons -- Submit batch processing runs for multiple slides -- Monitor run status and download results incrementally -- Automate repetitive tasks with shell scripts - -See as follows for a simple example where we download a sample dataset for the [Atlas -H&E-TME application](https://www.aignostics.com/products/he-tme-profiling-product), submit an application run, and download the results. - -### Example: Running Atlas H&E-TME with CLI - -1. Open a terminal or command prompt -2. Use the following commands to run the Atlas H&E-TME application on a sample dataset: - -```shell -# Download a sample dataset from the NCI Image Data Commons (IDC) portal to your current working directory -# As the dataset id refers to the TCGA LUAD collection, this creates a directory tcga_luad with the DICOM files -uvx aignostics dataset idc download 1.3.6.1.4.1.5962.99.1.1069745200.1645485340.1637452317744.2.0 data/ -# Prepare the metadata for the application run by creating a metadata.csv, extracting -# the required metadata from the DICOM files. We furthermore add the required -# information about the tissue type and disease. -uvx aignostics application run prepare he-tme data/tcga_luad/run.csv data/ -# Edit the metadata.csv to insert the required information about the staining method, tissue type and disease -# Adapt to your favourite editor -nano tcga_luad/metadata.csv -# Upload the metadata.csv and referenced whole slide images to the Aignostics Platform -uvx aignostics application run upload he-tme data/tcga_luad/run.csv -# Submit the application run and print the run id -uvx aignostics application run submit he-tme data/tcga_luad/run.csv -# Check the status of the application run you submitted -uvx aignostics application run list -# Incrementally download results when they become available -# Fill in the id from the output in the previous step -uvx aignostics application run result download APPLICATION_RUN_ID -``` +> 💡 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. -For convenience the `application run execute` command combines preparation, upload, submission and download. -The below is equivalent to the above, while adding additionally required metadata using a mapping: - -```shell -uvx aignostics dataset idc download 1.3.6.1.4.1.5962.99.1.1069745200.1645485340.1637452317744.2.0 data/ -uvx aignostics application run execute he-tme data/tcga_luad/run.csv data/ --mapping ".*\.dcm:staining_method=H&E,tissue=LUNG,disease=LUNG_CANCER" -``` - -The CLI provides extensive help: - -```shell -uvx aignostics --help # list all spaces such as application, dataset, bucket and system, -uvx aignostics application --help # list subcommands in the application space -uvx aignostics application run --help # list subcommands in the application run sub-space -uvx aignostics application run list --help # show help for specific command -uvx aignostics application run execute --help # show help for another command -``` - -Check out our -[CLI reference documentation](https://aignostics.readthedocs.io/en/latest/cli_reference.html) -to learn about all commands and options available. - -### System Health Checks - -The CLI automatically checks system health before uploading slides or submitting runs. If the system is unhealthy, the operation is blocked and an error message is displayed: - -``` -Error: Platform is not healthy: . Aborting. -``` - -To override this behavior (not recommended for production use), add the `--force` flag: - -```shell -uvx aignostics application run upload he-tme metadata.csv --force -uvx aignostics application run submit he-tme metadata.csv --force -uvx aignostics application run execute he-tme metadata.csv data/ --force -``` - -To manually check system health before running commands: - -```shell -uvx aignostics system health -``` - -## Python Library: Call the Aignostics Platform API from your Python scripts - -The Python SDK includes the *Aignostics Python Library* for integration with your Python codebase. - -**New to Python Library?** See Installation section above to get started. - - - -### Installation - -Add the Aignostics Python SDK to your Python project: - -**Install with [uv](https://docs.astral.sh/uv/):** - -```shell -uv add aignostics -``` - -**Install with [pip](https://pip.pypa.io/en/stable/):** - -```shell -# Add Python SDK as dependency to your project -pip install aignostics -``` - -#### Usage - -The following snippet shows how to use the Client to submit an application -run: - -```python -from aignostics import platform - -# initialize the client -client = platform.Client() -# submit an application run -application_run = client.runs.submit( - application_id="test-app", - items=[ - platform.InputItem( - external_id="slide-1", - input_artifacts=[ - platform.InputArtifact( - name="whole_slide_image", - download_url="", - metadata={ - "checksum_base64_crc32c": "AAAAAA==", - "resolution_mpp": 0.25, - "width_px": 1000, - "height_px": 1000, - }, - ) - ], - ), - ], -) -# wait for the results and download incrementally as they become available -application_run.download_to_folder("path/to/download/folder") -``` - -Please look at the notebooks in the `example` folder for a more detailed example -and read the -[client reference documentation](https://aignostics.readthedocs.io/en/latest/lib_reference.html) -to learn about all classes and methods. - -### System Health Checks - -The low-level Python SDK does **not** perform automated health checks before operations. If health verification is required for your use case, you should implement checks 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 design gives you full control over health check behavior, allowing you to: - -- Implement custom retry logic for transient failures -- Log health status for monitoring and debugging -- Gracefully handle unhealthy states in your application - -### Example Notebooks: Interact with the Aignostics Platform from your Python Notebook environment - -> [!IMPORTANT] -> Before you get started, you need to set up your authentication credentials if -> you did not yet do so! Please visit -> [your personal dashboard on the Aignostics Platform website](https://platform.aignostics.com/getting-started/quick-start) -> and follow the steps outlined in the `Use in Python Notebooks` section. - -The Python SDK includes ready-to-use Marimo notebooks that demonstrate platform interaction patterns. These notebooks are ideal for: - -- Learning the API through interactive examples -- Prototyping custom analysis workflows -- Integrating with existing data science pipelines - -The example notebooks use our "Test Application" (free for all users). To run them, -please follow the steps outlined in the snippet below to clone this repository and start the -[Marimo](https://marimo.io/) -([examples/notebook.py](https://github.com/aignostics/python-sdk/blob/main/examples/notebook.py)) -notebook: - -```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 -# show marimo example notebook in the browser -uv run marimo edit examples/notebook.py -``` - -> 💡 You can also run a notebook within the Aignostics Launchpad. To do so, select the -> Run you want to inspect in the left sidebar, and click the button "Open in Python Notebook". - -### Defining the input for an application run - -The following sections provide technical details for advanced use cases. These examples use the "Test Application" - a free application available to all users for testing and development purposes. - -When creating an application run, you need to specify the `application_id` and optionally the -`application_version` (version number) of the application you want to run. If you omit the version, -the latest version will be used automatically. Additionally, you need to define the input items you -want to process in the run. The input items are defined as follows: - -```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, - }, - ) - ], - ), -) -``` - -For each item you want to process, you need to provide a unique `reference` -string. This is used to identify the item in the results later on. The -`input_artifacts` field is a list of `InputArtifact` objects, which defines what -data & metadata you need to provide for each item. The required artifacts depend -on the application version you want to run - in the case of test application, -there is only one artifact required, which is the image to process on. The -artifact name is defined as `whole_slide_image` for this application. - -The `download_url` is a signed URL that allows the Aignostics Platform to -download the image data later during processing. - -### Self-signed URLs for large files - -To make the whole slide images you want to process available to the Aignostics Platform, you -need to provide a signed URL that allows the platform to download the data. -Self-signed URLs for files in google storage buckets can be generated using the -`generate_signed_url` -([code](https://github.com/aignostics/python-sdk/blob/407e74f7ae89289b70efd86cbda59ec7414050d5/src/aignostics/client/utils.py#L85)). - -**We expect that you provide the -[required credentials](https://cloud.google.com/docs/authentication/application-default-credentials) -for the Google Storage Bucket** - -## MCP Server: Integrate with AI Agents - -The Python SDK includes an MCP (Model Context Protocol) server that exposes SDK functionality to AI agents like Claude. This enables AI assistants to help you interact with the Aignostics Platform through natural conversation. - -### Quick Start with Claude Desktop - -Add the following to your Claude Desktop configuration file: - -**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json` -**Windows**: `%APPDATA%\Claude\claude_desktop_config.json` - -```json -{ - "mcpServers": { - "aignostics": { - "command": "uvx", - "args": ["aignostics", "mcp", "run"] - } - } -} -``` - -Restart Claude Desktop after adding this configuration. - -### CLI Commands - -```bash -# Using uvx (no installation required) -uvx aignostics mcp run -uvx aignostics mcp list-tools -``` - -### Using Plugins - -The MCP server supports plugins that extend its functionality with additional tools. To run the MCP server with a plugin installed: - -```bash -# With a local plugin -uv run --with /path/to/plugin aignostics mcp run +## Next Steps -# With a plugin from a git repository -uvx --with git+ssh://git@github.com/org/plugin aignostics mcp run -``` +The best next step is to **run your first analysis** end to end. -Plugins register themselves via Python entry points and their tools are automatically discovered and namespaced by the MCP server. +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. -### What AI Agents Can Do +Once you've run your first analysis: -Once configured, AI agents can help you with platform operations through natural language, with access to tools from the SDK and any installed plugins. +- **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). +- **Get support**: Contact [support@aignostics.com](mailto:support@aignostics.com) or browse the [full documentation](https://aignostics.readthedocs.io/en/latest/). -## Next Steps +## We take quality and security seriously -Now that you have an overview of the Aignostics Python SDK and its interfaces, here are some recommended next steps to deepen your understanding and get the most out of the platform: - -- **Understand the platform**: Read the [Aignostics Platform Overview](platform_overview.md) to learn about architecture and core concepts -- **Review detailed documentation**: 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) -- **Explore QuPath integration**: Use the QuPath extension to visualize and interact with your results -- **Get support**: Contact [support@aignostics.com](mailto:support@aignostics.com) or check the [full documentation](https://aignostics.readthedocs.io/en/latest/) +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 @@ -726,23 +146,24 @@ Once registered to the Platform, your organization will automatically gain acces To trigger the application run, users can use the Aignostics Launchpad, Aignostics CLI, Example Notebooks, our Client Library, or directly call the REST API. The platform expects the user payload, containing the metadata and the signed URLs to the whole slide images (WSIs). The detailed requirements of the payload depend on the application and are described in the documentation, and accessible via the Info button in the Launchpad, as well as via the CLI and `/v1/applications` endpoint in the API. -When the application run is created, it can be in one of the following states: +When the application run is created, it progresses through three states: -1. **received**: the application run received from the client -2. **scheduled**: the application run request is valid and is scheduled for execution -3. **running**: the application run execution started -4. **completed**: the application run execution is done and all outputs are available for download -5. **completed**: the application run execution is done, but some items end up in the failed state -6. **rejected**: the application run request is rejected before it is scheduled -7. **cancelled by the system**: the application run failed during the execution with the number of errors higher than the threshold -9. **cancelled by the user**: the application run is cancelled by the user before it is finished +1. **pending**: the application run has been received and is waiting to start processing +2. **processing**: the application run is being executed; results for individual slides become available as they complete +3. **terminated**: the application run has finished + +A terminated run carries a *termination reason* explaining the outcome: + +- **all items processed**: every slide was processed (individual slides may still have failed — check the per-slide results) +- **canceled by the user**: the run was canceled by the user before it finished +- **canceled by the system**: the run was stopped by the platform, for example when the number of failed slides exceeded the allowed threshold The status and operations of an application run are private to the user who triggered the run. ### Results When the processing of whole slide image is successfully completed, the resulting outputs become available for download. To assess specifics of application outputs please consult our application specific documentation, which you can find in the **Console**. Please note that you access to documentation is restricted to those applications your organisation subscribed to. -Application run outputs are automatically deleted 30 days after the application run has completed. However, the owner of the application run (the user who initiated it) can use the API to manually delete outputs earlier, once the run has reached a final state - completed, cancelled by the system or cancelled by the user. The Launchpad and CLI provide enable to delete results with one click resp. command. +Application run outputs are automatically deleted 30 days after the application run has terminated. However, the owner of the application run (the user who initiated it) can use the API to manually delete outputs earlier, once the run has terminated. The Launchpad and CLI let you delete results with one click or one command, respectively. ### Quotas Every organization has a limit on how many WSIs it can process in a calendar month. The following quotas exist: @@ -775,10 +196,95 @@ For integration with programming languages other than Python, you can use the RE ### Cost -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 cancelled, either by the system or by the user, only processed images incur a cost. +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. +### Platform workflow + +The Aignostics Platform delivers enterprise-grade computational pathology through a secure, scalable cloud architecture. Organizations subscribe to the platform, and their users interact through multiple interfaces - all part of the Python SDK - to leverage advanced AI/ML models running on dedicated NVIDIA® GPU infrastructure. + +**Key architectural components:** + +- **Python SDK**: Provides multiple interfaces (Launchpad desktop app, CLI, Python Library, and MCP server) with unified functionality +- **Enterprise authentication**: Powered by Auth0, supporting Single Sign-On (SSO) and existing identity management systems +- **Organization storage**: Dedicated Google Cloud Storage bucket per organization with automatic 30-day cleanup +- **Aignostics Platform API**: Orchestrates application discovery, run submission, status monitoring, and results delivery +- **NVIDIA® GPU clusters**: Dedicated compute provisioned per application run for maximum security and compliance + +```mermaid +%%{init: {'theme':'dark', 'themeVariables': { 'fontSize':'18px', 'fontFamily':'arial', 'darkMode':'true', 'background':'#1e1e1e', 'primaryColor':'#4a4a4a', 'primaryTextColor':'#ffffff', 'primaryBorderColor':'#ffffff', 'lineColor':'#ffffff', 'secondaryColor':'#3a3a3a', 'tertiaryColor':'#2a2a2a', 'actorBkg':'#4a4a4a', 'actorBorder':'#ffffff', 'actorTextColor':'#ffffff', 'actorLineColor':'#ffffff', 'signalColor':'#ffffff', 'signalTextColor':'#ffffff', 'labelBoxBkgColor':'#3a3a3a', 'labelBoxBorderColor':'#ffffff', 'labelTextColor':'#ffffff', 'noteBkgColor':'#4a4a4a', 'noteTextColor':'#ffffff', 'noteBorderColor':'#ffffff', 'sequenceNumberColor':'#000000'}}}%% +sequenceDiagram + autonumber + actor User as User
(Organization Member) + participant SDK as Python SDK
(Launchpad/CLI/Library/MCP) + participant Auth0 as Auth0
(Enterprise Identity) + participant Bucket as Organization Bucket
(Google Cloud Storage) + participant API as Aignostics Platform API + participant GPU as NVIDIA® GPU Cluster
(per-run isolation) + + Note over User,GPU: Authentication & Authorization + User->>SDK: Launch interface + SDK->>Auth0: Authenticate user + Auth0-->>SDK: Access token + SDK->>API: Validate token + API-->>SDK: User authorized + + Note over User,GPU: Application Selection + User->>SDK: Browse applications + SDK->>API: List applications & versions + API-->>SDK: Application catalog + SDK-->>User: Display options + + Note over User,GPU: Data Upload + User->>SDK: Select WSIs + metadata + SDK->>Bucket: Upload files + Note over Bucket: 30-day auto-cleanup + Bucket-->>SDK: Upload complete + SDK->>SDK: Generate signed download URLs + + Note over User,GPU: Run Submission + SDK->>API: Submit run (app, metadata, signed URLs) + API-->>SDK: Run ID + queue position + SDK-->>User: Confirm submission + + Note over User,GPU: GPU Processing + API->>GPU: Provision dedicated NVIDIA® cluster + GPU->>Bucket: Download WSIs via signed URLs + GPU->>GPU: Process slides incrementally + GPU->>API: Upload results per slide + Note over GPU: Deprovision after completion + + Note over User,GPU: Status Monitoring & Results + User->>SDK: Check status + SDK->>API: Poll run status + API-->>SDK: Progress (e.g., "3 of 10 complete") + SDK-->>User: Display progress + + User->>SDK: Download results + SDK->>API: Request result URLs + API-->>SDK: Signed download URLs + SDK->>API: Download files (GeoJSON, CSV, TIFF) + SDK-->>User: Results ready for inspection +``` + +**How it works:** + +Organizations subscribe to the Aignostics Platform and receive dedicated infrastructure including a Google Cloud Storage bucket and API access. Users within the organization authenticate through Auth0, which integrates with enterprise identity management systems for seamless Single Sign-On (SSO). + +The Python SDK - available as a desktop application (Launchpad), command-line interface (CLI), Python library, and MCP server - handles all complexity of authentication, data upload, run orchestration, and results delivery. Users simply select an application, provide whole slide images with metadata, and submit. + +Behind the scenes, the Aignostics Platform API provisions dedicated NVIDIA® GPU clusters for each application run, ensuring data isolation and compliance with healthcare regulations. Processing occurs incrementally (slide-by-slide), allowing users to monitor progress and download results as they become available rather than waiting for entire cohorts. + +The organization's Google Cloud Storage bucket stores uploaded files with automatic 30-day cleanup, optimizing costs while maintaining data availability throughout processing. All data transfers use time-limited signed URLs, eliminating credential management complexity and security risks. + +**Enterprise benefits:** + +- **Security & compliance**: Per-run GPU isolation, enterprise SSO integration, zero-trust architecture with signed URLs +- **Scalability**: Handles single exploratory slides through thousand-slide clinical studies with identical user experience +- **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 + ## Further Reading @@ -838,7 +344,7 @@ Software Development Kit providing multiple pathways to interact with the Aignos Fully automated advanced machine learning workflow composed of specific tasks (e.g., Tissue Quality Control, Tissue Segmentation, Cell Detection, Cell Classification) designed for particular analysis purposes. **Application Run** -The execution instance of an application on submitted whole slide images, which can be in various states: received, scheduled, running, completed, rejected, cancelled by system, or cancelled by user. +The execution instance of an application on submitted whole slide images. A run moves through three states — pending, processing, and terminated — and a terminated run records a termination reason (all items processed, canceled by user, or canceled by system). **Application Version** Specific version of an application with defined input requirements, processing tasks, and output formats. Each application can have multiple versions. @@ -961,8 +467,8 @@ Limit on the number of whole slide images an organization or user can process pe ### R -**Reference** -Unique identifier string for each input item in an application run, used to match results with original inputs. +**Reference** (`external_id`) +Unique identifier string you assign to each input item in an application run (the `external_id` field), used to match results with original inputs. **Results** Output data from application processing, including measurements, statistics, heatmaps, and annotations, automatically deleted after 30 days. diff --git a/docs/partials/README_glossary.md b/docs/partials/README_glossary.md index 5ae913532..1eb42c128 100644 --- a/docs/partials/README_glossary.md +++ b/docs/partials/README_glossary.md @@ -30,7 +30,7 @@ Software Development Kit providing multiple pathways to interact with the Aignos Fully automated advanced machine learning workflow composed of specific tasks (e.g., Tissue Quality Control, Tissue Segmentation, Cell Detection, Cell Classification) designed for particular analysis purposes. **Application Run** -The execution instance of an application on submitted whole slide images, which can be in various states: received, scheduled, running, completed, rejected, cancelled by system, or cancelled by user. +The execution instance of an application on submitted whole slide images. A run moves through three states — pending, processing, and terminated — and a terminated run records a termination reason (all items processed, canceled by user, or canceled by system). **Application Version** Specific version of an application with defined input requirements, processing tasks, and output formats. Each application can have multiple versions. @@ -153,8 +153,8 @@ Limit on the number of whole slide images an organization or user can process pe ### R -**Reference** -Unique identifier string for each input item in an application run, used to match results with original inputs. +**Reference** (`external_id`) +Unique identifier string you assign to each input item in an application run (the `external_id` field), used to match results with original inputs. **Results** Output data from application processing, including measurements, statistics, heatmaps, and annotations, automatically deleted after 30 days. diff --git a/docs/partials/README_main.md b/docs/partials/README_main.md index 9232a42bb..3d594e853 100644 --- a/docs/partials/README_main.md +++ b/docs/partials/README_main.md @@ -1,174 +1,6 @@ ## Introduction -The **Aignostics Python SDK** provides multiple ways to interact with the **Aignostics Platform** for running advanced computational pathology applications like [Atlas H&E-TME](https://www.aignostics.com/products/he-tme-profiling-product), which analyzes tumor microenvironments in H&E-stained tissue samples. - -### 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). - -## Installation - -The **Aignostics Python SDK** can be installed via the [uv package manager](https://docs.astral.sh/uv/). The installation process sets up the SDK along with the necessary dependencies, including the **uv** package manager itself if not already present. - -Before proceeding, ensure you have an **Aignostics Platform account**. You can get access either through your organization admin (if your organization has an Aignostics account) or directly from Aignostics. Check your email for an invitation before proceeding. - -### Requirements - -- **Python 3.11, 3.12, 3.13, or 3.14** -- **macOS 11.0+, Linux, or Windows** -- **Homebrew** (only if you previously installed `uv` via Homebrew) - -### Installation Steps - -The installation will: - -1. Install or update **uv** (Python package installer) -2. Install the **Aignostics Python SDK** (includes Launchpad, CLI, and Python Library) - -Copy and paste the appropriate command below into your terminal (macOS/Linux) or PowerShell (Windows): - -**Linux/macOS:** - -```bash -if ! command -v uv &> /dev/null; then - echo "uv not found, installing..." - curl -LsSf https://astral.sh/uv/install.sh | sh - source $HOME/.local/bin/env -else - UV_VERSION=$(uv --version | cut -d' ' -f2) - if [ "$(printf '%s\n' "0.6.17" "$UV_VERSION" | sort -V | head -n1)" != "0.6.17" ]; then - echo "Updating uv to the latest version..." - UV_PATH=$(which uv) - if [[ "$UV_PATH" == *"brew"* ]]; then - echo "Updating uv using Homebrew..." - brew upgrade uv - else - echo "Updating uv using the installer..." - uv self update - fi - else - echo "uv is up to date" - fi -fi -``` - -**Windows (PowerShell):** - -```powershell -winget install --id=Microsoft.VCRedist.2015+.x64 -e -powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex" -``` - -Verify your installation by running: - -```bash -uvx aignostics --help -``` - -You should see the Aignostics CLI help output. - -You can then proceed by choosing your preferred user interface below. - -## Platform Workflow Overview - -The Aignostics Platform delivers enterprise-grade computational pathology through a secure, scalable cloud architecture. Organizations subscribe to the platform, and their users interact through three interfaces - all part of the Python SDK - to leverage advanced AI/ML models running on dedicated NVIDIA® GPU infrastructure. - -**Key architectural components:** - -- **Python SDK**: Provides three user interfaces (Launchpad desktop app, CLI, and Client Library) with unified functionality -- **Enterprise authentication**: Powered by Auth0, supporting Single Sign-On (SSO) and existing identity management systems -- **Organization storage**: Dedicated Google Cloud Storage bucket per organization with automatic 30-day cleanup -- **Aignostics Platform API**: Orchestrates application discovery, run submission, status monitoring, and results delivery -- **NVIDIA® GPU clusters**: Dedicated compute provisioned per application run for maximum security and compliance - -```mermaid -%%{init: {'theme':'dark', 'themeVariables': { 'fontSize':'18px', 'fontFamily':'arial', 'darkMode':'true', 'background':'#1e1e1e', 'primaryColor':'#4a4a4a', 'primaryTextColor':'#ffffff', 'primaryBorderColor':'#ffffff', 'lineColor':'#ffffff', 'secondaryColor':'#3a3a3a', 'tertiaryColor':'#2a2a2a', 'actorBkg':'#4a4a4a', 'actorBorder':'#ffffff', 'actorTextColor':'#ffffff', 'actorLineColor':'#ffffff', 'signalColor':'#ffffff', 'signalTextColor':'#ffffff', 'labelBoxBkgColor':'#3a3a3a', 'labelBoxBorderColor':'#ffffff', 'labelTextColor':'#ffffff', 'noteBkgColor':'#4a4a4a', 'noteTextColor':'#ffffff', 'noteBorderColor':'#ffffff', 'sequenceNumberColor':'#000000'}}}%% -sequenceDiagram - autonumber - actor User as User
(Organization Member) - participant SDK as Python SDK
(Launchpad/CLI/Client Library) - participant Auth0 as Auth0
(Enterprise Identity) - participant Bucket as Organization Bucket
(Google Cloud Storage) - participant API as Aignostics Platform API - participant GPU as NVIDIA® GPU Cluster
(per-run isolation) - - Note over User,GPU: Authentication & Authorization - User->>SDK: Launch interface - SDK->>Auth0: Authenticate user - Auth0-->>SDK: Access token - SDK->>API: Validate token - API-->>SDK: User authorized - - Note over User,GPU: Application Selection - User->>SDK: Browse applications - SDK->>API: List applications & versions - API-->>SDK: Application catalog - SDK-->>User: Display options - - Note over User,GPU: Data Upload - User->>SDK: Select WSIs + metadata - SDK->>Bucket: Upload files - Note over Bucket: 30-day auto-cleanup - Bucket-->>SDK: Upload complete - SDK->>SDK: Generate signed download URLs - - Note over User,GPU: Run Submission - SDK->>API: Submit run (app, metadata, signed URLs) - API-->>SDK: Run ID + queue position - SDK-->>User: Confirm submission - - Note over User,GPU: GPU Processing - API->>GPU: Provision dedicated NVIDIA® cluster - GPU->>Bucket: Download WSIs via signed URLs - GPU->>GPU: Process slides incrementally - GPU->>API: Upload results per slide - Note over GPU: Deprovision after completion - - Note over User,GPU: Status Monitoring & Results - User->>SDK: Check status - SDK->>API: Poll run status - API-->>SDK: Progress (e.g., "3 of 10 complete") - SDK-->>User: Display progress - - User->>SDK: Download results - SDK->>API: Request result URLs - API-->>SDK: Signed download URLs - SDK->>API: Download files (GeoJSON, CSV, TIFF) - SDK-->>User: Results ready for inspection -``` - -**How it works:** - -Organizations subscribe to the Aignostics Platform and receive dedicated infrastructure including a Google Cloud Storage bucket and API access. Users within the organization authenticate through Auth0, which integrates with enterprise identity management systems for seamless Single Sign-On (SSO). - -The Python SDK - available as a desktop application (Launchpad), command-line interface (CLI), or programmable library (Client Library) - handles all complexity of authentication, data upload, run orchestration, and results delivery. Users simply select an application, provide whole slide images with metadata, and submit. - -Behind the scenes, the Aignostics Platform API provisions dedicated NVIDIA® GPU clusters for each application run, ensuring data isolation and compliance with healthcare regulations. Processing occurs incrementally (slide-by-slide), allowing users to monitor progress and download results as they become available rather than waiting for entire cohorts. - -The organization's Google Cloud Storage bucket stores uploaded files with automatic 30-day cleanup, optimizing costs while maintaining data availability throughout processing. All data transfers use time-limited signed URLs, eliminating credential management complexity and security risks. - -**Enterprise benefits:** - -- **Security & compliance**: Per-run GPU isolation, enterprise SSO integration, zero-trust architecture with signed URLs -- **Scalability**: Handles single exploratory slides through thousand-slide clinical studies with identical user experience -- **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 +The **Aignostics Platform** runs computational pathology applications — such as [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 whole slide images. The **Aignostics Python SDK** is how you work with it, through the interfaces below. ## Choose your interface @@ -181,7 +13,7 @@ Choose your preferred interface for working with the Aignostics Platform. Each i | **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** | Install and run your first analysis | +| **Get started** | Get started with Launchpad | ### ⌨️ CLI (Command-Line Interface) @@ -190,7 +22,7 @@ Choose your preferred interface for working with the Aignostics Platform. Each i | **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** | Manage datasets and application runs from your terminal | +| **Get started** | Get started with the CLI | ### 📚 Python Library @@ -199,7 +31,7 @@ Choose your preferred interface for working with the Aignostics Platform. Each i | **What it is** | Python library for programmatic access in scripts, notebooks, and applications | | **Best for** | Data scientists and developers who want to integrate the platform into Python-based workflows | | **Use when** | Building custom analysis pipeline in Python for repeated usage and processing large datasets (10s-1000s of slides) | -| **Get started** | Run example notebooks or call the Aignostics Platform API from your Python scripts | +| **Get started** | Get started with the Python Library | ### 🤖 MCP Server (AI Agent Integration) @@ -208,451 +40,38 @@ Choose your preferred interface for working with the Aignostics Platform. Each i | **What it is** | Model Context Protocol server that exposes SDK functionality to AI agents like Claude | | **Best for** | Users who want AI assistants to help with platform operations | | **Use when** | Working with Claude Desktop or other MCP-compatible AI tools to manage datasets, submit runs, or query results | -| **Get started** | Configure Claude Desktop for MCP integration | - -> 💡 Launchpad and CLI handle authentication automatically. Python Library requires manual setup (see [authentication section](#example-notebooks-interact-with-the-aignostics-platform-from-your-python-notebook-environment)). - -## Launchpad: Run your first computational pathology analysis in 10 minutes from your desktop - -The **Aignostics Launchpad** is a graphical desktop application that allows you to run applications on whole slide images (WSIs) from your computer, and inspect results with QuPath and Python Notebooks with one click. It is designed to be user-friendly and intuitive, for use by Research Pathologists and Data Scientists. - -**New to Launchpad?** See Installation section above to get started. - -### Running Your First Analysis - -This tutorial uses [Atlas H&E-TME](https://www.aignostics.com/products/he-tme-profiling-product) with a public lung cancer dataset from the NCI Image Data Commons. - -**Step 1: Start Aignostics Launchpad** - -1. Open a terminal or command prompt -2. Run the command: `uvx aignostics launchpad` -This starts the Launchpad application. - -**Step 2: Download a Sample Dataset** - -1. Click the menu icon (☰) in the top right corner -2. Click "Download Datasets". The system displays the dataset download interface. -3. Click "EXAMPLE DATASET". The system populates the dataset ID field with a TCGA lung adenocarcinoma sample. -4. Click "DATA". The system shows a folder selection dialog. -5. Click "OK" -6. Click "DOWNLOAD". The system downloads the DICOM dataset. A progress indicator shows download status. -7. Click the menu icon and select "Run Applications" - -**Step 3: Select Atlas H&E-TME** - -1. Click "Atlas H&E-TME" in the left sidebar. The system displays the application workflow with six steps. -2. Click the version dropdown to view available versions. The system shows all available versions with release notes accessible via the "RELEASE NOTES" button. -3. Keep the default version (latest) -4. Click "NEXT" - -**Step 4: Select Slides and Provide Metadata** - -1. Click "DATA". The system opens a folder selection dialog showing the Launchpad datasets directory. -2. Navigate to the downloaded dataset folder (e.g., `/datasets/idc/tcga_luad/`) -3. Click "OK". The system displays the selected folder path and scans the folder, showing a table with all compatible slides. Each row shows thumbnail preview, technical metadata (file size, MPP resolution, dimensions), and status indicators. -4. The system automatically extracts technical file metadata. You must provide the required medical metadata by double-clicking the red cells in the "Tissue" column. The system displays a dropdown menu with tissue types. -5. Select the tissue type (e.g., "LUNG") and disease (e.g., "LUNG_CANCER") by double-clicking in the red cells and selecting the value from the dropdown. The system marks these cells green indicating valid metadata. -6. Review the "Staining" column. The system shows "H&E" if this information was extracted from the DICOM file. -7. Click "NEXT" - -**Step 5: Add Notes and Tags (Optional)** - -1. The system displays the notes and tags screen. -2. Enter an optional note in the text field (e.g., "TCGA lung sample analysis") -3. Add optional tags by typing and pressing Enter (e.g., "TCGA", "lung") -4. Click "NEXT" - -**Step 6: Set Schedule (Optional)** - -1. The system displays scheduling options with soft due date and hard deadline pickers. -2. Click "NEXT" to leave the default settings. - -The soft due date indicates when the platform will attempt to complete processing. The hard deadline is when the platform may cancel the run if resources are unavailable. - -**Step 7: Submit Your Run** - -1. The system displays the submission screen showing number of slides to be analyzed, full file paths, and upload and submit button. -2. Review the slide information -3. Click "UPLOAD AND SUBMIT". The system uploads your slides to the Aignostics Platform and submits the analysis run. A progress indicator shows upload status. - -The left sidebar now shows your submitted run with application name and version, submission timestamp, running status icon (🏃), and any tags you added. - -**Step 8: Monitor Your Run** - -Atlas H&E-TME processing time depends on slide size and system load. Depending on the file size and the number of files, processing can take minutes to many hours. - -Click on your run in the sidebar to view run details and metadata, slide thumbnails, and processing status for each slide. The status icon updates as processing progresses. - -### Understanding Your Results - -When processing completes, Atlas H&E-TME provides comprehensive tumor microenvironment analysis results for each processed slide: - -**What You'll Receive:** - -- **Tissue analysis**: Identification of tissue regions (tumor, stroma, necrosis, etc.) with quality assessment in GeoJSON format -- **Cell analysis**: Individual cells detected and classified by type (tumor cells, immune cells, stromal cells, etc.) in GeoJSON format -- **Visual segmentation maps**: Color-coded images showing spatial distribution of tissue and cell types -- **Quantitative measurements**: Cell counts, densities, spatial relationships, and statistical summaries provided in CSV format - -**Downloading Results:** - -When processing completes, the status icon changes to show completion. To download results: - -1. Click the "Download Results" button -2. The system downloads a ZIP file containing all outputs to your computer - -**Inspecting Results in QuPath:** - -QuPath integration provides the most powerful way to visualize and interact with your results: - -1. Click "Open in QuPath" (requires QuPath extension - see Advanced Setup below) -2. The system automatically creates a QuPath project with your slides and annotations loaded -3. In QuPath, you can: - - View tissue and cell annotations overlaid on your slides - - Explore cell classifications and measurements - - Analyze spatial relationships between different cell types - - Export annotations or perform additional analysis - -**Congratulations!** You have successfully downloaded a public dataset, submitted an Atlas H&E-TME analysis run, and learned how to access and inspect your results. - -### System Health Checks - -The Launchpad automatically monitors system health before allowing run submissions. If the system is unhealthy (e.g., network connectivity issues, authentication problems, or platform unavailability), the submission workflow is blocked: - -- A tooltip displays "System is unhealthy, you cannot prepare a run at this time." -- The "Next" button in the application workflow is disabled. -- The health status is shown in the footer bar at the bottom of the Launchpad. +| **Get started** | Get started with the MCP Server | -To resolve health issues: +> 💡 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. -1. Check the health status indicator in the footer bar -2. Click "Info and Settings" in the menu to see detailed health information -3. Verify your network connection and authentication status -4. Check the [Aignostics Platform Status](https://status.aignostics.com) page - -### Advanced Setup: Extensions - -> 💡 The Launchpad features a growing ecosystem of extensions that seamlessly integrate with standard digital pathology tools. To use the Launchpad with all available extensions, run `uvx --from "aignostics[qupath,marimo]" aignostics launchpad`. Currently available extensions are: -> -> 1. **QuPath extension**: View your application results in [QuPath](https://qupath.github.io/) with a single click. The Launchpad creates QuPath projects on-the-fly. -> 2. **Marimo extension**: Analyze your application results using [Marimo](https://marimo.io/) notebooks embedded in the Launchpad. You don't have to leave the Launchpad to do real data science. - -## CLI: Manage datasets and application runs from your terminal - -The Python SDK includes the **Aignostics CLI**, a Command-Line Interface (CLI) that allows you to -interact with the Aignostics Platform directly from your terminal or shell script. - -**New to CLI?** See Installation section above to get started. - -**Common workflows:** - -- Download public datasets from NCI Image Data Commons -- Submit batch processing runs for multiple slides -- Monitor run status and download results incrementally -- Automate repetitive tasks with shell scripts - -See as follows for a simple example where we download a sample dataset for the [Atlas -H&E-TME application](https://www.aignostics.com/products/he-tme-profiling-product), submit an application run, and download the results. - -### Example: Running Atlas H&E-TME with CLI - -1. Open a terminal or command prompt -2. Use the following commands to run the Atlas H&E-TME application on a sample dataset: - -```shell -# Download a sample dataset from the NCI Image Data Commons (IDC) portal to your current working directory -# As the dataset id refers to the TCGA LUAD collection, this creates a directory tcga_luad with the DICOM files -uvx aignostics dataset idc download 1.3.6.1.4.1.5962.99.1.1069745200.1645485340.1637452317744.2.0 data/ -# Prepare the metadata for the application run by creating a metadata.csv, extracting -# the required metadata from the DICOM files. We furthermore add the required -# information about the tissue type and disease. -uvx aignostics application run prepare he-tme data/tcga_luad/run.csv data/ -# Edit the metadata.csv to insert the required information about the staining method, tissue type and disease -# Adapt to your favourite editor -nano tcga_luad/metadata.csv -# Upload the metadata.csv and referenced whole slide images to the Aignostics Platform -uvx aignostics application run upload he-tme data/tcga_luad/run.csv -# Submit the application run and print the run id -uvx aignostics application run submit he-tme data/tcga_luad/run.csv -# Check the status of the application run you submitted -uvx aignostics application run list -# Incrementally download results when they become available -# Fill in the id from the output in the previous step -uvx aignostics application run result download APPLICATION_RUN_ID -``` - -For convenience the `application run execute` command combines preparation, upload, submission and download. -The below is equivalent to the above, while adding additionally required metadata using a mapping: - -```shell -uvx aignostics dataset idc download 1.3.6.1.4.1.5962.99.1.1069745200.1645485340.1637452317744.2.0 data/ -uvx aignostics application run execute he-tme data/tcga_luad/run.csv data/ --mapping ".*\.dcm:staining_method=H&E,tissue=LUNG,disease=LUNG_CANCER" -``` - -The CLI provides extensive help: - -```shell -uvx aignostics --help # list all spaces such as application, dataset, bucket and system, -uvx aignostics application --help # list subcommands in the application space -uvx aignostics application run --help # list subcommands in the application run sub-space -uvx aignostics application run list --help # show help for specific command -uvx aignostics application run execute --help # show help for another command -``` - -Check out our -[CLI reference documentation](https://aignostics.readthedocs.io/en/latest/cli_reference.html) -to learn about all commands and options available. - -### System Health Checks - -The CLI automatically checks system health before uploading slides or submitting runs. If the system is unhealthy, the operation is blocked and an error message is displayed: - -``` -Error: Platform is not healthy: . Aborting. -``` - -To override this behavior (not recommended for production use), add the `--force` flag: - -```shell -uvx aignostics application run upload he-tme metadata.csv --force -uvx aignostics application run submit he-tme metadata.csv --force -uvx aignostics application run execute he-tme metadata.csv data/ --force -``` - -To manually check system health before running commands: - -```shell -uvx aignostics system health -``` - -## Python Library: Call the Aignostics Platform API from your Python scripts - -The Python SDK includes the *Aignostics Python Library* for integration with your Python codebase. - -**New to Python Library?** See Installation section above to get started. - - - -### Installation - -Add the Aignostics Python SDK to your Python project: - -**Install with [uv](https://docs.astral.sh/uv/):** - -```shell -uv add aignostics -``` - -**Install with [pip](https://pip.pypa.io/en/stable/):** - -```shell -# Add Python SDK as dependency to your project -pip install aignostics -``` - -#### Usage - -The following snippet shows how to use the Client to submit an application -run: - -```python -from aignostics import platform - -# initialize the client -client = platform.Client() -# submit an application run -application_run = client.runs.submit( - application_id="test-app", - items=[ - platform.InputItem( - external_id="slide-1", - input_artifacts=[ - platform.InputArtifact( - name="whole_slide_image", - download_url="", - metadata={ - "checksum_base64_crc32c": "AAAAAA==", - "resolution_mpp": 0.25, - "width_px": 1000, - "height_px": 1000, - }, - ) - ], - ), - ], -) -# wait for the results and download incrementally as they become available -application_run.download_to_folder("path/to/download/folder") -``` - -Please look at the notebooks in the `example` folder for a more detailed example -and read the -[client reference documentation](https://aignostics.readthedocs.io/en/latest/lib_reference.html) -to learn about all classes and methods. - -### System Health Checks - -The low-level Python SDK does **not** perform automated health checks before operations. If health verification is required for your use case, you should implement checks 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 design gives you full control over health check behavior, allowing you to: - -- Implement custom retry logic for transient failures -- Log health status for monitoring and debugging -- Gracefully handle unhealthy states in your application - -### Example Notebooks: Interact with the Aignostics Platform from your Python Notebook environment - -> [!IMPORTANT] -> Before you get started, you need to set up your authentication credentials if -> you did not yet do so! Please visit -> [your personal dashboard on the Aignostics Platform website](https://platform.aignostics.com/getting-started/quick-start) -> and follow the steps outlined in the `Use in Python Notebooks` section. - -The Python SDK includes ready-to-use Marimo notebooks that demonstrate platform interaction patterns. These notebooks are ideal for: - -- Learning the API through interactive examples -- Prototyping custom analysis workflows -- Integrating with existing data science pipelines - -The example notebooks use our "Test Application" (free for all users). To run them, -please follow the steps outlined in the snippet below to clone this repository and start the -[Marimo](https://marimo.io/) -([examples/notebook.py](https://github.com/aignostics/python-sdk/blob/main/examples/notebook.py)) -notebook: - -```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 -# show marimo example notebook in the browser -uv run marimo edit examples/notebook.py -``` - -> 💡 You can also run a notebook within the Aignostics Launchpad. To do so, select the -> Run you want to inspect in the left sidebar, and click the button "Open in Python Notebook". - -### Defining the input for an application run - -The following sections provide technical details for advanced use cases. These examples use the "Test Application" - a free application available to all users for testing and development purposes. - -When creating an application run, you need to specify the `application_id` and optionally the -`application_version` (version number) of the application you want to run. If you omit the version, -the latest version will be used automatically. Additionally, you need to define the input items you -want to process in the run. The input items are defined as follows: - -```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, - }, - ) - ], - ), -) -``` - -For each item you want to process, you need to provide a unique `reference` -string. This is used to identify the item in the results later on. The -`input_artifacts` field is a list of `InputArtifact` objects, which defines what -data & metadata you need to provide for each item. The required artifacts depend -on the application version you want to run - in the case of test application, -there is only one artifact required, which is the image to process on. The -artifact name is defined as `whole_slide_image` for this application. - -The `download_url` is a signed URL that allows the Aignostics Platform to -download the image data later during processing. - -### Self-signed URLs for large files - -To make the whole slide images you want to process available to the Aignostics Platform, you -need to provide a signed URL that allows the platform to download the data. -Self-signed URLs for files in google storage buckets can be generated using the -`generate_signed_url` -([code](https://github.com/aignostics/python-sdk/blob/407e74f7ae89289b70efd86cbda59ec7414050d5/src/aignostics/client/utils.py#L85)). - -**We expect that you provide the -[required credentials](https://cloud.google.com/docs/authentication/application-default-credentials) -for the Google Storage Bucket** - -## MCP Server: Integrate with AI Agents - -The Python SDK includes an MCP (Model Context Protocol) server that exposes SDK functionality to AI agents like Claude. This enables AI assistants to help you interact with the Aignostics Platform through natural conversation. - -### Quick Start with Claude Desktop - -Add the following to your Claude Desktop configuration file: - -**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json` -**Windows**: `%APPDATA%\Claude\claude_desktop_config.json` - -```json -{ - "mcpServers": { - "aignostics": { - "command": "uvx", - "args": ["aignostics", "mcp", "run"] - } - } -} -``` - -Restart Claude Desktop after adding this configuration. - -### CLI Commands - -```bash -# Using uvx (no installation required) -uvx aignostics mcp run -uvx aignostics mcp list-tools -``` - -### Using Plugins - -The MCP server supports plugins that extend its functionality with additional tools. To run the MCP server with a plugin installed: - -```bash -# With a local plugin -uv run --with /path/to/plugin aignostics mcp run - -# With a plugin from a git repository -uvx --with git+ssh://git@github.com/org/plugin aignostics mcp run -``` +## Next Steps -Plugins register themselves via Python entry points and their tools are automatically discovered and namespaced by the MCP server. +The best next step is to **run your first analysis** end to end. -### What AI Agents Can Do +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. -Once configured, AI agents can help you with platform operations through natural language, with access to tools from the SDK and any installed plugins. +Once you've run your first analysis: -## Next Steps +- **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). +- **Get support**: Contact [support@aignostics.com](mailto:support@aignostics.com) or browse the [full documentation](https://aignostics.readthedocs.io/en/latest/). -Now that you have an overview of the Aignostics Python SDK and its interfaces, here are some recommended next steps to deepen your understanding and get the most out of the platform: +## We take quality and security seriously -- **Understand the platform**: Read the [Aignostics Platform Overview](platform_overview.md) to learn about architecture and core concepts -- **Review detailed documentation**: 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) -- **Explore QuPath integration**: Use the QuPath extension to visualize and interact with your results -- **Get support**: Contact [support@aignostics.com](mailto:support@aignostics.com) or check the [full documentation](https://aignostics.readthedocs.io/en/latest/) +We know you take **quality** and **security** as seriously as we do. That's why +the Aignostics Python SDK is built following best practices and with full +transparency. This includes (1) making the complete +[source code of the SDK +available on GitHub](https://github.com/aignostics/python-sdk/), maintaining a +(2) +[A-grade code quality](https://sonarcloud.io/summary/new_code?id=aignostics_python-sdk) +with [high test coverage](https://app.codecov.io/gh/aignostics/python-sdk) in +all releases, (3) achieving +[A-grade security](https://sonarcloud.io/summary/new_code?id=aignostics_python-sdk) +with +[active scanning of dependencies](https://github.com/aignostics/python-sdk/issues/4), +and (4) providing +[extensive documentation](https://aignostics.readthedocs.io/en/latest/). Read +more about how we achieve +[operational excellence](https://aignostics.readthedocs.io/en/latest/operational_excellence.html) and +[security](https://aignostics.readthedocs.io/en/latest/security.html). diff --git a/docs/partials/README_platform.md b/docs/partials/README_platform.md index f21549d79..ed135b6a2 100644 --- a/docs/partials/README_platform.md +++ b/docs/partials/README_platform.md @@ -51,23 +51,24 @@ Once registered to the Platform, your organization will automatically gain acces To trigger the application run, users can use the Aignostics Launchpad, Aignostics CLI, Example Notebooks, our Client Library, or directly call the REST API. The platform expects the user payload, containing the metadata and the signed URLs to the whole slide images (WSIs). The detailed requirements of the payload depend on the application and are described in the documentation, and accessible via the Info button in the Launchpad, as well as via the CLI and `/v1/applications` endpoint in the API. -When the application run is created, it can be in one of the following states: +When the application run is created, it progresses through three states: -1. **received**: the application run received from the client -2. **scheduled**: the application run request is valid and is scheduled for execution -3. **running**: the application run execution started -4. **completed**: the application run execution is done and all outputs are available for download -5. **completed**: the application run execution is done, but some items end up in the failed state -6. **rejected**: the application run request is rejected before it is scheduled -7. **cancelled by the system**: the application run failed during the execution with the number of errors higher than the threshold -9. **cancelled by the user**: the application run is cancelled by the user before it is finished +1. **pending**: the application run has been received and is waiting to start processing +2. **processing**: the application run is being executed; results for individual slides become available as they complete +3. **terminated**: the application run has finished + +A terminated run carries a *termination reason* explaining the outcome: + +- **all items processed**: every slide was processed (individual slides may still have failed — check the per-slide results) +- **canceled by the user**: the run was canceled by the user before it finished +- **canceled by the system**: the run was stopped by the platform, for example when the number of failed slides exceeded the allowed threshold The status and operations of an application run are private to the user who triggered the run. ### Results When the processing of whole slide image is successfully completed, the resulting outputs become available for download. To assess specifics of application outputs please consult our application specific documentation, which you can find in the **Console**. Please note that you access to documentation is restricted to those applications your organisation subscribed to. -Application run outputs are automatically deleted 30 days after the application run has completed. However, the owner of the application run (the user who initiated it) can use the API to manually delete outputs earlier, once the run has reached a final state - completed, cancelled by the system or cancelled by the user. The Launchpad and CLI provide enable to delete results with one click resp. command. +Application run outputs are automatically deleted 30 days after the application run has terminated. However, the owner of the application run (the user who initiated it) can use the API to manually delete outputs earlier, once the run has terminated. The Launchpad and CLI let you delete results with one click or one command, respectively. ### Quotas Every organization has a limit on how many WSIs it can process in a calendar month. The following quotas exist: @@ -100,6 +101,91 @@ For integration with programming languages other than Python, you can use the RE ### Cost -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 cancelled, either by the system or by the user, only processed images incur a cost. +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. + +### Platform workflow + +The Aignostics Platform delivers enterprise-grade computational pathology through a secure, scalable cloud architecture. Organizations subscribe to the platform, and their users interact through multiple interfaces - all part of the Python SDK - to leverage advanced AI/ML models running on dedicated NVIDIA® GPU infrastructure. + +**Key architectural components:** + +- **Python SDK**: Provides multiple interfaces (Launchpad desktop app, CLI, Python Library, and MCP server) with unified functionality +- **Enterprise authentication**: Powered by Auth0, supporting Single Sign-On (SSO) and existing identity management systems +- **Organization storage**: Dedicated Google Cloud Storage bucket per organization with automatic 30-day cleanup +- **Aignostics Platform API**: Orchestrates application discovery, run submission, status monitoring, and results delivery +- **NVIDIA® GPU clusters**: Dedicated compute provisioned per application run for maximum security and compliance + +```mermaid +%%{init: {'theme':'dark', 'themeVariables': { 'fontSize':'18px', 'fontFamily':'arial', 'darkMode':'true', 'background':'#1e1e1e', 'primaryColor':'#4a4a4a', 'primaryTextColor':'#ffffff', 'primaryBorderColor':'#ffffff', 'lineColor':'#ffffff', 'secondaryColor':'#3a3a3a', 'tertiaryColor':'#2a2a2a', 'actorBkg':'#4a4a4a', 'actorBorder':'#ffffff', 'actorTextColor':'#ffffff', 'actorLineColor':'#ffffff', 'signalColor':'#ffffff', 'signalTextColor':'#ffffff', 'labelBoxBkgColor':'#3a3a3a', 'labelBoxBorderColor':'#ffffff', 'labelTextColor':'#ffffff', 'noteBkgColor':'#4a4a4a', 'noteTextColor':'#ffffff', 'noteBorderColor':'#ffffff', 'sequenceNumberColor':'#000000'}}}%% +sequenceDiagram + autonumber + actor User as User
(Organization Member) + participant SDK as Python SDK
(Launchpad/CLI/Library/MCP) + participant Auth0 as Auth0
(Enterprise Identity) + participant Bucket as Organization Bucket
(Google Cloud Storage) + participant API as Aignostics Platform API + participant GPU as NVIDIA® GPU Cluster
(per-run isolation) + + Note over User,GPU: Authentication & Authorization + User->>SDK: Launch interface + SDK->>Auth0: Authenticate user + Auth0-->>SDK: Access token + SDK->>API: Validate token + API-->>SDK: User authorized + + Note over User,GPU: Application Selection + User->>SDK: Browse applications + SDK->>API: List applications & versions + API-->>SDK: Application catalog + SDK-->>User: Display options + + Note over User,GPU: Data Upload + User->>SDK: Select WSIs + metadata + SDK->>Bucket: Upload files + Note over Bucket: 30-day auto-cleanup + Bucket-->>SDK: Upload complete + SDK->>SDK: Generate signed download URLs + + Note over User,GPU: Run Submission + SDK->>API: Submit run (app, metadata, signed URLs) + API-->>SDK: Run ID + queue position + SDK-->>User: Confirm submission + + Note over User,GPU: GPU Processing + API->>GPU: Provision dedicated NVIDIA® cluster + GPU->>Bucket: Download WSIs via signed URLs + GPU->>GPU: Process slides incrementally + GPU->>API: Upload results per slide + Note over GPU: Deprovision after completion + + Note over User,GPU: Status Monitoring & Results + User->>SDK: Check status + SDK->>API: Poll run status + API-->>SDK: Progress (e.g., "3 of 10 complete") + SDK-->>User: Display progress + + User->>SDK: Download results + SDK->>API: Request result URLs + API-->>SDK: Signed download URLs + SDK->>API: Download files (GeoJSON, CSV, TIFF) + SDK-->>User: Results ready for inspection +``` + +**How it works:** + +Organizations subscribe to the Aignostics Platform and receive dedicated infrastructure including a Google Cloud Storage bucket and API access. Users within the organization authenticate through Auth0, which integrates with enterprise identity management systems for seamless Single Sign-On (SSO). + +The Python SDK - available as a desktop application (Launchpad), command-line interface (CLI), Python library, and MCP server - handles all complexity of authentication, data upload, run orchestration, and results delivery. Users simply select an application, provide whole slide images with metadata, and submit. + +Behind the scenes, the Aignostics Platform API provisions dedicated NVIDIA® GPU clusters for each application run, ensuring data isolation and compliance with healthcare regulations. Processing occurs incrementally (slide-by-slide), allowing users to monitor progress and download results as they become available rather than waiting for entire cohorts. + +The organization's Google Cloud Storage bucket stores uploaded files with automatic 30-day cleanup, optimizing costs while maintaining data availability throughout processing. All data transfers use time-limited signed URLs, eliminating credential management complexity and security risks. + +**Enterprise benefits:** + +- **Security & compliance**: Per-run GPU isolation, enterprise SSO integration, zero-trust architecture with signed URLs +- **Scalability**: Handles single exploratory slides through thousand-slide clinical studies with identical user experience +- **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 diff --git a/docs/partials/_get_started_signup.md b/docs/partials/_get_started_signup.md new file mode 100644 index 000000000..859e1fcc3 --- /dev/null +++ b/docs/partials/_get_started_signup.md @@ -0,0 +1,16 @@ +## Sign up for the Aignostics Platform + +Before you can run an analysis, you need an account on the Aignostics Platform. These account steps are the same whichever interface you use. + +> 💡 **Already have an account?** Skip to the installation steps below. + +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.** 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. diff --git a/docs/partials/get_started_cli.md b/docs/partials/get_started_cli.md new file mode 100644 index 000000000..31b8fca53 --- /dev/null +++ b/docs/partials/get_started_cli.md @@ -0,0 +1,119 @@ +# Get started with the CLI + +The **Aignostics CLI** is a command-line tool for interacting with the Aignostics Platform directly from your terminal or shell scripts. It is well suited to processing larger cohorts, automating repetitive analyses, and integrating with computational pipelines. + +Common workflows: + +- Download public datasets from the NCI Image Data Commons +- Submit batch processing runs for many slides +- Monitor run status and download results incrementally +- Automate repetitive tasks with shell scripts + +```{include} ../partials/_get_started_signup.md +``` + +## Install the CLI + +The CLI runs through [uv](https://docs.astral.sh/uv/). The command below installs uv if it isn't already present, updates it if it's out of date (including Homebrew-managed installs), and makes it available in your current shell. Afterwards every command is available through `uvx aignostics`. + +**On macOS or Linux:** + +```bash +if ! command -v uv &> /dev/null; then + echo "uv not found, installing..." + curl -LsSf https://astral.sh/uv/install.sh | sh + source $HOME/.local/bin/env +else + UV_VERSION=$(uv --version | cut -d' ' -f2) + if [ "$(printf '%s\n' "0.6.17" "$UV_VERSION" | sort -V | head -n1)" != "0.6.17" ]; then + echo "Updating uv to the latest version..." + UV_PATH=$(which uv) + if [[ "$UV_PATH" == *"brew"* ]]; then + echo "Updating uv using Homebrew..." + brew upgrade uv + else + echo "Updating uv using the installer..." + uv self update + fi + else + echo "uv is up to date" + fi +fi +``` + +**On Windows (PowerShell):** + +```powershell +winget install --id=Microsoft.VCRedist.2015+.x64 -e +powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex" +``` + +Verify the install: + +```bash +uvx aignostics --help +``` + +You should see the list of available command groups (`application`, `dataset`, `bucket`, `system`, and more). If the command isn't found, open a new terminal and try again. + +## Run Atlas H&E-TME from the command line + +This example downloads a public lung cancer dataset, submits an [Atlas H&E-TME](https://www.aignostics.com/products/he-tme-profiling-product) run, and downloads the results: + +```shell +# Download a sample dataset from the NCI Image Data Commons (IDC) portal. +# This dataset id refers to the TCGA LUAD collection and creates a tcga_luad directory of DICOM files. +uvx aignostics dataset idc download 1.3.6.1.4.1.5962.99.1.1069745200.1645485340.1637452317744.2.0 data/ +# Prepare a run.csv, extracting the required metadata from the DICOM files. +uvx aignostics application run prepare he-tme data/tcga_luad/run.csv data/ +# Edit the run.csv to add the required staining method, tissue type, and disease (use any editor). +nano data/tcga_luad/run.csv +# Upload the run.csv and referenced whole slide images to the Aignostics Platform. +uvx aignostics application run upload he-tme data/tcga_luad/run.csv +# Submit the application run and print the run id. +uvx aignostics application run submit he-tme data/tcga_luad/run.csv +# Check the status of your run. +uvx aignostics application run list +# Incrementally download results as they become available (use the id from the previous step). +uvx aignostics application run result download APPLICATION_RUN_ID +``` + +For convenience, `application run execute` combines preparation, upload, submission, and download. The command below is equivalent to the above, supplying the required metadata with a mapping: + +```shell +uvx aignostics dataset idc download 1.3.6.1.4.1.5962.99.1.1069745200.1645485340.1637452317744.2.0 data/ +uvx aignostics application run execute he-tme data/tcga_luad/run.csv data/ --mapping ".*\.dcm:staining_method=H&E,tissue=LUNG,disease=LUNG_CANCER" +``` + +The CLI provides extensive help at every level: + +```shell +uvx aignostics --help # list all command groups +uvx aignostics application --help # subcommands in the application group +uvx aignostics application run --help # subcommands in the application run group +uvx aignostics application run list --help # help for a specific command +``` + +See the [CLI reference](https://aignostics.readthedocs.io/en/latest/cli_reference.html) for all commands and options. + +## System health checks + +The CLI checks system health before uploading slides or submitting runs. If the system is unhealthy, the operation is blocked: + +``` +Error: Platform is not healthy: . Aborting. +``` + +To override this (not recommended for production), add `--force`: + +```shell +uvx aignostics application run upload he-tme data/tcga_luad/run.csv --force +uvx aignostics application run submit he-tme data/tcga_luad/run.csv --force +uvx aignostics application run execute he-tme data/tcga_luad/run.csv data/ --force +``` + +To check system health manually: + +```shell +uvx aignostics system health +``` diff --git a/docs/partials/get_started_launchpad.md b/docs/partials/get_started_launchpad.md new file mode 100644 index 000000000..5c2103a71 --- /dev/null +++ b/docs/partials/get_started_launchpad.md @@ -0,0 +1,200 @@ +# Get started with Launchpad + +Launchpad is a desktop application for running Aignostics applications on your whole slide images. 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 an example slide, from signing up to viewing results in QuPath. + +You do not need any programming experience. You will copy and paste a few commands, but everything else happens in a normal point-and-click window. The hands-on setup takes about 15 minutes. After you submit your analysis, it runs on its own — you can close Launchpad and come back to your results later. + +**What you need:** a Mac, Windows (Windows 10 or later), or Linux (Ubuntu) computer with at least 8 GB of memory and 1 GB of free disk space, a web browser, and a mobile phone for the login security step. + +```{include} ../partials/_get_started_signup.md +``` + +## Install Launchpad + +You install Launchpad by pasting one command into a terminal. The terminal is a text window for typing commands. You only need it to start Launchpad — everything after that is point-and-click. + +Pick the instructions for your computer below. If a command does not work, see [Troubleshooting](#troubleshooting). + +### On macOS or Linux + +Open the **Terminal** app. On macOS, press `Cmd` + `Space` to open Spotlight, type `Terminal`, and press `Enter`. + +Paste this command and press `Enter`: + +```bash +curl -LsSf https://astral.sh/uv/install.sh | sh +``` + +When it finishes, **close the Terminal window and open a new one.** + +### On Windows + +Open **PowerShell**. Click the Start menu, type `PowerShell`, and press `Enter`. + +Paste this command and press `Enter`: + +```powershell +powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex" +``` + +When it finishes, **close the PowerShell window and open a new one.** + +### Start Launchpad + +In your fresh terminal window, paste this command and press `Enter`: + +```bash +uvx aignostics launchpad +``` + +The first time you run this, it takes a minute or two to get ready. Then the **Launchpad window opens** — that means everything installed correctly. + +![The Launchpad window when it first opens](_static/launchpad/01-launchpad-window.png) + +If you see an error instead of the window, see [Troubleshooting](#troubleshooting). + +## Run your first analysis + +This walkthrough runs Atlas H&E-TME on a public lung cancer slide so you can see the whole flow end to end. Launchpad should already be open from the previous step. If you closed it, start it again by pasting `uvx aignostics launchpad` into a terminal. + +### 1. Log in + +The first time you open Launchpad, it opens a browser window at `platform.aignostics.com` and asks you to log in. Enter your email and password, then the six-digit code from your authenticator app. When the browser confirms you are logged in, return to the Launchpad window. You stay logged in for future sessions. + +### 2. Download the example dataset + +You need a slide to analyze. Launchpad can download a public example slide for you — a TCGA lung adenocarcinoma case from the public cancer imaging archives. + +1. Click the menu icon (☰) in the top-right corner. + + ![The open menu showing Download Datasets and Run Applications](_static/launchpad/02-menu-open.png) + +2. Click **Download Datasets**. +3. Click **EXAMPLE DATASET**. Launchpad fills in the details of the example slide for you. +4. Click **DOWNLOAD**. A progress bar appears at the bottom of the window. The download takes a few minutes. Wait until it finishes. + +### 3. Open Run Applications and select Atlas H&E-TME + +1. Click the menu icon (☰) again and choose **Run Applications**. +2. In the list on the left, click **Atlas H&E-TME**. The analysis workflow opens on the right. +3. Click **NEXT** to continue with the latest version. + +### 4. Select slides and provide metadata + +This is the step where most people get stuck, so take it slowly. Atlas H&E-TME needs to know two things about each slide before it can run: what kind of tissue it is, and what disease it relates to. You fill these in by hand. + +1. Click **DATA** and select the folder you just downloaded. Launchpad scans the folder and shows a table with one row per slide. Each row has a small preview image and some details that were read automatically from the file. + +2. Look at the **Tissue** and **Disease** columns. Some cells are **red**. Red means a value is missing and you need to provide it. Launchpad will not let you continue while any red cells remain. + +3. **Double-click the red cell in the Tissue column.** A dropdown list of tissue types appears. Choose **LUNG**. The cell turns **green**, which means the value is accepted. + + ![Slide table with red Tissue and Disease cells and the Tissue dropdown open on LUNG](_static/launchpad/03-metadata-dropdown.png) + +4. **Double-click the red cell in the Disease column.** From the dropdown, choose **LUNG_CANCER**. That cell turns green too. + +5. Make sure every red cell in the table is now green. Then click **NEXT**. + +### 5. Submit the analysis + +After the slide table, Launchpad shows a few optional screens — one for notes and tags, one for scheduling. You don't need any of them for your first run. **Click NEXT through the optional screens until you reach the submission screen.** + +The submission screen shows how many slides will be analyzed and where they are. Click **UPLOAD AND SUBMIT**. A progress bar shows your slide uploading to the Aignostics Platform. When the upload finishes, your run appears in the list on the left with a running icon (🏃). + +### 6. Wait for results + +The analysis now runs on Aignostics servers, not on your computer, so you can do other things while you wait. How long it takes depends on the size and number of slides — anywhere from a few minutes to several hours. Click your run in the list on the left to see its status. The icon updates on its own as the slide is processed. + +![The left sidebar showing a run in progress and a completed run](_static/launchpad/04-run-status.png) + +You don't have to keep Launchpad open. Because the analysis runs on our servers, you can quit Launchpad and reopen it later — your run is still in the list on the left, with its latest status. + +### 7. Download your results + +When the run finishes, the icon next to it changes to show it is complete. Click your run, then click **Download**. Choose **Download all results**. Launchpad saves a ZIP file to your computer with the analysis outputs: the tissue regions it found (such as tumor, stroma, and necrosis), the individual cells it detected and classified by type, and a spreadsheet of measurements like cell counts and densities. + +For a much better way to look at these results, read on. + +## View results in QuPath + +QuPath is a free, widely used viewer for whole slide images. Launchpad can open your results directly in QuPath, with the tissue and cell annotations already loaded on top of your slide. This is the best way for a pathologist to explore what the analysis found. + +1. **The first time only, install the QuPath viewer.** Open the ☰ menu and choose **QuPath Extension**, then follow the prompts. Launchpad downloads and sets up QuPath for you, which takes a few minutes. You only do this once. +2. Click your finished run in the list on the left. +3. Click **QuPath**. Launchpad builds a QuPath project from your slide and results and opens QuPath. + +Your slide appears in QuPath with the analysis annotations layered on top — tissue regions and individual cells, colored by type — ready to explore. + +![The slide open in QuPath with tissue and cell annotations](_static/launchpad/05-qupath-result.png) + +**Congratulations** — you have signed up, installed Launchpad, run your first analysis, and opened the results in QuPath. + +## Troubleshooting + +
+How do I find Terminal or PowerShell? + +**macOS:** Press `Cmd` + `Space` to open Spotlight search, type `Terminal`, and press `Enter`. + +**Windows:** Click the Start menu, type `PowerShell`, and press `Enter`. + +Both are normal apps that come with your computer. You can keep them in your dock or taskbar if you use Launchpad often. + +
+ +
+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 launchpad` did not work right after installing, close that terminal window, open a new one, and try `uvx aignostics launchpad` 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`. + +
+ +
+The status indicator at the bottom of the window is red + +The colored indicator in the bottom bar of Launchpad shows whether everything is working. When it is red, Launchpad cannot reach the Aignostics Platform, and the **NEXT** button may be disabled so you cannot submit a run. + +Try these steps: + +1. Check that your computer is connected to the internet. +2. Make sure you are logged in. If you aren't, open the menu (☰) and log in again. +3. Wait a minute and check whether the indicator turns green on its own. + +If it stays red, email `support@aignostics.com`. + +
+ +
+How do I close Launchpad? + +Open the menu (☰) in the top-right corner and click **Quit Launcher**. You can leave the terminal window open or close it — it is not needed once Launchpad is closed. + +
+ +
+How do I restart Launchpad? + +Open a terminal and paste the launch command again: + +```bash +uvx aignostics launchpad +``` + +
+ +
+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`. + +
+ +Still stuck? Email `support@aignostics.com` and describe what you were doing and what you saw. diff --git a/docs/partials/get_started_library.md b/docs/partials/get_started_library.md new file mode 100644 index 000000000..0eb8bac21 --- /dev/null +++ b/docs/partials/get_started_library.md @@ -0,0 +1,134 @@ +# 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. + +```{include} ../partials/_get_started_signup.md +``` + +## Install the library + +Add the Aignostics Python SDK to your project. + +**With [uv](https://docs.astral.sh/uv/):** + +```shell +uv add aignostics +``` + +**With [pip](https://pip.pypa.io/en/stable/):** + +```shell +pip install aignostics +``` + +## Usage + +The following snippet shows how to use the client to submit an application run: + +```python +from aignostics import platform + +# initialize the client +client = platform.Client() +# submit an application run +application_run = client.runs.submit( + application_id="test-app", + items=[ + platform.InputItem( + external_id="slide-1", + input_artifacts=[ + platform.InputArtifact( + name="whole_slide_image", + download_url="", + metadata={ + "checksum_base64_crc32c": "AAAAAA==", + "resolution_mpp": 0.25, + "width_px": 1000, + "height_px": 1000, + }, + ) + ], + ), + ], +) +# wait for the results and download incrementally as they become available +application_run.download_to_folder("path/to/download/folder") +``` + +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] +> 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. + +The SDK includes ready-to-use [Marimo](https://marimo.io/) notebooks that demonstrate platform interaction patterns — ideal for learning the API, prototyping workflows, and integrating with data science pipelines. They use the "Test Application" (free for all users): + +```shell +# clone the python-sdk repository +git clone https://github.com/aignostics/python-sdk.git +# within the cloned repository, install the SDK and all dependencies +uv sync --all-extras +# open the example notebook in your browser +uv run marimo edit examples/notebook.py +``` + +> 💡 You can also run a notebook inside the Aignostics Launchpad: select the run you want to inspect in the left sidebar and click **Marimo**. + +## Defining the input for an application run + +The following details apply to advanced use cases. These examples use the "Test Application" — a free application available to all users for testing and development. + +When creating a run, you specify the `application_id` and optionally the `application_version`. If you omit the version, the latest is used automatically. You then define the input items to process: + +```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, + }, + ) + ], + ), +) +``` + +For each item you process, provide a unique `external_id` string — it is used to match results back to your inputs. The `input_artifacts` field is a list of `InputArtifact` objects defining the data and metadata for each item. The required artifacts depend on the application version; for the test application there is a single artifact, named `whole_slide_image`. + +The `download_url` is a signed URL that allows the Aignostics Platform to download the image data during processing. + +## Self-signed URLs for large files + +To make whole slide images available to the Aignostics Platform, you provide a signed URL the platform can download from. Signed URLs for files in Google Cloud Storage buckets can be generated with `generate_signed_url` ([code](https://github.com/aignostics/python-sdk/blob/main/src/aignostics/platform/_utils.py)). + +**You must provide the [required credentials](https://cloud.google.com/docs/authentication/application-default-credentials) for the Google Cloud Storage bucket.** diff --git a/docs/partials/get_started_mcp.md b/docs/partials/get_started_mcp.md new file mode 100644 index 000000000..f652e3ee7 --- /dev/null +++ b/docs/partials/get_started_mcp.md @@ -0,0 +1,85 @@ +# Get started with the MCP Server + +The Python SDK includes an **MCP (Model Context Protocol) server** that exposes SDK functionality to AI agents like Claude. This lets an AI assistant help you interact with the Aignostics Platform through natural conversation — managing datasets, submitting runs, and querying results. + +```{include} ../partials/_get_started_signup.md +``` + +## Configure Claude Desktop + +The MCP server runs through [uv](https://docs.astral.sh/uv/). Install uv first if you don't have it. The command below installs uv if needed, updates it if out of date (including Homebrew-managed installs), and makes it available in your current shell. + +**On macOS or Linux:** + +```bash +if ! command -v uv &> /dev/null; then + echo "uv not found, installing..." + curl -LsSf https://astral.sh/uv/install.sh | sh + source $HOME/.local/bin/env +else + UV_VERSION=$(uv --version | cut -d' ' -f2) + if [ "$(printf '%s\n' "0.6.17" "$UV_VERSION" | sort -V | head -n1)" != "0.6.17" ]; then + echo "Updating uv to the latest version..." + UV_PATH=$(which uv) + if [[ "$UV_PATH" == *"brew"* ]]; then + echo "Updating uv using Homebrew..." + brew upgrade uv + else + echo "Updating uv using the installer..." + uv self update + fi + else + echo "uv is up to date" + fi +fi +``` + +**On Windows (PowerShell):** + +```powershell +winget install --id=Microsoft.VCRedist.2015+.x64 -e +powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex" +``` + +Then add the following to your Claude Desktop configuration file: + +- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json` +- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json` + +```json +{ + "mcpServers": { + "aignostics": { + "command": "uvx", + "args": ["aignostics", "mcp", "run"] + } + } +} +``` + +Restart Claude Desktop after saving the configuration. + +## Run the server from the command line + +```bash +uvx aignostics mcp run +uvx aignostics mcp list-tools +``` + +## Using plugins + +The MCP server supports plugins that extend it with additional tools. To run the server with a plugin installed: + +```bash +# with a local plugin +uv run --with /path/to/plugin aignostics mcp run + +# with a plugin from a git repository +uvx --with git+ssh://git@github.com/org/plugin aignostics mcp run +``` + +Plugins register themselves via Python entry points; their tools are automatically discovered and namespaced by the MCP server. + +## What AI agents can do + +Once configured, AI agents can help with platform operations through natural language, using the tools exposed by the SDK and any installed plugins. diff --git a/docs/source/_static/aignostics-wordmark-dark.svg b/docs/source/_static/aignostics-wordmark-dark.svg new file mode 100644 index 000000000..2fb4e6ab0 --- /dev/null +++ b/docs/source/_static/aignostics-wordmark-dark.svg @@ -0,0 +1,14 @@ + + + + + + + + + + + + + + diff --git a/docs/source/_static/aignostics-wordmark-light.svg b/docs/source/_static/aignostics-wordmark-light.svg new file mode 100644 index 000000000..7161535d4 --- /dev/null +++ b/docs/source/_static/aignostics-wordmark-light.svg @@ -0,0 +1,14 @@ + + + + + + + + + + + + + + diff --git a/docs/source/_static/custom.css b/docs/source/_static/custom.css index d451c4033..ff9de28a5 100644 --- a/docs/source/_static/custom.css +++ b/docs/source/_static/custom.css @@ -1,3 +1,26 @@ +/* Left-align the sidebar brand (Aignostics wordmark + "Documentation") */ +.sidebar-brand { + align-items: flex-start; +} +.sidebar-logo { + margin: 0; +} +.sidebar-brand-text { + text-align: left; + /* Subordinate the "Platform Documentation" descriptor to the wordmark above it. + Title case (not all-caps) so the two-word phrase reads naturally and wraps cleanly. */ + font-size: 0.9rem; + font-weight: 500; + color: var(--color-foreground-secondary); + margin-top: 0.3rem; + line-height: 1.3; +} + +/* Version stamp inline with the footer's copyright / attribution line */ +.version-stamp { + color: var(--color-foreground-muted); +} + /* Make mermaid diagrams use full page width */ .mermaid { max-width: 100% !important; diff --git a/docs/source/_static/favicon.png b/docs/source/_static/favicon.png new file mode 100644 index 000000000..ab225a570 Binary files /dev/null and b/docs/source/_static/favicon.png differ diff --git a/docs/source/_static/launchpad/01-launchpad-window.png b/docs/source/_static/launchpad/01-launchpad-window.png new file mode 100644 index 000000000..36f04dcaa Binary files /dev/null and b/docs/source/_static/launchpad/01-launchpad-window.png differ diff --git a/docs/source/_static/launchpad/02-menu-open.png b/docs/source/_static/launchpad/02-menu-open.png new file mode 100644 index 000000000..b12abacbc Binary files /dev/null and b/docs/source/_static/launchpad/02-menu-open.png differ diff --git a/docs/source/_static/launchpad/03-metadata-dropdown.png b/docs/source/_static/launchpad/03-metadata-dropdown.png new file mode 100644 index 000000000..a95746ad7 Binary files /dev/null and b/docs/source/_static/launchpad/03-metadata-dropdown.png differ diff --git a/docs/source/_static/launchpad/04-run-status.png b/docs/source/_static/launchpad/04-run-status.png new file mode 100644 index 000000000..b4a00db0b Binary files /dev/null and b/docs/source/_static/launchpad/04-run-status.png differ diff --git a/docs/source/_static/launchpad/05-qupath-result.png b/docs/source/_static/launchpad/05-qupath-result.png new file mode 100644 index 000000000..351a2378a Binary files /dev/null and b/docs/source/_static/launchpad/05-qupath-result.png differ diff --git a/docs/source/_templates/page.html b/docs/source/_templates/page.html new file mode 100644 index 000000000..0749fda99 --- /dev/null +++ b/docs/source/_templates/page.html @@ -0,0 +1,93 @@ +{#- Extend Furo's page template to add the version inline in the footer's left-details. -#} +{% extends "!page.html" %} +{% block footer %} +
+ {% if next -%} + +
+
+ {{ _("Next") }} +
+
{{ next.title }}
+
+ + + {%- endif %} + {% if prev -%} + + +
+
+ {{ _("Previous") }} +
+ {% if prev.link == pathto(master_doc) %} +
{{ _("Home") }}
+ {% else %} +
{{ prev.title }}
+ {% endif %} +
+ + {%- endif %} +
+
+
+ {%- if show_copyright %} +
+ {%- if hasdoc('copyright') %} + {% trans path=pathto('copyright'), copyright=copyright|e -%} + Copyright © {{ copyright }} + {%- endtrans %} + {%- else %} + {% trans copyright=copyright|e -%} + Copyright © {{ copyright }} + {%- endtrans %} + {%- endif %} +
+ {%- endif %} + {% trans %}Made with {% endtrans -%} + {%- if show_sphinx -%} + {% trans %}Sphinx and {% endtrans -%} + @pradyunsg's + {% endif -%} + {% trans %} + Furo + {% endtrans %} + · Version {{ release }} + {%- if last_updated -%} +
+ {% trans last_updated=last_updated|e -%} + Last updated on {{ last_updated }} + {%- endtrans -%} +
+ {%- endif %} +
+
+ {% if theme_footer_icons or READTHEDOCS -%} +
+ {% if theme_footer_icons -%} + {% for icon_dict in theme_footer_icons -%} + + {{- icon_dict.html -}} + + {% endfor %} + {%- else -%} + {%- if READTHEDOCS and slug -%} + + + + + + {%- endif -%} + {%- if READTHEDOCS and display_github and github_user != "None" and github_repo != "None" -%} + + + + + + {%- endif -%} + {%- endif %} +
+ {%- endif %} +
+
+{% endblock footer %} diff --git a/docs/source/conf.py b/docs/source/conf.py index 768f7ce65..132fd2b02 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -93,15 +93,25 @@ html_theme = "furo" html_static_path = ["_static"] html_css_files = ["custom.css"] -html_logo = "../../logo.png" +html_favicon = "_static/favicon.png" +html_title = "Platform Documentation" html_theme_options = { - "announcement": ( - 'GitHub - ' - 'PyPI - ' - 'Docker - ' - 'SonarQube - ' - 'Codecov' - ), + # Theme-adaptive Aignostics wordmark: white on the dark sidebar, + # aubergine on the light sidebar (a single white logo would be + # invisible in light mode). + "light_logo": "aignostics-wordmark-light.svg", + "dark_logo": "aignostics-wordmark-dark.svg", + # Aignostics brand colors (from the Platform Console UI palette). + # Light mode uses the aubergine primary; dark mode uses the lighter + # tint so links stay legible on a dark background. + "light_css_variables": { + "color-brand-primary": "#483569", + "color-brand-content": "#483569", + }, + "dark_css_variables": { + "color-brand-primary": "#9b95ec", + "color-brand-content": "#9b95ec", + }, } diff --git a/docs/source/get_started_cli.rst b/docs/source/get_started_cli.rst new file mode 100644 index 000000000..2c38293ae --- /dev/null +++ b/docs/source/get_started_cli.rst @@ -0,0 +1,2 @@ +.. include:: ../partials/get_started_cli.md + :parser: myst_parser.sphinx_ diff --git a/docs/source/get_started_launchpad.rst b/docs/source/get_started_launchpad.rst new file mode 100644 index 000000000..715fb7986 --- /dev/null +++ b/docs/source/get_started_launchpad.rst @@ -0,0 +1,2 @@ +.. include:: ../partials/get_started_launchpad.md + :parser: myst_parser.sphinx_ diff --git a/docs/source/get_started_library.rst b/docs/source/get_started_library.rst new file mode 100644 index 000000000..b00225f7c --- /dev/null +++ b/docs/source/get_started_library.rst @@ -0,0 +1,2 @@ +.. include:: ../partials/get_started_library.md + :parser: myst_parser.sphinx_ diff --git a/docs/source/get_started_mcp.rst b/docs/source/get_started_mcp.rst new file mode 100644 index 000000000..cd635fec8 --- /dev/null +++ b/docs/source/get_started_mcp.rst @@ -0,0 +1,2 @@ +.. include:: ../partials/get_started_mcp.md + :parser: myst_parser.sphinx_ diff --git a/docs/source/index.rst b/docs/source/index.rst index 9e33aeb53..b12c53ab1 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -1,6 +1,7 @@ .. only:: html - .. include:: main.rst + .. include:: ../partials/README_main.md + :parser: myst_parser.sphinx_ .. toctree:: :hidden: @@ -10,8 +11,18 @@ .. toctree:: :maxdepth: 1 :hidden: + :caption: Get started + + get_started_launchpad + get_started_cli + get_started_library + get_started_mcp + +.. toctree:: + :maxdepth: 1 + :hidden: + :caption: Reference - main platform_overview cli_reference lib_reference diff --git a/docs/source/main.rst b/docs/source/main.rst deleted file mode 100644 index 5e86d8f51..000000000 --- a/docs/source/main.rst +++ /dev/null @@ -1,2 +0,0 @@ -.. include:: ../partials/README_main.md - :parser: myst_parser.sphinx_