osyra_ome.client

Private pre-release / network boundary: The currently usable customer surface is offline verification of an existing signed artifact against an out-of-band trust anchor. Memory/network RPC APIs and host snippets on this page describe protocol and interface shape; the public Edge bridge, package publication, and release acceptance remain pending. Do not treat api.osyra.ai:443 examples as a released customer route.

Sync :class:`OmeClient` — gRPC transport + namespaced sub-clients.

Per design doc §3.2 + §4.1: callers interact with the SDK through four namespaced sub-clients hung off a single :class:`OmeClient` instance:

>>> from osyra_ome import OmeClient >>> client = OmeClient(target="api.osyra.ai:443", token="ey...") >>> claim_id = client.memory.write_claim(claim) >>> ok = client.verify.receipt(signed.encoded_cbor, signed.sig, trusted_pub) >>> client.close()

The four namespaces (load-bearing API surface; frozen per ADR-044 stability commitment):

• ``client.verify`` — local-only verification. ``verify.receipt`` is WIRED (offline Ed25519 over the Form-B preimage); verify.bundle_manifest / verify.proof / verify.witness raise NotImplementedError (v0.2).
• ``client.memory`` — wire RPCs. WIRED: ``write_claim`` / write_claim_signed (SignAndInsert), get_claim (ListClaims), get_claim_body (GetClaimBody), tombstone (Tombstone, GDPR Art-17 crypto-erasure). batch_write / export_bundle / import_bundle raise NotImplementedError (v0.2 — the BatchInsert / ExportBundle / ImportBundle RPCs are not called yet).
• ``client.proof`` — JMT prove/verify (v0.2; stubs raise NotImplementedError)
• ``client.witness`` — completeness witness build/verify (v0.2; stubs)

Cross-language parity (per ADR-045): the TypeScript sibling at ``@osyra/ome`` exposes structurally identical sub-clients with mirror method signatures (Python snake_case ↔ TS camelCase).

Lifecycle:

• Construction opens an idle gRPC channel; first call dials.
• ``close()`` performs graceful shutdown (5000 ms default deadline); after close, all sub-client methods raise RuntimeError("client closed") (distinct from :class:OmeTransportError — that's a network failure on a live client).
• Supports context-manager protocol: ``with OmeClient(...) as client:``.

Classes

class OmeClient

Sync gRPC client for the Osyra Memory Engine (OME) service.

Construction:

client = OmeClient(
    target="api.osyra.ai:443",
    token="ey...",                # bearer JWT (Edge-validated)
    workspace_id="ws-...",        # binds Postgres GUC for tenancy
    timeout_seconds=30.0,
    insecure=False,               # set True ONLY for local dev
)

Attributes: verify, memory, proof, witness — namespaced sub-clients per design doc §3.2 (frozen API surface from v0.1.0; ADR-044).

Thread-safety: a single :class:`OmeClient` instance is safe to share across threads. The underlying gRPC channel is thread-safe; the only state-mutating operation is ``close()`` which is itself guarded by an internal lock.

Security:

• TLS by default — insecure=True requires explicit opt-in.
• Bearer token attached as authorization metadata on every call (per Edge Gateway contract). NEVER logged or returned in exceptions (we redact the token-prefix in repr).
• Hostname verification is non-optional (uses grpc's default SSL credentials with system root CAs).

Methods

__init__

def __init__(self, target: str, *, token: str | None = None, workspace_id: str | None = None, workspace_tier: str | None = None, timeout_seconds: float = DEFAULT_DEADLINE_SECONDS, insecure: bool = False, channel_options: list[tuple[str, object]] | None = None) -> None

close

def close(self, *, grace_seconds: float = DEFAULT_CLOSE_GRACE_SECONDS) -> None

Gracefully shutdown the gRPC channel.

Idempotent — calling close() a second time is a no-op. After close, all sub-client methods raise ``RuntimeError("client closed")``.