sectra-image-analysis-api 1.5.1__tar.gz

sectra_image_analysis_api-1.5.1/.github/workflows/docs.yml

@@ -0,0 +1,25 @@
+name: Deploy docs
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - docs/**
+      - mkdocs.yml
+    tags:
+      - "v*.*.*"
+
+permissions:
+  contents: write
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+          cache: pip
+      - run: pip install mkdocs-material
+      - run: mkdocs gh-deploy --force

sectra_image_analysis_api-1.5.1/.github/workflows/publish.yaml

@@ -0,0 +1,35 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - "v*.*.*"
+
+jobs:
+  publish:
+    name: Build and publish
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write  # required for OIDC trusted publisher
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0  # needed for hatch-vcs to resolve the tag
+
+      - name: Ensure tag is on main
+        run: |
+          git fetch origin main
+          if ! git merge-base --is-ancestor "$GITHUB_SHA" origin/main; then
+            echo "Tagged commit is not on main. Aborting."
+            exit 1
+          fi
+
+      - uses: astral-sh/setup-uv@v5
+
+      - name: Build
+        run: uv build
+
+      - name: Publish to PyPI
+        run: uv publish

sectra_image_analysis_api-1.5.1/.gitignore

@@ -0,0 +1,53 @@
+# These are some examples of commonly ignored file patterns.
+# You should customize this list as applicable to your project.
+# Learn more about .gitignore:
+#     https://www.atlassian.com/git/tutorials/saving-changes/gitignore
+
+# Node artifact files
+.vscode/
+node_modules/
+dist/
+
+# Compiled Java class files
+*.class
+
+# Compiled Python bytecode
+*.py[cod]
+
+# Log files
+*.log
+
+# Package files
+*.jar
+
+# Maven
+target/
+dist/
+
+# JetBrains IDE
+.idea/
+
+# Unit test reports
+TEST*.xml
+
+# Generated by MacOS
+.DS_Store
+
+# Generated by Windows
+Thumbs.db
+
+# Applications
+*.app
+*.exe
+*.war
+
+# Large media files
+*.mp4
+*.tiff
+*.avi
+*.flv
+*.mov
+*.wmv
+
+**/*.egg-info
+**/*build

sectra_image_analysis_api-1.5.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) [year] [fullname]
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

sectra_image_analysis_api-1.5.1/PKG-INFO

@@ -0,0 +1,143 @@
+Metadata-Version: 2.4
+Name: sectra-image-analysis-api
+Version: 1.5.1
+Summary: A wrapper for the Sectra Image Analysis API.
+Project-URL: Homepage, https://github.com/amspath/sectra-image-analysis-api
+Project-URL: Repository, https://github.com/amspath/sectra-image-analysis-api
+Author-email: Robin van Hoorn <r.d.vanhoorn@amsterdamumc.nl>
+License: MIT License
+        
+        Copyright (c) [year] [fullname]
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Keywords: WSI,digital pathology,medical imaging,whole slide image
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Scientific/Engineering :: Medical Science Apps.
+Requires-Python: >=3.11
+Requires-Dist: hl7>=0.4.5
+Requires-Dist: pillow>=10.0.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: requests-toolbelt>=1.0.0
+Requires-Dist: requests>=2.28.0
+Provides-Extra: dev
+Requires-Dist: fastapi[standard]>=0.115.0; extra == 'dev'
+Requires-Dist: honcho>=2.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.12.5; extra == 'dev'
+Requires-Dist: ty>=0.0.10; extra == 'dev'
+Requires-Dist: types-requests>=2.32.4; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Python Client for Sectra
+
+This python package aims to facilite the development of AI applications for Sectra PACS.
+
+## Version
+The library currently supports functionality up to do version 3.4 (Dec 2023). However, we will update to 5.0 in Juli, after which this library will be adjusted to the newest version as well. 
+
+## Installation
+
+To install sectra_client:
+```
+pip install sectra-image-analysis-api
+```
+
+## Usage
+
+Before using the client, make sure you have access to a valid authentication token, and url, sent in the analysis requests.
+
+### Example 1: Retrieve image information
+
+```python
+from sectra_client import SectraClient
+
+# Info, sent by Sectra in the request
+callback_url = "http://sectraweb.*.*.*/SectraPathologyServer/external/imageanalysis/v1"
+callback_token = "abcde"
+slide_id = "fghij"
+
+# Use the context manager
+with SectraClient(
+    url=callback_url,
+    token=callback_token
+) as client:
+    # Returns the image info with extended and personal health information data
+    image_info = client.get_image_metadata(slide_id, extended=True, phi=True)
+```
+
+### Example 2: Download WSI
+```python
+from sectra_client import SectraClient
+
+# Info, sent by Sectra in the request
+...
+
+# Use the context manager
+with SectraClient(
+    url=callback_url,
+    token=callback_token
+) as client:
+    # Download the file(s) to an output directory, and returns the file paths of the file(s). 
+    file_paths = client.download_slide_files(slide_id, output_dir="./path/to/output/dir/")
+```
+
+### Example 3: Without context manager
+It is also possible to use the SectraClient without the context manager
+```python
+from sectra_client import SectraClient
+
+# Info, sent by Setra in the request
+...
+
+# Open context manager
+client = SectraClient(url=callback_url, token=callback_token)
+
+# Perform API interactions
+image_info = client.get_image_metadata(slide_id, extended=True, phi=False)
+
+# Make sure to close the connection
+client.close()
+```
+
+## Local development with the mock server
+`MockSectraServer` simulates a Sectra PACS instance in memory so you can develop and test without a real server.
+
+```python
+from sectra_client.mock_server import MockSectraServer
+
+server = MockSectraServer(token="dev-token")
+with server.run(port=8001):
+    server.trigger(
+        webhook_url="http://localhost:8000/sectra/hook",
+        application_id="my-app",
+        slide_id="slide-001",
+    )
+    results = server.get_results(app_id="my-app", slide_id="slide-001")
+```
+
+See `examples/local_dev.py` for a complete round-trip: both servers started from a single script, a fake invocation fired, and results read back.

sectra_image_analysis_api-1.5.1/README.md

@@ -0,0 +1,88 @@
+# Python Client for Sectra
+
+This python package aims to facilite the development of AI applications for Sectra PACS.
+
+## Version
+The library currently supports functionality up to do version 3.4 (Dec 2023). However, we will update to 5.0 in Juli, after which this library will be adjusted to the newest version as well. 
+
+## Installation
+
+To install sectra_client:
+```
+pip install sectra-image-analysis-api
+```
+
+## Usage
+
+Before using the client, make sure you have access to a valid authentication token, and url, sent in the analysis requests.
+
+### Example 1: Retrieve image information
+
+```python
+from sectra_client import SectraClient
+
+# Info, sent by Sectra in the request
+callback_url = "http://sectraweb.*.*.*/SectraPathologyServer/external/imageanalysis/v1"
+callback_token = "abcde"
+slide_id = "fghij"
+
+# Use the context manager
+with SectraClient(
+    url=callback_url,
+    token=callback_token
+) as client:
+    # Returns the image info with extended and personal health information data
+    image_info = client.get_image_metadata(slide_id, extended=True, phi=True)
+```
+
+### Example 2: Download WSI
+```python
+from sectra_client import SectraClient
+
+# Info, sent by Sectra in the request
+...
+
+# Use the context manager
+with SectraClient(
+    url=callback_url,
+    token=callback_token
+) as client:
+    # Download the file(s) to an output directory, and returns the file paths of the file(s). 
+    file_paths = client.download_slide_files(slide_id, output_dir="./path/to/output/dir/")
+```
+
+### Example 3: Without context manager
+It is also possible to use the SectraClient without the context manager
+```python
+from sectra_client import SectraClient
+
+# Info, sent by Setra in the request
+...
+
+# Open context manager
+client = SectraClient(url=callback_url, token=callback_token)
+
+# Perform API interactions
+image_info = client.get_image_metadata(slide_id, extended=True, phi=False)
+
+# Make sure to close the connection
+client.close()
+```
+
+## Local development with the mock server
+`MockSectraServer` simulates a Sectra PACS instance in memory so you can develop and test without a real server.
+
+```python
+from sectra_client.mock_server import MockSectraServer
+
+server = MockSectraServer(token="dev-token")
+with server.run(port=8001):
+    server.trigger(
+        webhook_url="http://localhost:8000/sectra/hook",
+        application_id="my-app",
+        slide_id="slide-001",
+    )
+    results = server.get_results(app_id="my-app", slide_id="slide-001")
+```
+
+See `examples/local_dev.py` for a complete round-trip: both servers started from a single script, a fake invocation fired, and results read back.

sectra_image_analysis_api-1.5.1/docs/api/client.md

@@ -0,0 +1,137 @@
+# SectraClient
+
+```python
+from sectra_client import SectraClient
+```
+
+The primary interface for communicating with a Sectra PACS instance. Supports use as a context manager (recommended) or manually via `close()`.
+
+## Constructor
+
+```python
+SectraClient(url: str, token: str, _allow_http: bool = False)
+```
+
+| Parameter | Description |
+|---|---|
+| `url` | Base URL of the Sectra Image Analysis API (from `callbackInfo.url`) |
+| `token` | Auth token (from `callbackInfo.token`) |
+| `_allow_http` | Whether to allow plain HTTP during communication with Sectra (useful for `MockSectraServer`) |
+
+## Properties
+
+| Property | Type | Description |
+|---|---|---|
+| `version_info` | `ApplicationInfo` | API and software version reported by the server |
+| `response_headers` | `dict` | Headers to forward in your webhook response (required by Sectra) |
+
+## Image metadata
+
+### `get_image_metadata`
+
+```python
+client.get_image_metadata(slide_id: str, extended: bool = False, phi: bool = False) -> ImageMetadata
+```
+
+Retrieves slide metadata including dimensions, focal planes, optical paths, and staining info. Set `extended=True` for additional fields and `phi=True` to include protected health information.
+
+### `get_image_infos_in_case`
+
+```python
+client.get_image_infos_in_case(
+    accession_number: str,
+    phi: bool = False,
+    accession_number_issuer_id: str | None = None,
+) -> list[CaseImageInfo]
+```
+
+Returns all slides belonging to a case, looked up by accession number. Requires IA-API 1.9+.
+
+### `get_image_infos_in_case_by_slide_id`
+
+```python
+client.get_image_infos_in_case_by_slide_id(
+    slide_id: str,
+    phi: bool = False,
+    accession_number_issuer_id: str | None = None,
+) -> list[CaseImageInfo]
+```
+
+Same as above but resolves the case from a known `slide_id`. Requires IA-API 1.9+.
+
+## File operations
+
+### `get_label_image`
+
+```python
+client.get_label_image(slide_id: str) -> LabelImage
+```
+
+Retrieves the slide's label/thumbnail image. Call `.convert_to_pil()` on the result to get a Pillow `Image`.
+
+### `download_slide_files`
+
+```python
+client.download_slide_files(slide_id: str, output_dir: pathlib.Path | str) -> list[pathlib.Path]
+```
+
+Downloads all WSI files for a slide into `output_dir` (created if absent). Returns the paths of the saved files. Handles multipart responses transparently.
+
+## Results
+
+### `create_results`
+
+```python
+client.create_results(app_id: str, results: Result) -> ResultResponse
+```
+
+Submits analysis results to Sectra. Returns the stored result including its assigned `id`.
+
+### `get_result_by_result_id`
+
+```python
+client.get_result_by_result_id(app_id: str, result_id: int) -> ResultResponse
+```
+
+Fetches a single stored result by ID.
+
+### `get_all_results`
+
+```python
+client.get_all_results(wsi_id: str, app_id: str) -> list[ResultResponse]
+```
+
+Returns all results stored for a slide/application pair.
+
+### `update_results`
+
+```python
+client.update_results(app_id: str, result_id: int, result: AdaptedResult) -> ResultResponse
+```
+
+Updates an existing result. `AdaptedResult` requires the current `versionId` (optimistic concurrency).
+
+## Quality control
+
+### `set_quality_control`
+
+```python
+client.set_quality_control(slide_id: str, quality_control: QualityControl) -> None
+```
+
+Sets the QC status for a slide. Requires IA-API 1.10+.
+
+## Errors
+
+`SectraRequestError` is raised when Sectra returns a non-2xx response.
+
+```python
+from sectra_client.utils.errors import SectraRequestError
+
+try:
+    client.get_image_metadata(slide_id)
+except SectraRequestError as e:
+    print(e.status_code, e.path, e.text)
+```
+
+Failed requests are retried up to 5 times with exponential backoff on connection errors.

sectra_image_analysis_api-1.5.1/docs/api/mock-server.md

@@ -0,0 +1,119 @@
+# MockSectraServer
+
+```python
+from sectra_client.mock_server import MockSectraServer
+```
+
+An in-memory Sectra PACS simulation for local development and testing. Exposes the same HTTP API as a real Sectra server, so your analysis app needs no code changes when switching between mock and production.
+
+## Constructor
+
+```python
+MockSectraServer(
+    api_version: str = "1.10",
+    software_version: str = "4.2.0.0",
+    token: str = "dev-token",
+    slides: dict[str, ImageMetadata] | None = None,
+    slide_files: dict[str, pathlib.Path | list[pathlib.Path]] | None = None,
+)
+```
+
+| Parameter | Description |
+|---|---|
+| `token` | Auth token your analysis app must present |
+| `slides` | Pre-populate slide metadata (keyed by slide ID) |
+| `slide_files` | Pre-populate real WSI files to serve (keyed by slide ID) |
+
+## Starting the server
+
+Use `run()` as a context manager — it starts the server in a background thread and stops it on exit:
+
+```python
+mock = MockSectraServer(token="dev-token")
+with mock.run(port=8001):
+    # server is running at http://localhost:8001
+    ...
+# server is stopped
+```
+
+You can also call `start()` / `stop()` manually.
+
+## Registering slides
+
+```python
+mock.add_slide(metadata: ImageMetadata) -> None
+mock.add_slide_files(slide_id: str, files: pathlib.Path | list[pathlib.Path]) -> None
+```
+
+Use these before (or after) starting the server to register slide metadata and real WSI files. Auto-generated metadata is used for any slide ID not explicitly registered.
+
+## Triggering invocations
+
+```python
+mock.trigger(webhook_url: str, invocation: Invocation) -> dict
+```
+
+Sends a fake invocation from the mock Sectra server to your app's webhook. Use this to drive an end-to-end test without clicking through a real PACS UI.
+
+## Reading results
+
+```python
+mock.get_results(app_id: str, slide_id: str) -> list[ResultResponse]
+```
+
+Returns results stored in the mock server's memory — useful for asserting your app submitted the expected output.
+
+## Full round-trip example
+
+```python
+import threading, time
+import uvicorn
+from sectra_client.mock_server import MockSectraServer
+from sectra_client.schemas import CallbackInfo, CreateInvocation, WholeSlideInput
+
+MOCK_PORT = 8001
+APP_PORT  = 8000
+SLIDE_ID  = "slide-001"
+
+mock = MockSectraServer(token="dev-token")
+with mock.run(port=MOCK_PORT):
+    # Start your analysis app in the background
+    app_config = uvicorn.Config(my_fastapi_app, host="localhost", port=APP_PORT, log_level="warning")
+    app_server = uvicorn.Server(app_config)
+    thread = threading.Thread(target=app_server.run, daemon=True)
+    thread.start()
+    time.sleep(1)  # wait for app to be ready
+
+    # Fire a fake invocation
+    mock.trigger(
+        webhook_url=f"http://localhost:{APP_PORT}/sectra/hook",
+        invocation=CreateInvocation(
+            applicationId="my-app",
+            slideId=SLIDE_ID,
+            callbackInfo=CallbackInfo(
+                url=f"http://localhost:{MOCK_PORT}",
+                token="dev-token",
+            ),
+            cancellationToken="tok-001",
+            input=WholeSlideInput(),
+        ),
+    )
+
+    # Poll until the result arrives
+    for _ in range(30):
+        results = mock.get_results(app_id="my-app", slide_id=SLIDE_ID)
+        if results:
+            break
+        time.sleep(1)
+
+    print(results[0].displayResult)
+```
+
+See `examples/local_dev.py` in the repository for the complete, runnable version.
+
+!!! note
+    When connecting `SectraClient` to a `MockSectraServer`, pass `_allow_http=True` because the mock runs on plain HTTP.
+
+    ```python
+    SectraClient(url="http://localhost:8001", token="dev-token", _allow_http=True)
+    ```