chore(platform): fix race condition in e2e test due to caching (#206)

* feat(platform): Support for tags in custom sdk metadata, run and item-level
* feat(platform):  Support created_at and updated_at in custom sdk metadata, run and item-level
* feat(platform): Support nocache=True on cached operations
* feat(platform): Custom run and item metadata can be updated
* chore(platform): Improved depth of tests
* chore(platform): Fix race condition in e2e test due to caching by using nocache
* chore(platform): Start with submit-and-find e2e tests later replacing submit-and-wait
* feat(application): Custom run and item metadata can be dumped as JSON via the CLI
* feat(application): custom run metadata can be updated via the CLI
* feat(application): Custom run metadata can be edited via the GUI (admins only)
* feat(application): Allow to submit tags via CLI and find back runs via tags
* chore(qupath): Enable complex automated test scenario covering creating QuPath projects
* chore(deps): bump
* docs(AI): update

Author: helmut-hoffer-von-ankershoffen

.pre-commit-config.yaml

@@ -52,7 +52,7 @@ repos:
         args: ["--baseline", ".secrets.baseline"]
         additional_dependencies: ["gibberish-detector"]
   - repo: https://github.com/astral-sh/uv-pre-commit
-    rev: 0.8.9
+    rev: 0.9.5
     hooks:
       - id: uv-lock
   - repo: local

CHANGELOG.md

@@ -1762,5 +1762,3 @@
 
 
 * @helmut-hoffer-von-ankershoffen made their first contribution
-
-

CLAUDE.md

@@ -509,20 +509,24 @@ Some modules have conditional loading based on dependencies:
 * 5-minute refresh buffer before expiry
 * OAuth 2.0 device flow
 
-### SDK Metadata System (NEW in v1.0.0-beta.7)
+### SDK Metadata System (ENHANCED - Run v0.0.4, Item v0.0.3)
 
-**Automatic Run Tracking**: Every application run submitted through the SDK automatically includes comprehensive metadata about the execution context.
+**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.
 
 **Key Features:**
 
-* **Automatic Attachment**: SDK metadata added to every run without user action
+* **Automatic Attachment**: SDK metadata added to every run and item without user action
 * **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 (v0.0.1)
-* **Versioned Schema**: Published JSON Schema at `docs/source/_static/sdk_metadata_schema_*.json`
+* **Schema Validation**: Pydantic-based validation with JSON Schema (Run: v0.0.4, 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`)
+* **Metadata Updates** (NEW): Update custom metadata via CLI and GUI
+* **Item Metadata** (NEW): Separate schema for item-level metadata including platform bucket information
 
-**What's Tracked:**
+**What's Tracked (Run Level):**
 
 * Submission metadata (date, interface, initiator)
 * Enhanced user agent with platform and CI/CD context
@@ -532,21 +536,41 @@ Some modules have conditional loading based on dependencies:
 * Workflow control flags (validate_only, onboard_to_portal)
 * Scheduling information (due dates, deadlines)
 * Optional user notes
+* **Tags** (NEW): Set of tags for filtering (`set[str]`)
+* **Timestamps** (NEW): `created_at`, `updated_at`
 
-**CLI Command:**
+**What's Tracked (Item Level - NEW):**
+
+* **Platform Bucket Metadata**: Cloud storage location (bucket name, object key, signed URL)
+* **Tags**: Item-level tags (`set[str]`)
+* **Timestamps**: `created_at`, `updated_at`
+
+**CLI Commands:**
 
 ```bash
-# Export SDK metadata JSON Schema
-aignostics sdk metadata-schema --pretty > schema.json
+# Export SDK run metadata JSON Schema
+aignostics sdk metadata-schema --pretty > run_schema.json
+
+# Update run custom metadata (including tags)
+aignostics application run custom-metadata update RUN_ID \
+  --custom-metadata '{"sdk": {"tags": ["experiment-1", "batch-A"]}}'
+
+# Dump run custom metadata as JSON
+aignostics application run custom-metadata dump RUN_ID --pretty
+
+# Find runs by tags
+aignostics application run list --tags experiment-1,batch-A
 ```
 
 **Implementation:**
 
 * Module: `platform._sdk_metadata`
-* Functions: `build_sdk_metadata()`, `validate_sdk_metadata()`, `get_sdk_metadata_json_schema()`
+* **Run Functions**: `build_run_sdk_metadata()`, `validate_run_sdk_metadata()`, `get_run_sdk_metadata_json_schema()`
+* **Item Functions** (NEW): `build_item_sdk_metadata()`, `validate_item_sdk_metadata()`, `get_item_sdk_metadata_json_schema()`
 * 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`
 
 See `platform/CLAUDE.md` for detailed documentation.
 
@@ -616,10 +640,19 @@ AIGNOSTICS_RUN_TIMEOUT=30.0
 AIGNOSTICS_RUN_CACHE_TTL=15
 ```
 
+**Cache Control:**
+
+```python
+# Bypass cache for specific operations (useful in tests or when fresh data is required)
+run = client.runs.details(run_id, nocache=True)  # Force API call
+applications = client.applications.list(nocache=True)  # Bypass cache
+```
+
 **Design Decisions:**
 
 * ✅ **Read-Only Retries**: Only safe, idempotent read operations retry
 * ✅ **Global Cache Clearing**: Simple consistency model - clear everything on writes
+* ✅ **Cache Bypass** (NEW): `nocache=True` parameter forces fresh API calls
 * ✅ **Logging**: Warnings logged before retry sleeps for observability
 * ✅ **Re-raise**: Original exception re-raised after exhausting retries
 

CLI_REFERENCE.md

@@ -162,7 +162,11 @@ $ aignostics application run [OPTIONS] COMMAND [ARGS]...
 * `submit`: Submit run by referencing the metadata CSV...
 * `list`: List runs.
 * `describe`: Describe run.
+* `dump-metadata`: Dump custom metadata of a run as JSON to...
+* `dump-item-metadata`: Dump custom metadata of an item as JSON to...
 * `cancel`: Cancel run.
+* `update-metadata`: Update custom metadata for a run.
+* `update-item-metadata`: Update custom metadata for an item in a run.
 * `result`: Download or delete run results.
 
 #### `aignostics application run execute`
@@ -200,7 +204,7 @@ $ aignostics application run execute [OPTIONS] APPLICATION_ID METADATA_CSV_FILE
 * `--application-version TEXT`: Version of the application. If not provided, the latest version will be used.
 * `--create-subdirectory-for-run / --no-create-subdirectory-for-run`: Create a subdirectory for the results of the run in the destination directory  [default: create-subdirectory-for-run]
 * `--create-subdirectory-per-item / --no-create-subdirectory-per-item`: Create a subdirectory per item in the destination directory  [default: create-subdirectory-per-item]
-* `--upload-prefix TEXT`: Prefix for the upload destination. If not given will be set to current milliseconds.  [default: 1761393428019.061]
+* `--upload-prefix TEXT`: Prefix for the upload destination. If not given will be set to current milliseconds.  [default: 1761499056785.385]
 * `--wait-for-completion / --no-wait-for-completion`: Wait for run completion and download results incrementally  [default: wait-for-completion]
 * `--note TEXT`: Optional note to include with the run submission via custom metadata.
 * `--due-date TEXT`: Optional soft due date to include with the run submission, ISO8601 format. The scheduler will try to complete the run by this date, taking the subscription tierand available GPU resources into account.
@@ -263,7 +267,7 @@ $ aignostics application run upload [OPTIONS] APPLICATION_ID METADATA_CSV_FILE
 **Options**:
 
 * `--application-version TEXT`: Version of the application. If not provided, the latest version will be used.
-* `--upload-prefix TEXT`: Prefix for the upload destination. If not given will be set to current milliseconds.  [default: 1761393428019.1792]
+* `--upload-prefix TEXT`: Prefix for the upload destination. If not given will be set to current milliseconds.  [default: 1761499056785.492]
 * `--onboard-to-aignostics-portal / --no-onboard-to-aignostics-portal`: If set, the run will be onboarded to the Aignostics Portal.  [default: no-onboard-to-aignostics-portal]
 * `--help`: Show this message and exit.
 
@@ -291,6 +295,7 @@ $ aignostics application run submit [OPTIONS] APPLICATION_ID METADATA_CSV_FILE
 
 * `--application-version TEXT`: Version of the application to generate the metadata for. If not provided, the latest version will be used.
 * `--note TEXT`: Optional note to include with the run submission via custom metadata.
+* `--tags TEXT`: Optional comma-separated list of tags to attach to the run for filtering.
 * `--due-date TEXT`: Optional soft due date to include with the run submission, ISO8601 format. The scheduler will try to complete the run by this date, taking the subscription tierand available GPU resources into account.
 * `--deadline TEXT`: Optional hard deadline to include with the run submission, ISO8601 format. If processing exceeds this deadline, the run can be aborted.
 * `--onboard-to-aignostics-portal / --no-onboard-to-aignostics-portal`: If True, onboard the run to the Aignostics Portal.  [default: no-onboard-to-aignostics-portal]
@@ -311,6 +316,10 @@ $ aignostics application run list [OPTIONS]
 
 * `--verbose / --no-verbose`: Show application details  [default: no-verbose]
 * `--limit INTEGER`: Maximum number of runs to display
+* `--tags TEXT`: Optional comma-separated list of tags to filter runs. All tags must match.
+* `--note-regex TEXT`: Optional regex pattern to filter runs by note metadata.
+* `--query TEXT`: Optional query string to filter runs by note OR tags.
+* `--note-case-insensitive / --no-note-case-insensitive`: Make note regex search case-insensitive.  [default: note-case-insensitive]
 * `--help`: Show this message and exit.
 
 #### `aignostics application run describe`
@@ -331,6 +340,45 @@ $ aignostics application run describe [OPTIONS] RUN_ID
 
 * `--help`: Show this message and exit.
 
+#### `aignostics application run dump-metadata`
+
+Dump custom metadata of a run as JSON to stdout.
+
+**Usage**:
+
+```console
+$ aignostics application run dump-metadata [OPTIONS] RUN_ID
+```
+
+**Arguments**:
+
+* `RUN_ID`: Id of the run to dump custom metadata for  [required]
+
+**Options**:
+
+* `--pretty / --no-pretty`: Pretty print JSON output with indentation  [default: no-pretty]
+* `--help`: Show this message and exit.
+
+#### `aignostics application run dump-item-metadata`
+
+Dump custom metadata of an item as JSON to stdout.
+
+**Usage**:
+
+```console
+$ aignostics application run dump-item-metadata [OPTIONS] RUN_ID EXTERNAL_ID
+```
+
+**Arguments**:
+
+* `RUN_ID`: Id of the run containing the item  [required]
+* `EXTERNAL_ID`: External ID of the item to dump custom metadata for  [required]
+
+**Options**:
+
+* `--pretty / --no-pretty`: Pretty print JSON output with indentation  [default: no-pretty]
+* `--help`: Show this message and exit.
+
 #### `aignostics application run cancel`
 
 Cancel run.
@@ -349,6 +397,45 @@ $ aignostics application run cancel [OPTIONS] RUN_ID
 
 * `--help`: Show this message and exit.
 
+#### `aignostics application run update-metadata`
+
+Update custom metadata for a run.
+
+**Usage**:
+
+```console
+$ aignostics application run update-metadata [OPTIONS] RUN_ID METADATA_JSON
+```
+
+**Arguments**:
+
+* `RUN_ID`: Id of the run to update  [required]
+* `METADATA_JSON`: Custom metadata as JSON string (e.g., '{"key": "value"}')  [required]
+
+**Options**:
+
+* `--help`: Show this message and exit.
+
+#### `aignostics application run update-item-metadata`
+
+Update custom metadata for an item in a run.
+
+**Usage**:
+
+```console
+$ aignostics application run update-item-metadata [OPTIONS] RUN_ID EXTERNAL_ID METADATA_JSON
+```
+
+**Arguments**:
+
+* `RUN_ID`: Id of the run containing the item  [required]
+* `EXTERNAL_ID`: External ID of the item to update  [required]
+* `METADATA_JSON`: Custom metadata as JSON string (e.g., '{"key": "value"}')  [required]
+
+**Options**:
+
+* `--help`: Show this message and exit.
+
 #### `aignostics application run result`
 
 Download or delete run results.
@@ -644,9 +731,6 @@ WHERE
 
 Download from manifest file, identifier, or comma-separate set of identifiers.
 
-Raises:
-    typer.Exit: If the target directory does not exist.
-
 **Usage**:
 
 ```console
@@ -655,7 +739,7 @@ $ aignostics dataset idc download [OPTIONS] SOURCE [TARGET]
 
 **Arguments**:
 
-* `SOURCE`: Identifier or comma-separated set of identifiers. IDs matched against collection_id, PatientId, StudyInstanceUID, SeriesInstanceUID or SOPInstanceUID.  [required]
+* `SOURCE`: Identifier or comma-separated set of identifiers. IDs matched against collection_id, PatientId, StudyInstanceUID, SeriesInstanceUID or SOPInstanceUID. Example: 1.3.6.1.4.1.5962.99.1.1069745200.1645485340.1637452317744.2.0  [required]
 * `[TARGET]`: target directory for download  [default: /Users/helmut/Library/Application Support/aignostics/datasets/idc]
 
 **Options**:
@@ -694,7 +778,7 @@ $ aignostics dataset aignostics download [OPTIONS] SOURCE_URL [DESTINATION_DIREC
 
 **Arguments**:
 
-* `SOURCE_URL`: URL to download, e.g. gs://aignx-storage-service-dev/sample_data_formatted/9375e3ed-28d2-4cf3-9fb9-8df9d11a6627.tiff  [required]
+* `SOURCE_URL`: URL to download. Example: gs://aignx-storage-service-dev/sample_data_formatted/9375e3ed-28d2-4cf3-9fb9-8df9d11a6627.tiff  [required]
 * `[DESTINATION_DIRECTORY]`: Destination directory to download to  [default: /Users/helmut/Library/Application Support/aignostics/datasets/aignostics]
 
 **Options**:

VERSION

@@ -1 +1 @@
-0.2.195
+0.2.196

docs/source/_static/sdk_item_custom_metadata_schema_latest.json

@@ -37,6 +37,33 @@
       "title": "Schema Version",
       "type": "string"
     },
+    "created_at": {
+      "description": "ISO 8601 timestamp when the metadata was first created",
+      "title": "Created At",
+      "type": "string"
+    },
+    "updated_at": {
+      "description": "ISO 8601 timestamp when the metadata was last updated",
+      "title": "Updated At",
+      "type": "string"
+    },
+    "tags": {
+      "anyOf": [
+        {
+          "items": {
+            "type": "string"
+          },
+          "type": "array",
+          "uniqueItems": true
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "default": null,
+      "description": "Optional list of tags associated with the item",
+      "title": "Tags"
+    },
     "platform_bucket": {
       "anyOf": [
         {
@@ -51,10 +78,12 @@
     }
   },
   "required": [
-    "schema_version"
+    "schema_version",
+    "created_at",
+    "updated_at"
   ],
   "title": "ItemSdkMetadata",
   "type": "object",
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://raw.githubusercontent.com/aignostics/python-sdk/main/docs/source/_static/item_sdk_metadata_schema_v0.0.1.json"
+  "$id": "https://raw.githubusercontent.com/aignostics/python-sdk/main/docs/source/_static/item_sdk_metadata_schema_v0.0.3.json"
 }