IServer.ts

/**
 * Design principles:
 * 1. No backward compatibility is required. As the server and client's version are always in sync.
 * 2. Simplicity is preferred.
 */

export type SetMetadataParams = {
    /**
     * For example, ['global'] means global metadata,
     * ['user'] means current user's private metadata,
     * ['user', 'public' ] means current user's public metadata,
     * ['chat', '123'] means chat metadata for chat with id 123.
     * ['model', 'abc'] means model metadata for model with id abc.
     */
    path: Array<string>;
    entries: {
        [key: string]: unknown;
    };
};

export type GetMetadataParams = {
    path: Array<string>;
    keys: Array<string>;
};

export type GetMetadataResult = {
    [key: string]: unknown;
};

export type DeleteMetadataParams = {
    path: Array<string>;
    keys: Array<string>;
};

export type MessageContent = {
    type: 'text' | 'image_url' | 'refusal';
    data: string;
}

export type ChatMessage = {
    role: 'user' | 'assistant' | 'developer';
    content: Array<MessageContent>;
};

export type FunctionCallMessage = {
    type: 'function_call';
    call_id: string;
    name: string;
    arguments: string;
    /** Provider specific trash required for the message but not the logic. */
    extra?: unknown;
};

export type FunctionCallOutputMessage = {
    type: 'function_call_output';
    call_id: string;
    output: Array<MessageContent>;
    /** Provider specific trash. */
    extra?: unknown;
};

export type Message = ChatMessage | FunctionCallMessage | FunctionCallOutputMessage;

export type MessageNode = {
    id: string;
    message: Message;
    parent?: string;
    children: Array<string>;
    timestamp: number;
}

export type LinearHistory = Array<Message>;

export type TreeHistory = {
    nodes: {
        [id: string]: MessageNode;
    };
};

export type GetChatListParams = {
    start: number;
    quantity: number;
    /** If no key is specified, no metadata will be returned. */
    metaDataKeys?: Array<string>;
};

export type GetChatListResult = Array<{
    id: string;
    metadata?: {
        [key: string]: unknown;
    };
}>;

export type Tool = {
    name: string;
    description: string;
    /** JSON schema for the parameter */
    parameters: unknown;
};

export type ChatCompletionParams = {
    id: string;
    /** If parent is not present, treat as a new root. */
    parent?: string;
    modelId: string;
    messages: Array<Message>;
    tools?: Array<Tool>;
};

export type ChatCompletionSegment = string | {
    event: 'function_call_start'
} | {
    event: 'function_call_end';
    data: FunctionCallMessage;
};

export type ChatCompletionInfo = {
    /** Message ids for the new requests and responses. */
    messageIds: Array<string>;
};

export type executeGenerationTaskParams = {
    modelId: string;
    messages: Array<Message>;
    tools?: Array<Tool>;
};

export type executeGenerationTaskResult = {
    messages: Array<Message>;
};

export type GetModelListParams = {
    metadataKeys?: Array<string>;
};

export type GetModelListResult = Array<{
    id: string;
    metadata?: {
        [key: string]: unknown;
    }
}>;

export type ModelSettings = {
    providerName: string;
    providerParams: unknown;
};

export type ModifyModelSettingsParams = {
    id: string;
    settings: ModelSettings;
};

export type UserAdminSettings = {
    role: 'admin' | 'user';
};

export type UserCredential = {
    /** Hex string */
    w0: string;
    /** Hex string */
    L: string;
    /** Hex string */
    salt: string;
};

export type GetUserListParams = {
    publicMetadataKeys?: Array<string>;
    adminMetadataKeys?: Array<string>;
};

export type GetUserListResult = Array<{
    id: string;
    userName: string;
    adminSettings: UserAdminSettings;
    publicMetadata?: {
        [key: string]: unknown;
    };
    adminMetadata?: {
        [key: string]: unknown;
    };
    isSelf?: boolean;
}>;

export type NewUserParams = {
    /** User name cannot be changed. As this is how the admin identifies a user. */
    userName: string;
    adminSettings: UserAdminSettings;
    credential: UserCredential;
};

export type SetUserAdminSettingsParams = {
    id: string;
    adminSettings: UserAdminSettings;
};

/** These two messages are not exposed to the application layer. */
export type ProtocolNegotiationRequest = {
    turnOffEncryption: boolean;
};

export type ProtocolNegotiationResponse = {
    sessionResumptionKeyIndex: string;
    sessionResumptionKey: string;
    wasUnderAttack: boolean;
};

export type PutFileParams = {
    contentBase64: string;
    fileMetadata: unknown;
};

export type PutFileResult = {
    fileId: string;
    /** Multiple file can point to the same content. */
    contentId: string;
};

export type GetFileMetaParams = {
    fileId: string;
};

