seenrelay 0.1.0__tar.gz

seenrelay-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Vlad Belciug
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this client wrapper 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.

seenrelay-0.1.0/PKG-INFO

@@ -0,0 +1,99 @@
+Metadata-Version: 2.4
+Name: seenrelay
+Version: 0.1.0
+Summary: Deterministic zero-dependency SeenRelay client for repeated source-backed validation workflows.
+Author: Vlad Belciug
+License-Expression: MIT
+Project-URL: Homepage, https://seenrelay.com/clients
+Project-URL: Repository, https://github.com/ovladon/seenrelay
+Project-URL: Issues, https://github.com/ovladon/seenrelay/issues
+Keywords: ai-agents,validation,freshness,cache,mcp
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# 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
+
+```python
+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:
+
+```python
+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:
+
+```python
+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
+
+```python
+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.

seenrelay-0.1.0/README.md

@@ -0,0 +1,82 @@
+# 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
+
+```python
+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:
+
+```python
+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:
+
+```python
+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
+
+```python
+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.

seenrelay-0.1.0/pyproject.toml

@@ -0,0 +1,28 @@
+[build-system]
+requires = ["setuptools>=75"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "seenrelay"
+version = "0.1.0"
+description = "Deterministic zero-dependency SeenRelay client for repeated source-backed validation workflows."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+authors = [
+  { name = "Vlad Belciug" }
+]
+keywords = ["ai-agents", "validation", "freshness", "cache", "mcp"]
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "Operating System :: OS Independent"
+]
+dependencies = []
+
+[project.urls]
+Homepage = "https://seenrelay.com/clients"
+Repository = "https://github.com/ovladon/seenrelay"
+Issues = "https://github.com/ovladon/seenrelay/issues"
+
+[tool.setuptools]
+py-modules = ["seenrelay", "seenrelay_shadow", "seenrelay_easy"]

seenrelay-0.1.0/seenrelay.egg-info/PKG-INFO

@@ -0,0 +1,99 @@
+Metadata-Version: 2.4
+Name: seenrelay
+Version: 0.1.0
+Summary: Deterministic zero-dependency SeenRelay client for repeated source-backed validation workflows.
+Author: Vlad Belciug
+License-Expression: MIT
+Project-URL: Homepage, https://seenrelay.com/clients
+Project-URL: Repository, https://github.com/ovladon/seenrelay
+Project-URL: Issues, https://github.com/ovladon/seenrelay/issues
+Keywords: ai-agents,validation,freshness,cache,mcp
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# 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
+
+```python
+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:
+
+```python
+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:
+
+```python
+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
+
+```python
+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.

seenrelay-0.1.0/seenrelay.egg-info/SOURCES.txt

@@ -0,0 +1,10 @@
+LICENSE
+README.md
+pyproject.toml
+seenrelay.py
+seenrelay_easy.py
+seenrelay_shadow.py
+seenrelay.egg-info/PKG-INFO
+seenrelay.egg-info/SOURCES.txt
+seenrelay.egg-info/dependency_links.txt
+seenrelay.egg-info/top_level.txt

seenrelay-0.1.0/seenrelay.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

seenrelay-0.1.0/seenrelay.egg-info/top_level.txt

@@ -0,0 +1,3 @@
+seenrelay
+seenrelay_easy
+seenrelay_shadow

seenrelay-0.1.0/seenrelay.py

