Clients

A client owns one gRPC connection, the credential sent on every call, and the checks performed when it is opened — a health probe, then a call that proves the credential. With a token, that is list_domains, which also reports the service’s input limits. With an API client’s client_id and client_secret, it is the exchange of those for a token, which the client renews by itself before it expires. The operations themselves live on namespaces hanging off it: client.memory, and client.networks and client.users for a client with client credentials.

Closing a client ends the key of any session still acting for one of your users, so a session left open does not hold a key until it expires.

class Memco(token=None, host=None, *, client_id=None, client_secret=None, token_lifetime=None, tls=None, 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 proves the credential, so a bad one fails here rather than on the first real call. With a token, it is list_domains(), which also 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.

With an API client’s client_id and client_secret instead, the second call exchanges them for a token, and no memory method is called: an issued token carries no content role of its own, so the service would refuse one. The client renews the token by itself, before it expires.

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, and the environment holds no client credentials, 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.

  • client_id (str | None) – An API client’s id, passed with client_secret instead of a token. When neither they nor token is passed, and both MEMCO_CLIENT_ID and MEMCO_CLIENT_SECRET are set, those are used, even if MEMCO_API_TOKEN is set too.

  • client_secret (str | None) – The API client’s secret, passed with client_id. It is sent only to exchange for a token, and never logged.

  • token_lifetime (int | None) – Lifetime in seconds to ask for on each token issued for the client credentials. Omitted, the service’s default applies. The service owns the maximum, and refuses a longer lifetime.

  • tls (bool | None) – Whether to dial over TLS using the system trust store. Set to False only for a plaintext endpoint such as a local server. When omitted, MEMCO_API_TLS decides – true or false – falling back to True. Without TLS, the client logs a WARNING as it is built.

  • timeout (float) – Default deadline in seconds for each call, covering any wait for a credential as well as the request itself. 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, a token is passed beside client credentials, only half of the client pair is given, token_lifetime is given without client credentials or is not positive, the host is unusable, MEMCO_API_TLS is neither true nor false, 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:

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.

networks

The network administration. See NetworkOperations.

users

The user administration. See UserOperations.

property credential_kind: Literal['token', 'api_client']

Which credential the client resolved from its arguments and the environment.

"token" for an API token, "api_client" for an API client’s client_id and client_secret. Only an API client can administer networks and users, or open a session acting as one of your users.

close()[source]

End the keys of impersonated sessions left open, then close the channel.

Blocks until any in-flight call has finished, so a client shared between threads can be closed from one of them safely, and so no key is ended under a call still using it. Safe to call more than once: a close on another thread is waited for, and one cut short – a signal handler raising in it, say – is finished by the next. Never raises of its own accord: a key that cannot be ended is logged at WARNING and expires on its own. After closing, any further call raises MemcoConfigError, and closing a session changes nothing.

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, *, client_id=None, client_secret=None, token_lifetime=None, tls=None, 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, and the environment holds no client credentials, 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.

  • client_id (str | None) – An API client’s id, passed with client_secret instead of a token. When neither they nor token is passed, and both MEMCO_CLIENT_ID and MEMCO_CLIENT_SECRET are set, those are used, even if MEMCO_API_TOKEN is set too.

  • client_secret (str | None) – The API client’s secret, passed with client_id. It is sent only to exchange for a token, and never logged.

  • token_lifetime (int | None) – Lifetime in seconds to ask for on each token issued for the client credentials. Omitted, the service’s default applies. The service owns the maximum, and refuses a longer lifetime.

  • tls (bool | None) – Whether to dial over TLS using the system trust store. When omitted, MEMCO_API_TLS decides – true or false – falling back to True. Without TLS, the client logs a WARNING as it is built.

  • timeout (float) – Default deadline in seconds for each call, covering any wait for a credential as well as the request itself.

  • 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, a token is passed beside client credentials, only half of the client pair is given, token_lifetime is given without client credentials or is not positive, the host is unusable, MEMCO_API_TLS is neither true nor false, or log_level is not a level this SDK accepts.

Variables:

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.

networks

The network administration.

See AsyncNetworkOperations.

users

The user administration. See AsyncUserOperations.

async connect()[source]

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

Probes the health endpoint, then proves the credential. With a token that is list_domains(), which also teaches the client the input limits the service enforces. With client credentials it is the exchange for a token, and no memory method is called, since an issued token carries no content role. Calling this more than once repeats both, except that a token already issued is reused until it is due for renewal.

Returns:

This client.

Raises:
Return type:

AsyncMemco

property credential_kind: Literal['token', 'api_client']

Which credential the client resolved from its arguments and the environment.

"token" for an API token, "api_client" for an API client’s client_id and client_secret. Only an API client can administer networks and users, or open a session acting as one of your users.

async close()[source]

End the keys of impersonated sessions left open, then close the channel.

Waits for any in-flight call to finish first, so no key is ended under a call still using it. Safe to call more than once, and never raises: a key that cannot be ended is logged at WARNING and expires on its own. After closing, any further call raises MemcoConfigError, and closing a session changes nothing. A close that is cancelled still finishes, and closing again waits for it to.

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 descriptor is compiled in, and the result is cached.

Returns:

The provenance recorded when this package was built.

Raises:

MemcoConfigError – If the descriptor does not match the expected shape.

Return type:

Provenance

Example

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