yera.ui.sessions_store.base
Define persisted session records and their storage contract.
A session record holds navigation and lifecycle metadata. Its ordered event log contains the output and persistence-safe input needed to reconstruct a transcript without executing the app again.
Symbols
BaseSessionStore
ABCSQLiteSessionStoreDefine storage for session metadata and ordered event histories.
Implementations must preserve event order and support atomically appending an event with an optional title or lifecycle update. Stores are context managers: callers open them before use and close their underlying resources when the server exits.
Methods
BaseSessionStore.create
create(
app_id: str,
) → SessionRecordCreates a new session in the store.
Parameters
The ID of the application associated with the session.
Returns
The created SessionRecord.
BaseSessionStore.has
has(
session_id: str,
) → boolChecks if a session exists in the store.
Parameters
The unique identifier of the session.
Returns
True if the session exists, False otherwise.
BaseSessionStore.has_events
has_events(
session_id: str,
) → boolReport whether a session has any persisted runtime history.
The server uses this distinction to launch a genuinely new session but replay an existing transcript without executing its app again.
Parameters
Session whose event history is inspected.
Returns
True when at least one event is stored.
BaseSessionStore.get
get(
session_id: str,
) → SessionRecordRetrieves a session record by its ID.
Parameters
The unique identifier of the session.
Returns
The requested SessionRecord.
BaseSessionStore.list
list() → list[SessionRecord]Lists all stored session records.
Returns
A list of all SessionRecords.
BaseSessionStore.update
update(
session_id: str,
title: str | None = None,
status: SessionStatus | None = None,
) → NoneUpdates the metadata of an existing session.
Parameters
The unique identifier of the session.
An optional new title for the session.
An optional new lifecycle status for the session.
BaseSessionStore.append_event
append_event(
session_id: str,
event: OutputEvent | InputEvent,
update: SessionRecordUpdate | None = None,
) → NoneAppend one event and optionally update session metadata atomically.
Implementations must preserve append order and update updated_at in
the same transaction as the event. This prevents transcript history and
lifecycle state from diverging when recording an input request, exit,
or title change.
Parameters
Session receiving the event.
Typed runtime input or output event to persist.
Optional title or lifecycle change committed with the event.
BaseSessionStore.read_records
read_records(
session_id: str,
) → Iterator[StoredEventRecord]Read timestamped event records in append order.
The record timestamp describes when the store committed the event. It is distinct from any producer timestamp carried by the event itself.
Parameters
Session whose timestamped history is read.
Returns
An iterator of stored records in append order.
BaseSessionStore.read_events
read_events(
session_id: str,
) → Iterator[OutputEvent | InputEvent]Read a session's typed event history in append order.
This compatibility API projects events from :meth:read_records, so
timestamp-aware and event-only consumers share the same
deserialization behavior.
Parameters
Session whose history is read.
Returns
An iterator of deserialized input and output events in append order.
BaseSessionStore.__enter__
__enter__() → SelfOpen the store for session operations.
Returns
The open session store.
BaseSessionStore.__exit__
__exit__(
exc_type: type[BaseException] | None,
exc_val: BaseException | None,
exc_tb: TracebackType | None,
) → NoneClose resources owned by the store.
Parameters
Type of exception leaving the context, if any.
Exception instance leaving the context, if any.
Traceback associated with the exception, if any.
SessionRecord
BaseModelDescribe one persisted Yera app session.
Fields
Stable session identifier.
App originally associated with the session.
User-facing session title.
UTC time at which the session was created.
UTC time of the latest metadata or event change.
Current persisted lifecycle state.
Methods
SessionRecord.new
new(
app_id: str,
title: str | None = None,
) → SessionRecordCreate initial metadata for a new app session.
The record receives a UUID, matching creation and update timestamps,
and the created lifecycle state. When no title is supplied, a short
portion of the UUID provides a unique placeholder title.
Parameters
Stable identifier of the session's app.
Optional initial user-facing title.
Returns
A new, unpersisted session record.
SessionRecordUpdate
BaseModelDescribe metadata to persist atomically with an event.
Fields
Replacement session title, or None to retain the current one.
Replacement lifecycle state, or None to retain the current
one.
StoredEventRecord
BaseModelPair a persisted runtime event with its authoritative storage time.
Fields
Typed runtime event reconstructed from storage.
UTC time at which the event was committed to the store.