calute.session.store

calute.session.store#

Session storage backends and high-level session manager.

Provides an abstract SessionStore protocol with two concrete implementations (in-memory and file-based) and a SessionManager for session lifecycle management.

class calute.session.store.FileSessionStore(base_dir: str | pathlib.Path)[source]#

Bases: SessionStore

File-backed session store using JSON files.

Each session is persisted as an individual JSON file on disk. The directory layout is determined by whether the session has a workspace ID:

Directory layout:

{base_dir}/{session_id}.json                  -- workspace_id is None
{base_dir}/{workspace_id}/{session_id}.json   -- workspace_id is set

Thread-safe via an internal threading.Lock.

_base_dir#: Root directory for session JSON files.

_lock#: Threading lock for safe concurrent access.

Example

>>> import tempfile
>>> store = FileSessionStore(tempfile.mkdtemp())
>>> store.list_sessions()
[]

delete_session(session_id: str) → bool[source]#

Delete a session JSON file from disk.

Searches the directory tree for the matching file and removes it.

Parameters: session_id – The unique session identifier to delete.
Returns: True if the file was found and deleted, False if no matching file existed.

list_sessions(workspace_id: str | None = None) → list[str][source]#

List session IDs by scanning JSON files on disk.

When workspace_id is provided, only the corresponding workspace subdirectory is scanned. Otherwise, both the flat base directory and all workspace subdirectories are scanned.

Parameters: workspace_id – When provided, restricts the scan to the {base_dir}/{workspace_id}/ subdirectory only. When None, all JSON files across all directories are included.
Returns: A list of session ID strings (JSON file stems).

load_session(session_id: str) → calute.session.models.SessionRecord | None[source]#

Load a session record from a JSON file on disk.

Searches the directory tree for a matching JSON file, reads it, and deserializes it into a SessionRecord.

Parameters: session_id – The unique session identifier to load.
Returns: The deserialized SessionRecord, or None if no matching file is found.

save_session(session: SessionRecord) → None[source]#

Save a session record as a JSON file on disk.

Creates the parent directory (including workspace subdirectories) if it does not already exist. Existing files are overwritten.

Parameters: session – The session record to persist.

class calute.session.store.InMemorySessionStore[source]#

Bases: SessionStore

Thread-safe in-memory session store backed by a dictionary.

Sessions are kept in a plain dict protected by a threading.Lock. Data does not survive process restarts; use FileSessionStore for persistent storage.

_sessions#: Internal dictionary mapping session IDs to records.

_lock#: Threading lock for safe concurrent access.

Example

>>> store = InMemorySessionStore()
>>> store.list_sessions()
[]

delete_session(session_id: str) → bool[source]#

Delete a session record from memory.

Parameters: session_id – The unique session identifier to delete.
Returns: True if a session was found and deleted, False if no session with the given ID existed.

list_sessions(workspace_id: str | None = None) → list[str][source]#

List session IDs stored in memory, optionally filtered by workspace.

Parameters: workspace_id – When provided, only session IDs belonging to this workspace are returned. When None, all session IDs are returned.
Returns: A list of session ID strings.

load_session(session_id: str) → calute.session.models.SessionRecord | None[source]#

Load a session record from memory by its identifier.

Parameters: session_id – The unique session identifier to look up.
Returns: The matching SessionRecord, or None if no session with the given ID exists.

save_session(session: SessionRecord) → None[source]#

Save or overwrite a session record in memory.

If a session with the same session_id already exists, it is silently replaced.

Parameters: session – The session record to store.

class calute.session.store.SessionManager(store: SessionStore)[source]#

Bases: object

High-level API for session lifecycle management.

Wraps a SessionStore to provide convenient methods for creating, recording turns, recording agent transitions, and ending sessions. Each mutation automatically updates the updated_at timestamp and persists the session back to the store.

_store#: The underlying session store backend used for persistence.

Example

>>> store = InMemorySessionStore()
>>> manager = SessionManager(store)
>>> session = manager.start_session(agent_id="default")
>>> session.agent_id
'default'

end_session(session_id: str) → None[source]#

Mark a session as ended by updating its timestamp.

Parameters: session_id – The session to end.
Raises: ValueError – If the session does not exist.

get_session(session_id: str) → calute.session.models.SessionRecord | None[source]#

Retrieve a session record.

Parameters: session_id – The session to retrieve.
Returns: The session record, or None if not found.

list_sessions(workspace_id: str | None = None) → list[str][source]#

List session IDs.

Parameters: workspace_id – If provided, filter by workspace.
Returns: List of session ID strings.

record_agent_transition(session_id: str, transition: AgentTransitionRecord) → None[source]#

Record an agent transition in a session.

Parameters

session_id – The session to record the transition in.
transition – The transition record.

Raises

ValueError – If the session does not exist.

record_turn(session_id: str, turn: TurnRecord) → None[source]#

Append a turn record to an existing session.

Parameters

session_id – The session to append to.
turn – The turn record to add.

Raises

ValueError – If the session does not exist.

start_session(workspace_id: str | None = None, agent_id: str | None = None, *, session_id: str | None = None, metadata: dict[str, Any] | None = None) → SessionRecord[source]#

Create and persist a new session.

Parameters

workspace_id – Workspace to associate the session with.
agent_id – Initial agent for the session.
session_id – Explicit session ID; auto-generated if omitted.
metadata – Optional metadata dict.

Returns

The newly created SessionRecord.

property store: SessionStore#: The underlying session store.

class calute.session.store.SessionStore[source]#

Bases: ABC

Abstract base class for session storage backends.

All concrete session stores must implement the four CRUD methods defined here: save_session(), load_session(), list_sessions(), and delete_session(). Implementations are expected to be thread-safe.

abstract delete_session(session_id: str) → bool[source]#

Delete a session record.

Parameters: session_id – The unique session identifier.
Returns: True if a session was deleted, False if not found.

abstract list_sessions(workspace_id: str | None = None) → list[str][source]#

List session IDs, optionally filtered by workspace.

Parameters: workspace_id – If provided, only return sessions in this workspace.
Returns: List of session ID strings.

abstract load_session(session_id: str) → calute.session.models.SessionRecord | None[source]#

Load a session record by ID.

Parameters: session_id – The unique session identifier.
Returns: The session record, or None if not found.

abstract save_session(session: SessionRecord) → None[source]#

Persist a session record.

Parameters: session – The session record to save.

calute.session.store

Contents

calute.session.store#