opedd 0.1.0__tar.gz

opedd-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,43 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  unit-tests:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install package + dev deps
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+
+      - name: Lint with ruff
+        run: ruff check src/ tests/
+
+      - name: Type-check with mypy
+        run: mypy src/
+
+      - name: Run unit tests
+        run: pytest tests/test_unit.py -v
+
+  # Integration tests intentionally NOT run in CI.
+  # Per Phase 11 M6 ratification 6: SDK live tests running autonomously in CI
+  # could pollute usage_records, distort metered-publisher-payouts aggregation,
+  # fire production API calls with founder identity at scale. Integration suite
+  # is documented in RELEASE.md as "run locally with your JWT before each SDK
+  # release."

opedd-0.1.0/.gitignore

@@ -0,0 +1,55 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# Virtual env
+.venv/
+venv/
+ENV/
+env/
+
+# Type checker / linter caches
+.mypy_cache/
+.ruff_cache/
+.pytest_cache/
+.tox/
+.nox/
+htmlcov/
+.coverage
+.coverage.*
+nosetests.xml
+coverage.xml
+*.cover
+.hypothesis/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+.DS_Store
+
+# Secrets
+.env
+.env.*
+!.env.example

opedd-0.1.0/CHANGELOG.md

@@ -0,0 +1,40 @@
+# Changelog
+
+All notable changes to opedd-python are documented in this file.
+
+The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] — 2026-05-15
+
+Initial public release. Phase 11 M6 ship.
+
+### Added
+
+- `Opedd` client class with 5 namespaces:
+  - `client.content.get(article_id)` — fetch licensed article (`GET /content-delivery`)
+  - `client.feed.list(since, cursor, limit)` — paginated JSON catalog (`GET /enterprise-license?format=json`)
+  - `client.feed.stream_ndjson(since, cursor, limit)` — NDJSON streaming generator (`GET /enterprise-license?format=ndjson`)
+  - `client.audit.events(from_, to, event_type, cursor, limit)` — per-event audit browse (`GET /buyer-audit`)
+  - `client.compliance.report(from_, to, cursor)` — procurement-defense dossier (`GET /buyer-compliance-report`)
+  - `client.licenses.purchase(...)` — enterprise license purchase (`POST /enterprise-license`)
+  - `client.licenses.list()` — buyer profile + masked key list (`GET /buyer-account`)
+- Three credential modes:
+  - `buyer_token` (bearer) for `/content-delivery`
+  - `access_key` (query param) for `/enterprise-license` GET feed
+  - `buyer_jwt` (Supabase session) for `/buyer-audit` + `/buyer-compliance-report` + `/buyer-account`
+- Env-var fallbacks: `OPEDD_BUYER_TOKEN`, `OPEDD_BUYER_JWT`, `OPEDD_ACCESS_KEY`, `OPEDD_BASE_URL`
+- `Opedd.from_access_key(access_key, buyer_email)` constructor that exchanges `eak_*` for a bearer token via `POST /enterprise-auth`
+- Context manager support (`with Opedd(...) as client:` closes the underlying HTTP pool)
+- Typed exception hierarchy: `OpeddError`, `OpeddAuthError`, `OpeddNotFoundError`, `OpeddValidationError`, `OpeddRateLimitError`, `OpeddServerError`. Each carries `status_code`, `request_id`, `body`. `OpeddRateLimitError` additionally carries `retry_after_seconds`.
+- NDJSON streaming with auto-pagination across `_meta.next_cursor` until `_meta.truncated == false`.
+- 29 unit tests with mocked HTTPX (`pytest tests/test_unit.py`).
+- Integration test suite gated on `pytest --integration` flag (manual local execution before release; not run in CI per institutional risk discipline).
+- Schema version pin: `phase-11-m4`. Surfaced as `opedd.__schema_version__`.
+
+### Wire-format contract
+
+- Successful response body is flat (no nested `data.data` envelope on most endpoints).
+- Error response: `{"success": false, "error": "..."}` or `{"success": false, "error": {"code": "...", "message": "...", "details": {...}}}` (Phase 8 nested envelope).
+- `X-Opedd-Request-Id` propagated to all SDK exception `request_id` fields.
+
+[0.1.0]: https://github.com/Opedd/opedd-python/releases/tag/v0.1.0

opedd-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Opedd
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

