opedd 0.2.0

Official Python SDK for the Opedd content licensing API (buyer-side)

opedd

Official Python SDK for the Opedd 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

pip install opedd

Requires Python 3.10+.

Quickstart

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="ent_xxx", buyer_email="[e-mail]")
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.

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="ent_...")
client.audit.events(...)	Supabase JWT	Opedd(buyer_jwt="eyJhbGc...")
client.compliance.report(...)	Supabase JWT	Opedd(buyer_jwt="eyJhbGc...")
client.compliance.article_53_attestation(...)	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...")
client.rsl.get(...)	None (public)	Any (constructor still requires one)
client.onboarding.detect_platform(...)	None (public)	Any (constructor still requires one)

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

client = Opedd.from_access_key(
    access_key="ent_xyz...",
    buyer_email="[e-mail]",
)
# client.buyer_token is now set; you can call /content-delivery

API surface

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.compliance.article_53_attestation(
    license_id, content_id=None, window_start=None, window_end=None,
)                                                # 0.2.0 — Phase 12 Wave 1 W1.4

client.licenses.purchase(publisher_ids, buyer_email, buyer_org, ...)
client.licenses.list()

client.rsl.get(publisher_id, jsonld=False)        # 0.2.0 — Phase 12 Wave 1 W1.1
client.onboarding.detect_platform(url)            # 0.2.0 — Phase 12 Wave 3 W3.1

All methods return dicts matching the backend wire format. See docs.opedd.com for full response shapes.

Regulatory framing (CDSM Article 4 vs EU AI Act Article 53)

Three distinct compliance surfaces — never conflated per INVARIANTS.md W1.6:

• client.rsl.get(publisher_id, jsonld=True) — publisher-side CDSM Article 4(3) opt-out declaration (signed JSON-LD receipt over the reservation state).
• client.compliance.article_53_attestation(license_id) — buyer-side EU AI Act Article 53 attestation (signed JWT scoped to one license).
• client.compliance.report(from_, to) — comprehensive procurement-defense dossier covering BOTH frameworks (publisher CDSM reservation honored + buyer Article 53 evidence chain).

These serve different audit-defensibility modes and never share wire format. Method docstrings cite the W1.6 invariant inline.

Not in SDK

The SDK is buyer-side by design (Stripe-style audience separation — different SDK for publishers if/when that ships). Publisher-side write endpoints are reachable via raw HTTP only, not wrapped here. Canonical excluded surface as of 0.2.0:

• PATCH /publisher-profile (Phase 12 Wave 1 W1.2 — publisher updates tdm_reservation_signed_at + cdsm_tdm_opt_out from the publisher dashboard). The endpoint exists on the backend but is not yet documented in opedd-docs/openapi.json and uses publisher-portal Supabase JWT auth (a credential mode the buyer-side SDK does not carry). The publisher React dashboard at opedd-frontend calls it via raw fetch().

Reconsider expanding the SDK surface to publisher-side write endpoints when both of these hold: (i) opedd-docs/openapi.json includes the /publisher-profile PATCH spec, and (ii) a buyer integration ask for tdm_reservation state surfaces. Tracked in opedd-backend/docs/cleanup/active-deferrals.md for the institutional record.

Error handling

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.

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)

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)

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

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. For broader questions about Opedd as a platform, email [e-mail].

License

MIT

See also

• docs.opedd.com — full API reference + cookbook
• opedd-mcp — Model Context Protocol server for Claude Desktop / Cursor
• opedd-backend — backend implementation (private)