Currently, the parameters of methods such as insert and aql.execute are typed concretely (with Json and Optional[MutableMapping[str, str]] respectively).

This is overly restrictive because these methods will in fact accept other types, as long as the serialiser in use supports them (and in fact, even the default json.loads serialiser can accept a wider range of types).

My suggestion:

Make ArangoClient, AQL, Database, and Collection generic in their serializer type (with the client's serializer type being passed down to everything created from it), something like this (using Python 3.12's new type parameter syntax):

class Serializer[T](Protocol):

    def __call__(self, value: T) -> Json:
        pass


class ArangoClient[T]:

    def __init__(self, serializer: Serializer[T], *args, **kwargs):
        pass

    def db(self, *args, **kwargs) -> Database[T]:
        pass


class StandardDatabase[T]:

    def collection(self, *args, **kwargs) -> Collection[T]:
        pass

    
class StandardCollection[T]:

    def insert(self, document: T, *args, **kwargs):  # no longer Json
        pass