@@ -0,0 +1,383 @@
+from __future__ import annotations
+
+from copy import deepcopy
+from dataclasses import dataclass
+import json
+import threading
+import time
+import uuid
+from typing import Any, Callable, Generic, Mapping, MutableMapping, Optional, TypeVar
+from urllib import request as urllib_request
+from urllib.error import HTTPError
+
+T = TypeVar("T")
+JsonValue = Any
+
+@dataclass(frozen=True)
+class TransportResponse:
+    status: int
+    headers: Mapping[str, str]
+    body: Any
+
+@dataclass(frozen=True)
+class ValidationContext:
+    check: Optional[Mapping[str, Any]]
+    conditional_headers: Mapping[str, str]
+
+@dataclass(frozen=True)
+class ReuseDecision(Generic[T]):
+    reuse: bool
+    value: Optional[T] = None
+
+@dataclass(frozen=True)
+class GuardDetailedResult(Generic[T]):
+    value: T
+    path: str
+    check: Optional[Mapping[str, Any]]
+    check_ok: bool
+    observe_ok: Optional[bool]
+    observe_deferred: bool = False
+    check_error: Optional[str] = None
+    observe_error: Optional[str] = None
+
+@dataclass(frozen=True)
+class TelemetrySnapshot:
+    guard_calls: int
+    check_calls: int
+    check_successes: int
+    check_failures: int
+    check_timeouts: int
+    check_network_requests: int
+    check_coalesced: int
+    check_network_latency_ms_total: float
+    check_network_latency_ms_max: float
+    check_network_latency_ms_average: float
+    reuse_hits: int
+    validation_calls: int
+    conditional_hint_validations: int
+    observe_attempts: int
+    observe_scheduled: int
+    observe_schedule_failures: int
+    observe_successes: int
+    observe_failures: int
+    observe_timeouts: int
+    observe_network_requests: int
+    observe_network_latency_ms_total: float
+    observe_network_latency_ms_max: float
+    observe_network_latency_ms_average: float
+
+@dataclass(frozen=True)
+class ReuseEconomicsEstimate:
+    gross_avoided_validation_cost: float
+    relay_request_cost: float
+    net_estimated_savings: float
+    excludes_conditional_request_savings: bool = True
+
+Transport = Callable[[str, str, Mapping[str, str], Any, float], TransportResponse]
+ReusePolicy = Callable[[Mapping[str, Any], T], ReuseDecision[T]]
+ValidatorMetadata = Mapping[str, Any]
+ObservationFactory = Callable[[T, ValidationContext], Optional[ValidatorMetadata]]
+Validator = Callable[[ValidationContext], T]
+
+class _InflightCheck:
+    __slots__ = ("event", "result", "error")
+    def __init__(self) -> None:
+        self.event = threading.Event()
+        self.result: Optional[Mapping[str, Any]] = None
+        self.error: Optional[Exception] = None
+
+def _empty_metrics() -> MutableMapping[str, float | int]:
+    return {
+        "guard_calls": 0, "check_calls": 0, "check_successes": 0, "check_failures": 0,
+        "check_timeouts": 0, "check_network_requests": 0, "check_coalesced": 0,
+        "check_network_latency_ms_total": 0.0, "check_network_latency_ms_max": 0.0,
+        "reuse_hits": 0, "validation_calls": 0, "conditional_hint_validations": 0,
+        "observe_attempts": 0, "observe_scheduled": 0, "observe_schedule_failures": 0,
+        "observe_successes": 0, "observe_failures": 0,
+        "observe_timeouts": 0, "observe_network_requests": 0,
+        "observe_network_latency_ms_total": 0.0, "observe_network_latency_ms_max": 0.0,
+    }
+
+def reuse_known_on_same_observed(check: Mapping[str, Any], known_value: T) -> ReuseDecision[T]:
+    if check.get("status") == "SAME_OBSERVED":
+        return ReuseDecision(reuse=True, value=known_value)
+    return ReuseDecision(reuse=False)
+
+def _default_transport(method: str, url: str, headers: Mapping[str, str], body: Any, timeout: float) -> TransportResponse:
+    data = json.dumps(body, separators=(",", ":"), allow_nan=False).encode("utf-8")
+    req = urllib_request.Request(url, data=data, method=method, headers=dict(headers))
+    try:
+        with urllib_request.urlopen(req, timeout=timeout) as response:
+            parsed = json.loads(response.read().decode("utf-8"))
+            return TransportResponse(status=response.status, headers={k.lower(): v for k, v in response.headers.items()}, body=parsed)
+    except HTTPError as exc:
+        raw = exc.read().decode("utf-8", errors="replace")
+        try:
+            parsed = json.loads(raw)
+        except json.JSONDecodeError:
+            parsed = {"error": raw}
+        return TransportResponse(status=exc.code, headers={k.lower(): v for k, v in exc.headers.items()}, body=parsed)
+
+def _safe_conditional_headers(check: Optional[Mapping[str, Any]]) -> Mapping[str, str]:
+    if not check:
+        return {}
+    hint = check.get("conditional_request_hint")
+    if not isinstance(hint, Mapping):
+        return {}
+    name = hint.get("request_header")
+    value = hint.get("header_value")
+    if name not in {"If-None-Match", "If-Modified-Since"}:
+        return {}
+    if not isinstance(value, str) or not value or "\r" in value or "\n" in value:
+        return {}
+    return {str(name): value}
+
+def _positive_finite(value: float, name: str) -> float:
+    number = float(value)
+    if not (number > 0.0 and number < float("inf")):
+        raise ValueError(f"{name} must be a positive finite number")
+    return number
+
+def _non_negative_finite(value: float, name: str) -> float:
+    number = float(value)
+    if not (number >= 0.0 and number < float("inf")):
+        raise ValueError(f"{name} must be a non-negative finite number")
+    return number
+
+def _coalescing_key(fact: Mapping[str, Any], known_value: Any, max_age_seconds: Optional[int]) -> Optional[str]:
+    payload: MutableMapping[str, Any] = {"fact": dict(fact), "known_value": known_value}
+    if max_age_seconds is not None:
+        payload["max_age_seconds"] = max_age_seconds
+    try:
+        return json.dumps(payload, sort_keys=True, separators=(",", ":"), ensure_ascii=False, allow_nan=False)
+    except (TypeError, ValueError):
+        return None
+
+class SeenRelayClient:
+    def __init__(self, *, base_url: str = "https://seenrelay.com", client_hint: Optional[str] = None,
+                 initial_lease: Optional[str] = None, on_lease: Optional[Callable[[str], None]] = None,
+                 check_timeout_seconds: float = 1.0, observe_timeout_seconds: float = 0.75,
+                 coalesce_checks: bool = True,
+                 schedule_observe: Optional[Callable[[Callable[[], None]], None]] = None,
+                 on_deferred_observe_error: Optional[Callable[[Exception], None]] = None,
+                 transport: Transport = _default_transport) -> None:
+        self.base_url = base_url.rstrip("/")
+        self.client_hint = client_hint.strip() if client_hint and client_hint.strip() else None
+        self.lease = initial_lease.strip() if initial_lease and initial_lease.strip() else None
+        self.on_lease = on_lease
+        self.check_timeout_seconds = _positive_finite(check_timeout_seconds, "check_timeout_seconds")
+        self.observe_timeout_seconds = _positive_finite(observe_timeout_seconds, "observe_timeout_seconds")
+        self.coalesce_checks = bool(coalesce_checks)
+        self.schedule_observe = schedule_observe
+        self.on_deferred_observe_error = on_deferred_observe_error
+        self.transport = transport
+        self._state_lock = threading.Lock()
+        self._inflight_checks: MutableMapping[str, _InflightCheck] = {}
+        self._metrics: MutableMapping[str, float | int] = _empty_metrics()
+
+    def _metric_add(self, name: str, amount: float | int = 1) -> None:
+        with self._state_lock:
+            self._metrics[name] = self._metrics[name] + amount
+
+    def _metric_latency(self, prefix: str, elapsed_ms: float) -> None:
+        with self._state_lock:
+            total = f"{prefix}_latency_ms_total"
+            maximum = f"{prefix}_latency_ms_max"
+            self._metrics[total] = float(self._metrics[total]) + elapsed_ms
+            self._metrics[maximum] = max(float(self._metrics[maximum]), elapsed_ms)
+
+    def get_telemetry(self) -> TelemetrySnapshot:
+        with self._state_lock:
+            m = dict(self._metrics)
+        check_requests = int(m["check_network_requests"])
+        observe_requests = int(m["observe_network_requests"])
+        return TelemetrySnapshot(
+            guard_calls=int(m["guard_calls"]), check_calls=int(m["check_calls"]), check_successes=int(m["check_successes"]),
+            check_failures=int(m["check_failures"]), check_timeouts=int(m["check_timeouts"]), check_network_requests=check_requests,
+            check_coalesced=int(m["check_coalesced"]), check_network_latency_ms_total=float(m["check_network_latency_ms_total"]),
+            check_network_latency_ms_max=float(m["check_network_latency_ms_max"]),
+            check_network_latency_ms_average=(float(m["check_network_latency_ms_total"]) / check_requests if check_requests else 0.0),
+            reuse_hits=int(m["reuse_hits"]), validation_calls=int(m["validation_calls"]),
+            conditional_hint_validations=int(m["conditional_hint_validations"]), observe_attempts=int(m["observe_attempts"]),
+            observe_scheduled=int(m["observe_scheduled"]), observe_schedule_failures=int(m["observe_schedule_failures"]),
+            observe_successes=int(m["observe_successes"]), observe_failures=int(m["observe_failures"]),
+            observe_timeouts=int(m["observe_timeouts"]), observe_network_requests=observe_requests,
+            observe_network_latency_ms_total=float(m["observe_network_latency_ms_total"]),
+            observe_network_latency_ms_max=float(m["observe_network_latency_ms_max"]),
+            observe_network_latency_ms_average=(float(m["observe_network_latency_ms_total"]) / observe_requests if observe_requests else 0.0),
+        )
+
+    def reset_telemetry(self) -> None:
+        with self._state_lock:
+            self._metrics = _empty_metrics()
+
+    def estimate_reuse_economics(self, *, avoided_validation_cost: float, check_request_cost: float = 0.0,
+                                 observe_request_cost: float = 0.0) -> ReuseEconomicsEstimate:
+        avoided = _positive_finite(avoided_validation_cost, "avoided_validation_cost")
+        check_cost = _non_negative_finite(check_request_cost, "check_request_cost")
+        observe_cost = _non_negative_finite(observe_request_cost, "observe_request_cost")
+        m = self.get_telemetry()
+        gross = m.reuse_hits * avoided
+        relay = m.check_network_requests * check_cost + m.observe_network_requests * observe_cost
+        return ReuseEconomicsEstimate(gross_avoided_validation_cost=gross, relay_request_cost=relay, net_estimated_savings=gross - relay)
+
+    def guard(self, *, fact: Mapping[str, Any], known_value: T, validate: Validator[T], reuse: Optional[ReusePolicy[T]] = None,
+              max_age_seconds: Optional[int] = None, observation: Optional[ObservationFactory[T]] = None) -> T:
+        return self.guard_detailed(fact=fact, known_value=known_value, validate=validate, reuse=reuse,
+                                   max_age_seconds=max_age_seconds, observation=observation).value
+
+    def guard_detailed(self, *, fact: Mapping[str, Any], known_value: T, validate: Validator[T],
+                       reuse: Optional[ReusePolicy[T]] = None, max_age_seconds: Optional[int] = None,
+                       observation: Optional[ObservationFactory[T]] = None) -> GuardDetailedResult[T]:
+        self._metric_add("guard_calls")
+        self._metric_add("check_calls")
+        check: Optional[Mapping[str, Any]] = None
+        check_ok = False
+        check_error: Optional[str] = None
+        try:
+            check = self._check(fact, known_value, max_age_seconds)
+            check_ok = True
+            self._metric_add("check_successes")
+        except Exception as exc:
+            self._metric_add("check_failures")
+            if isinstance(exc, TimeoutError): self._metric_add("check_timeouts")
+            check_error = str(exc)
+        if check is not None and reuse is not None:
+            decision = reuse(check, known_value)
+            if decision.reuse:
+                self._metric_add("reuse_hits")
+                return GuardDetailedResult(value=decision.value, path="reused", check=check, check_ok=check_ok,
+                                           observe_ok=None, check_error=check_error)  # type: ignore[arg-type]
+        conditional_headers = _safe_conditional_headers(check)
+        context = ValidationContext(check=check, conditional_headers=conditional_headers)
+        self._metric_add("validation_calls")
+        if conditional_headers: self._metric_add("conditional_hint_validations")
+        value = validate(context)
+        observe_ok: Optional[bool] = None
+        observe_error: Optional[str] = None
+        observe_deferred = False
+        self._metric_add("observe_attempts")
+
+        def perform_observe(*, deferred: bool) -> tuple[bool, Optional[str]]:
+            try:
+                metadata = observation(value, context) if observation else None
+                self._observe(fact, value, metadata)
+                self._metric_add("observe_successes")
+                return True, None
+            except Exception as exc:
+                self._metric_add("observe_failures")
+                if isinstance(exc, TimeoutError): self._metric_add("observe_timeouts")
+                if deferred and self.on_deferred_observe_error is not None:
+                    try:
+                        self.on_deferred_observe_error(exc)
+                    except Exception:
+                        pass
+                return False, str(exc)
+
+        if self.schedule_observe is not None:
+            observe_deferred = True
+            try:
+                self.schedule_observe(lambda: perform_observe(deferred=True))
+                self._metric_add("observe_scheduled")
+            except Exception as exc:
+                self._metric_add("observe_schedule_failures")
+                observe_ok = False
+                observe_error = str(exc)
+        else:
+            observe_ok, observe_error = perform_observe(deferred=False)
+
+        return GuardDetailedResult(value=value, path="validated", check=check, check_ok=check_ok, observe_ok=observe_ok,
+                                   observe_deferred=observe_deferred, check_error=check_error, observe_error=observe_error)
+
+    def _headers(self) -> MutableMapping[str, str]:
+        with self._state_lock:
+            lease = self.lease
+        headers: MutableMapping[str, str] = {"content-type": "application/json"}
+        if lease: headers["x-seenrelay-lease"] = lease
+        if self.client_hint: headers["x-seenrelay-client"] = self.client_hint
+        return headers
+
+    def _update_lease(self, response: TransportResponse) -> None:
+        header_lease = response.headers.get("x-seenrelay-lease") or response.headers.get("X-SeenRelay-Lease")
+        body_lease = None
+        if isinstance(response.body, Mapping):
+            hive = response.body.get("hive")
+            if isinstance(hive, Mapping) and isinstance(hive.get("lease"), str): body_lease = hive.get("lease")
+        next_lease = str(header_lease or body_lease or "").strip()
+        if not next_lease: return
+        callback: Optional[Callable[[str], None]] = None
+        with self._state_lock:
+            if next_lease == self.lease: return
+            self.lease = next_lease
+            callback = self.on_lease
+        if callback: callback(next_lease)
+
+    def _post(self, path: str, body: Any, timeout: float) -> Any:
+        response = self.transport("POST", f"{self.base_url}{path}", self._headers(), body, timeout)
+        self._update_lease(response)
+        if response.status < 200 or response.status >= 300:
+            raise RuntimeError(f"SeenRelay {path} returned HTTP {response.status}")
+        return response.body
+
+    def _check(self, fact: Mapping[str, Any], known_value: T, max_age_seconds: Optional[int]) -> Mapping[str, Any]:
+        key = _coalescing_key(fact, known_value, max_age_seconds) if self.coalesce_checks else None
+        if key is None: return self._check_network(fact, known_value, max_age_seconds)
+        with self._state_lock:
+            inflight = self._inflight_checks.get(key)
+            if inflight is None:
+                inflight = _InflightCheck(); self._inflight_checks[key] = inflight; leader = True
+            else:
+                leader = False; self._metrics["check_coalesced"] = self._metrics["check_coalesced"] + 1
+        if not leader:
+            inflight.event.wait()
+            if inflight.error is not None: raise RuntimeError(str(inflight.error)) from inflight.error
+            if inflight.result is None: raise RuntimeError("coalesced SeenRelay CHECK completed without a result")
+            return deepcopy(inflight.result)
+        try:
+            result = self._check_network(fact, known_value, max_age_seconds); inflight.result = result; return deepcopy(result)
+        except Exception as exc:
+            inflight.error = exc; raise
+        finally:
+            inflight.event.set()
+            with self._state_lock:
+                if self._inflight_checks.get(key) is inflight: del self._inflight_checks[key]
+
+    def _check_network(self, fact: Mapping[str, Any], known_value: T, max_age_seconds: Optional[int]) -> Mapping[str, Any]:
+        self._metric_add("check_network_requests")
+        started = time.monotonic()
+        try:
+            payload: MutableMapping[str, Any] = {"fact": dict(fact), "known_value": known_value}
+            if max_age_seconds is not None: payload["max_age_seconds"] = max_age_seconds
+            body = self._post("/v1/check", payload, self.check_timeout_seconds)
+            if not isinstance(body, Mapping): raise RuntimeError("SeenRelay CHECK response is not an object")
+            if body.get("status") not in {"SAME_OBSERVED", "CHANGED_OBSERVED", "CONTESTED", "STALE", "UNKNOWN"}:
+                raise RuntimeError("SeenRelay CHECK response has an invalid status")
+            return body
+        finally:
+            self._metric_latency("check_network", max(0.0, (time.monotonic() - started) * 1000.0))
+
+    def _observe(self, fact: Mapping[str, Any], value: T, metadata: Optional[Mapping[str, Any]]) -> None:
+        meta = dict(metadata or {})
+        source_validator = meta.pop("source_validator", None)
+        if source_validator is not None:
+            if not isinstance(source_validator, Mapping): raise ValueError("source_validator must be an object")
+            validator_value = source_validator.get("value")
+            if not isinstance(validator_value, str) or "\r" in validator_value or "\n" in validator_value:
+                raise ValueError("source_validator.value must not contain CR or LF")
+        payload: MutableMapping[str, Any] = {
+            "fact": dict(fact), "value": value,
+            "observed_at": meta.pop("observed_at", None) or __import__("datetime").datetime.now(__import__("datetime").timezone.utc).isoformat().replace("+00:00", "Z"),
+            "idempotency_key": meta.pop("idempotency_key", None) or str(uuid.uuid4()),
+        }
+        observer_id = meta.pop("observer_id", None)
+        evidence_fingerprint = meta.pop("evidence_fingerprint", None)
+        if observer_id: payload["observer_id"] = observer_id
+        if evidence_fingerprint: payload["evidence_fingerprint"] = evidence_fingerprint
+        if source_validator is not None: payload["source_validator"] = dict(source_validator)
+        if meta: raise ValueError(f"unsupported observation metadata: {', '.join(sorted(meta))}")
+        self._metric_add("observe_network_requests")
+        started = time.monotonic()
+        try:
+            self._post("/v1/observe", payload, self.observe_timeout_seconds)
+        finally:
+            self._metric_latency("observe_network", max(0.0, (time.monotonic() - started) * 1000.0))

