recallrai
Version:
Official Node.js SDK for RecallrAI - Revolutionary contextual memory system that enables AI assistants to form meaningful connections between conversations, just like human memory.
190 lines (189 loc) • 9.73 kB
TypeScript
/**
* Session management functionality for the RecallrAI SDK.
*/
import { HTTPClient } from "./utils";
import { ContextResponse, SessionMessagesList, SessionModel, SessionStatus, MessageRole, RecallStrategy } from "./models";
import type { Unavailable } from "./models";
/**
* Manages a conversation session with RecallrAI.
*
* This class handles adding messages, retrieving context, and processing the session
* to update the user's memory.
*/
export declare class Session {
private http;
private sessionData;
private _userId;
sessionId: string;
status: SessionStatus | Unavailable;
createdAt: Date | Unavailable;
metadata: Record<string, any> | Unavailable;
/**
* Initialize a session.
*
* @param httpClient - HTTP client for API communication.
* @param userId - ID of the user who owns this session.
* @param sessionData - Initial session data from the API.
*/
constructor(httpClient: HTTPClient, userId: string, sessionData: SessionModel);
/**
* Internal helper to add a message to the session.
*
* @param role - Role of the message sender.
* @param content - Content of the message.
* @throws {UserNotFoundError} If the user is not found.
* @throws {SessionNotFoundError} If the session is not found.
* @throws {InvalidSessionStateError} If the session is already processed or processing.
* @throws {AuthenticationError} If the API key or project ID is invalid.
* @throws {InternalServerError} If the server encounters an error.
* @throws {NetworkError} If there are network issues.
* @throws {TimeoutError} If the request times out.
* @throws {RecallrAIError} For other API-related errors.
*/
addMessage(role: MessageRole, content: string): Promise<void>;
/**
* Get the current context for this session.
*
* @param recallStrategy - The type of recall strategy to use. Defaults to RecallStrategy.BALANCED.
* @param minTopK - Minimum number of memories to return. Defaults to 15.
* @param maxTopK - Maximum number of memories to return. Defaults to 50.
* @param memoriesThreshold - Similarity threshold for memories. Defaults to 0.6.
* @param summariesThreshold - Similarity threshold for summaries. Defaults to 0.5.
* @param lastNMessages - Number of last messages to include in context.
* @param lastNSummaries - Number of last summaries to include in context.
* @param timezone - Timezone for formatting timestamps (e.g., 'America/New_York'). Defaults to UTC.
* @param includeSystemPrompt - Whether to include the default system prompt of Recallr AI. Defaults to true.
* @param includeMetadataIds - Whether to include memory IDs and session IDs that contributed to the context. Defaults to false.
* @returns ContextResponse with the context and optional metadata.
* @throws {UserNotFoundError} If the user is not found.
* @throws {SessionNotFoundError} If the session is not found.
* @throws {AuthenticationError} If the API key or project ID is invalid.
* @throws {InternalServerError} If the server encounters an error.
* @throws {NetworkError} If there are network issues.
* @throws {TimeoutError} If the request times out.
* @throws {RecallrAIError} For other API-related errors.
*/
getContext({ recallStrategy, minTopK, maxTopK, memoriesThreshold, summariesThreshold, lastNMessages, lastNSummaries, timezone, includeSystemPrompt, includeMetadataIds, }?: {
recallStrategy?: RecallStrategy;
minTopK?: number;
maxTopK?: number;
memoriesThreshold?: number;
summariesThreshold?: number;
lastNMessages?: number;
lastNSummaries?: number;
timezone?: string;
includeSystemPrompt?: boolean;
includeMetadataIds?: boolean;
}): Promise<ContextResponse>;
/**
* Stream context events for this session using Server-Sent Events (SSE).
*
* @param recallStrategy - The type of recall strategy to use. Defaults to RecallStrategy.BALANCED.
* @param minTopK - Minimum number of memories to return. Defaults to 15.
* @param maxTopK - Maximum number of memories to return. Defaults to 50.
* @param memoriesThreshold - Similarity threshold for memories. Defaults to 0.6.
* @param summariesThreshold - Similarity threshold for summaries. Defaults to 0.5.
* @param lastNMessages - Number of last messages to include in context.
* @param lastNSummaries - Number of last summaries to include in context.
* @param timezone - Timezone for formatting timestamps (e.g., 'America/New_York'). Defaults to UTC.
* @param includeSystemPrompt - Whether to include the default system prompt of Recallr AI. Defaults to true.
* @param includeMetadataIds - Whether to include memory IDs and session IDs that contributed to the context. Defaults to false.
* @returns An async generator yielding context events as they are processed.
* @throws {UserNotFoundError} If the user is not found.
* @throws {SessionNotFoundError} If the session is not found.
* @throws {AuthenticationError} If the API key or project ID is invalid.
* @throws {InternalServerError} If the server encounters an error.
* @throws {NetworkError} If there are network issues.
* @throws {TimeoutError} If the request times out.
* @throws {RecallrAIError} For other API-related errors.
*/
getContextStream({ recallStrategy, minTopK, maxTopK, memoriesThreshold, summariesThreshold, lastNMessages, lastNSummaries, timezone, includeSystemPrompt, includeMetadataIds, }?: {
recallStrategy?: RecallStrategy;
minTopK?: number;
maxTopK?: number;
memoriesThreshold?: number;
summariesThreshold?: number;
lastNMessages?: number;
lastNSummaries?: number;
timezone?: string;
includeSystemPrompt?: boolean;
includeMetadataIds?: boolean;
}): AsyncGenerator<ContextResponse>;
private parseContextResponse;
/**
* Delete this session and all associated data.
*
* Permanently deletes the session along with its messages and any memories,
* memory connections, memory categories, and merge conflicts created from it.
*
* @throws {UserNotFoundError} If the user is not found.
* @throws {SessionNotFoundError} If the session is not found.
* @throws {AuthenticationError} If the API key or project ID is invalid.
* @throws {InternalServerError} If the server encounters an error.
* @throws {NetworkError} If there are network issues.
* @throws {TimeoutError} If the request times out.
* @throws {RecallrAIError} For other API-related errors.
*/
delete(): Promise<void>;
/**
* Update the session's metadata.
*
* @param newMetadata - New metadata to associate with the session.
* @throws {UserNotFoundError} If the user is not found.
* @throws {SessionNotFoundError} If the session is not found.
* @throws {AuthenticationError} If the API key or project ID is invalid.
* @throws {InternalServerError} If the server encounters an error.
* @throws {NetworkError} If there are network issues.
* @throws {TimeoutError} If the request times out.
* @throws {RecallrAIError} For other API-related errors.
*/
update(newMetadata?: Record<string, any>): Promise<void>;
/**
* Refresh the session data from the API.
*
* This method updates the local session data to reflect any changes
* that may have occurred on the server.
*
* @throws {UserNotFoundError} If the user is not found.
* @throws {SessionNotFoundError} If the session is not found.
* @throws {AuthenticationError} If the API key or project ID is invalid.
* @throws {InternalServerError} If the server encounters an error.
* @throws {NetworkError} If there are network issues.
* @throws {TimeoutError} If the request times out.
* @throws {RecallrAIError} For other API-related errors.
*/
refresh(): Promise<void>;
/**
* Process the session to update the user's memory.
*
* This method triggers the processing of the conversation to extract and update
* the user's memory.
*
* @throws {UserNotFoundError} If the user is not found.
* @throws {SessionNotFoundError} If the session is not found.
* @throws {InvalidSessionStateError} If the session is already processed or being processed.
* @throws {AuthenticationError} If the API key or project ID is invalid.
* @throws {InternalServerError} If the server encounters an error.
* @throws {NetworkError} If there are network issues.
* @throws {TimeoutError} If the request times out.
* @throws {RecallrAIError} For other API-related errors.
*/
process(): Promise<void>;
/**
* Get all messages in the session.
*
* @param offset - Number of records to skip.
* @param limit - Maximum number of records to return.
* @returns Paginated list of messages in the session.
* @throws {UserNotFoundError} If the user is not found.
* @throws {SessionNotFoundError} If the session is not found.
* @throws {AuthenticationError} If the API key or project ID is invalid.
* @throws {InternalServerError} If the server encounters an error.
* @throws {NetworkError} If there are network issues.
* @throws {TimeoutError} If the request times out.
* @throws {RecallrAIError} For other API-related errors.
*/
getMessages(offset?: number, limit?: number): Promise<SessionMessagesList>;
private parseSessionResponse;
toString(): string;
}