osp-provider-contracts 0.2.20

Shared contracts for OSP providers and orchestrator.

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
• 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.

Approval-Required Contract

Providers that need human approval should raise ValidationError with detail="approval_required" and include a structured extra payload:

• gate_reason: one of osp_provider_contracts.GateReason string values
• importance: integer risk/urgency indicator when applicable (1 => 2 approvals)
• required_approvals: optional explicit total quorum override (e.g., 2 for dual control)
• reason: stable machine-readable reason string
• details: provider-specific context for operators and audit

Providers do not send approval-authority tiers. required_approvals only requests the total number of approvals. The orchestrator may add fixed-tier requirements from gate policy, such as provider-admin sudo or global break-glass approval, without changing provider payloads.

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