Skip to content

aaa.data

Items and codecs

Item

Bases: BaseModel, Generic[T]

Envelope around user data. Algorithms see Items; users own the payload type T.

Provenance

Bases: BaseModel

CodecRegistry 

CodecRegistry()

wrap 

wrap(kind: str, payload: Any, **kw: Any) -> Item[Any]

Create an Item and stamp its content hash via the registered codec.

Codec

Bases: Protocol[T]

Teaches AAA how to render, persist and describe a user type. One per kind.

TypeAdapterCodec 

TypeAdapterCodec(tp: Any)

Bases: Generic[T]

Covers Pydantic models, dataclasses, TypedDicts, dict/list/str — anything Pydantic can validate. This is the default path for 'arbitrary data'.

FunctionCodec 

FunctionCodec(
    *,
    to_text,
    to_json,
    from_json,
    schema: dict[str, Any] | None = None,
)

Bases: Generic[T]

Escape hatch: wrap your own render/serialize functions (DataFrame rows, images, ...).

Capabilities

Embedder

Bases: Protocol

Scorer

Bases: Protocol

Utility / heuristic / quality score for an item (higher is better).

Keyer

Bases: Protocol

Stable identity for dedup and search closed-sets.

preflight 

preflight(
    required: set[str], available: dict[str, object]
) -> None

Fail fast at startup, listing everything an algorithm needs but wasn't given.

Blob storage

BlobStore

Bases: Protocol

Content-addressed (sha256) storage for payloads too large to live in an event.

InMemoryBlobStore 

InMemoryBlobStore()

FileBlobStore 

FileBlobStore(root: str | Path)

Local-disk store, sharded by hash prefix, atomic writes, verified reads.

Retrieval

Index

Bases: Protocol

InMemoryIndex 

InMemoryIndex(
    embedder: Embedder | None = None,
    k1: float = 1.5,
    b: float = 0.75,
)

BM25 keyword search; if an Embedder is supplied, fused with cosine similarity via reciprocal-rank fusion (hybrid). Brute force: fine to ~1e5 docs; swap in pgvector/Qdrant behind the same protocol for more.

Doc

Bases: BaseModel

Hit

Bases: BaseModel