SeenRelay Python client
Deterministic, standard-library-only client for placing SeenRelay CHECK directly in front of repeated source-backed validation.
Install
Package metadata is prepared and continuously validated for registry publication. Until the package is published, use the repository copy from clients/python/.
Smallest integration: bind once, one line per revalidation
from seenrelay import SeenRelayClient
from seenrelay_easy import protect_validation
relay = SeenRelayClient()
validate_price = protect_validation(
relay,
fact=fact,
validate=lambda ctx: expensive_validation(ctx.conditional_headers),
)
value = validate_price(known_value)
That is strict shadow mode by default: SeenRelay CHECK runs, your original validation still runs, and the independently obtained result is OBSERVEd best-effort. Nothing is skipped merely because SeenRelay is installed.
Only after measurement and policy approval should you add an explicit reuse policy:
from seenrelay import reuse_known_on_same_observed
validate_price = protect_validation(
relay,
fact=fact,
validate=lambda ctx: expensive_validation(ctx.conditional_headers),
reuse=reuse_known_on_same_observed,
)
Direct client form
The same behavior is available without the convenience binder:
value = relay.guard(
fact=fact,
known_value=known_value,
validate=lambda ctx: expensive_validation(ctx.conditional_headers),
)
Without an explicit reuse policy, validation is never skipped.
Prove value before enabling reuse
from seenrelay import SeenRelayClient
from seenrelay_shadow import SeenRelayShadowProof
proof = SeenRelayShadowProof(SeenRelayClient())
value = proof.guard(
fact=fact,
known_value=known_value,
validate=lambda ctx: expensive_validation(ctx.conditional_headers),
)
print(proof.report(
avoided_validation_cost=0.01, # use your own invoice/cost unit
))
Shadow Proof always keeps the original validation. It measures CHECK status distribution, validation time and SeenRelay request latency locally. Potential savings count only SAME_OBSERVED calls and subtract caller-supplied request costs. Savings from conditional ETag / Last-Modified requests are deliberately excluded unless measured separately by the application.
Use SeenRelay around repeated validation that is materially more expensive than the preflight: paid search, scraping/proxy work, browser or extraction calls, rate-limited APIs, model-assisted parsing, or multi-step validation. It is generally a poor fit for a cheap one-off GET.
For fleet economics and current public-price illustrations, see https://seenrelay.com/economics and docs/ECONOMICS_LAB.md in the repository.
License
The client package is MIT licensed. The hosted SeenRelay service implementation remains governed by the repository root license.
1 maintainer
Metadata
1 maintainer
Release files for seenrelay 0.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| seenrelay-0.1.0.tar.gz | 9.4 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| seenrelay-0.1.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 20.1 kB
Release files / seenrelay-0.1.0.tar.gz
| Download URL | seenrelay-0.1.0.tar.gz |
|---|---|
| Size | 9.4 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
70e251a0ed894dffc49d94a43d798bde23e8b228458ab9dfea5c1c8f81d83de1
|
|
BLAKE2b-256 checksum How to use checksums |
d67357cd44b598558d69c098408c16f8c464d0d0a79a08368d6b1cf87f5481df
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
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.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Aug 26, 2026.
Transparency logRelease files / seenrelay-0.1.0-py3-none-any.whl
| Download URL | seenrelay-0.1.0-py3-none-any.whl |
|---|---|
| Size | 10.8 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
d3a8e53707bf46f5899355b1d3f484fedea0fd668bf162755f615ac6a2f788fd
|
|
BLAKE2b-256 checksum How to use checksums |
6da2d3a38ea33bcb5e59dc7882e36f44f6897e8bf3de61e9c92de462d678b84a
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
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.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Aug 26, 2026.
Transparency log
