Ada SDK for Python

AdaClient represents one authenticated namespace. Its cached principal facades share one gRPC channel and one lazy, persistent namespace stream for events, signals, and jobs.

Installation

python -m pip install ada-grpc-sdk

Python 3.10 or newer is required. Construct the namespace client only in trusted backend code; api_key or api_key_provider authenticates the whole namespace.

Backend client

import os

from ada_sdk import AdaClient, StreamConfig, SubscriptionOptions

with AdaClient(
    "memory.example.com:443",
    api_key=os.environ["ADA_API_KEY"],
    streams=StreamConfig(
        events=SubscriptionOptions(
            after_event_id=saved_event_cursor,
            replay_limit=100,
        ),
        signals=SubscriptionOptions(after_event_id=saved_signal_cursor),
        jobs=SubscriptionOptions(after_event_id=saved_job_cursor),
    ),
) as ada:
    alice = ada.principal("alice")
    bob = ada.principal("bob")

    stop_alice = alice.events.on(
        "memory.ingest.finished",
        lambda event: print(event.document_id),
    )
    stop_bob = bob.signals.on(
        "routine.broken",
        lambda signal: print(signal),
    )
    stop_job = alice.jobs.on(
        "job.finished",
        lambda event: print(event),
    )

    stop_alice()
    stop_alice()
    stop_bob()
    stop_job()

Every event-name overload selects an exact generated protobuf payload type and returns an idempotent synchronous unsubscribe callable. Strict mypy fixtures reject unknown event names, mismatched payloads, open(), root data-plane calls, and principal creation on a browser client.

All ingest, recall, document, job, data, and summary operations live on the principal facade:

result = alice.ingest(ingest_pb2.IngestRequest(document=document))
status = alice.documents.get_status(
    ingest_pb2.GetDocumentStatusRequest(document_id=document_id),
)

The facade overwrites every request principal. Public-event and signal catalogs remain on the root through get_public_event_catalog() and get_signal_catalog().

Replay cursors, reconnect policy, lifecycle handlers, and shutdown live on the root:

stop_cursor = ada.lifecycle.on(
    "stream.cursor",
    lambda info: save_cursor(
        info.stream,
        info.event_id,
        info.principal_id,
    ),
)
stop_terminal = ada.lifecycle.on(
    "stream.terminal",
    lambda info: report_failure(info.stream, info.error),
)

close() and the context manager perform idempotent graceful shutdown and prevent later registrations.

AdaBrowserClient(endpoint, session_token=...) is a separate principal-bound client. It accepts no namespace API key and has no principal() method. Use it only with a short-lived browser session minted by a trusted backend.

Never embed a namespace API key in browser or otherwise untrusted client code. The TypeScript package is the supported browser/gRPC-Web implementation.