Session Manager

Conversation session management with SQLite storage.

folderbot.session_manager.validate_topic_name(name)

Normalize and validate a topic name.

Converts to lowercase, replaces spaces/hyphens with underscores, strips non-allowed characters, and validates the result.

Raises ValueError if the result is empty after normalization.

Return type:

str

Parameters:

name (str)

class folderbot.session_manager.Message

Bases: TypedDict

role: str

content: str

timestamp: str

topic: str

class folderbot.session_manager.TopicReassignment

Bases: object

A single topic reassignment instruction.

message_index: int

new_topic: str

__init__(message_index, new_topic)

Parameters:

• message_index (int)

• new_topic (str)

Return type:

None

class folderbot.session_manager.UploadRecord

Bases: object

Metadata for an uploaded file.

id: int

user_id: int

original_filename: str

hash_filename: str

extension: str

file_size: int

mime_type: str

created_at: str

__init__(id, user_id, original_filename, hash_filename, extension, file_size, mime_type, created_at)

Parameters:

• id (int)

• user_id (int)

• original_filename (str)

• hash_filename (str)

• extension (str)

• file_size (int)

• mime_type (str)

• created_at (str)

Return type:

None

class folderbot.session_manager.TokenUsageRecord

Bases: object

A single token usage record.

id: int

user_id: int

input_tokens: int

output_tokens: int

model: str

topic: str

created_at: str

__init__(id, user_id, input_tokens, output_tokens, model, topic, created_at)

Parameters:

• id (int)

• user_id (int)

• input_tokens (int)

• output_tokens (int)

• model (str)

• topic (str)

• created_at (str)

Return type:

None

class folderbot.session_manager.SessionManager

Bases: object

Manages conversation history in SQLite.

__init__(db_path)

Parameters:

db_path (Path)

get_history(user_id, topic=None)

Get conversation history for a user, optionally filtered by topic.

Return type:

list[Message]

Parameters:

• user_id (int)

• topic (str | None)

add_message(user_id, role, content, topic='general')

Add a message to the conversation history.

Return type:

None

Parameters:

• user_id (int)

• role (str)

• content (str)

• topic (str)

get_topics(user_id)

Get unique topics with message counts for a user.

Return type:

list[dict]

Parameters:

user_id (int)

update_message_topics(user_id, reassignments)

Bulk-update topic labels on messages by index.

Returns the number of messages actually updated. Raises ValueError if any topic name is invalid or index is out of bounds.

Return type:

int

Parameters:

• user_id (int)

• reassignments (list[TopicReassignment])

clear_session(user_id)

Clear conversation history for a user.

Return type:

None

Parameters:

user_id (int)

get_session_info(user_id)

Get session metadata.

Return type:

dict

Parameters:

user_id (int)

get_last_notified_version(user_id)

Get the last version the user was notified about.

Return type:

str | None

Parameters:

user_id (int)

set_last_notified_version(user_id, version)

Set the last version the user was notified about.

Return type:

None

Parameters:

• user_id (int)

• version (str)

get_file_notifications_enabled(user_id)

Check if file notifications are enabled for a user.

Return type:

bool

Parameters:

user_id (int)

set_file_notifications_enabled(user_id, enabled)

Enable or disable file notifications for a user.

Return type:

None

Parameters:

• user_id (int)

• enabled (bool)

get_users_with_file_notifications()

Get all user IDs that have file notifications enabled.

Return type:

list[int]

save_upload(user_id, original_filename, hash_filename, extension, file_size, mime_type='application/pdf')

Save upload metadata to the database.

Return type:

UploadRecord

Parameters:

• user_id (int)

• original_filename (str)

• hash_filename (str)

• extension (str)

• file_size (int)

• mime_type (str)

get_uploads(user_id)

Get all uploads for a user.

Return type:

list[UploadRecord]

Parameters:

user_id (int)

get_upload_by_id(upload_id, user_id)

Get a single upload by ID, scoped to a user.

Return type:

UploadRecord | None

Parameters:

• upload_id (int)

• user_id (int)

delete_upload(upload_id, user_id)

Delete an upload record. Returns True if a row was deleted.

Return type:

bool

Parameters:

• upload_id (int)

• user_id (int)

record_token_usage(user_id, input_tokens, output_tokens, model, topic)

Record token usage from a single LLM call.

Return type:

None

Parameters:

• user_id (int)

• input_tokens (int)

• output_tokens (int)

• model (str)

• topic (str)

get_token_usage(user_id, since=None)

Get token usage records for a user, optionally filtered by date.

Return type:

list[TokenUsageRecord]

Parameters:

• user_id (int)

• since (str | None)