Metadata-Version: 2.4
Name: osp-provider-contracts
Version: 0.2.22
Summary: Shared contracts for OSP providers and orchestrator.
Author: OSP Team
License: MIT
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.13
Classifier: Typing :: Typed
Requires-Python: >=3.13
Provides-Extra: dev
Requires-Dist: build<2,>=1.2; extra == 'dev'
Requires-Dist: hatch<2,>=1.14; extra == 'dev'
Requires-Dist: pytest<9,>=8.3; extra == 'dev'
Requires-Dist: ruff>=0.15; extra == 'dev'
Requires-Dist: twine<7,>=6; extra == 'dev'
Requires-Dist: ty>=0.0.18; extra == 'dev'
Description-Content-Type: text/markdown

# 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

```bash
pip install osp-provider-contracts
```

## Development

```bash
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:

```bash
git tag v0.2.0
git push origin v0.2.0
```