seenrelay-0.1.0/seenrelay_easy.py

@@ -0,0 +1,38 @@
+from __future__ import annotations
+
+from typing import Any, Callable, Mapping, Optional, TypeVar
+
+from seenrelay import ObservationFactory, ReusePolicy, SeenRelayClient, ValidationContext
+
+T = TypeVar("T")
+Validator = Callable[[ValidationContext], T]
+
+
+def protect_validation(
+    client: SeenRelayClient,
+    *,
+    fact: Mapping[str, Any],
+    validate: Validator[T],
+    reuse: Optional[ReusePolicy[T]] = None,
+    max_age_seconds: Optional[int] = None,
+    observation: Optional[ObservationFactory[T]] = None,
+) -> Callable[[T], T]:
+    """Bind SeenRelay around one existing validator.
+
+    Without an explicit reuse policy this remains strict shadow mode: CHECK runs,
+    the original validation still runs, and the independently obtained result is
+    OBSERVEd best-effort. The returned callable accepts only the caller's known
+    value, making each later protected revalidation a one-line call.
+    """
+
+    def protected(known_value: T) -> T:
+        return client.guard(
+            fact=fact,
+            known_value=known_value,
+            validate=validate,
+            reuse=reuse,
+            max_age_seconds=max_age_seconds,
+            observation=observation,
+        )
+
+    return protected

