feat: aignostics-sdk v2 — consolidated integration branch [PYSDK-133]

.github/workflows/_package-publish.yml

@@ -171,17 +171,36 @@ jobs:
           GIT_CLIFF_CHANGELOG: ${{ steps.git-cliff.outputs.changelog }}
         run: cat "$GIT_CLIFF_CHANGELOG"
 
-      - name: Build distribution into dist/
+      - name: Verify lockstep versioning
         shell: bash
-        run: make dist
+        run: |
+          SDK_VERSION=$(grep '^version = ' packages/aignostics-sdk/pyproject.toml | head -1 | sed 's/version = "\(.*\)"/\1/')
+          FULL_VERSION=$(grep '^version = ' packages/aignostics/pyproject.toml | head -1 | sed 's/version = "\(.*\)"/\1/')
+          if [ "$SDK_VERSION" != "$FULL_VERSION" ]; then
+            echo "❌ Version mismatch: aignostics-sdk=$SDK_VERSION, aignostics=$FULL_VERSION"
+            exit 1
+          fi
+          echo "✅ Versions match: $SDK_VERSION"
 
-      - name: Publish distribution to Python Package Index at pypi.org
+      - name: Build aignostics-sdk distribution
+        shell: bash
+        run: uv build --package aignostics-sdk --out-dir dist/
+
+      - name: Publish aignostics-sdk to PyPI
         shell: bash
         env:
           UV_PUBLISH_TOKEN: ${{ secrets.UV_PUBLISH_TOKEN }}
-        run: |
-          # Use uv's credential storage - uv will read from UV_PUBLISH_TOKEN env var automatically
-          uv publish
+        run: uv publish dist/aignostics_sdk-*
+
+      - name: Build aignostics distribution
+        shell: bash
+        run: uv build --package aignostics --out-dir dist/
+
+      - name: Publish aignostics to PyPI
+        shell: bash
+        env:
+          UV_PUBLISH_TOKEN: ${{ secrets.UV_PUBLISH_TOKEN }}
+        run: uv publish dist/aignostics-*
 
       - name: Download test results for ubuntu-latest generated in _test.yml
         if: |
@@ -276,3 +295,25 @@ jobs:
           # See https://github.com/cli/cli/discussions/10696
           gh api repos/aignostics/python-sdk/dispatches \
             -f event_type=release_created_programatically
+
+  smoke_test_slim:
+    runs-on: ubuntu-latest
+    needs: package_publish
+    continue-on-error: true
+    steps:
+      - name: Install uv
+        uses: astral-sh/setup-uv@cec208311dfd045dd5311c1add060b2062131d57 # v8.0.0
+
+      - name: Smoke test aignostics-sdk
+        shell: bash
+        run: |
+          VERSION=$(echo "${{ github.ref_name }}" | sed 's/^v//')
+          uv venv /tmp/slim-venv
+          uv pip install --python /tmp/slim-venv/bin/python "aignostics-sdk==$VERSION"
+          /tmp/slim-venv/bin/aignostics-sdk --help
+          /tmp/slim-venv/bin/python -c "from aignostics_sdk.platform import Client; print('✅ slim import OK')"
+          if /tmp/slim-venv/bin/python -c "import openslide" 2>/dev/null; then
+            echo "❌ openslide should not be installed in slim package"
+            exit 1
+          fi
+          echo "✅ Heavy deps correctly absent"

docs/partials/CLI_REFERENCE_header.md

@@ -0,0 +1,141 @@
+# 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

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.

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.

docs/source/index.rst

@@ -12,6 +12,7 @@
    :hidden:
 
    main
+   migration
    platform_overview
    cli_reference
    lib_reference