LanguageModel: append() method

Secure context: This feature is available only in secure contexts (HTTPS), in some or all supporting browsers.

The append() method of the LanguageModel interface adds content to the session's context window without generating a model response. It returns a Promise that resolves when the content has been successfully loaded into context. Use this method to preload a context before asking the model a question.

A context may be a document, conversation, history, or background information. You can call the append() method at any point during the session's lifetime.

Syntax

js
append(input)
append(input, options)

Parameters

input

The content to append to the context window. This is either:

options Optional

An object representing the options that can be passed. Properties include:

signal

An AbortSignal to cancel the append operation.

Return value

A Promise that resolves with undefined when the content has been prefilled into the context window, or rejects with one of the following exception values on failure.

Exceptions

AbortError DOMException

Thrown if the operation was cancelled via the signal option.

NotAllowedError DOMException

Thrown if usage of the method is blocked by a language-model Permissions-Policy.

NotSupportedError DOMException

Thrown if:

OperationError DOMException

Thrown if prefilling fails for any other reason not listed in the other exception types.

QuotaExceededError DOMException

Thrown if appending input would cause the session's context usage to exceed the model's LanguageModel.contextWindow.

SyntaxError DOMException

Thrown if:

TypeError DOMException

Thrown if a message's role is system but it was not the first message passed to the context.

Examples

See also Adding context with initial and ongoing prompt inputs > Appending extra messages to the context.

Append context before prompting

This example shows how to append to a context for the user role before calling prompt(). Note that we can just specify text input (documentText) in this case, because user is the default role.

js
const documentText = "This is my important essay...";
const session = await LanguageModel.create();

// Preload the document text into context
await session.append(documentText);

// Now ask questions about the document
const summary = await session.prompt(
  "Summarize the key points of this document.",
);
console.log(summary);

Appending context with an abort signal

An abort signal lets you cancel an append operation. The example below passes an AbortSignal to the signal member and calls its abort() method after 3 seconds.

js
const controller = new AbortController();
setTimeout(() => controller.abort(), 3000);

try {
  await session.append(
    "Here is some background context for future questions.",
    {
      signal: controller.signal,
    },
  );
  console.log("Context appended successfully.");
} catch (err) {
  if (err.name === "AbortError") {
    console.log("Append was aborted.");
  }
}

Checking context usage after appending

The code below shows how to log the number of tokens used after appending a large amount of context.

js
const largeDocument = "This is my large body of text...";
const session = await LanguageModel.create();
await session.append(largeDocument);

console.log(
  `Context used: ${session.contextUsage} / ${session.contextWindow} tokens`,
);

Specifications

See also