Skip to main content

opedd

PyPI Python License

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

Opedd is content licensing for the AI era. Publishers set the terms and get paid per use, with a verifiable receipt for every event.

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="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']}")

Phase 12 Wave 1 + 3 surfaces (0.2.0)

# Catalog scoping — discover what a publisher licenses (public, no auth needed for the call)
manifest = client.rsl.get(publisher_id="8268c353-ffa3-4db3-bbb2-90ddbbb43e41")
for license_type, terms in manifest["permits"].items():
    if terms["permitted"]:
        print(f"{license_type}: {terms['endpoint']}")

# CDSM Article 4(3) provenance — signed JSON-LD receipt for EU regulator verification
signed = client.rsl.get(publisher_id="8268c353-...", jsonld=True)
assert signed["opedd:legalBasis"].startswith("EU CDSM")
print("HMAC signature:", signed["opedd:signature"]["signature"])

claims = attestation["data"]["claims"]
print(f"Events in window: {claims['usage']['events_in_window']}")
print(f"Tempo Merkle root: {claims['tempo']['merkle_root']}")

# Programmatic publisher onboarding — detect platform behind a URL
detection = client.onboarding.detect_platform(url="https://noahpinion.substack.com")
data = detection["data"]
if data["confidence"] == "high":
    print(f"Platform: {data['platform']}, archive via {data['archive_method']}")
else:
    print(data["instructions"])  # human-readable operator copy

# Buyer-discovery catalog browse + URL → licensable check + license verification
directory = client.discovery.publisher_directory(category="finance", min_articles=5, limit=20)
for pub in directory["data"]["publishers"]:
    print(pub["name"], pub["article_count"], pub["pricing"])

try:
    hit = client.discovery.lookup_article(url="https://publisher.com/articles/...")
    print(f"Licensable: ${hit['data']['ai_price']} per article")
except OpeddNotFoundError:
    print("Not in Opedd registry")

check = client.discovery.verify_license(key="OP-XXXX-XXXX")
print(f"Blockchain status: {check['data']['blockchain_status']}")

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, or buyer API key + order_id Opedd(access_key="ent_...") or Opedd(buyer_token="opedd_buyer_live_...") with order_id= — full text in the feed for AI training and Full catalogue orders (content_access="included"); monthly orders are discovery-only: fetch articles via client.content.get(...); per-request orders are "search_only": ask with client.content.search(...)
client.audit.events(...) Supabase JWT Opedd(buyer_jwt="eyJhbGc...")
client.compliance.report(...) Supabase JWT Opedd(buyer_jwt="eyJhbGc...")
client.licenses.order(...) Buyer session JWT Opedd(buyer_jwt="eyJhbGc...")
client.licenses.orders(...) / client.licenses.get_order(...) Audit-scoped buyer API key or JWT Opedd(buyer_token="opedd_buyer_live_...")
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)
client.discovery.publisher_directory(...) None (public) Any (constructor still requires one)
client.discovery.lookup_article(...) None (public) Any (constructor still requires one)
client.discovery.verify_license(...) 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="eng@yourlab.com",
)
# 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, order_id=None)
client.feed.stream_ndjson(since=None, cursor=None, limit=5000, order_id=None)  # generator

# Ask a question (buyer key with the `search` scope). Filters only narrow.
client.content.search(
    "How did chip export controls change in 2026?",
    published_after="2026-01-01", published_before="2026-07-01", max_results=10,
)

client.audit.events(from_=None, to=None, event_type=None, cursor=None, limit=100)

client.compliance.report(from_, to, cursor=None)

client.licenses.order(licence, billing_mode, publisher_ids,
                      quantity=None, terms_accepted=True)  # 0.3.0 — licence orders
client.licenses.orders(cursor=None, limit=20)      # 0.3.0 — orders + lines
client.licenses.get_order(order_id)                # 0.3.0 — + Schedule documents and SHA-256
client.licenses.list()                             # buyer account + keys

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

client.discovery.publisher_directory(             # 0.2.0+ — public catalog browse
    category=None, min_articles=None, verified=None, limit=None, offset=None,
)
client.discovery.lookup_article(url)              # 0.2.0+ — URL → licensable check
client.discovery.verify_license(key)              # 0.2.0+ — license key verification

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

Compliance surfaces

  • 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.report(from_, to) — procurement-defense dossier: every licensed retrieval in a window, with licence terms and public-record proof.

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 support@opedd.com.

License

MIT

See also

Metadata

Release files for opedd 0.7.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for opedd 0.7.1
File Size Uploaded Provenance Actions
opedd-0.7.1.tar.gz 41.5 kB Without provenance Details for opedd-0.7.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for opedd 0.7.1
File Interpreter ABI Platform Actions
opedd-0.7.1-py3-none-any.whl Python 3 none any Details for opedd-0.7.1-py3-none-any.whl

Total release size: 71.1 kB

Release files / opedd-0.7.1.tar.gz

Download URL opedd-0.7.1.tar.gz
Size 41.5 kB
Tags Source
SHA-256 checksum
How to use checksums
3143da5f23e15761cb0e67c35f0458bdfead96f25720bb36d778a97959bd3810
BLAKE2b-256 checksum
How to use checksums
34d9efedd0881ffb8c682759494543f46d45c5fec2215314b0afd49625e4e420
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.14.6

Release files / opedd-0.7.1-py3-none-any.whl

Download URL opedd-0.7.1-py3-none-any.whl
Size 29.7 kB
Tags Python 3
SHA-256 checksum
How to use checksums
b24f5d9ac97b358e5339618d770f4448b8e899f8fe4e168a37040fcc888de3cb
BLAKE2b-256 checksum
How to use checksums
2ebc8d6f6b61066d226ef18d6cadf668bdb37dc91c792051d98fcec1cfff66a4
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.14.6

Security for opedd 0.7.1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page