mstar.engine.resources.kv.keys

mstar.engine.resources.kv.keys#

Page keys for cross-request prefix reuse.

A key commits to the whole prefix below it: the previous key, this page’s token ids, and for each input on the page that is not a token, its digest and where it sits. One match confirms every page under it, and a new root leaves every old key unreachable.

The encoding is canonical because one process builds these keys and another matches them: fixed-width little-endian ints, and a length prefix on every variable-length field so that no two different spans encode alike.

Functions

chain(pages_of_tokens[, items_by_page, root])

Key every page of one stream, folding each key into the next.

end_key(prev, tokens, items, end)

Key a page's first end slots, where an item on it ends.

fingerprint(*fields)

SHA-256 over fields, in the encoding page keys use.

page_items(spans, page_size)

Each page's items, given every span's length and digest (None for ids).

page_key(prev, tokens[, items])

Hash a page's parent key, its token ids and its items into the page's key.

Classes

PageItem(start, offset, length, digest)

An input that is not a token, as it sits on one page.
class mstar.engine.resources.kv.keys.PageItem(start, offset, length, digest)[source]#

Bases: NamedTuple

An input that is not a token, as it sits on one page.

start is its first slot on this page, offset counts its slots on earlier pages, and length counts all of its slots.

Parameters:
digest: bytes#

Alias for field number 3

length: int#

Alias for field number 2

offset: int#

Alias for field number 1

start: int#

Alias for field number 0

mstar.engine.resources.kv.keys.chain(pages_of_tokens, items_by_page=None, root=b'')[source]#

Key every page of one stream, folding each key into the next.

Parameters:
Return type:

list[bytes]

mstar.engine.resources.kv.keys.end_key(prev, tokens, items, end)[source]#

Key a page’s first end slots, where an item on it ends.

Parameters:
Return type:

bytes

mstar.engine.resources.kv.keys.fingerprint(*fields)[source]#

SHA-256 over fields, in the encoding page keys use.

Used for process constants, so changing one makes every older key unreachable.

Parameters:

fields (object)

Return type:

bytes

mstar.engine.resources.kv.keys.page_items(spans, page_size)[source]#

Each page’s items, given every span’s length and digest (None for ids).

The preprocess worker keys a prompt’s pages with this, and the engine keys the page that generation fills after the prompt. If the two worked out the items differently, that page’s key would never match.

Parameters:
Return type:

dict[int, list[PageItem]]

mstar.engine.resources.kv.keys.page_key(prev, tokens, items=())[source]#

Hash a page’s parent key, its token ids and its items into the page’s key.

The ids fill the slots the items leave, in order, so an item’s start is what tells [t1 t2 IMG] from [t1 IMG t2]. Every page an item touches carries the item’s whole length and digest, because attention inside an item is not causal and a page’s KV depends on the item’s later slots too.

Parameters:
Return type:

bytes