export type GetFileMetaResult = {
    contentId: string;
    fileMetadata: unknown;
};

export type GetFileContentParams = {
    contentId: string;
};

export type GetFileContentResult = {
    contentBase64: string;
};

export type DeleteFileParams = {
    fileId: string;
};

export type ListFileResult = Array<{
    fileId: string;
    contentId: string;
    fileMetadata: unknown;
}>;

/**
 * There are two types of data:
 * 1. Data related to server operations, such as chat history, model parameters, etc.
 *      This kind of data has their own get/set/delete/modify methods.
 *      Data access is controlled by each method.
 * 2. Data not related to server operations, such as chat name, model name, etc.
 *      This kind of data is stored as metadata. They are indexed by a resource path.
 *      | Resource path      | Admin       | Current user | Other users |
 *      | -------------------|-------------|--------------|-------------|
 *      | global             | Read/Write  | Read         | Read        |
 *      | model, <id>        | Read/Write  | Read         | Read        |
 *      | user               | None        | Read/Write   | None        |
 *      | userPublic, [<id>] | Read        | Read/Write   | None        |
 *      | userAdmin, [<id>]  | Read/Write  | None         | None        |
 *      | chat, <id>         | None        | Read/Write   | None        |
 */

/**
 * The server manages each connection's data version.
 * When getting a resource, if the data is up-do-data, the call will fail with a NOT_MODIFIED error.
 * When modifying a resource, if the original data is outdated, the call will fail with a CONFLICT error.
 * The caller should then get the latest data and retry the operation.
 * When modifying a resource that is busy (e.g., a chat with active completion), the call will fail with a LOCKED error.
 * The caller should inform the user to take actions. Auto retry is not recommended.
 */

export interface IServer {
    /** Metadata, chat title, model name, etc. */
    setMetadataAsync(params: SetMetadataParams): Promise<void>;
    getMetadataAsync(params: GetMetadataParams): Promise<GetMetadataResult>;
    deleteMetadataAsync(params: DeleteMetadataParams): Promise<void>;

    /** Chat, current user. */
    getChatListAsync(params: GetChatListParams): Promise<GetChatListResult>;
    newChatAsync(): Promise<string>;
    getChatAsync(id: string): Promise<TreeHistory>;
    deleteChatAsync(id: string): Promise<void>;
    /** There is no set chat call. As modifying the chat content is a side effect of chat completion. */

    /** Model inference */
    /** Current user */
    chatCompletionAsync(params: ChatCompletionParams): AsyncGenerator<ChatCompletionSegment, ChatCompletionInfo, void>;
    /**
     * Execute a one-off generation task. This task is not associated with any chat.
     * This can be used for generating chat titles, summaries, etc.
     * Any user.
     */
    executeGenerationTaskAsync(params: executeGenerationTaskParams): Promise<executeGenerationTaskResult>;

    /** Model */
    /** Any user */
    getModelListAsync(params: GetModelListParams): Promise<GetModelListResult>;
    /** Admin */
    newModelAsync(params: ModelSettings): Promise<string>;
    /** Admin */
    getModelAsync(id: string): Promise<ModelSettings>;
    /** Admin */
    deleteModelAsync(id: string): Promise<void>;
    /** Admin */
    modifyModelAsync(params: ModifyModelSettingsParams): Promise<void>;

    /** User management */
    /** Admin */
    getUserListAsync(params: GetUserListParams): Promise<GetUserListResult>;
    /** Admin */
    newUserAsync(params: NewUserParams): Promise<string>;
    /** Admin, current user */
    deleteUserAsync(id: string): Promise<void>;
    /**
     * Admin settings: user role, permissions, etc.
     * Read/write for admin. Read only for current user.
     */
    /** Admin, current user */
    getUserAdminSettingsAsync(id: string): Promise<UserAdminSettings>;
    /** Admin */
    setUserAdminSettingsAsync(params: SetUserAdminSettingsParams): Promise<void>;
    /**
     * Credential, stuffs used for authentication.
     * Write only for current user.
     * No one should read the credential.
     * The Admin sets the initial credential for a new user.
     * The user should later change it to their own credential before generating any data.
     */
    /** Current user */
    setUserCredentialAsync(params: UserCredential): Promise<void>;

    /** File (context) management */
    /** Current user */
    /** File content type is different from message type. */
    putFileAsync(params: {content: Uint8Array, metadata: unknown}): Promise<PutFileResult>;
    getFileMetaAsync(params: GetFileMetaParams): Promise<GetFileMetaResult>;
    getFileContentAsync(params: GetFileContentParams): Promise<{content: Uint8Array}>;
    deleteFileAsync(params: DeleteFileParams): Promise<void>;
    listFileAsync(): Promise<ListFileResult>;
};