Clients¶

A client owns one gRPC connection, the credential sent on every call, and the checks performed when it is opened — a health probe, and the list_domains call that proves the credential and reports the service’s input limits. The operations themselves live on namespaces hanging off it.

class Memco(token=None, host=None, *, tls=True, timeout=30.0, env=None, log_level=None)[source]¶

Bases: object

Synchronous client for Memco Shared Memory.

Opens one gRPC channel and holds it until closed, so a single client should be created once and reused. It is safe to share between threads.

Construction makes two calls. The first is the standard gRPC health endpoint, which is unauthenticated: it proves the host, port and TLS settings are sound. The second is list_domains(), which carries the credential — so a bad token fails here rather than on the first real call — and reports the input limits the service enforces. The client keeps those, and from then on refuses an oversized field locally instead of spending a round trip on a call the service would refuse.

Connecting and closing are reported to the memcoai logger at INFO, and a rejected credential at ERROR before it is raised, since a client is often built somewhere the traceback does not reach. The credential itself is never logged, at any level.

Parameters:

token (str | None) – Credential to authenticate with, either a static Memco API key or a session token. When omitted, MEMCO_API_TOKEN is used, falling back to the deprecated MEMCO_API_KEY with a warning.
host (str | None) – Service endpoint, optionally including a port such as localhost:50051. When omitted, MEMCO_API_HOST is used, falling back to grpc.memco.ai. Port 443 is assumed when the host carries none.
tls (bool) – Whether to dial over TLS using the system trust store. Set to False only for a plaintext endpoint such as a local server.
timeout (float) – Default per-call deadline in seconds. Individual methods can override it.
env (Mapping[str, str] | None) – Environment mapping to read defaults from. Defaults to os.environ; supplying one is mainly useful in tests.
log_level (str | int | None) – The SDK’s log level, as a name — "debug", "info", "warning", "error", "critical", or "none" to turn it off — or a logging constant. Defaults to "info" and overrides MEMCO_LOG. Any level but "none" attaches the SDK’s own stderr handler and stops the memcoai logger propagating, so records bypass the handlers the application configured; it is process-wide, since a logger is. An application with its own logging should pass "none" and set the level on the memcoai logger instead.

Raises:

MemcoConfigError – If no credential is available, the host is unusable, or log_level is not a level this SDK accepts.
MemcoUnavailableError – If the service cannot be reached.
MemcoUnhealthyError – If the service reports that it is not serving.
MemcoAuthenticationError – If the credential is rejected.
MemcoSunsetError – If what this client uses is past its sunset date.

Variables:

memory – The memory operations, as MemoryOperations.

Example

>>> with Memco() as client:
...     session = client.memory.start_session("coding")
...     result = session.search("how does gRPC health checking work")
...     for memory in result.memories:
...         print(memory.idx, len(memory.insights))

memory¶: The memory operations. See MemoryOperations.

close()[source]¶

Close the underlying channel.

Blocks until any in-flight call has finished, so a client shared between threads can be closed from one of them safely. Safe to call more than once. After closing, any further call raises MemcoConfigError.

Return type:: None

provenance()[source]¶

Report which version of the contract this SDK was generated from.

Returns:: The provenance recorded when this package was built.
Return type:: Provenance

Example

>>> client.provenance().server_commit  # the commit this wheel was built from
'762721a87ab0...'

class AsyncMemco(token=None, host=None, *, tls=True, timeout=30.0, env=None, log_level=None)[source]¶

Bases: object

Asyncio client for Memco Shared Memory.

Mirrors Memco method for method; only the awaiting differs. Because opening a connection requires I/O, the checks the synchronous client runs in __init__ cannot run here: use it as an async context manager, or call connect() yourself.

Parameters:

token (str | None) – Credential to authenticate with, either a static Memco API key or a session token. When omitted, MEMCO_API_TOKEN is used, falling back to the deprecated MEMCO_API_KEY with a warning.
host (str | None) – Service endpoint, optionally including a port. When omitted, MEMCO_API_HOST is used, falling back to grpc.memco.ai.
tls (bool) – Whether to dial over TLS using the system trust store.
timeout (float) – Default per-call deadline in seconds.
env (Mapping[str, str] | None) – Environment mapping to read defaults from. Defaults to os.environ.
log_level (str | int | None) – The SDK’s log level, as a name — "debug", "info", "warning", "error", "critical", or "none" to turn it off — or a logging constant. Defaults to "info" and overrides MEMCO_LOG. Any level but "none" attaches the SDK’s own stderr handler and stops the memcoai logger propagating, so records bypass the handlers the application configured; it is process-wide, since a logger is. An application with its own logging should pass "none" and set the level on the memcoai logger instead.

Raises:

MemcoConfigError – If no credential is available, the host is unusable, or log_level is not a level this SDK accepts.

Variables:

memory – The memory operations, as AsyncMemoryOperations.

Example

>>> async with AsyncMemco() as client:
...     session = await client.memory.start_session("coding")
...     result = await session.search("how does health checking work")

memory¶: The memory operations. See AsyncMemoryOperations.

async connect()[source]¶

Verify the connection, running the checks the constructor could not.

Probes the health endpoint, then calls list_domains(), which proves the credential and teaches the client the input limits the service enforces. Calling this more than once simply repeats both.

Returns:

This client.

Raises:

MemcoUnavailableError – If the service cannot be reached.
MemcoUnhealthyError – If the service reports that it is not serving.
MemcoAuthenticationError – If the credential is rejected.
MemcoSunsetError – If what this client uses is past its sunset date.

Return type:

AsyncMemco

async close()[source]¶

Close the underlying channel.

Safe to call more than once. After closing, any further call raises MemcoConfigError.

Return type:: None

provenance()[source]¶

Report which version of the contract this SDK was generated from.

Returns:: The provenance recorded when this package was built.
Return type:: Provenance

Example

>>> client.provenance().server_commit  # the commit this wheel was built from
'762721a87ab0...'

Provenance¶

provenance()[source]¶

Read the provenance of the installed generated client.

The result is cached, so repeated calls do not re-read the file.

Returns:: The provenance recorded when this package was built.
Raises:: MemcoConfigError – If the descriptor is missing from the installed package or does not match the expected shape.
Return type:: Provenance

Example

>>> provenance().server_commit  # the commit this wheel was built from
'762721a87ab0...'

Quickstart