Skip to content
Edit on GitHub

AI

The AI layer of GoTipe — your provider, the manager that builds context and applies results, the built-in commands, cancellation, ghost text and PII blocking.

@gotipe/aiMIT

@gotipe/ai connects the editor to a language model of your choice. You implement an AiProvider that talks to your backend or to GoTipe Cloud. The package builds the request context from the document, runs one request at a time, checks every result against the document it was made for, and applies it as a single undoable change. It ships no vendor SDK and no tool calling: a provider returns text, proofreading edits or review comments.

Install

npm install @gotipe/ai

Set up

writing-assistant.tsx
import { defineAi, defineAiAgent, defineAiContext } from "@gotipe/ai";
import { BlockEditor } from "@gotipe/block-editor";
import { DefaultPreset } from "@gotipe/core/presets";
import { useEditor } from "@gotipe/react";
import { backendProvider } from "./ai-provider";

export function WritingAssistant() {
  const editor = useEditor({
    extensions: [
      DefaultPreset,
      defineAi.configure({ provider: backendProvider, enableAutoComplete: true }),
      defineAiContext,
      defineAiAgent,
    ],
  });
  return <BlockEditor editor={editor} />;
}

AI provider shows backendProvider. Without a provider every command fails with "No AI provider configured". AI UI covers the command bar, Improve, ghost text and proofreading controls.

Extensions

Extension Adds
defineAi The manager (getAiManager(editor)), ghost text (opt-in) and the cancelAi command. The other two need it.
defineAiContext rewrite, continueWriting, askAi, and the slash items Continue Writing (/continue, /write, /generate) and Ask AI (/ai, /ask, /prompt).
defineAiAgent freeText, proofread, addParagraph, review.
AiPreset The three extensions without options. It sets no provider, so most apps configure defineAi instead.

defineAiContext and defineAiAgent also accept { provider }, which replaces the provider of the shared manager. Options of defineAi.configure():

Option Type Default Description
provider AiProvider — Your adapter.
enableAutoComplete boolean false Ghost text after a pause.
debounceMs number 500 The pause, in ms, before ghost text is requested.
maxContextBlocks number 5 Blocks before and after the current one sent as context, 0 to 100.
enablePiiDetection boolean false Block requests that contain an email address, a phone number or a card number.

Commands

Run a command by emitting executeAiCommand. The UI components do the same.

TypeScript
editor.emit("executeAiCommand", { commandId: "proofread" });
editor.emit("executeAiCommand", { commandId: "askAi", prompt: "the risks of this plan" });
Command Description
rewrite Rewrites the selection with streamRewrite (or executeCommand("rewrite")) and replaces it. Fails with "Select text to improve" without a selection.
continueWriting Continues with generateCompletion in a new paragraph after the current block, or in a new list or to-do item after an item.
askAi With a prompt, inserts a block after the current one from generateParagraph (or executeCommand("addParagraph:" + prompt)). Without one, nothing is requested and a shown AI command bar opens.
addParagraph Same as askAi with a prompt.
freeText prompt proofread, proofread document or check grammar runs proofread; review, review document or check document runs review; any other prompt adds a paragraph, without a leading add paragraph about or add paragraph:.
proofread Gets edits from proofread, validates them and emits aiProofreadChange. Read them with getProofreadSuggestions(editor); apply them with acceptProofreadSuggestion, rejectProofreadSuggestion, acceptAllProofreadSuggestions or rejectAllProofreadSuggestions.
review Gets comments from reviewComments, validates them and emits aiReviewChange with them. Read them with getAiReviewComments(editor). They are not in the comments manager and emit none of its events. They follow the text of their blocks: an edit before a comment's quote, yours or a collaborator's, moves it, an edit elsewhere leaves it, and it goes when the edit touches the quote or removes the block; each change emits aiReviewChange.
cancelAi Cancels the running request.

Generated text is collected completely before it is inserted, so an error or a cancellation never leaves a half-written block. Accept All of proofreading is one transaction and one undo step.

aiStatusChange reports an AiStatus when a request starts and ends: { active: true, task, label }, then { active: false }. task says what the request does — suggestions, completion, rewrite, continue, paragraph, proofread, review or command — and the interface says it in its own words (AiStatusIndicator reads the keys ai.status.*). A finished proofread or review ends with one more { active: false, task, count }, where count is how many suggestions or comments it found. label keeps English words for hosts that show it as it is ("Proofreading...", "Found 3 suggestions"); show task and count in your own words instead. A failure, other than a cancellation, emits error with a GoTipeError of code EXTENSION_ERROR and details.extension === "ai", and a final aiStatusChange whose label is the message.

proofread-found.ts
import type { GoTipeEditor } from "@gotipe/core";

/** Calls `found` with the number of suggestions when a proofread ends. */
export function onProofreadFound(editor: GoTipeEditor, found: (count: number) => void) {
  return editor.on("aiStatusChange", (status) => {
    if (!status.active && status.task === "proofread" && status.count !== undefined)
      found(status.count);
  });
}

