refactor(utils): introduce library mode

refactor(utils): don't initialize sentry, logfire, ssl trust store or certifi in library mode
chore(deps): bump
refactor(utils): lower log level of boot message

Author: helmut-hoffer-von-ankershoffen

pyproject.toml

@@ -74,7 +74,7 @@ requires-python = ">=3.11, <3.14"
 
 dependencies = [
     # From Template
-    "fastapi[standard,all]>=0.120.4,<1",
+    "fastapi[standard,all]>=0.121.1,<1",
     "humanize>=4.14.0,<5",
     "logfire[system-metrics]>=4.14.2,<5",
     "nicegui[native]>=3.1.0,<3.2.0", # Regression in 3.2.0
@@ -88,31 +88,32 @@ dependencies = [
     "opentelemetry-instrumentation-urllib3>=0.53b0,<1",
     "packaging>=25.0,<26",
     "platformdirs>=4.5.0,<5",
-    "psutil>=7.1.2,<8",
-    "pydantic-settings>=2.11.0,<3",
+    "psutil>=7.1.3,<8",
+    "pydantic-settings>=2.12.0,<3",
     "pywin32>=310,<311 ; sys_platform == 'win32'",
     "pyyaml>=6.0.3,<7",
-    "sentry-sdk>=2.43.0,<3",
+    "sentry-sdk>=2.44.0,<3",
     "typer>=0.20.0,<1",
     "uptime>=3.0.1,<4",
     # Custom
     "aiopath>=0.6.11,<1",
-    "boto3>=1.40.64,<2",
-    "certifi>=2025.10.5,<2026",
+    "boto3>=1.40.61,<2",
+    "certifi>=2025.11.12,<2026",
     "defusedxml>=0.7.1",
     "dicom-validator>=0.7.3,<1",
     "dicomweb-client[gcp]>=0.59.3,<1",
     "duckdb>=0.10.0,<=1.4.1",
     "fastparquet>=2024.11.0,<2025",
-    "google-cloud-storage>=3.4.1,<4",
+    "google-cloud-storage>=3.5.0,<4",
     "google-crc32c>=1.7.1,<2",
     "highdicom>=0.26.1,<1",
     "html-sanitizer>=2.6.0,<3",
     "httpx>=0.28.1,<1",
-    "idc-index-data==22.0.2",
+    "idc-index-data==22.1.2",
     "ijson>=3.4.0.post0,<4",
     "jsf>=0.11.2,<1",
     "jsonschema[format-nongpl]>=4.25.1,<5",
+    "loguru>=0.7.3",
     "openslide-bin>=4.0.0.8,<5",
     "openslide-python>=1.4.2,<2",
     "pandas>=2.3.3,<3",
@@ -138,8 +139,8 @@ pyinstaller = ["pyinstaller>=6.14.0,<7"]
 jupyter = ["jupyter>=1.1.1,<2"]
 marimo = [
     "cloudpathlib>=0.23.0,<1",
-    "ipython>=9.6.0,<10",
-    "marimo>=0.17.2,<1",
+    "ipython>=9.7.0,<10",
+    "marimo>=0.17.7,<1",
     "matplotlib>=3.10.7,<4",
     "shapely>=2.1.0,<3",
 ]
@@ -154,15 +155,15 @@ dev = [
     "furo>=2025.9.25,<2026",
     "git-cliff>=2.10.1,<3",
     "mypy>=1.18.2,<2",
-    "nox[uv]>=2025.10.16,<2026",
+    "nox[uv]>=2025.11.12,<2026",
     "pip-audit>=2.9.0,<3",
     "pip-licenses @ git+https://github.com/neXenio/pip-licenses.git@master", # https://github.com/raimon49/pip-licenses/pull/224
-    "pre-commit>=4.3.0,<5",
+    "pre-commit>=4.4.0,<5",
     "pyright>=1.1.406,<1.1.407", # Regression in 1.1.407, see https://github.com/microsoft/pyright/issues/11060
     "pytest>=8.4.2,<9",
-    "pytest-asyncio>=1.2.0,<2",
+    "pytest-asyncio>=1.3.0,<2",
     "pytest-cov>=7.0.0,<8",
-    "pytest-docker>=3.2.3,<4",
+    "pytest-docker>=3.2.5,<4",
     "pytest-durations>=1.6.1,<2",
     "pytest-env>=1.2.0,<2",
     "pytest-md-report>=0.7.0,<1",
@@ -173,7 +174,7 @@ dev = [
     "pytest-timeout>=2.4.0,<3",
     "pytest-watcher>=0.4.3,<1",
     "pytest-xdist[psutil]>=3.8.0,<4",
-    "ruff>=0.14.3,<1",
+    "ruff>=0.14.4,<1",
     "scalene>=1.5.55,<2",
     "sphinx>=8.2.3,<9",
     "sphinx-autobuild>=2025.8.25,<2026",

src/aignostics/utils/__init__.py

@@ -11,8 +11,10 @@
     __env__,
     __env_file__,
     __is_development_mode__,
+    __is_library_mode__,
     __is_running_in_container__,
     __is_running_in_read_only_environment__,
+    __is_testing_mode__,
     __project_name__,
     __project_path__,
     __repository_url__,
@@ -45,8 +47,10 @@
     "__env__",
     "__env_file__",
     "__is_development_mode__",
+    "__is_library_mode__",
     "__is_running_in_container__",
     "__is_running_in_read_only_environment__",
+    "__is_testing_mode__",
     "__project_name__",
     "__project_path__",
     "__repository_url__",

src/aignostics/utils/_constants.py

@@ -19,6 +19,12 @@
 __is_development_mode__ = "uvx" not in sys.argv[0].lower()
 __is_running_in_container__ = os.getenv(f"{__project_name__.upper()}_RUNNING_IN_CONTAINER")
 
+# Detect if we're runnning as CLI (not during doc generation or testing)
+# Check if sys.argv[0] ends with project name (the actual CLI executable)
+__is_cli_execution__ = sys.argv[0].endswith(__project_name__) or (len(sys.argv) > 1 and sys.argv[1] == __project_name__)
+__is_library_mode__ = not __is_cli_execution__ and not os.getenv("PYTEST_RUNNING_AIGNOSTICS")
+__is_testing_mode__ = "pytest" in sys.modules and os.getenv("PYTEST_RUNNING_AIGNOSTICS")
+
 # Determine if we're running in a read-only runtime environment
 READ_ONLY_ENV_INDICATORS = [
     f"{__project_name__.upper()}_RUNNING_IN_CONTAINER",

src/aignostics/utils/_logfire.py

@@ -7,7 +7,7 @@
 from pydantic import BeforeValidator, Field, PlainSerializer, SecretStr
 from pydantic_settings import SettingsConfigDict
 
-from ._constants import __env__, __env_file__, __project_name__, __repository_url__, __version__
+from ._constants import __env__, __env_file__, __is_library_mode__, __project_name__, __repository_url__, __version__
 from ._settings import OpaqueSettings, load_settings, strip_to_none_before_validator
 
 
@@ -51,6 +51,9 @@ def logfire_initialize(modules: list["str"]) -> bool:
     Returns:
         bool: True if initialized successfully False otherwise
     """
+    if __is_library_mode__:
+        return False
+
     settings = load_settings(LogfireSettings)
 
     if not find_spec("logfire") or not settings.enabled or settings.token is None:

src/aignostics/utils/_sentry.py

@@ -8,7 +8,7 @@
 from pydantic import AfterValidator, BeforeValidator, Field, PlainSerializer, SecretStr
 from pydantic_settings import SettingsConfigDict
 
-from ._constants import __env__, __env_file__, __project_name__, __version__
+from ._constants import __env__, __env_file__, __is_library_mode__, __project_name__, __version__
 from ._settings import OpaqueSettings, load_settings, strip_to_none_before_validator
 
 _ERR_MSG_MISSING_SCHEME = "Sentry DSN is missing URL scheme (protocol)"
@@ -189,6 +189,9 @@ def sentry_initialize() -> bool:
     Returns:
         bool: True if initialized successfully, False otherwise
     """
+    if __is_library_mode__:
+        return False
+
     settings = load_settings(SentrySettings)
 
     if not find_spec("sentry_sdk") or not settings.enabled or settings.dsn is None:

src/aignostics/utils/boot.py

@@ -5,9 +5,18 @@
 import sys
 from pathlib import Path
 
-import certifi
-import truststore
-
+# Optional SSL certificate modules - gracefully degrade if not available
+try:
+    import certifi
+except ImportError:
+    certifi = None  # type: ignore[assignment]
+
+try:
+    import truststore  # pyright: ignore[reportMissingImports]
+except ImportError:
+    truststore = None  # type: ignore[assignment]
+
+from ._constants import __is_library_mode__
 from ._log import logging_initialize
 
 # Import third party dependencies.
@@ -60,9 +69,6 @@ def _parse_env_args() -> None:
 
     - Last but not least removes those args so typer does not complain about them.
     """
-    logger = get_logger(__name__)
-    logger.debug("_parse_env_args called with sys.argv: %s", sys.argv)
-
     i = 1  # Start after script name
     to_remove = []
     prefix = f"{__project_name__.upper()}_"
@@ -89,6 +95,8 @@ def _parse_env_args() -> None:
 
 
 def _amend_ssl_trust_chain() -> None:
+    if __is_library_mode__:
+        return
     truststore.inject_into_ssl()
 
     if ssl.get_default_verify_paths().cafile is None and os.environ.get("SSL_CERT_FILE") is None:
@@ -99,12 +107,14 @@ def _log_boot_message() -> None:
     """Log boot message with version and process information."""
     logger = get_logger(__name__)
     process_info = get_process_info()
-    logger.info(
-        "⭐ Booting %s v%s (project root %s, pid %s), parent '%s' (pid %s)",
+    mode_suffix = ", library-mode" if __is_library_mode__ else ""
+    logger.debug(
+        "⭐ Booting %s v%s (project root %s, pid %s), parent '%s' (pid %s)%s",
         __project_name__,
         __version__,
         process_info.project_root,
         process_info.pid,
         process_info.parent.name,
         process_info.parent.pid,
+        mode_suffix,
     )

tests/conftest.py

@@ -2,8 +2,13 @@
 
 from __future__ import annotations
 
-import logging
 import os
+
+from .constants_test import TEST_SUITE
+
+os.environ[f"PYTEST_RUNNING_{TEST_SUITE}"] = "1"  # Doing this at the top ensures aignostics src code sees it early
+
+import logging
 from asyncio import sleep
 from importlib.util import find_spec
 from pathlib import Path

tests/constants_test.py

@@ -6,59 +6,37 @@
 
 import os
 
+TEST_SUITE = "AIGNOSTICS"
+
 SPOT_0_GS_URL = "gs://platform-api-application-test-data/heta/slides/8fafc17d-a5cc-4e9d-a982-030b1486ca88.tiff"
 SPOT_0_FILENAME = "8fafc17d-a5cc-4e9d-a982-030b1486ca88.tiff"
-SPOT_0_FILESIZE = 10562338
-SPOT_0_EXPECTED_RESULT_FILES = [
-    ("tissue_qc_segmentation_map_image.tiff", 1698570, 10),
-    ("tissue_qc_geojson_polygons.json", 315019, 10),
-    ("tissue_segmentation_geojson_polygons.json", 927599, 10),
-    ("readout_generation_slide_readouts.csv", 299865, 10),
-    ("readout_generation_cell_readouts.csv", 1470036, 10),
-    ("cell_classification_geojson_polygons.json", 9915953, 10),
-    ("tissue_segmentation_segmentation_map_image.tiff", 2989980, 10),
-    ("tissue_segmentation_csv_class_information.csv", 361, 10),
-    ("tissue_qc_csv_class_information.csv", 236, 10),
-]
-SPOT_0_EXPECTED_CELLS_CLASSIFIED = (35160, 10)
 SPOT_0_CRC32C = "5onqtA=="
+SPOT_0_FILESIZE = 10562338
 SPOT_0_RESOLUTION_MPP = 0.26268186053789266
 SPOT_0_WIDTH = 7447
 SPOT_0_HEIGHT = 7196
 
 SPOT_1_GS_URL = "gs://aignx-storage-service-dev/sample_data_formatted/9375e3ed-28d2-4cf3-9fb9-8df9d11a6627.tiff"
 SPOT_1_FILENAME = "9375e3ed-28d2-4cf3-9fb9-8df9d11a6627.tiff"
-SPOT_1_FILESIZE = 14681750
-SPOT_1_EXPECTED_RESULT_FILES = [
-    ("tissue_qc_segmentation_map_image.tiff", 464908, 10),
-    ("tissue_qc_geojson_polygons.json", 180522, 10),
-    ("tissue_segmentation_geojson_polygons.json", 270931, 10),
-    ("readout_generation_slide_readouts.csv", 295268, 10),
-    ("readout_generation_cell_readouts.csv", 2228907, 10),
-    ("cell_classification_geojson_polygons.json", 16054058, 10),
-    ("tissue_segmentation_segmentation_map_image.tiff", 581258, 10),
-    ("tissue_segmentation_csv_class_information.csv", 342, 10),
-    ("tissue_qc_csv_class_information.csv", 232, 10),
-]
 SPOT_1_CRC32C = "9l3NNQ=="
+SPOT_1_FILESIZE = 14681750
+SPOT_1_RESOLUTION_MPP = 0.46499982
 SPOT_1_WIDTH = 3728
 SPOT_1_HEIGHT = 3640
-SPOT_1_RESOLUTION_MPP = 0.46499982
 
 SPOT_2_GS_URL = "gs://aignx-storage-service-dev/sample_data_formatted/8c7b079e-8b8a-4036-bfde-5818352b503a.tiff"
 SPOT_2_FILENAME = "8c7b079e-8b8a-4036-bfde-5818352b503a.tiff"
-SPOT_2_FILESIZE = 20153772
 SPOT_2_CRC32C = "w+ud3g=="
+SPOT_2_RESOLUTION_MPP = 0.46499982
 SPOT_2_WIDTH = 3616
 SPOT_2_HEIGHT = 3400
-SPOT_2_RESOLUTION_MPP = 0.46499982
 
 SPOT_3_GS_URL = "gs://aignx-storage-service-dev/sample_data_formatted/1f4f366f-a2c5-4407-9f5e-23400b22d50e.tiff"
 SPOT_3_FILENAME = "1f4f366f-a2c5-4407-9f5e-23400b22d50e.tiff"
 SPOT_3_CRC32C = "Zmx0wA=="
+SPOT_3_RESOLUTION_MPP = 0.46499982
 SPOT_3_WIDTH = 4016
 SPOT_3_HEIGHT = 3952
-SPOT_3_RESOLUTION_MPP = 0.46499982
 
 match os.getenv("AIGNOSTICS_PLATFORM_ENVIRONMENT", "production"):
     case "production":
@@ -67,12 +45,64 @@
 
         HETA_APPLICATION_ID = "he-tme"
         HETA_APPLICATION_VERSION = "1.0.0-beta.8"
+
+        SPOT_0_EXPECTED_RESULT_FILES = [
+            ("tissue_qc_segmentation_map_image.tiff", 1698570, 10),
+            ("tissue_qc_geojson_polygons.json", 315019, 10),
+            ("tissue_segmentation_geojson_polygons.json", 927599, 10),
+            ("readout_generation_slide_readouts.csv", 299865, 10),
+            ("readout_generation_cell_readouts.csv", 1470036, 10),
+            ("cell_classification_geojson_polygons.json", 9915953, 10),
+            ("tissue_segmentation_segmentation_map_image.tiff", 2989980, 10),
+            ("tissue_segmentation_csv_class_information.csv", 361, 10),
+            ("tissue_qc_csv_class_information.csv", 236, 10),
+        ]
+        SPOT_0_EXPECTED_CELLS_CLASSIFIED = (35160, 10)
+
+        SPOT_1_EXPECTED_RESULT_FILES = [
+            ("tissue_qc_segmentation_map_image.tiff", 464908, 10),
+            ("tissue_qc_geojson_polygons.json", 180522, 10),
+            ("tissue_segmentation_geojson_polygons.json", 270931, 10),
+            ("readout_generation_slide_readouts.csv", 295268, 10),
+            ("readout_generation_cell_readouts.csv", 2228907, 10),
+            ("cell_classification_geojson_polygons.json", 16054058, 10),
+            ("tissue_segmentation_segmentation_map_image.tiff", 581258, 10),
+            ("tissue_segmentation_csv_class_information.csv", 342, 10),
+            ("tissue_qc_csv_class_information.csv", 232, 10),
+        ]
+
     case "staging":
         TEST_APPLICATION_ID = "test-app"
         TEST_APPLICATION_VERSION = "0.0.5"
 
         HETA_APPLICATION_ID = "he-tme"
         HETA_APPLICATION_VERSION = "1.0.0-sl+4"
+
+        SPOT_0_EXPECTED_RESULT_FILES = [
+            ("tissue_qc_segmentation_map_image.tiff", 1698570, 10),
+            ("tissue_qc_geojson_polygons.json", 315019, 10),
+            ("tissue_segmentation_geojson_polygons.json", 927599, 10),
+            ("readout_generation_slide_readouts.csv", 299865, 10),
+            ("readout_generation_cell_readouts.csv", 1470036, 10),
+            ("cell_classification_geojson_polygons.json", 9915953, 10),
+            ("tissue_segmentation_segmentation_map_image.tiff", 2989980, 10),
+            ("tissue_segmentation_csv_class_information.csv", 361, 10),
+            ("tissue_qc_csv_class_information.csv", 236, 10),
+        ]
+        SPOT_0_EXPECTED_CELLS_CLASSIFIED = (35160, 10)
+
+        SPOT_1_EXPECTED_RESULT_FILES = [
+            ("tissue_qc_segmentation_map_image.tiff", 440122, 10),
+            ("tissue_qc_geojson_polygons.json", 139943, 10),
+            ("tissue_segmentation_geojson_polygons.json", 270931, 10),
+            ("readout_generation_slide_readouts.csv", 295268, 10),
+            ("readout_generation_cell_readouts.csv", 300408, 10),
+            ("cell_classification_geojson_polygons.json", 16384866, 10),
+            ("tissue_segmentation_segmentation_map_image.tiff", 508552, 10),
+            ("tissue_segmentation_csv_class_information.csv", 443, 10),
+            ("tissue_qc_csv_class_information.csv", 284, 10),
+        ]
+
     case _:
         message = f"Unsupported AIGNOSTICS_PLATFORM_ENVIRONMENT value: {os.getenv('AIGNOSTICS_PLATFORM_ENVIRONMENT')}"
         raise ValueError(message)