From cb625d002bf64cbd97132a37cafe03d69a38deaf Mon Sep 17 00:00:00 2001 From: Ari Angelo Date: Thu, 28 May 2026 12:24:34 +0200 Subject: [PATCH 1/3] docs: add v2 migration guide and dual-package install instructions Adds documentation for the v2 dual-package distribution that splits the SDK into aignostics-sdk (slim API client) and aignostics (full SDK), including migration guide for users upgrading from v1. --- docs/partials/CLI_REFERENCE_header.md | 142 ++++++++++++++++++++++++++ docs/partials/README_footer.md | 3 + docs/partials/README_main.md | 94 +++++++++++++++++ docs/source/index.rst | 1 + docs/source/migration.md | 112 ++++++++++++++++++++ noxfile.py | 23 ++++- packages/aignostics-sdk/CLAUDE.md | 82 +++++++++++++++ src/aignostics/CLAUDE.md | 7 ++ 8 files changed, 463 insertions(+), 1 deletion(-) create mode 100644 docs/partials/CLI_REFERENCE_header.md create mode 100644 docs/source/migration.md create mode 100644 packages/aignostics-sdk/CLAUDE.md diff --git a/docs/partials/CLI_REFERENCE_header.md b/docs/partials/CLI_REFERENCE_header.md new file mode 100644 index 000000000..df97712e3 --- /dev/null +++ b/docs/partials/CLI_REFERENCE_header.md @@ -0,0 +1,142 @@ +# CLI Reference + +The Aignostics Python SDK provides two CLI entry points: + +- **`aignostics`** — Full SDK (installed with `pip install aignostics`). Includes all commands + for application runs, WSI processing, dataset downloads, cloud storage, and the Launchpad. +- **`aignostics-sdk`** — Slim API client (installed with `pip install aignostics-sdk`). Includes + only user authentication and SDK metadata schema commands. + +When the full `aignostics` package is installed both entry points are available. + +--- + +## `aignostics-sdk` CLI Reference + +Command Line Interface of the slim `aignostics-sdk` distribution. + +**Usage**: + +```console +$ aignostics-sdk [OPTIONS] COMMAND [ARGS]... +``` + +**Options**: + +* `--install-completion`: Install completion for the current shell. +* `--show-completion`: Show completion for the current shell, to copy it or customize the installation. +* `--help`: Show this message and exit. + +**Commands**: + +* `user`: User operations such as login, logout and whoami. +* `sdk`: Platform operations such as dumping the SDK run and item metadata schemas. + +### `aignostics-sdk user` + +User operations such as login, logout and whoami. + +**Usage**: + +```console +$ aignostics-sdk user [OPTIONS] COMMAND [ARGS]... +``` + +**Commands**: + +* `login`: Authenticate with the Aignostics Platform using OAuth 2.0 device flow. +* `logout`: Remove cached authentication token. +* `whoami`: Show the currently authenticated user. + +#### `aignostics-sdk user login` + +Authenticate with the Aignostics Platform using OAuth 2.0 device flow. + +**Usage**: + +```console +$ aignostics-sdk user login [OPTIONS] +``` + +**Options**: + +* `--help`: Show this message and exit. + +#### `aignostics-sdk user logout` + +Remove cached authentication token. + +**Usage**: + +```console +$ aignostics-sdk user logout [OPTIONS] +``` + +**Options**: + +* `--help`: Show this message and exit. + +#### `aignostics-sdk user whoami` + +Show the currently authenticated user. + +**Usage**: + +```console +$ aignostics-sdk user whoami [OPTIONS] +``` + +**Options**: + +* `--mask-secrets / --no-mask-secrets`: Mask secrets in output. [default: mask-secrets] +* `--help`: Show this message and exit. + +### `aignostics-sdk sdk` + +Platform operations such as dumping the SDK run and item metadata schemas. + +**Usage**: + +```console +$ aignostics-sdk sdk [OPTIONS] COMMAND [ARGS]... +``` + +**Commands**: + +* `run-metadata-schema`: Export the JSON Schema for SDK run custom metadata. +* `item-metadata-schema`: Export the JSON Schema for SDK item custom metadata. + +#### `aignostics-sdk sdk run-metadata-schema` + +Export the JSON Schema for SDK run custom metadata. + +**Usage**: + +```console +$ aignostics-sdk sdk run-metadata-schema [OPTIONS] +``` + +**Options**: + +* `--pretty / --no-pretty`: Pretty-print the JSON output. [default: no-pretty] +* `--help`: Show this message and exit. + +#### `aignostics-sdk sdk item-metadata-schema` + +Export the JSON Schema for SDK item custom metadata. + +**Usage**: + +```console +$ aignostics-sdk sdk item-metadata-schema [OPTIONS] +``` + +**Options**: + +* `--pretty / --no-pretty`: Pretty-print the JSON output. [default: no-pretty] +* `--help`: Show this message and exit. + +--- + +## `aignostics` CLI Reference + diff --git a/docs/partials/README_footer.md b/docs/partials/README_footer.md index 26a29209b..9a511460e 100644 --- a/docs/partials/README_footer.md +++ b/docs/partials/README_footer.md @@ -1,5 +1,8 @@ ## Further Reading +1. **Upgrading from v1?** Read the + [v2 Migration Guide](https://aignostics.readthedocs.io/en/latest/migration.html) + for updated import paths and install instructions. 1. Inspect our [security policy](https://aignostics.readthedocs.io/en/latest/security.html) with detailed documentation of checks, tools and principles. diff --git a/docs/partials/README_main.md b/docs/partials/README_main.md index 9232a42bb..647d6ed67 100644 --- a/docs/partials/README_main.md +++ b/docs/partials/README_main.md @@ -24,6 +24,62 @@ more about how we achieve ## Installation +> **v2 dual-package distribution**: The SDK is now published as two separate PyPI packages. +> Use `aignostics-sdk` for the slim API client, or `aignostics` for the full SDK with GUI, WSI +> processing, and dataset downloads. See the [v2 Migration Guide](#migrating-from-v1-to-v2) +> if you are upgrading from v1. + +### API client only (slim) + +For users who only need the platform API client with minimal dependencies: + +```bash +pip install aignostics-sdk +``` + +Python imports: + +```python +from aignostics_sdk.platform import Client +``` + +CLI: + +```bash +aignostics-sdk user login +aignostics-sdk user whoami +``` + +### Full SDK + +For users who need WSI processing, dataset downloads, the desktop Launchpad, and all features: + +```bash +pip install aignostics +``` + +Python imports (full SDK modules unchanged from v1): + +```python +from aignostics.application import ... # ML application orchestration +from aignostics.wsi import ... # Whole slide image processing +from aignostics.dataset import ... # IDC dataset downloads +``` + +Platform/utils imports (updated namespace in v2): + +```python +from aignostics_sdk.platform import Client # was: from aignostics.platform import Client +from aignostics_sdk.utils import BaseService # was: from aignostics.utils import BaseService +``` + +CLI (unchanged): + +```bash +aignostics user login +aignostics application list +``` + 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. @@ -656,3 +712,41 @@ Now that you have an overview of the Aignostics Python SDK and its interfaces, h - **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/) +- **Upgrading from v1?** See the [v2 Migration Guide](https://aignostics.readthedocs.io/en/latest/migration.html) for updated import paths and install instructions + +## Migrating from v1 to v2 + +v2 introduces `aignostics-sdk`, a slim distribution containing only the platform API client. +The full `aignostics` package now depends on `aignostics-sdk`. + +### Import path changes + +| v1 | v2 | +|----|----| +| `from aignostics.platform import Client` | `from aignostics_sdk.platform import Client` | +| `from aignostics.utils import BaseService` | `from aignostics_sdk.utils import BaseService` | +| `from aignostics.constants import INTERNAL_ORGS` | `from aignostics_sdk.constants import INTERNAL_ORGS` | + +All other modules (`application`, `wsi`, `dataset`, `bucket`, `qupath`, `notebook`, `gui`, +`system`) remain under the `aignostics.*` namespace and are unchanged. + +### CLI changes + +The `aignostics` CLI is unchanged. A new `aignostics-sdk` CLI is available when only the slim +package is installed: + +```bash +# slim install +aignostics-sdk user login +aignostics-sdk user whoami + +# full install (unchanged) +aignostics user login +aignostics application list +``` + +### If you only use the API client + +Replace `pip install aignostics` with `pip install aignostics-sdk` for a significantly smaller +install footprint. See the [full migration guide](https://aignostics.readthedocs.io/en/latest/migration.html) +for a complete checklist. diff --git a/docs/source/index.rst b/docs/source/index.rst index 9e33aeb53..957ca1693 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -12,6 +12,7 @@ :hidden: main + migration platform_overview cli_reference lib_reference diff --git a/docs/source/migration.md b/docs/source/migration.md new file mode 100644 index 000000000..e505409ae --- /dev/null +++ b/docs/source/migration.md @@ -0,0 +1,112 @@ +# Migrating from v1 to v2 + +v2 of the Aignostics Python SDK introduces `aignostics-sdk`, a slim distribution that contains +only the platform API client and core utilities. The full `aignostics` package now depends on +`aignostics-sdk` and delegates platform/utils functionality to it. + +This is a **breaking change** for anyone importing `aignostics.platform` or `aignostics.utils` +directly. + +## What changed + +The `platform` and `utils` modules (and `constants`) have moved to a separate PyPI package called +`aignostics-sdk`. Their Python namespace has changed from `aignostics.*` to `aignostics_sdk.*`. + +| v1 (Python namespace) | v2 (Python namespace) | +|-----------------------|-----------------------| +| `aignostics.platform` | `aignostics_sdk.platform` | +| `aignostics.utils` | `aignostics_sdk.utils` | +| `aignostics.constants` | `aignostics_sdk.constants` | + +All other modules (`application`, `wsi`, `dataset`, `bucket`, `qupath`, `notebook`, `gui`, +`system`) remain under the `aignostics.*` namespace and are only available in the full package. + +## Import path changes + +Update your Python imports as follows: + +| v1 import | v2 import | +|-----------|-----------| +| `from aignostics.platform import Client` | `from aignostics_sdk.platform import Client` | +| `from aignostics.platform import InputItem, InputArtifact` | `from aignostics_sdk.platform import InputItem, InputArtifact` | +| `from aignostics.utils import BaseService` | `from aignostics_sdk.utils import BaseService` | +| `from aignostics.utils import Health` | `from aignostics_sdk.utils import Health` | +| `from aignostics.utils import locate_implementations` | `from aignostics_sdk.utils import locate_implementations` | +| `from aignostics.constants import INTERNAL_ORGS` | `from aignostics_sdk.constants import INTERNAL_ORGS` | +| `from aignostics import platform` | `from aignostics_sdk import platform` | + +## Installation changes + +### If you only use the API client + +Replace the full package with the slim package for a significantly smaller install footprint: + +```bash +# v1 +pip install aignostics + +# v2 — slim install +pip install aignostics-sdk +``` + +The slim `aignostics-sdk` package includes only `platform`, `utils`, and `constants`. +It has no dependency on OpenSlide, wsidicom, boto3, Google Cloud Storage, or other heavy +libraries required by the WSI and dataset modules. + +### If you use the full SDK + +The install command is **unchanged**: + +```bash +pip install aignostics +``` + +The full package automatically pulls in `aignostics-sdk` as a dependency, so all +`aignostics_sdk.*` imports work after installing `aignostics`. + +## CLI changes + +The `aignostics` CLI command is **unchanged**. A new `aignostics-sdk` CLI entry point is +registered when the slim package is installed: + +```bash +# Slim install — available commands +aignostics-sdk user login +aignostics-sdk user logout +aignostics-sdk user whoami +aignostics-sdk sdk run-metadata-schema +aignostics-sdk sdk item-metadata-schema + +# Full install — unchanged command, full feature set +aignostics user login +aignostics application list +aignostics wsi inspect slide.svs +``` + +## Health checks using the full SDK + +In v1, the health check import was: + +```python +# v1 +from aignostics.system import Service as SystemService + +health = SystemService().health() +``` + +This is **unchanged** in v2 — `system` remains in the `aignostics` namespace: + +```python +# v2 — same as v1 +from aignostics.system import Service as SystemService + +health = SystemService().health() +``` + +## Quick migration checklist + +1. Update `from aignostics.platform import ...` to `from aignostics_sdk.platform import ...` +2. Update `from aignostics.utils import ...` to `from aignostics_sdk.utils import ...` +3. Update `from aignostics.constants import ...` to `from aignostics_sdk.constants import ...` +4. If you only need the API client, switch `pip install aignostics` to `pip install aignostics-sdk` +5. If you use the full SDK, keep `pip install aignostics` — no pip change needed diff --git a/noxfile.py b/noxfile.py index dd69ce240..df227084d 100644 --- a/noxfile.py +++ b/noxfile.py @@ -502,10 +502,17 @@ def _generate_sdk_metadata_schemas(session: nox.Session) -> None: def _generate_cli_reference(session: nox.Session) -> None: """Generate CLI_REFERENCE.md. + The generated file is assembled from two parts: + 1. A static header partial (docs/partials/CLI_REFERENCE_header.md) that documents + the aignostics-sdk slim CLI entry point and provides an introduction. + 2. The auto-generated aignostics CLI reference produced by typer-cli. + Args: session: The nox session instance """ if CLI_MODULE: + # Generate the aignostics CLI reference into a temporary file + tmp_output = Path("CLI_REFERENCE_aignostics.md") session.run( "python", "-W", @@ -520,10 +527,24 @@ def _generate_cli_reference(session: nox.Session) -> None: "--title", "CLI Reference", "--output", - "CLI_REFERENCE.md", + str(tmp_output), external=True, ) + # Prepend the static header (aignostics-sdk CLI docs + intro) to the typer output. + # The header already includes its own "# CLI Reference" heading and the + # "## `aignostics` CLI Reference" sub-heading, so we strip the auto-generated + # top-level heading from the typer output to avoid duplication. + header = Path("docs/partials/CLI_REFERENCE_header.md").read_text(encoding=UTF8) + aignostics_body = tmp_output.read_text(encoding=UTF8) + # Remove the first "# CLI Reference" heading generated by typer (first line) + aignostics_body_lines = aignostics_body.splitlines(keepends=True) + if aignostics_body_lines and aignostics_body_lines[0].startswith("# CLI Reference"): + aignostics_body = "".join(aignostics_body_lines[1:]).lstrip("\n") + Path("CLI_REFERENCE.md").write_text(header + aignostics_body, encoding=UTF8) + tmp_output.unlink(missing_ok=True) + session.log("Generated CLI_REFERENCE.md with aignostics-sdk header and aignostics CLI docs") + def _generate_api_reference(session: nox.Session) -> None: """Generate API_REFERENCE_v1.md and API_REFERENCE_v2.md. diff --git a/packages/aignostics-sdk/CLAUDE.md b/packages/aignostics-sdk/CLAUDE.md new file mode 100644 index 000000000..72278085a --- /dev/null +++ b/packages/aignostics-sdk/CLAUDE.md @@ -0,0 +1,82 @@ +# CLAUDE.md - aignostics-sdk (Slim Package) + +This is the **slim distribution** of the Aignostics SDK, published to PyPI as `aignostics-sdk`. +It contains only the platform API client and core utilities — no WSI processing, no GUI, no dataset +downloads, no cloud storage abstraction. + +## What this package contains + +| Module | Purpose | +|--------|---------| +| `aignostics_sdk.platform` | OAuth 2.0 authentication, API client, SDK metadata tracking, run/item resources | +| `aignostics_sdk.utils` | Core infrastructure: DI container, logging, settings, `BaseService`, health checks, user agent | +| `aignostics_sdk.constants` | Shared constants (e.g. `INTERNAL_ORGS`) | + +## Python namespace + +All public APIs are under the `aignostics_sdk.*` namespace: + +```python +from aignostics_sdk.platform import Client +from aignostics_sdk.utils import BaseService, Health +from aignostics_sdk.constants import INTERNAL_ORGS +``` + +> This is a **breaking change** from v1, where these modules lived under `aignostics.platform`, +> `aignostics.utils`, and `aignostics.constants`. +> See the [v2 migration guide](../../docs/source/migration.md) for the full import mapping. + +## CLI entry point + +The slim package registers the `aignostics-sdk` CLI entry point (in addition to the `aignostics` +entry point provided by the full package): + +```bash +# Slim install only +aignostics-sdk user login +aignostics-sdk user logout +aignostics-sdk user whoami +aignostics-sdk sdk run-metadata-schema +aignostics-sdk sdk item-metadata-schema +``` + +The `aignostics` CLI (full package) provides the same commands plus all heavy-module commands +(`application`, `wsi`, `dataset`, `bucket`, etc.). + +## Source history + +The source for this package was migrated from: + +- `src/aignostics/platform/` → `packages/aignostics-sdk/src/aignostics_sdk/platform/` +- `src/aignostics/utils/` → `packages/aignostics-sdk/src/aignostics_sdk/utils/` +- `src/aignostics/constants.py` → `packages/aignostics-sdk/src/aignostics_sdk/constants.py` + +## Dependencies + +Minimal by design — no OpenSlide, wsidicom, boto3, google-cloud-storage, or other heavy libraries. +Runtime dependencies are limited to what the platform API client strictly needs (httpx/requests, +pydantic, tenacity, etc.). + +## Module architecture + +This package follows the same three-layer pattern as the rest of the SDK: + +```text +aignostics_sdk/ +├── platform/ +│ ├── _service.py # Business logic (API client, OAuth, caching, retry) +│ ├── _cli.py # CLI: user login/logout/whoami, sdk metadata-schema +│ ├── _settings.py # Pydantic settings +│ └── CLAUDE.md # Platform module documentation +├── utils/ +│ ├── _service.py # BaseService, Health, DI container +│ ├── _cli.py # CLI: mcp run/list-tools +│ ├── _settings.py # Pydantic settings +│ └── CLAUDE.md # Utils module documentation +└── constants.py # Shared constants +``` + +## Testing + +Tests for this package live alongside the source in the shared `tests/` tree at the repo root. +Run them with the standard test commands documented in the root `CLAUDE.md`. diff --git a/src/aignostics/CLAUDE.md b/src/aignostics/CLAUDE.md index d14706c47..183662b27 100644 --- a/src/aignostics/CLAUDE.md +++ b/src/aignostics/CLAUDE.md @@ -1,5 +1,12 @@ # CLAUDE.md - Aignostics SDK Modules Overview +> **v2 Architecture Note**: In v2, this `src/aignostics/` tree contains only the *heavy* modules: +> `application`, `wsi`, `dataset`, `bucket`, `qupath`, `notebook`, `gui`, and `system`. +> The `platform` and `utils` modules (plus `constants`) have moved to the slim package at +> `packages/aignostics-sdk/` under the `aignostics_sdk` namespace. +> The full `aignostics` package depends on `aignostics-sdk` and re-exports nothing from those +> moved modules — callers must update their imports (see `migration.md` in the docs). + This file provides a comprehensive overview of all modules in the Aignostics SDK, their core features, user interfaces, and interactions. ## Module Index From e1483140475d48acf5ec5d6149a88b1514ab74b8 Mon Sep 17 00:00:00 2001 From: Ari Angelo Date: Thu, 28 May 2026 12:24:50 +0200 Subject: [PATCH 2/3] fix: add missing end-of-file newline to CLI_REFERENCE_header.md --- docs/partials/CLI_REFERENCE_header.md | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/partials/CLI_REFERENCE_header.md b/docs/partials/CLI_REFERENCE_header.md index df97712e3..4ae10b0a0 100644 --- a/docs/partials/CLI_REFERENCE_header.md +++ b/docs/partials/CLI_REFERENCE_header.md @@ -139,4 +139,3 @@ $ aignostics-sdk sdk item-metadata-schema [OPTIONS] --- ## `aignostics` CLI Reference - From e804c403d57fb7a951096f294f65a20209507b43 Mon Sep 17 00:00:00 2001 From: Ari Angelo Date: Thu, 28 May 2026 12:25:10 +0200 Subject: [PATCH 3/3] fix: fix trailing whitespace in code comments in README_main.md --- docs/partials/README_main.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/partials/README_main.md b/docs/partials/README_main.md index 647d6ed67..4bb043a77 100644 --- a/docs/partials/README_main.md +++ b/docs/partials/README_main.md @@ -69,8 +69,8 @@ from aignostics.dataset import ... # IDC dataset downloads Platform/utils imports (updated namespace in v2): ```python -from aignostics_sdk.platform import Client # was: from aignostics.platform import Client -from aignostics_sdk.utils import BaseService # was: from aignostics.utils import BaseService +from aignostics_sdk.platform import Client # was: from aignostics.platform import Client +from aignostics_sdk.utils import BaseService # was: from aignostics.utils import BaseService ``` CLI (unchanged):