provevi.live

What a viewer of the live feed of a run may see, and the feed of a finished run.

provrun can give a live feed of a run, which a program such as a web app streams to a browser. The policy names the viewer as a destination of kind live, with a level, and TelemetryPolicy.live_level gives that level. shown_at cuts one evidence event to what a viewer at that level may see. replay gives the feed of a run that has ended, from its evidence, so a browser that connects after the end sees the same items.

The feed is a list of items, each a JSON object with a type:

event: one evidence event, as shown_at cuts it;
text: text of the model’s answer, only at bodies. Live, it comes in pieces of any size; replayed, it is the whole answer of each model call. A viewer adds the pieces in order;
done: the end, with the run’s status, completed, failed or cancelled, and its run_id.

Each item has n, its number in the feed, from 1, as provrun’s live feed numbers its items.

Below bodies, an event shows its type, its time, and only the data under keys that hold names or counts, such as model, status and input_tokens. Any other key, such as a note’s text, a purpose or a file’s name, stays out. At names, a value shows if it is a plain name, as plain_attribute says. usage adds the counts and timings. bodies adds everything: all the data, the refs and the payload.

shown_at

source

shown_at(event: EvidenceEvent, level: str | None, record: RunRecord | None = None) -> dict | None

Cut an event to the event item that a viewer at a level sees.

At bodies the item holds the event’s refs, and its payload if record can read it. Raises ProveviError for a level that is not one.

Parameter	Type	Default	Description
`event`	EvidenceEvent	required	The evidence event
`level`	str \| None	required	The viewer’s level, one of `LEVELS`; `None` when the policy has no live viewer
`record`	RunRecord \| None	`None`	The run, to read the event’s payload from at `bodies`
returns	dict \| None		The `event` item, without its `n`; `None` when level is `None`

payload_of

source

payload_of(record: RunRecord, digest: str) -> Any

Read a payload of a run.

It cuts nothing by level, unlike shown_at and replay.

Parameter	Type	Default	Description
`record`	RunRecord	required	The run that holds the payload
`digest`	str	required	The payload’s SHA-256, as an event’s `payload` names it
returns	Any		Its JSON if it is JSON, else its text, with bytes that are not UTF-8 replaced; `None` when record does not hold it

answer_of

source

answer_of(payload: Any) -> str | None

Find the text of a model call’s answer in its payload.

The payload holds a text from LiteLLM, or PydanticAI’s messages, whose text parts are joined. A stream that failed part way keeps the text so far as partial_response.

Parameter	Type	Default	Description
`payload`	Any	required	A model call’s payload, as `payload_of` reads it
returns	str \| None		The answer’s text; `None` when the payload holds none

replay

source

replay(store: EvidenceStore, run_id: str, level: str, *, folder: Path | None = None) -> Iterator[dict]

Give the feed of a run that has ended, from its evidence.

The feed has an event item for each event, a text item at bodies after each model call and after a stream that failed part way, and a done item. Raises ProveviError, before the first item, if the run does not verify, as a run that has not ended does not.

Parameter	Type	Default	Description
`store`	EvidenceStore	required	The store that holds the run
`run_id`	str	required	The run’s ID
`level`	str	required	The viewer’s level, one of `LEVELS`
`folder`	Path \| None	`None`	The run’s evidence folder; the file store finds it by itself when it is left out
returns	Iterator[dict]		The feed’s items, each with its `n` from 1