Package org.springframework.ai.session

Interface SessionService

All Known Implementing Classes:

DefaultSessionService

public interface SessionService

The sessions of an application and their conversations: creating and finding sessions, appending and reading their events, compacting them. DefaultSessionService implements it on a SessionRepository.

Since:

2.1.0

Author:

Christian Tzolov

Method Summary

Modifier and Type	Method	Description
void	appendEvent(SessionEvent event)	Appends an event to the session named by SessionEvent.getSessionId().
default void	appendMessage(String sessionId, Message message)	Wraps the message in a SessionEvent and appends it; see appendEvent(SessionEvent).
CompactionResult	compact(String sessionId, CompactionTrigger trigger, CompactionStrategy strategy)	Evaluates the trigger on the active view and, when it fires, runs the strategy and records its result: one EventType.COMPACTION boundary event followed by the summary events, in one version-checked append.
Session	create(CreateSessionRequest request)	Creates a session with the request's id, a random UUID when it has none, its time to live and its metadata.
void	delete(String sessionId)	Deletes the session and its events.
int	deleteExpiredSessions(Instant before)	Deletes every session that expired before the given instant, with their events, and returns how many.
@Nullable Session	findById(String sessionId)
List<Session>	findByMetadata(String name, String value)	The sessions whose metadata holds value under name, oldest first, for the keys the store indexes; see SessionRepository.findByMetadata(java.lang.String, java.lang.String).
default Session	findOrCreate(CreateSessionRequest request)	The session with the request's id, created from the request when there is none.
default List<Message>	getActiveMessages(String sessionId)	The messages of the active view, the context window to send to the model: getEvents(sessionId, EventFilter.active()) as messages.
default List<SessionEvent>	getEvents(String sessionId)	Every event of the log, oldest first.
List<SessionEvent>	getEvents(String sessionId, EventFilter filter)	The events the filter selects, oldest first; see EventFilter.
default List<Message>	getMessages(String sessionId)	The messages of the whole log, the events a compaction covered and the summaries included: the full history, not a prompt.

Method Details

create

Session create(CreateSessionRequest request)

Creates a session with the request's id, a random UUID when it has none, its time to live and its metadata.

Throws:

SessionAlreadyExistsException - if a session with the requested id exists

findOrCreate

default Session findOrCreate(CreateSessionRequest request)

The session with the request's id, created from the request when there is none. Safe under concurrent first use: when another caller creates it first, the stored session is returned, not this request's. The default finds, creates, and on a SessionAlreadyExistsException finds again, through this service's own findById(java.lang.String) and create(org.springframework.ai.session.CreateSessionRequest).

Throws:

IllegalArgumentException - if the request has no id, null or blank

findById

@Nullable Session findById(String sessionId)

findByMetadata

List<Session> findByMetadata(String name,
 String value)

The sessions whose metadata holds value under name, oldest first, for the keys the store indexes; see SessionRepository.findByMetadata(java.lang.String, java.lang.String). The sessions of a principal are findByMetadata(SessionAttributes.PRINCIPAL_NAME, name).

delete

void delete(String sessionId)

Deletes the session and its events.

deleteExpiredSessions

int deleteExpiredSessions(Instant before)

Deletes every session that expired before the given instant, with their events, and returns how many. Nothing calls this on its own: call it from a scheduler, every hour for example.

appendEvent

void appendEvent(SessionEvent event)

Appends an event to the session named by SessionEvent.getSessionId().

Throws:

IllegalArgumentException - if the event wraps a SystemMessage and the service does not allow storing system messages; see DefaultSessionService.Builder.allowSystemMessages(boolean)

appendMessage

default void appendMessage(String sessionId,
 Message message)

Wraps the message in a SessionEvent and appends it; see appendEvent(SessionEvent).

getEvents

List<SessionEvent> getEvents(String sessionId,
 EventFilter filter)

The events the filter selects, oldest first; see EventFilter.

getEvents

default List<SessionEvent> getEvents(String sessionId)

Every event of the log, oldest first.

getMessages

default List<Message> getMessages(String sessionId)

The messages of the whole log, the events a compaction covered and the summaries included: the full history, not a prompt. Use getActiveMessages(String) for the prompt.

getActiveMessages

default List<Message> getActiveMessages(String sessionId)

The messages of the active view, the context window to send to the model: getEvents(sessionId, EventFilter.active()) as messages.

compact

CompactionResult compact(String sessionId,
 CompactionTrigger trigger,
 CompactionStrategy strategy)

Evaluates the trigger on the active view and, when it fires, runs the strategy and records its result: one EventType.COMPACTION boundary event followed by the summary events, in one version-checked append. The log is never changed; the boundary defines the view from then on. An append that lands in between does not waste the summary: the new events join the view verbatim and the write is retried, a bounded number of times. Pass request -> true to compact unconditionally.

Returns:

the result as written, the events appended meanwhile added to its preserved tail; CompactionResult.isUnchanged() when nothing was written: the trigger did not fire, the strategy covered nothing, another compaction landed first, or appends kept overtaking the write