Metadata-Version: 2.4
Name: osp-provider-contracts
Version: 0.4.1
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<10,>=9.0.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'
Requires-Dist: uv<0.13,>=0.12.5; 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
- 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

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:

```python
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 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

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