Repository navigation
feat(sdk): split the shared runtime out of pyoaev into xtm-oaev-sdk (#303) - #363
Draft
Christophe Melchior (Kakudou) wants to merge 22 commits into
Draft
Christophe Melchior (Kakudou) wants to merge 22 commits into
Christophe Melchior (Kakudou) wants to merge 22 commits into
Conversation
…ectors-sdk and injectors-sdk
…rs-sdk public layer
Christophe Melchior (Kakudou)
marked this pull request as draft
October 15, 2026 11:20
There was a problem hiding this comment.
🟡 Changes recommended
One or more issues must be addressed before approval.
2 open findings
What changed in this PR
Separates the shared runtime from the OpenAEV API client while retaining deprecated legacy imports.
Changes:
- Introduces a layered SDK with versioned contracts.
- Replaces moved implementations with compatibility shims.
- Updates packaging, CI, tests, and migration decisions.
SDK/ below denotes libs/xtm-oaev-sdk/.
| File | Description |
|---|---|
| test/test_legacy_surface.py | Updated as part of this pull request. |
| test/generate_legacy_surface.py | Updated as part of this pull request. |
| pyproject.toml | Updated as part of this pull request. |
| pyoaev/signatures/signature_type.py | Updated as part of this pull request. |
| pyoaev/signatures/signature_match.py | Updated as part of this pull request. |
| pyoaev/signatures/ai_marker.py | Updated as part of this pull request. |
| pyoaev/signatures/__init__.py | Updated as part of this pull request. |
| pyoaev/security_domain/types.py | Updated as part of this pull request. |
| pyoaev/daemons/__init__.py | Updated as part of this pull request. |
| pyoaev/credential/utils.py | Updated as part of this pull request. |
| pyoaev/credential/types.py | Updated as part of this pull request. |
| pyoaev/credential/__init__.py | Updated as part of this pull request. |
| pyoaev/contracts/contract_utils.py | Updated as part of this pull request. |
| pyoaev/contracts/contract_builder.py | Updated as part of this pull request. |
| pyoaev/contracts/__init__.py | Updated as part of this pull request. |
| pyoaev/configuration/sources.py | Updated as part of this pull request. |
| pyoaev/configuration/__init__.py | Updated as part of this pull request. |
| pyoaev/client.py | Updated as part of this pull request. |
| pyoaev/base.py | Updated as part of this pull request. |
| pyoaev/apis/vulnerability.py | Updated as part of this pull request. |
| pyoaev/apis/user.py | Updated as part of this pull request. |
| pyoaev/apis/team.py | Updated as part of this pull request. |
| pyoaev/apis/tag.py | Updated as part of this pull request. |
| pyoaev/apis/signature.py | Updated as part of this pull request. |
| pyoaev/apis/security_platform.py | Updated as part of this pull request. |
| pyoaev/apis/payload.py | Updated as part of this pull request. |
| pyoaev/apis/kill_chain_phase.py | Updated as part of this pull request. |
| pyoaev/apis/injector_contract.py | Updated as part of this pull request. |
| pyoaev/apis/inject.py | Updated as part of this pull request. |
| pyoaev/apis/inject_expectation/model/__init__.py | Updated as part of this pull request. |
| pyoaev/apis/inject_expectation/__init__.py | Updated as part of this pull request. |
| pyoaev/apis/inject_expectation_trace.py | Updated as part of this pull request. |
| pyoaev/apis/endpoint.py | Updated as part of this pull request. |
| pyoaev/apis/document.py | Updated as part of this pull request. |
| pyoaev/apis/cve.py | Updated as part of this pull request. |
| pyoaev/apis/collector.py | Updated as part of this pull request. |
| pyoaev/apis/attack_pattern.py | Updated as part of this pull request. |
| pyoaev/apis/ai_target.py | Updated as part of this pull request. |
| pyoaev/apis/__init__.py | Updated as part of this pull request. |
| pyoaev/__init__.py | Updated as part of this pull request. |
| libs/xtm-oaev-sdk/xtm_oaev_sdk/seam/signatures/__init__.py | Updated as part of this pull request. |
| libs/xtm-oaev-sdk/xtm_oaev_sdk/seam/port_io/__init__.py | Updated as part of this pull request. |
| libs/xtm-oaev-sdk/xtm_oaev_sdk/seam/deprecation/ports.py | Updated as part of this pull request. |
| libs/xtm-oaev-sdk/xtm_oaev_sdk/seam/deprecation/__init__.py | Updated as part of this pull request. |
| libs/xtm-oaev-sdk/xtm_oaev_sdk/seam/daemons/ports.py | Updated as part of this pull request. |
| libs/xtm-oaev-sdk/xtm_oaev_sdk/seam/daemons/__init__.py | Updated as part of this pull request. |
| libs/xtm-oaev-sdk/xtm_oaev_sdk/seam/contracts/__init__.py | Updated as part of this pull request. |
| libs/xtm-oaev-sdk/xtm_oaev_sdk/seam/configuration/__init__.py | Updated as part of this pull request. |
| libs/xtm-oaev-sdk/xtm_oaev_sdk/seam/common/security_domains.py | Updated as part of this pull request. |
| libs/xtm-oaev-sdk/xtm_oaev_sdk/seam/common/ports.py | Updated as part of this pull request. |
| libs/xtm-oaev-sdk/xtm_oaev_sdk/seam/common/__init__.py | Updated as part of this pull request. |
| libs/xtm-oaev-sdk/xtm_oaev_sdk/seam/__init__.py | Updated as part of this pull request. |
| libs/xtm-oaev-sdk/xtm_oaev_sdk/py.typed | Updated as part of this pull request. |
| libs/xtm-oaev-sdk/xtm_oaev_sdk/public/deprecation.py | Updated as part of this pull request. |
| libs/xtm-oaev-sdk/xtm_oaev_sdk/_core/signatures/targets.py | Updated as part of this pull request. |
| libs/xtm-oaev-sdk/xtm_oaev_sdk/_core/signatures/marker.py | Updated as part of this pull request. |
| libs/xtm-oaev-sdk/xtm_oaev_sdk/_core/signatures/addresses.py | Updated as part of this pull request. |
| libs/xtm-oaev-sdk/xtm_oaev_sdk/_core/signatures/__init__.py | Updated as part of this pull request. |
| libs/xtm-oaev-sdk/xtm_oaev_sdk/_core/deprecation/shims.py | Updated as part of this pull request. |
| libs/xtm-oaev-sdk/xtm_oaev_sdk/_core/deprecation/__init__.py | Updated as part of this pull request. |
| libs/xtm-oaev-sdk/xtm_oaev_sdk/_core/daemons/runtime.py | Updated as part of this pull request. |
| libs/xtm-oaev-sdk/xtm_oaev_sdk/_core/daemons/heartbeat.py | Updated as part of this pull request. |
| libs/xtm-oaev-sdk/xtm_oaev_sdk/_core/daemons/__init__.py | Updated as part of this pull request. |
| libs/xtm-oaev-sdk/xtm_oaev_sdk/_core/contracts/serializer.py | Updated as part of this pull request. |
| libs/xtm-oaev-sdk/xtm_oaev_sdk/_core/contracts/credentials.py | Updated as part of this pull request. |
| libs/xtm-oaev-sdk/xtm_oaev_sdk/_core/contracts/assembly.py | Updated as part of this pull request. |
| libs/xtm-oaev-sdk/xtm_oaev_sdk/_core/contracts/__init__.py | Updated as part of this pull request. |
| libs/xtm-oaev-sdk/xtm_oaev_sdk/_core/configuration/truthiness.py | Updated as part of this pull request. |
| libs/xtm-oaev-sdk/xtm_oaev_sdk/_core/configuration/sources.py | Updated as part of this pull request. |
| libs/xtm-oaev-sdk/xtm_oaev_sdk/_core/configuration/settings_sources.py | Updated as part of this pull request. |
| libs/xtm-oaev-sdk/xtm_oaev_sdk/_core/configuration/resolver.py | Updated as part of this pull request. |
| libs/xtm-oaev-sdk/xtm_oaev_sdk/_core/configuration/__init__.py | Updated as part of this pull request. |
| libs/xtm-oaev-sdk/xtm_oaev_sdk/_core/common/logging_setup.py | Updated as part of this pull request. |
| libs/xtm-oaev-sdk/xtm_oaev_sdk/_core/common/encoding.py | Updated as part of this pull request. |
| libs/xtm-oaev-sdk/xtm_oaev_sdk/_core/common/certificates.py | Updated as part of this pull request. |
| libs/xtm-oaev-sdk/xtm_oaev_sdk/_core/common/__init__.py | Updated as part of this pull request. |
| libs/xtm-oaev-sdk/xtm_oaev_sdk/_core/__init__.py | Updated as part of this pull request. |
| libs/xtm-oaev-sdk/xtm_oaev_sdk/__init__.py | Updated as part of this pull request. |
| libs/xtm-oaev-sdk/test/test_boundaries.py | Updated as part of this pull request. |
| libs/xtm-oaev-sdk/test/signatures/test_signature_type.py | Updated as part of this pull request. |
| libs/xtm-oaev-sdk/test/signatures/test_signature_match.py | Updated as part of this pull request. |
| libs/xtm-oaev-sdk/test/signatures/test_ai_signature_types.py | Updated as part of this pull request. |
| libs/xtm-oaev-sdk/test/signatures/shim/test_signature_type.py | Updated as part of this pull request. |
| libs/xtm-oaev-sdk/test/signatures/shim/test_signature_match.py | Updated as part of this pull request. |
| libs/xtm-oaev-sdk/test/signatures/shim/test_ai_signature_types.py | Updated as part of this pull request. |
| libs/xtm-oaev-sdk/test/signatures/shim/test_ai_marker.py | Updated as part of this pull request. |
| libs/xtm-oaev-sdk/test/signatures/shim/features/signature_manager_post_execution.feature | Updated as part of this pull request. |
| libs/xtm-oaev-sdk/test/signatures/shim/constraints/signature_manager_pre_execution_constraints.feature | Updated as part of this pull request. |
| libs/xtm-oaev-sdk/test/signatures/shim/constraints/signature_manager_post_execution_constraints.feature | Updated as part of this pull request. |
| libs/xtm-oaev-sdk/test/signatures/shim/__init__.py | Updated as part of this pull request. |
| libs/xtm-oaev-sdk/test/signatures/features/signature_manager_post_execution.feature | Updated as part of this pull request. |
| libs/xtm-oaev-sdk/test/signatures/features/signature_manager_ip_resolution.feature | Updated as part of this pull request. |
| libs/xtm-oaev-sdk/test/signatures/constraints/signature_manager_pre_execution_constraints.feature | Updated as part of this pull request. |
| libs/xtm-oaev-sdk/test/signatures/constraints/signature_manager_post_execution_constraints.feature | Updated as part of this pull request. |
| libs/xtm-oaev-sdk/test/signatures/constraints/signature_manager_ip_resolution_constraints.feature | Updated as part of this pull request. |
| libs/xtm-oaev-sdk/test/signatures/__init__.py | Updated as part of this pull request. |
| libs/xtm-oaev-sdk/test/seam/test_seam_golden.py | Updated as part of this pull request. |
| libs/xtm-oaev-sdk/test/seam/test_seam_closed.py | Updated as part of this pull request. |
| libs/xtm-oaev-sdk/test/seam/__init__.py | Updated as part of this pull request. |
| libs/xtm-oaev-sdk/test/daemons/test_ping_alive.py | Updated as part of this pull request. |
| libs/xtm-oaev-sdk/test/daemons/shim/test_ping_alive.py | Updated as part of this pull request. |
| libs/xtm-oaev-sdk/test/daemons/shim/__init__.py | Updated as part of this pull request. |
| libs/xtm-oaev-sdk/test/daemons/__init__.py | Updated as part of this pull request. |
| libs/xtm-oaev-sdk/test/contracts/test_primitive_type.py | Updated as part of this pull request. |
| libs/xtm-oaev-sdk/test/contracts/test_credential_utils.py | Updated as part of this pull request. |
| libs/xtm-oaev-sdk/test/contracts/test_credential_types.py | Updated as part of this pull request. |
| libs/xtm-oaev-sdk/test/contracts/test_contract_referenced_credential.py | Updated as part of this pull request. |
| libs/xtm-oaev-sdk/test/contracts/test_contract_output_types.py | Updated as part of this pull request. |
| libs/xtm-oaev-sdk/test/contracts/test_contract_element_argument_type.py | Updated as part of this pull request. |
| libs/xtm-oaev-sdk/test/contracts/shim/test_primitive_type.py | Updated as part of this pull request. |
| libs/xtm-oaev-sdk/test/contracts/shim/test_credential_utils.py | Updated as part of this pull request. |
| libs/xtm-oaev-sdk/test/contracts/shim/test_credential_types.py | Updated as part of this pull request. |
| libs/xtm-oaev-sdk/test/contracts/shim/test_contract_referenced_credential.py | Updated as part of this pull request. |
| libs/xtm-oaev-sdk/test/contracts/shim/test_contract_output_types.py | Updated as part of this pull request. |
| libs/xtm-oaev-sdk/test/contracts/shim/test_contract_element_argument_type.py | Updated as part of this pull request. |
| libs/xtm-oaev-sdk/test/contracts/shim/__init__.py | Updated as part of this pull request. |
| libs/xtm-oaev-sdk/test/contracts/__init__.py | Updated as part of this pull request. |
| libs/xtm-oaev-sdk/test/configuration/shim/test_sources.py | Updated as part of this pull request. |
| libs/xtm-oaev-sdk/test/configuration/shim/__init__.py | Updated as part of this pull request. |
| libs/xtm-oaev-sdk/test/configuration/__init__.py | Updated as part of this pull request. |
| libs/xtm-oaev-sdk/test/common/test_ssl_utils.py | Updated as part of this pull request. |
| libs/xtm-oaev-sdk/test/common/test_exceptions.py | Updated as part of this pull request. |
| libs/xtm-oaev-sdk/test/common/shim/test_utils.py | Updated as part of this pull request. |
| libs/xtm-oaev-sdk/test/common/shim/test_exceptions.py | Updated as part of this pull request. |
| libs/xtm-oaev-sdk/test/common/shim/__init__.py | Updated as part of this pull request. |
| libs/xtm-oaev-sdk/test/common/__init__.py | Updated as part of this pull request. |
| libs/xtm-oaev-sdk/pyproject.toml | Updated as part of this pull request. |
| libs/xtm-oaev-sdk/docs/tdr/xtm-oaev-sdk-stays-connector-agnostic.tdr.md | Updated as part of this pull request. |
| libs/xtm-oaev-sdk/docs/tdr/shims-return-the-identical-sdk-object.tdr.md | Updated as part of this pull request. |
| libs/xtm-oaev-sdk/docs/tdr/seam-holds-data-contracts-and-their-own-invariants.tdr.md | Updated as part of this pull request. |
| libs/xtm-oaev-sdk/docs/tdr/seam-changes-are-versioned-contract-changes.tdr.md | Updated as part of this pull request. |
| libs/xtm-oaev-sdk/docs/tdr/sdks-never-import-pyoaev.tdr.md | Updated as part of this pull request. |
| libs/xtm-oaev-sdk/docs/tdr/pyoaev-hard-depends-on-the-sdks-during-deprecation.tdr.md | Updated as part of this pull request. |
| libs/xtm-oaev-sdk/docs/tdr/public-seam-core-dependency-rule.tdr.md | Updated as part of this pull request. |
| libs/xtm-oaev-sdk/docs/tdr/public-class-extends-seam-data.tdr.md | Updated as part of this pull request. |
| libs/xtm-oaev-sdk/docs/tdr/pass-bound-callables-to-keep-dispatch.tdr.md | Updated as part of this pull request. |
| libs/xtm-oaev-sdk/docs/tdr/no-breaking-change-for-legacy-pyoaev-code.tdr.md | Updated as part of this pull request. |
| libs/xtm-oaev-sdk/docs/tdr/legacy-surface-guarded-from-the-release.tdr.md | Updated as part of this pull request. |
| libs/xtm-oaev-sdk/docs/tdr/legacy-patch-targets-are-part-of-the-surface.tdr.md | Updated as part of this pull request. |
| libs/xtm-oaev-sdk/docs/tdr/legacy-names-served-by-pep562-module-getattr.tdr.md | Updated as part of this pull request. |
| libs/xtm-oaev-sdk/docs/tdr/importing-pyoaev-stays-silent.tdr.md | Updated as part of this pull request. |
| libs/xtm-oaev-sdk/docs/tdr/import-from-the-package-root.tdr.md | Updated as part of this pull request. |
| libs/xtm-oaev-sdk/docs/tdr/every-sdk-module-imports-alone.tdr.md | Updated as part of this pull request. |
| libs/xtm-oaev-sdk/docs/tdr/every-behaviour-behind-a-port.tdr.md | Updated as part of this pull request. |
| libs/xtm-oaev-sdk/docs/tdr/cross-process-seams-pin-their-json-schemas.tdr.md | Updated as part of this pull request. |
| libs/xtm-oaev-sdk/docs/tdr/colliding-names-get-a-capability-prefix.tdr.md | Updated as part of this pull request. |
| libs/xtm-oaev-sdk/docs/tdr/adapters-keep-the-user-facing-shape.tdr.md | Updated as part of this pull request. |
| libs/xtm-oaev-sdk/CHANGELOG.md | Updated as part of this pull request. |
| libs/sdk-requirements.txt | Updated as part of this pull request. |
| .github/workflows/coverage.yml | Updated as part of this pull request. |
| .circleci/config.yml | Updated as part of this pull request. |
🧠 Review effort: Balanced
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
| - name: Install dependencies | ||
| run: | | ||
| uv venv && uv pip install -e '.[dev]' coverage | ||
| uv venv && uv pip install -e ./libs/xtm-oaev-sdk -r libs/sdk-requirements.txt -e '.[dev]' coverage |
|
|
||
| # The expectation models moved to collectors_sdk; their legacy names here | ||
| # resolve to the identical objects and emit a DeprecationWarning on access. | ||
| __getattr__ = _make_deprecated_getattr( |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.


Proposed changes
client-pythonwas doing two jobs: the OpenAEV API client, and the shared runtime every collector and injector builds on. This PR cuts them apart. The SDK is built by moving the code out, not by rewriting it.xtm-oaev-sdk(libs/xtm-oaev-sdk): the shared, client-free code ofpyoaev, one capability per commit. The capabilities areconfiguration,common(errors, logging, JSON, SSL, enums, protocols),contracts(including thepyoaev.credentialreferences),signatures,port_io(the wire models),daemons(BaseDaemon,PingAlive) anddeprecation(make_deprecated_getattr).public/holds the adapters users import,seam/the stable contracts (ports, data models, enums, versioned with aSEAM_VERSION), and_core/the private implementations. The seam never importspublicor_core. The issue'scontracts/layer is calledseam/here, becausecontractsis already one of the capabilities.collectors-sdk(OpenAEV-Platform/collectors#) andinjectors-sdk(OpenAEV-Platform/injectors#).xtm-oaev-sdkstays agnostic of both, and none of the SDKs importspyoaev: the API client is injected (api_client=,transport=).pyoaevgoes back to being the API client.OpenAEV,pyoaev.apis, the backends, and the REST helpers (EncodedId,RequiredOptional,copy_dict,remove_none_from_dict,on_http_error) stay here.pyoaevnow depends onxtm-oaev-sdk,collectors-sdkandinjectors-sdkinstead ofpika,thefuzz,PyYAML,pydantic-settingsandpython_json_logger.__getattr__shim. It returns the SDK object and fires aDeprecationWarningnaming the new import, and importingpyoaevitself stays silent.test/test_legacy_surface.pyholds the whole public surface of the releasedpyoaevagainst the branch. The pre-split tests of the moved code are kept verbatim against their legacy paths.libs/xtm-oaev-sdk/test/seam/fingerprints every public seam object (normalized AST, plus the JSON schemas of pydantic models). Any seam change fails a test until someone regenerates the golden on purpose, version bump included.pyoaevwheel now shipspyoaevonly. Until now it also shipped the top-leveldocs,scriptsandtestpackages.requires-pythonmoves from>=3.11to>=3.12in all four packages, the versiontyping.overrideactually needs. Releasedpyoaevalready failed to import on 3.11.libs/xtm-oaev-sdk:docs/migration_guide.md: the full import table, client injection, renamed names;docs/shim_strategy.mdanddocs/seam_strategy.md: how the shims and the layering work;docs/tdr/;CONTRIBUTING.md,CHANGELOG.md, and the agent instructions.Testing Instructions
python -W always -c "from pyoaev.helpers import OpenAEVConfigHelper"warns and namesinjectors_sdk, whilepython -W error -c "import pyoaev"stays silent.Verified locally:
pyoaevstays silent;main, show no regression against the releasedpyoaev(i haven´t test them all :D).Related issues
Checklist
Further comments
Merge order.
libs/sdk-requirements.txt(used by CircleCI and the coverage workflow) installscollectors-sdkandinjectors-sdkfrom theirfeat/303-sdk-initbranches. So:libs/sdk-requirements.txtfrom@feat/303-sdk-initto@main(or a tag) on this branch;Release: open question.
pyoaevnow hard-depends onxtm-oaev-sdk,collectors-sdkandinjectors-sdk, and none of them is on PyPI yet. PyPI rejects any upload whose dependencies point to a URL ("Can't have direct dependency"), sopyoaevcan't depend on the GitHub repositories directly. Before the nextpyoaevrelease, we need to pick one of two options.Option 1: publish the three SDKs on PyPI.
pyoaevkeeps declaring the three packages.twine uploadaspyoaev).Option 2: bundle the SDKs inside the
pyoaevwheel.pyoaevwheel carriespyoaev,xtm_oaev_sdk,collectors_sdkandinjectors_sdk, and depends only on PyPI packages.It needs these specific steps:
pyproject.toml:pydantic-settings,PyYAML,python_json_logger,thefuzzandpika;scripts/bundle_sdks.sh):libs/xtm-oaev-sdk/xtm_oaev_sdkto the repository root;collectorsandinjectorsat a pinned tag or commit, and copylibs/collectors-sdk/collectors_sdkandlibs/injectors-sdk/injectors_sdkto the root;libs/sdk-requirements.txt, so there's one place to bump them. They must be tags or commits, not branches..gitignore: ignore the three copies at the root, so they're never committed.buildjob: run the script right beforepython3 -m build.deploykeeps uploadingdist/as today../libs/xtm-oaev-sdkpluslibs/sdk-requirements.txt). Never run the bundling script before an editable install, or each SDK gets installed twice.docs/migration_guide.md, and the TDRpyoaev-hard-depends-on-the-sdks-during-deprecation(or supersede it with a TDR recording the bundling).Each commit holds one capability or one concern, so the PR can be read commit by commit.