opedd-0.1.0/PKG-INFO

@@ -0,0 +1,212 @@
+Metadata-Version: 2.4
+Name: opedd
+Version: 0.1.0
+Summary: Official Python SDK for the Opedd content licensing API (buyer-side)
+Project-URL: Homepage, https://opedd.com
+Project-URL: Documentation, https://docs.opedd.com
+Project-URL: Repository, https://github.com/Opedd/opedd-python
+Project-URL: Issues, https://github.com/Opedd/opedd-python/issues
+Project-URL: Changelog, https://github.com/Opedd/opedd-python/blob/main/CHANGELOG.md
+Author-email: Opedd <support@opedd.com>
+License: MIT
+License-File: LICENSE
+Keywords: ai-licensing,ai-training,content-licensing,opedd,rag
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27.0
+Provides-Extra: dev
+Requires-Dist: mypy>=1.8.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
+Requires-Dist: pytest-httpx>=0.30.0; extra == 'dev'
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.4.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# opedd
+
+[![PyPI](https://img.shields.io/pypi/v/opedd.svg)](https://pypi.org/project/opedd/)
+[![Python](https://img.shields.io/pypi/pyversions/opedd.svg)](https://pypi.org/project/opedd/)
+[![License](https://img.shields.io/pypi/l/opedd.svg)](https://github.com/Opedd/opedd-python/blob/main/LICENSE)
+
+Official Python SDK for the [Opedd](https://opedd.com) content licensing API (buyer-side).
+
+Opedd is programmatic licensing infrastructure between AI buyers and publishers — rights, usage tracking, and payment. "Stripe for content licensing."
+
+## Install
+
+```bash
+pip install opedd
+```
+
+Requires Python 3.10+.
+
+## Quickstart
+
+```python
+from opedd import Opedd
+
+client = Opedd(buyer_token="opedd_buyer_live_...")
+
+# Fetch a single licensed article
+article = client.content.get("article-uuid")
+print(article["title"], article["author"], article["word_count"])
+
+# Stream the full licensed catalog as NDJSON
+client = Opedd(access_key="eak_xxx", buyer_email="eng@yourlab.com")
+for row in client.feed.stream_ndjson(limit=5000):
+    train_model.ingest(row["content"], metadata=row)
+
+# Pull a procurement-defense compliance dossier
+client = Opedd(buyer_jwt="eyJhbGc...")
+dossier = client.compliance.report(from_="2026-04-01", to="2026-04-30")
+print(f"Retrievals: {dossier['dossier_metadata']['summary']['total_retrievals']}")
+```
+
+For end-to-end walkthroughs, see the [cookbook](https://docs.opedd.com/cookbook.md).
+
+## Credentials
+
+The SDK supports three credential types depending on which endpoint you call:
+
+| Endpoint | Credential | Construction |
+|---|---|---|
+| `client.content.get(...)` | Bearer buyer token | `Opedd(buyer_token="opedd_buyer_live_...")` |
+| `client.feed.list(...)` / `client.feed.stream_ndjson(...)` | Access key (query param) | `Opedd(access_key="eak_...")` |
+| `client.audit.events(...)` | Supabase JWT | `Opedd(buyer_jwt="eyJhbGc...")` |
+| `client.compliance.report(...)` | Supabase JWT | `Opedd(buyer_jwt="eyJhbGc...")` |
+| `client.licenses.purchase(...)` | None (returns Stripe `client_secret`) | `Opedd(buyer_token="...")` |
+| `client.licenses.list()` | Supabase JWT | `Opedd(buyer_jwt="eyJhbGc...")` |
+
+Multiple credentials can be supplied at once and the SDK selects the correct one per endpoint.
+
+### Env-var fallbacks
+
+The constructor reads from these env vars when arguments are omitted:
+
+- `OPEDD_BUYER_TOKEN`
+- `OPEDD_BUYER_JWT`
+- `OPEDD_ACCESS_KEY`
+- `OPEDD_BASE_URL` (default `https://api.opedd.com`)
+
+### Exchanging an access key for a bearer token
+
+```python
+client = Opedd.from_access_key(
+    access_key="eak_xyz...",
+    buyer_email="eng@yourlab.com",
+)
+# client.buyer_token is now set; you can call /content-delivery
+```
+
+## API surface
+
+```python
+client.content.get(article_id)
+
+client.feed.list(since=None, cursor=None, limit=200)
+client.feed.stream_ndjson(since=None, cursor=None, limit=5000)  # generator
+
+client.audit.events(from_=None, to=None, event_type=None, cursor=None, limit=100)
+
+client.compliance.report(from_, to, cursor=None)
+
+client.licenses.purchase(publisher_ids, buyer_email, buyer_org, ...)
+client.licenses.list()
+```
+
+All methods return dicts matching the backend wire format. See [docs.opedd.com](https://docs.opedd.com) for full response shapes.
+
+## Error handling
+
+```python
+from opedd import (
+    OpeddError,
+    OpeddAuthError,
+    OpeddNotFoundError,
+    OpeddRateLimitError,
+    OpeddServerError,
+    OpeddValidationError,
+)
+
+try:
+    article = client.content.get(uuid)
+except OpeddRateLimitError as e:
+    time.sleep(e.retry_after_seconds or 60)
+    retry()
+except OpeddAuthError:
+    refresh_token()
+except OpeddNotFoundError:
+    log.warning("article gone; skipping")
+except OpeddError as e:
+    log.error(f"{e} request_id={e.request_id}")
+```
+
+Every error carries `status_code`, `request_id`, and `body` for forensic correlation.
+
+## Schema version pinning
+
+The SDK ships pinned to backend schema version **`phase-11-m4`** (`opedd.__schema_version__`).
+
+When the backend bumps `X-Opedd-Schema-Version`, the SDK ships a follow-up release within 1 sprint per the [schema-pin invariant](https://github.com/Opedd/opedd-backend/blob/main/INVARIANTS.md#python-sdk--mcp-server-pin-to-backend-x-opedd-schema-version-phase-11-m6).
+
+Additive field bumps are absorbed transparently (dict pass-through). Subtractive or rename bumps require an SDK release; ensure your `requirements.txt` pins to a tested version.
+
+## Tests
+
+Two test suites:
+
+### Unit tests (run in CI, no live API calls)
+
+```bash
+pip install -e ".[dev]"
+pytest tests/test_unit.py
+```
+
+29+ unit tests covering: client construction, credential precedence, env-var fallback, auth-header building per credential type, HTTP error mapping (401/403/404/400/422/429/5xx), NDJSON streaming + cursor pagination, all 5 namespaces' request shapes.
+
+### Integration tests (manual, before each release)
+
+```bash
+export OPEDD_BUYER_JWT="..."     # for /buyer-audit + /buyer-compliance-report
+export OPEDD_BUYER_TOKEN="..."   # for /content-delivery
+export OPEDD_ACCESS_KEY="..."    # for /enterprise-license GET feed
+pytest --integration
+```
+
+Live tests against `api.opedd.com`. Read-only. Skipped by default (require `--integration` flag).
+
+Per [release discipline](./RELEASE.md), integration tests must pass locally before any version tag is pushed. CI does NOT run integration tests — per institutional risk discipline, autonomous CI runs against production state can pollute `usage_records`, distort metered-publisher payouts, and fire production API calls at scale.
+
+## Development
+
+```bash
+git clone https://github.com/Opedd/opedd-python.git
+cd opedd-python
+pip install -e ".[dev]"
+pytest tests/test_unit.py            # unit only (default)
+pytest --integration                  # unit + integration (requires env vars)
+ruff check src/ tests/                # lint
+mypy src/                             # type-check
+```
+
+## Contributing
+
+Issues and PRs welcome at [github.com/Opedd/opedd-python](https://github.com/Opedd/opedd-python). For broader questions about Opedd as a platform, email [support@opedd.com](mailto:support@opedd.com).
+
+## License
+
+[MIT](./LICENSE)
+
+## See also
+
+- [docs.opedd.com](https://docs.opedd.com) — full API reference + cookbook
+- [opedd-mcp](https://github.com/Opedd/opedd-mcp) — Model Context Protocol server for Claude Desktop / Cursor
+- [opedd-backend](https://github.com/Opedd/opedd-backend) — backend implementation (private)

opedd-0.1.0/README.md

@@ -0,0 +1,180 @@
+# opedd
+
+[![PyPI](https://img.shields.io/pypi/v/opedd.svg)](https://pypi.org/project/opedd/)
+[![Python](https://img.shields.io/pypi/pyversions/opedd.svg)](https://pypi.org/project/opedd/)
+[![License](https://img.shields.io/pypi/l/opedd.svg)](https://github.com/Opedd/opedd-python/blob/main/LICENSE)
+
+Official Python SDK for the [Opedd](https://opedd.com) content licensing API (buyer-side).
+
+Opedd is programmatic licensing infrastructure between AI buyers and publishers — rights, usage tracking, and payment. "Stripe for content licensing."
+
+## Install
+
+```bash
+pip install opedd
+```
+
+Requires Python 3.10+.
+
+## Quickstart
+
+```python
+from opedd import Opedd
+
+client = Opedd(buyer_token="opedd_buyer_live_...")
+
+# Fetch a single licensed article
+article = client.content.get("article-uuid")
+print(article["title"], article["author"], article["word_count"])
+
+# Stream the full licensed catalog as NDJSON
+client = Opedd(access_key="eak_xxx", buyer_email="eng@yourlab.com")
+for row in client.feed.stream_ndjson(limit=5000):
+    train_model.ingest(row["content"], metadata=row)
+
+# Pull a procurement-defense compliance dossier
+client = Opedd(buyer_jwt="eyJhbGc...")
+dossier = client.compliance.report(from_="2026-04-01", to="2026-04-30")
+print(f"Retrievals: {dossier['dossier_metadata']['summary']['total_retrievals']}")
+```
+
+For end-to-end walkthroughs, see the [cookbook](https://docs.opedd.com/cookbook.md).
+
+## Credentials
+
+The SDK supports three credential types depending on which endpoint you call:
+
+| Endpoint | Credential | Construction |
+|---|---|---|
+| `client.content.get(...)` | Bearer buyer token | `Opedd(buyer_token="opedd_buyer_live_...")` |
+| `client.feed.list(...)` / `client.feed.stream_ndjson(...)` | Access key (query param) | `Opedd(access_key="eak_...")` |
+| `client.audit.events(...)` | Supabase JWT | `Opedd(buyer_jwt="eyJhbGc...")` |
+| `client.compliance.report(...)` | Supabase JWT | `Opedd(buyer_jwt="eyJhbGc...")` |
+| `client.licenses.purchase(...)` | None (returns Stripe `client_secret`) | `Opedd(buyer_token="...")` |
+| `client.licenses.list()` | Supabase JWT | `Opedd(buyer_jwt="eyJhbGc...")` |
+
+Multiple credentials can be supplied at once and the SDK selects the correct one per endpoint.
+
+### Env-var fallbacks
+
+The constructor reads from these env vars when arguments are omitted:
+
+- `OPEDD_BUYER_TOKEN`
+- `OPEDD_BUYER_JWT`
+- `OPEDD_ACCESS_KEY`
+- `OPEDD_BASE_URL` (default `https://api.opedd.com`)
+
+### Exchanging an access key for a bearer token
+
+```python
+client = Opedd.from_access_key(
+    access_key="eak_xyz...",
+    buyer_email="eng@yourlab.com",
+)
+# client.buyer_token is now set; you can call /content-delivery
+```
+
+## API surface
+
+```python
+client.content.get(article_id)
+
+client.feed.list(since=None, cursor=None, limit=200)
+client.feed.stream_ndjson(since=None, cursor=None, limit=5000)  # generator
+
+client.audit.events(from_=None, to=None, event_type=None, cursor=None, limit=100)
+
+client.compliance.report(from_, to, cursor=None)
+
+client.licenses.purchase(publisher_ids, buyer_email, buyer_org, ...)
+client.licenses.list()
+```
+
+All methods return dicts matching the backend wire format. See [docs.opedd.com](https://docs.opedd.com) for full response shapes.
+
+## Error handling
+
+```python
+from opedd import (
+    OpeddError,
+    OpeddAuthError,
+    OpeddNotFoundError,
+    OpeddRateLimitError,
+    OpeddServerError,
+    OpeddValidationError,
+)
+
+try:
+    article = client.content.get(uuid)
+except OpeddRateLimitError as e:
+    time.sleep(e.retry_after_seconds or 60)
+    retry()
+except OpeddAuthError:
+    refresh_token()
+except OpeddNotFoundError:
+    log.warning("article gone; skipping")
+except OpeddError as e:
+    log.error(f"{e} request_id={e.request_id}")
+```
+
+Every error carries `status_code`, `request_id`, and `body` for forensic correlation.
+
+## Schema version pinning
+
+The SDK ships pinned to backend schema version **`phase-11-m4`** (`opedd.__schema_version__`).
+
+When the backend bumps `X-Opedd-Schema-Version`, the SDK ships a follow-up release within 1 sprint per the [schema-pin invariant](https://github.com/Opedd/opedd-backend/blob/main/INVARIANTS.md#python-sdk--mcp-server-pin-to-backend-x-opedd-schema-version-phase-11-m6).
+
+Additive field bumps are absorbed transparently (dict pass-through). Subtractive or rename bumps require an SDK release; ensure your `requirements.txt` pins to a tested version.
+
+## Tests
+
+Two test suites:
+
+### Unit tests (run in CI, no live API calls)
+
+```bash
+pip install -e ".[dev]"
+pytest tests/test_unit.py
+```
+
+29+ unit tests covering: client construction, credential precedence, env-var fallback, auth-header building per credential type, HTTP error mapping (401/403/404/400/422/429/5xx), NDJSON streaming + cursor pagination, all 5 namespaces' request shapes.
+
+### Integration tests (manual, before each release)
+
+```bash
+export OPEDD_BUYER_JWT="..."     # for /buyer-audit + /buyer-compliance-report
+export OPEDD_BUYER_TOKEN="..."   # for /content-delivery
+export OPEDD_ACCESS_KEY="..."    # for /enterprise-license GET feed
+pytest --integration
+```
+
+Live tests against `api.opedd.com`. Read-only. Skipped by default (require `--integration` flag).
+
+Per [release discipline](./RELEASE.md), integration tests must pass locally before any version tag is pushed. CI does NOT run integration tests — per institutional risk discipline, autonomous CI runs against production state can pollute `usage_records`, distort metered-publisher payouts, and fire production API calls at scale.
+
+## Development
+
+```bash
+git clone https://github.com/Opedd/opedd-python.git
+cd opedd-python
+pip install -e ".[dev]"
+pytest tests/test_unit.py            # unit only (default)
+pytest --integration                  # unit + integration (requires env vars)
+ruff check src/ tests/                # lint
+mypy src/                             # type-check
+```
+
+## Contributing
+
+Issues and PRs welcome at [github.com/Opedd/opedd-python](https://github.com/Opedd/opedd-python). For broader questions about Opedd as a platform, email [support@opedd.com](mailto:support@opedd.com).
+
+## License
+
+[MIT](./LICENSE)
+
+## See also
+
+- [docs.opedd.com](https://docs.opedd.com) — full API reference + cookbook
+- [opedd-mcp](https://github.com/Opedd/opedd-mcp) — Model Context Protocol server for Claude Desktop / Cursor
+- [opedd-backend](https://github.com/Opedd/opedd-backend) — backend implementation (private)

opedd-0.1.0/RELEASE.md

@@ -0,0 +1,106 @@
+# Release process for opedd-python
+
+This document codifies the SDK release discipline established in Phase 11 M6.
+
+## Trigger
+
+A release ships when:
+
+1. The backend bumps `X-Opedd-Schema-Version` on any buyer-facing endpoint, AND the bump requires a wrapper change (additive bumps are absorbed transparently; subtractive/rename bumps require code).
+2. A new buyer-side endpoint ships in the backend (e.g., Phase 12 onwards).
+3. A bug is fixed in the SDK itself.
+4. A new minor feature lands in the SDK (e.g., new error type, retry helper).
+
+Per the [schema-pin invariant](https://github.com/Opedd/opedd-backend/blob/main/INVARIANTS.md#python-sdk--mcp-server-pin-to-backend-x-opedd-schema-version-phase-11-m6), backend schema bumps trigger a follow-up SDK release within 1 sprint.
+
+## Version-bump rules
+
+- **MAJOR** (1.0.0 → 2.0.0): breaking SDK API change — method removed/renamed, parameter signature change.
+- **MINOR** (0.1.0 → 0.2.0): new endpoint surface, new namespace, new optional parameter, backend schema-pin bump.
+- **PATCH** (0.1.0 → 0.1.1): bug fix, doc update, dependency-version bump that doesn't change behavior.
+
+While the SDK is pre-1.0, MINOR bumps are also acceptable for behavior-breaking changes; the README + CHANGELOG must call them out explicitly.
+
+## Pre-release checklist
+
+1. **Update `__version__`** in `src/opedd/__init__.py` AND `version` in `pyproject.toml`.
+2. **Update `__schema_version__`** if the backend bumped any buyer-facing endpoint schema version.
+3. **Update `CHANGELOG.md`** with a new section dated today's UTC date.
+4. **Run unit tests**: `pytest tests/test_unit.py` — must be all-green.
+5. **Run integration tests locally** with founder credentials:
+   ```bash
+   export OPEDD_BUYER_JWT="..."
+   export OPEDD_BUYER_TOKEN="..."
+   export OPEDD_ACCESS_KEY="..."
+   pytest --integration
+   ```
+   Per founder M6 ratification 6, integration tests do NOT run in CI — they run locally before each release. Verify all-green.
+6. **Lint + type-check**: `ruff check src/ tests/` AND `mypy src/`. Must be clean.
+7. **Build the package**: `pip install --upgrade build && python -m build`. Confirm `dist/opedd-<version>-py3-none-any.whl` and `dist/opedd-<version>.tar.gz` produced.
+8. **Verify install from local wheel**: `pip install --force-reinstall dist/opedd-<version>-py3-none-any.whl && python -c "import opedd; print(opedd.__version__)"`.
+
+## PyPI publish
+
+```bash
+pip install --upgrade twine
+twine check dist/*
+twine upload dist/*
+```
+
+You'll need a PyPI API token (`pypi-AgEIcHlw...`) stored either in `~/.pypirc`:
+
+```ini
+[pypi]
+username = __token__
+password = pypi-AgEIcHlw...
+```
+
+Or passed via `TWINE_USERNAME=__token__ TWINE_PASSWORD=pypi-...`.
+
+Verify install from PyPI after upload (give the CDN ~30s to propagate):
+
+```bash
+pip install --upgrade opedd
+python -c "import opedd; print(opedd.__version__, opedd.__schema_version__)"
+```
+
+## Git tag + GitHub release
+
+```bash
+git tag -a v0.1.0 -m "v0.1.0 — initial buyer-side SDK"
+git push origin v0.1.0
+gh release create v0.1.0 \
+  --title "v0.1.0 — initial buyer-side SDK" \
+  --notes-file CHANGELOG.md
+```
+
+## Post-release
+
+- Cross-link from opedd-docs `python-sdk.md` if the README example block changed.
+- If schema pin changed: update `opedd-backend/INVARIANTS.md` "Python SDK + MCP server pin to backend X-Opedd-Schema-Version" section with the new version.
+- Email `support@opedd.com` (or whatever the buyer-facing channel is) if the bump is breaking.
+
+## Yank / unpublish
+
+If a release ships with a critical bug:
+
+```bash
+# Yank (preferred — removes from default index but keeps for pinned installs)
+twine upload --skip-existing dist/opedd-<patched-version>-*  # ship the patch first
+pip install --upgrade twine
+# Then yank the broken version via PyPI web UI: https://pypi.org/manage/project/opedd/release/<version>/
+```
+
+NEVER fully delete a PyPI release; PyPI does not allow re-publishing the same version number, so deletion creates a permanent gap. Yank-then-patch is the canonical recovery path.
+
+## CI
+
+CI runs unit tests on every push (see `.github/workflows/ci.yml`). Integration tests run locally only (per Phase 11 M6 ratification 6: "SDK live tests running autonomously in CI could pollute usage_records, distort metered-publisher-payouts aggregation, fire production API calls with founder identity at scale").
+
+## Maintenance schedule
+
+- **Backend X-Opedd-Schema-Version bump**: ship follow-up SDK within 1 sprint per the schema-pin invariant.
+- **Dependency security advisory (httpx, pytest)**: ship patch release within 1 week.
+- **Python EOL versions (3.10 EOL October 2026)**: drop EOL'd versions in a MINOR bump, document in CHANGELOG.
+
+See [opedd-backend/docs/cleanup/active-deferrals.md](https://github.com/Opedd/opedd-backend/blob/main/docs/cleanup/active-deferrals.md) for the institutional schema-pin maintenance discipline entry.