panelini.panels.ai.history.document

Document-shaped chat history: schema, converters, shared store logic.

The documents defined by chat_history_schema.json (an OO-LD document: JSON-Schema plus a JSON-LD @context) are both the storage model and the import/export interchange format. :class:DocumentHistoryStore implements every :class:~.store.ChatHistoryStore semantic once, on top of a minimal per-document CRUD that each backend provides.

Module Contents

Classes

DocumentHistoryStore	Implements every store semantic over a minimal document CRUD.
InMemoryHistoryStore	Thread-safe in-memory backend for tests, stubs, and Pyodide builds.

Functions

load_schema	Return the bundled chat history document schema.
document_context	Return the schema’s JSON-LD @context block.
validate_conversation_document	Validate a conversation document against the v2 schema.
validate_folder_document	Validate a folder document against the v2 schema.
message_to_dict	Return the embedded-message dict for one message record.
conversation_to_document	Compose the v2 conversation document from records.
conversation_from_document	Extract the conversation record (without messages) from a document.
messages_from_document	Extract the embedded message records from a conversation document.
folder_to_document	Compose the folder document from a record.
folder_from_document	Extract the folder record from a document.

Data

SCHEMA_VERSION
KIND_CONVERSATION
KIND_FOLDER

API

panelini.panels.ai.history.document.SCHEMA_VERSION

2

panelini.panels.ai.history.document.KIND_CONVERSATION

‘conversation’

panelini.panels.ai.history.document.KIND_FOLDER

‘folder’

panelini.panels.ai.history.document.load_schema() → dict[str, Any]

Return the bundled chat history document schema.

panelini.panels.ai.history.document.document_context() → dict[str, Any]

Return the schema’s JSON-LD @context block.

panelini.panels.ai.history.document.validate_conversation_document(document: dict[str, Any]) → None

Validate a conversation document against the v2 schema.

Raises: ValueError: When the document does not match the schema.

panelini.panels.ai.history.document.validate_folder_document(document: dict[str, Any]) → None

Validate a folder document against the v2 schema.

Raises: ValueError: When the document does not match the schema.

panelini.panels.ai.history.document.message_to_dict(record: panelini.panels.ai.history.store.MessageRecord) → dict[str, Any]

Return the embedded-message dict for one message record.

panelini.panels.ai.history.document.conversation_to_document(record: panelini.panels.ai.history.store.ConversationRecord, messages: collections.abc.Sequence[panelini.panels.ai.history.store.MessageRecord] = ()) → dict[str, Any]

Compose the v2 conversation document from records.

panelini.panels.ai.history.document.conversation_from_document(document: dict[str, Any]) → panelini.panels.ai.history.store.ConversationRecord

Extract the conversation record (without messages) from a document.

panelini.panels.ai.history.document.messages_from_document(document: dict[str, Any]) → list[panelini.panels.ai.history.store.MessageRecord]

Extract the embedded message records from a conversation document.

panelini.panels.ai.history.document.folder_to_document(record: panelini.panels.ai.history.store.FolderRecord) → dict[str, Any]

Compose the folder document from a record.

panelini.panels.ai.history.document.folder_from_document(document: dict[str, Any]) → panelini.panels.ai.history.store.FolderRecord

Extract the folder record from a document.

class panelini.panels.ai.history.document.DocumentHistoryStore

Bases: panelini.panels.ai.history.store.ChatHistoryStore

Implements every store semantic over a minimal document CRUD.

Backends provide only :meth:_get, :meth:_put, :meth:_delete,

Meth:

_iter (all scoped by user_id) and :meth:_transaction, a context manager making the enclosed read-modify-write atomic.

list_conversations(user_id: str, include_archived: bool = False) → list[panelini.panels.ai.history.store.ConversationRecord]

search_conversations(user_id: str, query: str, include_archived: bool = False) → list[panelini.panels.ai.history.store.ConversationRecord]

get_conversation(user_id: str, conversation_id: str) → panelini.panels.ai.history.store.ConversationRecord | None

create_conversation(user_id: str, title: str = DEFAULT_TITLE, folder_ids: collections.abc.Sequence[str] = ()) → panelini.panels.ai.history.store.ConversationRecord

rename_conversation(user_id: str, conversation_id: str, title: str) → None

delete_conversation(user_id: str, conversation_id: str) → None

move_conversation(user_id: str, conversation_id: str, folder_id: str | None) → None

link_conversation(user_id: str, conversation_id: str, folder_id: str) → None

unlink_conversation(user_id: str, conversation_id: str, folder_id: str) → None

set_pinned(user_id: str, conversation_id: str, pinned: bool) → None

set_archived(user_id: str, conversation_id: str, archived: bool) → None

append_message(user_id: str, conversation_id: str, role: str, content: str, extra: dict[str, Any] | None = None, parent_message_id: str | None = None) → panelini.panels.ai.history.store.MessageRecord

load_messages(user_id: str, conversation_id: str) → list[panelini.panels.ai.history.store.MessageRecord]

restore_conversation(user_id: str, document: dict[str, Any]) → None

Re-put a conversation document as-is (lossless delete-undo).

The restoring user becomes the owner regardless of the document’s user_id.

list_folders(user_id: str) → list[panelini.panels.ai.history.store.FolderRecord]

create_folder(user_id: str, name: str, parent_id: str | None = None) → panelini.panels.ai.history.store.FolderRecord

rename_folder(user_id: str, folder_id: str, name: str) → None

move_folder(user_id: str, folder_id: str, parent_id: str | None) → None

delete_folder(user_id: str, folder_id: str) → None

class panelini.panels.ai.history.document.InMemoryHistoryStore

Bases: panelini.panels.ai.history.document.DocumentHistoryStore

Thread-safe in-memory backend for tests, stubs, and Pyodide builds.

Documents are copied on the way in and out, mirroring the serialization boundary a browser object store would impose.

Initialization

close() → None

Nothing to release for the in-memory backend.