The core declares the event's type with these fields; @gotipe/ai names it AiStatus, and the codes of task AiTask.

Context

Each request gets an AiContext built from the document's public JSON, so the provider works on detached copies.

Field Description
signal The request's AbortSignal.
selectedText The selected text, blocks joined with line breaks. Absent for a caret.
currentBlock The block that holds the selection anchor.
surroundingBlocks The current block with up to maxContextBlocks blocks before and after it, in document order; nested blocks count one by one. Proofread and review get every block.
fullText The whole document as text. Proofread and review only.

Cancellation

  • A manager runs one request at a time. A new request cancels the previous one.
  • A request is cancelled by cancelAi, by a change you make to the document (update with origin: "local"), by switching to read-only, by changing the provider and by destroying the editor. A collaborator's change doesn't cancel it.
  • The provider receives context.signal. Pass it to fetch to stop network work.
  • A late result is dropped even when the provider ignores the signal. Before applying anything, the manager checks the blocks the result applies to: a suggestion, a rewrite or an added paragraph needs the selected blocks as they were, or it fails with "The document changed while AI was working". Proofreading and review drop the results for blocks a collaborator changed meanwhile and keep the rest.
  • A cancellation is silent: an AbortError is not reported as an error.

Ghost text

With enableAutoComplete: true, a pause of debounceMs after typing or moving the caret requests a completion when the editor has focus, the caret sits at the end of a text block and no other AI request runs. The provider's generateCompletion streams into aiGhostTextChange events { text, blockId, offset }, and null clears them.

  • Tab inserts the suggestion at the caret where it was requested, as one change.
  • Escape dismisses it. Typing, moving the caret, leaving the editor and read-only mode dismiss it and abort the stream.

BlockEditor draws the text after the caret; see AI UI.

PII blocking

With enablePiiDetection: true, the manager checks every string of the context and the prompt before it calls the provider. A match stops the request with "AI request contains a detected email, phone or card number. Remove it or disable PII detection explicitly." The manager never edits the text, because a redacted context would no longer match the document's offsets.

It detects email addresses, North American phone numbers with at least 10 digits (an optional +1, area code and separators), and 16-digit card numbers, with or without separators between groups of four, that pass the Luhn check. detectPii(text) returns the matches as { pii_type, start, end, matched_text } with UTF-16 offsets.

Use the manager directly

getAiManager(editor) returns the manager that defineAi created for the editor, or undefined without the extension and after the editor is destroyed. It is the manager the commands, ghost text and cancelAi use, with their provider (also one set by defineAiContext or defineAiAgent). It runs one request at a time, yours or theirs: a new request cancels the running one, and so do closing the command bar and any change you make to the document. A cancelled request rejects with an AbortError. The extension owns the manager and releases it with the editor, so do not call destroy() on it.

summarize.ts
import { getAiManager } from "@gotipe/ai";
import { type GoTipeEditor, createId } from "@gotipe/core";

export async function summarizeSelection(editor: GoTipeEditor) {
  const ai = getAiManager(editor);
  if (!ai) throw new Error("Add defineAi to the editor");
  const target = ai.captureTarget(); // the document and selection to change
  const content = await ai.executeCommand("summarize");
  ai.applySuggestion({ id: createId(), type: "summarize", content, confidence: 1 }, target);
}

AiManager also works without the extensions: new AiManager(editor, { provider }) is a manager of your own, with its own request, which you release with destroy().

Method Description
setProvider(provider) / getProvider() Changes the provider (cancels the running request) / returns it.
processing true while a request runs.
buildContext() / buildFullContext() The context for a request / with every block and fullText.
captureTarget() The current document and selection, to apply a result to later.
executeCommand(command) / getSuggestions(prompt) One text / validated AiSuggestion[] from the provider.
streamCompletion(signal?), streamRewrite(text), streamContinueWriting(), streamGenerateParagraph(prompt) Chunk streams for a preview of your own.
proofread() / reviewComments() Validated proofreading edits / review comments for the whole document.
applySuggestion(suggestion, target?) Replaces the target's selection with the text. Throws when the document changed.
insertParagraph(text, target) Inserts a block after the target's block.
applyProofreadSuggestion(s) / applyProofreadSuggestions(list) Applies proofreading edits in one transaction.
cancelPending() / destroy() Cancels the running request / releases the manager.

Limitations

  • Proofreading edits refer to offsets in one version of the document and go stale when their block changes. Review comments move with the text of their block, but they are not collaborative anchors: an edit that touches a quote removes its comment, and each client keeps its own. Keep lasting discussions in CommentsManager.
  • In a collaborative document, a collaborator's edit cancels your running request.
  • The PII check covers the patterns above only. It is not a full classifier of personal data.
  • PageEditor shows no AI controls.
  • AI provider: connect your backend or GoTipe Cloud.
  • AI UI: the command bar, Improve, ghost text and proofreading.
  • Events: executeAiCommand, aiStatusChange and the other events.