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

• Small, explicit provider protocol
• Shared request/result/context types
• One executable-mode vocabulary (check or apply)
• 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

Execution intent is a shared request field: ExecutionMode.CHECK validates without applying changes; ExecutionMode.APPLY executes the action. The public API supplies mode, and the runtime exposes it as request.execution_mode. Provider-owned request.payload contains action options only.

from osp_provider_contracts import ExecutionMode

if request.execution_mode is ExecutionMode.APPLY:
    create_vm()

Provider entrypoints use execute(request, context, *, progress=None). request.name, request.target_ref and request.comment describe the task subject separately from its options. context.task_ref is the persisted global execution identity, not the originating orchestrator's local integer task ID.

Return actual outputs as ProviderResult.produced_resources, using typed ProducedResource(kind=..., ref=..., name=...) entries. Existing-resource operations retain their input target even when they produce other resources. A partial failure reports surviving outputs through ProviderError.produced_resources. Checks and simulations report no created resources.

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 hold
• approval_kind: peer, maintainer, or admin
• required_approvals: explicit positive quorum
• reason and message: policy explanation and user-facing consequence
• violations and tags: 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

Provider manifest fixtures

The real-provider fixtures in tests/fixtures/provider_manifests/{nrec,vmware}.json are generated from the provider source and sibling data repositories. From this repository, run:

bash scripts/regenerate-manifest-fixtures.sh

The script calls nrec_provider.domain.capabilities.build_capabilities with ../osp-provider-nrec-data and vmware_provider.domain.capabilities.build_capabilities with ../osp-provider-vmware-data/policy.yaml, using each provider's .venv. Output is formatted with sorted keys and written to the two fixture paths above. The builders run with explicit source/data paths and a clean environment so ambient credentials and secret files do not affect the result. The venvs provide third-party dependencies only: inside env -i, PYTHONPATH explicitly selects this contracts checkout, ../osp-provider-runtime/src, and the corresponding provider src tree. Installed copies of those three packages are not used. The script requires the sibling provider checkouts, their virtualenvs, and the matching data checkouts; missing inputs fail the command. Each provider builder validates its manifest before returning, and the script replaces the tracked files only after both builders succeed.

After provider contract or data changes, regenerate the fixtures and run the existing fixture contract check. To verify deterministic output, generate twice and compare the first result before running the check:

(
  set -euo pipefail
  tmp_dir="$(mktemp -d)"
  trap 'rm -rf "${tmp_dir}"' EXIT
  bash scripts/regenerate-manifest-fixtures.sh
  cp tests/fixtures/provider_manifests/nrec.json "${tmp_dir}/nrec.json"
  cp tests/fixtures/provider_manifests/vmware.json "${tmp_dir}/vmware.json"
  bash scripts/regenerate-manifest-fixtures.sh
  cmp --silent "${tmp_dir}/nrec.json" tests/fixtures/provider_manifests/nrec.json
  cmp --silent "${tmp_dir}/vmware.json" tests/fixtures/provider_manifests/vmware.json
)
./.venv/bin/pytest -q tests/unit/contracts/test_provider_manifest_fixtures.py

That test validates the saved JSON against the shared manifest contract; it does not establish that a fixture is fresh against a provider, so run both the regeneration command and the check.

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