feat(platform): support external token providers and simplify caching [PYSDK-123]

[akunft]

🛡️ Implements PYSDK-123 following CC-SOP-01 Change Control, part of our ISO 13485-certified QMS | Ketryx Project

Why

Add an external token_provider parameter to Client.__init__() so callers can supply their own bearer-token callable (e.g. machine-to-machine / service-account flows) instead of relying on the built-in OAuth device-code flow. Internal OAuth remains the default; with this change it is no longer the only supported path.

Primary motivation: enable headless deployment scenarios (CI/CD jobs, Auth0 M2M, custom auth backends) where the device-code browser flow is impractical or impossible. Driving use case is M2M tokens cached upstream in Redis with stale-while-validate semantics.

What

SIS — specifications/SPEC_PLATFORM_SERVICE.md:

• New FR-14:"Support external token providers to bypass internal OAuth 2.0 flows for machine-to-machine, service account, or custom token lifecycle scenarios."
• Constraint relaxed: the "Browser dependency: Interactive flow requires web browser availability, limiting headless deployment options" line is removed because external token_provider enables headless operation.
• Strategy pattern updated to describe external-token-provider as a fully independent alternative auth strategy.
• Auth flow Mermaid diagram updated with the external-provider branch.
• Outputs table & class signatures updated for the new token_provider parameter and the internal _AuthenticatedApi return type.

Code — src/aignostics/platform/:

