Prompt API: Add overview for Prompt API

files/en-us/web/api/Prompt_API/index.md

@@ -0,0 +1,67 @@
+---
+title: Prompt API
+slug: Web/API/Prompt_API
+page-type: web-api-overview
+spec-urls: https://webmachinelearning.github.io/prompt-api/
+---
+
+{{DefaultAPISidebar("Prompt API")}}{{SecureContext_Header}}
+
+The **Prompt API** allows web pages to directly prompt a language model provided by the user agent model through a uniform JavaScript interface, without needing to manage implementation-specific details of the AI model being used. The API does not provide a way to specify a model other than the one provided by the user agent.
+
+## Concepts and usage
+
+### Sessions
+
+All interaction with the language model happens through a {{domxref("LanguageModel")}} session. A session is created by calling the static {{domxref("LanguageModel.create_static", "LanguageModel.create()")}} method, which returns a {{jsxref("Promise")}} that resolves with a `LanguageModel` instance. If the model is not yet downloaded, the browser begins the download automatically; you can monitor progress with the `monitor` option passed to the {{domxref("LanguageModel.create_static", "LanguageModel.create()")}} method.
+
+Once you have a session, use {{domxref("LanguageModel.prompt()")}} to send text or multimodal input and receive the model's complete response, or {{domxref("LanguageModel.promptStreaming()")}} to receive the response incrementally as it is generated. Both methods add to the session's running context, maintaining conversational history across multiple interactions.
+
+Use {{domxref("LanguageModel.append()")}} to preload content into the context window without generating a response — useful for providing documents, background information, or conversation history before asking a question.
+
+Before creating a session, call the static {{domxref("LanguageModel.availability_static", "LanguageModel.availability()")}} method to determine whether the language model supports a given configuration on the current device. The method resolves with one of four string values: `"available"`, `"downloadable"`, `"downloading"`, or `"unavailable"`. This allows pages to adapt gracefully — for example, by displaying a download prompt or falling back to a server-side implementation — rather than creating a session only to have it fail.
+
+### The context window
+
+Every `LanguageModel` session has a finite context window, which constrains the total number of input and output tokens it can hold at once. The {{domxref("LanguageModel.contextWindow")}} property reports the session's maximum capacity, and {{domxref("LanguageModel.contextUsage")}} reports how many tokens have been consumed so far.
+
+When a {{domxref("LanguageModel.prompt()")}}, {{domxref("LanguageModel.promptStreaming()")}}, or {{domxref("LanguageModel.append()")}} call would exceed the context window, they throw a `QuotaExceededError` {{domxref("DOMException")}} and the {{domxref("LanguageModel.oncontextoverflow", "contextoverflow")}} event fires. To check how many tokens a piece of input would consume without actually sending it, use {{domxref("LanguageModel.measureContextUsage()")}}.
+
+To branch from a session at a specific point in a conversation — for example, to explore different response paths in parallel without affecting each other — use {{domxref("LanguageModel.clone()")}}.
+
+### Trigger developer functions from prompts
+
+The Prompt API supports tool use, allowing the language model to invoke developer-defined functions during generation. Tools are registered when creating a session via the `tools` option of {{domxref("LanguageModelCreateOptions")}}. Each tool is described with a name, a natural-language description, and a JSON Schema object defining its input parameters. When the model decides to call a tool, the user agent invokes the tool's {{domxref("LanguageModelToolFunction")}} callback with the arguments the model specified, and feeds the returned string back to the model to continue generation.
+
+### Multimodal input
+
+Sessions can accept text, image, and audio input, depending on the capabilities of the underlying model. Declare the expected input and output modalities when creating a session using the `expectedInputs` and `expectedOutputs` options, each of which accepts an array of {{domxref("LanguageModelExpected")}} objects. These declarations also allow {{domxref("LanguageModel.availability_static", "LanguageModel.availability()")}} to check whether the desired modalities and languages are supported before committing to session creation.
+
+Multimodal messages are expressed using the {{domxref("LanguageModelMessage")}} and {{domxref("LanguageModelMessageContent")}} dictionaries. When a session is configured to accept images or audio, you can include `ImageBitmapSource` or `AudioBuffer` values alongside text parts in a single message.
+
+### Permissions policy
+
+Access to the Prompt API is controlled by the `language-model` [Permissions Policy](/en-US/docs/Web/HTTP/Permissions_Policy) feature, whose default allowlist is `'self'`. This means the API is available to same-origin contexts by default. To enable it in cross-origin {{HTMLElement("iframe")}} elements, the embedding page must explicitly grant permission via the `allow` attribute or an appropriate `Permissions-Policy` response header.
+
+### Security considerations
+
+The Prompt API is restricted to [secure contexts](/en-US/docs/Web/Security/Secure_Contexts) (HTTPS). The privacy and security considerations for the API — including protections against fingerprinting through model capability queries, restrictions on the information revealed by availability checks, and requirements on how user agents must handle sensitive or harmful outputs — are discussed in the [Writing Assistance APIs](https://webmachinelearning.github.io/writing-assistance-apis/) specification, which defines the shared infrastructure on which the Prompt API is built.
+
+## Interfaces
+
+- {{domxref("LanguageModel")}}
+  - : Represents a session with a browser-provided language model. Provides static methods for creating sessions and checking availability, and instance methods for prompting the model, managing context, and cloning sessions.
+
+## Callback functions
+
+- {{domxref("LanguageModelToolFunction")}}
+  - : The type of function assigned to the `execute` property of a {{domxref("LanguageModelTool")}}. Called by the user agent when the language model invokes a tool; must return a {{jsxref("Promise")}} that resolves with a string representing the tool's result.
+
+## Specifications
+
+{{Specifications}}
+
+## See also
+
+- [Writing Assistance APIs](https://webmachinelearning.github.io/writing-assistance-apis/) — the specification defining the shared infrastructure underlying the Prompt API
+- [Web Machine Learning Working Group](https://www.w3.org/groups/wg/webmachinelearning/)

files/en-us/web/api/languagemodel/append/index.md

@@ -0,0 +1,153 @@
+---
+title: "LanguageModel: append() method"
+short-title: append()
+slug: Web/API/LanguageModel/append
+page-type: web-api-instance-method
+spec-urls: https://webmachinelearning.github.io/prompt-api/
+---
+
+{{APIRef("Prompt API")}}{{SecureContext_Header}}
+
+The **`append()`** method of the {{domxref("LanguageModel")}} interface adds content to the session's context window without generating a model response. It returns a {{jsxref("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. Because it does not trigger generation, it is more efficient than calling `prompt()` to set the context. You can call the `append()` method at any point during the session's lifetime.
+
+## Syntax
+
+```js-nolint
+append(input)
+append(input, options)
+```
+
+### Parameters
+
+- `input`
+  - : The content to append to the context window. This is either:
+    - A string — Shorthand for a single message. Sending only a string is equivalent to sending the following with a `"user"` role in the next option: `[{ type: "text", value: "Some string" }]`.
+    - An array of objects, each representing a single message in a conversation with a language model.
+      Objects may have the following properties:
+      - `role`
+        - : A string indicating who sent the message. Must be one of:
+        - `"user"`
+          - : A message from the user.
+        - `"assistant"`
+          - : A message from the model. Use this for few-shot examples or continued dialogue. A few-shot example is a set of input-output pairs passed as an example to an AI before asking it to complete a similar task.
+      - `content` — An object containing the text to add to the context.
+        - `type`
+          - : One of `"text"`, `"image"`, `"audio"`, `"tool-call"`, or `"tool-response"`.
+        - `value`
+          - : The actual text of the content to append.
+- `options` {{optional_inline}}
+  - : Represents the options that can be passed. Options include:
+    - `signal`
+      - : An {{domxref("AbortSignal")}} to cancel the operation. Reasons to cancel an append operation include:
+        - The user cancelled the request or navigated away.
+        - A newer request superseded the old one.
+        - A timeout.
+        - A dependent resource was destroyed.
+
+### Return value
+
+A {{jsxref("Promise")}} that resolves with `undefined` when the content has been prefilled into the context window, or rejects with one of the exception values on failure.
+
+### Exceptions
+
+- `AbortError` {{domxref("DOMException")}}
+  - : Thrown if the operation was cancelled via the `signal` option.
+- `NotSupportedError` {{domxref("DOMException")}}
+  - : Thrown in the following situations:
+    - The `role` is `"assistant"` and `type` is anything other than `"text"`.
+    - The input or output text is in a language the user agent doesn't support for prompting.
+- `OperationError` {{domxref("DOMException")}}
+  - : Thrown if prefilling fails for any other reason not listed in the other exception types.
+- `QuotaExceededError` {{domxref("DOMException")}}
+  - : Thrown if appending `input` would cause the session's context usage to exceed {{domxref("LanguageModel.contextWindow")}}.
+
+## Examples
+
+### 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 session = await LanguageModel.create();
+
+// Pre-load 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);
+```
+
+### Providing few-shot examples
+
+A few-shot example is a set of user role (input) and assistant role (output) pairs passed as an example to an AI, using the `initialPrompts` property, before asking it to complete a similar task.
+
+```js
+const session = await LanguageModel.create({
+  initialPrompts: [
+    { role: "system", content: "Translate the user's input to French." },
+    { role: "user", content: "Hello" },
+    { role: "assistant", content: "Bonjour" },
+    { role: "user", content: "Goodbye" },
+    { role: "assistant", content: "Au revoir" },
+  ],
+});
+
+const result = await session.prompt("Good morning");
+console.log(result); // "Bonjour matin" or "Bonjour"
+```
+
+### Appending context with an abort signal
+
+An abort signal lets you cancel an append message. The example below passes an {{domxref("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 percentage of tokens used after appending a large amount of context.
+
+```js
+const session = await LanguageModel.create();
+await session.append(largeDocument);
+
+console.log(
+  `Context used: ${session.contextUsage} / ${session.contextWindow} tokens`,
+);
+```
+
+## Specifications
+
+{{Specifications}}
+
+## Browser compatibility
+
+{{Compat}}
+
+## See also
+
+- {{domxref("LanguageModel.prompt()")}}
+- {{domxref("LanguageModel.measureContextUsage()")}}
+- [Prompt API](/en-US/docs/Web/API/Prompt_API)