seenrelay-0.1.0/seenrelay_shadow.py

@@ -0,0 +1,175 @@
+from __future__ import annotations
+
+from copy import deepcopy
+from math import isfinite
+import time
+from typing import Any, Callable, Mapping, Optional, TypeVar
+
+from seenrelay import SeenRelayClient, ValidationContext
+
+T = TypeVar("T")
+_STATUSES = ("SAME_OBSERVED", "CHANGED_OBSERVED", "CONTESTED", "STALE", "UNKNOWN")
+
+
+def _non_negative_finite(value: float, name: str) -> float:
+    number = float(value)
+    if not isfinite(number) or number < 0:
+        raise ValueError(f"{name} must be a non-negative finite number")
+    return number
+
+
+def _empty_metrics() -> dict[str, Any]:
+    return {
+        "calls": 0,
+        "checks_without_usable_response": 0,
+        "conditional_hints_seen": 0,
+        "validation_ms_total": 0.0,
+        "same_observed_validation_ms": 0.0,
+        "statuses": {status: 0 for status in _STATUSES},
+    }
+
+
+class SeenRelayShadowProof:
+    """Measure SeenRelay in strict shadow mode without suppressing validation."""
+
+    def __init__(self, client: SeenRelayClient) -> None:
+        if not hasattr(client, "guard_detailed") or not hasattr(client, "get_telemetry"):
+            raise TypeError("client must be a SeenRelayClient-compatible instance")
+        self.client = client
+        self._metrics = _empty_metrics()
+
+    def reset(self) -> None:
+        self._metrics = _empty_metrics()
+        if hasattr(self.client, "reset_telemetry"):
+            self.client.reset_telemetry()
+
+    def snapshot(self) -> Mapping[str, Any]:
+        metrics = deepcopy(self._metrics)
+        calls = int(metrics["calls"])
+        metrics["validation_ms_average"] = float(metrics["validation_ms_total"]) / calls if calls else 0.0
+        return metrics
+
+    def guard(
+        self,
+        *,
+        fact: Mapping[str, Any],
+        known_value: T,
+        validate: Callable[[ValidationContext], T],
+        max_age_seconds: Optional[int] = None,
+        observation: Optional[Callable[[T, ValidationContext], Optional[Mapping[str, Any]]]] = None,
+    ) -> T:
+        validation_ms = 0.0
+
+        def measured_validate(context: ValidationContext) -> T:
+            nonlocal validation_ms
+            started = time.monotonic()
+            try:
+                return validate(context)
+            finally:
+                validation_ms += max(0.0, (time.monotonic() - started) * 1000.0)
+
+        result = self.client.guard_detailed(
+            fact=fact,
+            known_value=known_value,
+            validate=measured_validate,
+            reuse=None,
+            max_age_seconds=max_age_seconds,
+            observation=observation,
+        )
+
+        self._metrics["calls"] += 1
+        self._metrics["validation_ms_total"] += validation_ms
+        check = result.check
+        status = check.get("status") if isinstance(check, Mapping) else None
+        if status in _STATUSES:
+            self._metrics["statuses"][status] += 1
+            if status == "SAME_OBSERVED":
+                self._metrics["same_observed_validation_ms"] += validation_ms
+        else:
+            self._metrics["checks_without_usable_response"] += 1
+
+        hint = check.get("conditional_request_hint") if isinstance(check, Mapping) else None
+        if isinstance(hint, Mapping):
+            self._metrics["conditional_hints_seen"] += 1
+
+        return result.value
+
+    def report(
+        self,
+        *,
+        avoided_validation_cost: float = 0.0,
+        check_request_cost: float = 0.0,
+        observe_request_cost: float = 0.0,
+        observe_off_critical_path: bool = False,
+    ) -> Mapping[str, Any]:
+        avoided = _non_negative_finite(avoided_validation_cost, "avoided_validation_cost")
+        check_cost = _non_negative_finite(check_request_cost, "check_request_cost")
+        observe_cost = _non_negative_finite(observe_request_cost, "observe_request_cost")
+        proof = self.snapshot()
+        relay = self.client.get_telemetry()
+
+        calls = int(proof["calls"])
+        same = int(proof["statuses"]["SAME_OBSERVED"])
+        observed_same_rate = same / calls if calls else 0.0
+        prospective_observe_requests = max(0, int(relay.observe_network_requests) - same)
+
+        gross_potential_savings = same * avoided
+        prospective_relay_request_cost = (
+            int(relay.check_network_requests) * check_cost
+            + prospective_observe_requests * observe_cost
+        )
+        net_potential_savings = gross_potential_savings - prospective_relay_request_cost
+
+        check_average_ms = float(relay.check_network_latency_ms_average)
+        observe_average_ms = float(relay.observe_network_latency_ms_average)
+        validation_average_ms = float(proof["validation_ms_average"])
+        off_critical_path = bool(observe_off_critical_path)
+        prospective_relay_latency_ms = (
+            float(relay.check_network_latency_ms_total)
+            + (0.0 if off_critical_path else prospective_observe_requests * observe_average_ms)
+        )
+        potential_net_time_saved_ms = float(proof["same_observed_validation_ms"]) - prospective_relay_latency_ms
+
+        if off_critical_path:
+            break_even_reuse_rate_by_time = check_average_ms / validation_average_ms if validation_average_ms > 0 else None
+        else:
+            time_denominator = validation_average_ms + observe_average_ms
+            break_even_reuse_rate_by_time = (
+                (check_average_ms + observe_average_ms) / time_denominator
+                if time_denominator > 0
+                else None
+            )
+        cost_denominator = avoided + observe_cost
+        break_even_reuse_rate_by_cost = (
+            (check_cost + observe_cost) / cost_denominator
+            if cost_denominator > 0
+            else None
+        )
+
+        return {
+            "mode": "shadow-proof",
+            "calls": calls,
+            "status_counts": deepcopy(proof["statuses"]),
+            "observed_same_rate": observed_same_rate,
+            "conditional_hints_seen": int(proof["conditional_hints_seen"]),
+            "validation_ms_average": validation_average_ms,
+            "check_network_latency_ms_average": check_average_ms,
+            "observe_network_latency_ms_average": observe_average_ms,
+            "potential_validation_calls_avoided": same,
+            "gross_potential_savings": gross_potential_savings,
+            "prospective_relay_request_cost": prospective_relay_request_cost,
+            "net_potential_savings": net_potential_savings,
+            "same_observed_validation_ms": float(proof["same_observed_validation_ms"]),
+            "prospective_relay_latency_ms": prospective_relay_latency_ms,
+            "potential_net_time_saved_ms": potential_net_time_saved_ms,
+            "break_even_reuse_rate_by_time": break_even_reuse_rate_by_time,
+            "break_even_reuse_rate_by_cost": break_even_reuse_rate_by_cost,
+            "assumptions": {
+                "direct_reuse_only": True,
+                "conditional_request_savings_excluded": True,
+                "active_mode_would_not_observe_direct_reuse_hits": True,
+                "caller_supplied_cost_units": True,
+                "no_savings_claim_when_same_observed_is_zero": True,
+                "observe_off_critical_path": off_critical_path,
+            },
+        }

seenrelay-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+