• New file _api.py introducing internal _AuthenticatedApi (PublicApi subclass that hoists token_provider to a top-level attribute), _OAuth2TokenProviderConfiguration, and _AuthenticatedResource base class.
• Client.__init__(cache_token=True, token_provider=None) — additive optional kwarg.
• Client.get_api_client() — same kwarg; returns _AuthenticatedApi. Three singleton-cache pools: cached-token, uncached-token, external-provider (bounded at 16 entries with clear-on-overflow safety net to address Sentry's flagged unbounded-growth concern).
• cached_operation decorator — use_token: bool replaced by token_provider: Callable[[], str] | None, so per-user cache key isolation is wired through the explicit provider rather than reaching into the global get_token().

What does NOT change

• No backend / API-server change.
• Internal OAuth device-code and authorization-code flows continue to work unchanged when token_provider is not supplied.
• No change to aignostics user login, token caching at ~/.aignostics/token.json, or refresh-token semantics.
• No change to existing public method signatures other than the additive token_provider kwarg.
• Backwards-compatible — existing callers continue to work without modification.

Risks introduced

None material. The new parameter is opt-in. The bounded _api_client_external cache addresses Sentry's flagged unbounded-growth concern. No patient-safety, security, or data-integrity risk identified — the external token continues to flow through the same Authorization: Bearer … header path; the SDK never inspects, persists, or logs the token value.

Test plan

• make lint green (ruff, format, pyright, mypy)
• make test_unit green; new tests/aignostics/platform/client_token_provider_test.py covers external-provider wiring
• Cache-test suite refactored to mock token_provider callable rather than patching get_token — exercises the new key-derivation path
• Codecov on patch
• CodeQL clean; SonarQube quality gate passed
• Required Testing = Verification only — automated CI proves the surface area; the headless-M2M path itself will be exercised when a downstream caller integrates it (out of scope for this CR)

Note: Originally provided retroactively for PYSDK-112 (Helmut); governing ticket corrected to PYSDK-123 (Andreas, Claude claude-sonnet-4-6 via cc-sop-01).

[Copilot]

Pull request overview

Adds support for supplying an external bearer-token provider to the Platform Client, and refactors operation caching to key per-user via an explicit token_provider callable rather than relying on a global auth helper.

Changes:

• Introduces _AuthenticatedApi + _OAuth2TokenProviderConfiguration in a new _api.py to surface token_provider as a top-level attribute (avoiding circular imports).
• Updates cached_operation to accept token_provider (replacing the previous use_token flag) and wires it through Client and resource modules.
• Updates and expands unit tests to cover external token providers and the revised caching behavior.

Reviewed changes

Copilot reviewed 11 out of 11 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
src/aignostics/platform/_api.py	Adds _AuthenticatedApi wrapper + configuration class to lift token_provider out of codegen internals.
src/aignostics/platform/_client.py	Adds token_provider parameter to Client, introduces external-provider singleton caching, and passes token_provider into cached_operation.
src/aignostics/platform/_operation_cache.py	Replaces use_token with token_provider in the caching decorator API and key generation.
src/aignostics/platform/resources/runs.py	Updates resource API type hints and passes token_provider=self._api.token_provider into cached operations.
src/aignostics/platform/resources/applications.py	Same as above for applications/versions resources.
tests/aignostics/platform/client_token_provider_test.py	Adds unit tests for external token providers and adjusts existing tests to the new API wiring.
tests/aignostics/platform/client_cache_test.py	Updates cache tests to use mocked token_provider for token-aware cache keys.
tests/aignostics/platform/nocache_test.py	Updates decorator calls to the new cached_operation signature.
tests/aignostics/platform/conftest.py	Ensures new external-client singleton cache is cleared between tests; adds token_provider to mocked API clients.
tests/aignostics/platform/resources/runs_test.py	Updates resource mocks to include token_provider/api_client attributes.
tests/aignostics/platform/resources/applications_test.py	Updates resource mocks to include token_provider/api_client attributes.

[codecov]

Codecov Report

❌ Patch coverage is 98.95833% with 1 line in your changes missing coverage. Please review.
✅ All tests successful. No failed tests found.

Files with missing lines	Patch %	Lines
src/aignostics/platform/resources/applications.py	91.66%	1 Missing ⚠️

Files with missing lines	Coverage Δ
src/aignostics/platform/_api.py	100.00% <100.00%> (ø)
src/aignostics/platform/_authentication.py	77.92% <100.00%> (-0.40%)	⬇️
src/aignostics/platform/_client.py	93.02% <100.00%> (-0.67%)	⬇️
src/aignostics/platform/_operation_cache.py	78.43% <100.00%> (+0.88%)	⬆️
src/aignostics/platform/resources/runs.py	84.67% <100.00%> (-0.44%)	⬇️
src/aignostics/platform/resources/applications.py	84.52% <91.66%> (+1.28%)	⬆️

... and 3 files with indirect coverage changes

[Copilot]

Pull request overview

Copilot reviewed 11 out of 11 changed files in this pull request and generated 3 comments.

[Copilot]

Pull request overview

Copilot reviewed 11 out of 11 changed files in this pull request and generated 4 comments.

[Copilot]

Pull request overview

Copilot reviewed 11 out of 11 changed files in this pull request and generated 4 comments.

[Copilot]

Pull request overview

Copilot reviewed 11 out of 11 changed files in this pull request and generated 2 comments.

[Copilot]

Pull request overview

Copilot reviewed 11 out of 11 changed files in this pull request and generated 2 comments.

Comments suppressed due to low confidence (1)

src/aignostics/platform/resources/runs.py:137

• Run.for_run_id() always constructs its API client via Client.get_api_client(cache_token=...), so there is currently no way to use it with an external token_provider (the new auth path). Consider adding an optional token_provider parameter (and documenting cache_token as ignored when it’s provided) so this convenience constructor remains usable for M2M/service-account flows.

 @classmethod
def for_run_id(cls, run_id: str, cache_token: bool = True) -> "Run":
"""Creates an Run instance for an existing run.
Args:
run_id (str): The ID of the application run.
cache_token (bool): Whether to cache the API token.
Returns:
Run: The initialized Run instance.
"""
from aignostics.platform._client import Client # noqa: PLC0415
return cls(Client.get_api_client(cache_token=cache_token), run_id)

[olivermeyer]

I believe this impacts https://github.com/aignostics/python-sdk/blob/main/specifications/SPEC_PLATFORM_SERVICE.md, therefore it needs a CR?

[arne-aignx]

I believe this impacts https://github.com/aignostics/python-sdk/blob/main/specifications/SPEC_PLATFORM_SERVICE.md, therefore it needs a CR?

Yes, I concur...
I don't even think this is strictly covered by the requirements stated in that SIS.

-> SW requirement + SIS update is in order here :/

[akunft]

I believe this impacts https://github.com/aignostics/python-sdk/blob/main/specifications/SPEC_PLATFORM_SERVICE.md, therefore it needs a CR?

Yes, I concur... I don't even think this is strictly covered by the requirements stated in that SIS.

-> SW requirement + SIS update is in order here :/

Agreed. I will look into this, but only on Monday.

[Copilot]

Pull request overview

Copilot reviewed 17 out of 17 changed files in this pull request and generated 3 comments.

[Copilot]

Pull request overview

Copilot reviewed 18 out of 18 changed files in this pull request and generated no new comments.

Comments suppressed due to low confidence (1)

tests/aignostics/platform/resources/runs_test.py:731

• The unit test coverage for artifact download behavior appears to have been removed from this module (e.g., Artifact.get_download_url redirect/status handling and Run.ensure_artifacts_downloaded download/resume/checksum logic), but the corresponding production code in src/aignostics/platform/resources/runs.py still exists. Please reintroduce these tests (or move them to a new dedicated test module) so changes to /file URL resolution, retry/error mapping, and download-resume behavior remain covered at the unit level (not only via slower e2e/integration tests).

@pytest.mark.unit
def test_run_details_does_not_retry_other_exceptions(app_run, mock_api) -> None:
"""Test that the outer retry does not catch non-NotFoundException errors.
This verifies that exceptions like ForbiddenException pass straight through
the outer retry without being retried.
Args:
app_run: Run instance with mock API.
mock_api: Mock ExternalsApi instance.
"""
from aignx.codegen.exceptions import ForbiddenException
mock_api.get_run_v1_runs_run_id_get.side_effect = ForbiddenException()
with pytest.raises(ForbiddenException):
app_run.details()
assert mock_api.get_run_v1_runs_run_id_get.call_count == 1

[Copilot]

Pull request overview

Copilot reviewed 19 out of 20 changed files in this pull request and generated 2 comments.

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud