osp-provider-contracts
Shared Python contract package for OSP providers and orchestrator: typed interfaces, canonical errors, capabilities schema, idempotency helpers, and a reusable provider conformance kit.
For maintainer-facing internals and invariants, see src/README.md.
Scope (v0.1)
- Small, explicit provider protocol
- Shared request/result/context types
- One executable-mode vocabulary (
checkorapply) - Canonical error taxonomy with retry metadata
- Capabilities and manifest v2 schema validation
- Conformance assertions and a reusable pytest suite for provider CI
- Canonical gate reason enum for approval-required flows
No pytest plugin is included. Providers opt in by subclassing the conformance suite from a local test module.
Execution
Planning is read-only and does not execute provider actions. An executed task
is either ExecutionMode.CHECK when its canonical dry_run or check flag is
true, or ExecutionMode.APPLY otherwise:
from osp_provider_contracts import ExecutionMode, resolve_execution_mode
mode = resolve_execution_mode(request.payload)
if mode is ExecutionMode.APPLY:
create_vm()
The resolver deliberately ignores a payload's execution_mode string so an
ordinary dispatched task cannot become an unmarked successful no-op.
Approval-Required Contract
Providers that need human approval should raise ValidationError with
detail="approval_required" and include a structured extra payload:
gate_key: provider-stable identity for this policy holdapproval_kind:peer,maintainer, oradminrequired_approvals: explicit positive quorumreasonandmessage: policy explanation and user-facing consequenceviolationsandtags: structured provider evidence
The provider states the complete decision requirement. The orchestrator stores and evaluates it without deriving authority from reason strings.
Install
pip install osp-provider-contracts
Development
env -u VIRTUAL_ENV uv sync --extra dev
hatch shell
hatch run dev:check
hatch run dev:build
hatch run dev:verify
Release
See docs/release.md for the manual/gated publish flow.
Tag and push:
git tag v0.2.0
git push origin v0.2.0
1 maintainer
Release files for osp-provider-contracts 0.5.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| osp_provider_contracts-0.5.0.tar.gz | 68.9 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| osp_provider_contracts-0.5.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 124.8 kB
Release files / osp_provider_contracts-0.5.0.tar.gz
| Download URL | osp_provider_contracts-0.5.0.tar.gz |
|---|---|
| Size | 68.9 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
63c995ee83447c9743350f5f368f7a74d047cb4307d4aa7e7aa9d7fbb3652907
|
|
BLAKE2b-256 checksum How to use checksums |
4f052c22ead813fbd5086f59044b8191ce451cc3b73f8d7eaa2a6487de0191ea
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.13.5
|
Release files / osp_provider_contracts-0.5.0-py3-none-any.whl
| Download URL | osp_provider_contracts-0.5.0-py3-none-any.whl |
|---|---|
| Size | 55.9 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
e6c5c4ef6be1a52fe2aa3f509d66e5094597a9a2b8eda1a9f4fb86d8e87bb7b2
|
|
BLAKE2b-256 checksum How to use checksums |
75aef3baf3053d61b283e42b1c1e6c9e96e337c8e8e83fc4d6817d7c1712c565
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.13.5
|
