Chat¶

Methods for managing AI chat sessions and messages (/api/chat/sessions).

pyclann.client.ChatClient ¶

ChatClient(http: _HttpSession)

Methods for AI chat sessions (/api/chat/sessions).

list_sessions(created_by: str, *, tree: str | None = None) -> list[ChatSession]

Return chat sessions for a user, ordered by most-recently-updated.

Parameters:

Name	Type	Description	Default
`created_by`	`str`	Username of the session owner.	required
`tree`	`str \| None`	Filter by tree slug.	`None`

Returns:

Type	Description
`list[ChatSession]`	List of :class:`~pyclann.models.ChatSession` objects.

Raises:

Type	Description
`ClannAuthError`	If not authenticated.

create_session(title: str, created_by: str, *, tree: str | None = None) -> ChatSession

Create a new chat session.

Parameters:

Name	Type	Description	Default
`title`	`str`	Session title.	required
`created_by`	`str`	Username of the session owner.	required
`tree`	`str \| None`	Tree slug to scope this session to.	`None`

Returns:

Type	Description
`ChatSession`	The newly created :class:`~pyclann.models.ChatSession`.

Raises:

Type	Description
`ClannAuthError`	If not authenticated.

delete_session(session_id: str) -> None

Delete a chat session and all its messages.

Parameters:

Name	Type	Description	Default
`session_id`	`str`	Full record ID (`"chat_session:01jd4a8xyz"`) or bare ULID.	required

Raises:

Type	Description
`ClannNotFoundError`	If the session does not exist.
`ClannAuthError`	If not authenticated.

list_messages(session_id: str) -> list[ChatMessage]

Return all messages in a session, ordered by creation time.

Parameters:

Name	Type	Description	Default
`session_id`	`str`	Full record ID or bare ULID.	required

Returns:

Type	Description
`list[ChatMessage]`	List of :class:`~pyclann.models.ChatMessage` objects.

Raises:

Type	Description
`ClannNotFoundError`	If the session does not exist.
`ClannAuthError`	If not authenticated.

append_message(session_id: str, role: str, content: str) -> ChatMessage

Append a message to a chat session.

Also updates session.updated_at so the session sorts to the top of :meth:list_sessions.

Parameters:

Name	Type	Description	Default
`session_id`	`str`	Full record ID or bare ULID.	required
`role`	`str`	`"user"` or `"assistant"`.	required
`content`	`str`	Message text.	required

Returns:

Type	Description
`ChatMessage`	The created :class:`~pyclann.models.ChatMessage`.

Raises:

Type	Description
`ClannNotFoundError`	If the session does not exist.
`ClannAuthError`	If not authenticated.