Protocols

Protocols define abstract interfaces (ports) used by applications and adapters. Providers implement these protocols for specific backends.

Supported Protocols

KeyValueStoreProtocol

The KeyValueStoreProtocol defines asynchronous operations for storing and retrieving values by key. It is generic over the value type V, which is determined by the concrete store implementation. Keys are ordinary str values, i.e. normal Unicode strings.

Its core operations are:

  • get(key: str, default: V | None = None) -> V | None: Retrieve a value by key. Returns default (or None) when the key is not present.
  • set(key: str, value: V) -> None: Store a value for a key.
  • delete(key: str) -> None: Remove a key/value pair if present.
  • exists(key: str) -> bool: Check whether a key exists.

The protocol is implemented by multiple provider families:

Across these families, the same value-type variants are used:

  • *BytesKeyValueStore: Stores raw bytes values.
  • *StrKeyValueStore: Stores str values.
  • *JsonKeyValueStore: Stores JSON objects.
  • *DtoKeyValueStore: Stores Pydantic model instances (DTOs).

This naming convention is backend-agnostic, so switching provider families does not require changing your value model at the protocol level.

Choose the provider family based on the operational properties you need: in-memory for tests, Redis for fast access to small hot values, MongoDB for durable structured values, S3 for large or opaque payloads, and Vault for secrets or other sensitive values.

Choose the value-type variant based on how much structure and validation you want: Bytes for binary or already-serialized payloads, Str for plain text, Json for flexible schema-light objects, and Dto for schema-validated typed models.

(one section for each protocol)

TBD

Adding Protocols

TBD