Skip to main content
Reference for AIActions helpers and the high-level action surface. AIActions exposes two layers of functionality:
  1. Wrapper methods on the AIActions instance (lifecycle & raw completions).
  2. Action helpers under ai.action, which combine prompting, response parsing, and editor updates.

​
Instance methods

​
waitUntilReady

Resolves once provider/user set-up completes. Safe to call multiple times. Returns: Promise<void> Example: 
await ai.waitUntilReady();
console.log('AI is ready!');

​
getIsReady

Returns true after initialisation. Returns: boolean Example: 
if (ai.getIsReady()) {
  console.log('AI is ready!');
}

​
getCompletion

Single-shot completion that includes the serialized document context. Parameters:
​
prompt
string
required
The user prompt for the AI
​
options
CompletionOptions
Optional completion configuration
Returns: Promise<string> Example: 
const response = await ai.getCompletion('Summarise the introduction', {
  temperature: 0.3,
  maxTokens: 600,
  stop: ['</summary>'],
  metadata: { documentId: 'contract-42' },
  providerOptions: { top_p: 0.9 },
});

​
streamCompletion

Streams a completion, firing hooks for each chunk and resolving with the full string. Parameters:
​
prompt
string
required
The user prompt for the AI
​
options
StreamOptions
Optional streaming configuration
Returns: Promise<string> Example: 
const response = await ai.streamCompletion('Explain the GDPR section', {
  temperature: 0.7,
  maxTokens: 1000,
});

​
getDocumentContext

Retrieves the current document context for AI processing. Returns the plain text content of the active editor document. Returns: string Example: 
const context = ai.getDocumentContext();
console.log('Document text:', context);

​
Action helpers

All actions return a Result object containing { success: boolean; results: FoundMatch[] }. Each FoundMatch includes the AI text (originalText, suggestedText) alongside the resolved document positions.

​
find

Finds the first occurrence and resolves its document positions. Parameters:
​
instruction
string
required
AI instruction describing what to find
Returns: Promise<Result> Example: 
const { success, results } = await ai.action.find('GDPR clause');
if (success && results[0]?.positions?.length) {
  console.log('Found at', results[0].positions[0]);
}

​
findAll

Finds every occurrence matching the instruction. Parameters:
​
instruction
string
required
AI instruction describing what to find
Returns: Promise<Result>

​
highlight

Highlights the first match in the editor with the specified color. Parameters:
​
instruction
string
required
AI instruction describing what to highlight
​
color
string
default:"#6CA0DC"
Hex color code for the highlight
Returns: Promise<Result>

​
replace

Replaces a single match with AI-generated text. Parameters:
​
instruction
string
required
AI instruction describing what to replace and how
Returns: Promise<Result> Example: 
await ai.action.replace('Replace "utilize" with "use"');
Note: Replacements are inserted as fresh text, so existing styling (bold, numbering, etc.) might not carry over. Re-apply any required formatting after the AI edit.

​
replaceAll

Replaces every match with AI-generated text. Parameters:
​
instruction
string
required
AI instruction describing what to replace and how
Returns: Promise<Result>

​
literalReplace

Performs literal text replacement when you have exact find and replace text. Prefer this over replaceAll when the user provides explicit text pairs (e.g., “change X to Y”, “replace A with B”). Automatically replaces all instances. Parameters:
​
findText
string
required
Exact text to find
​
replaceText
string
required
Exact replacement text
​
options
object
Optional replacement options
{
  caseSensitive?: boolean;      // Default: false
  trackChanges?: boolean;        // Default: false
}
Returns: Promise<Result> Example: 
// Direct replacement
await ai.action.literalReplace('CompanyA', 'CompanyB');

// Case-sensitive replacement with tracked changes
await ai.action.literalReplace('utilize', 'use', {
  caseSensitive: true,
  trackChanges: true
});

​
insertTrackedChange

Inserts a tracked change attributed to the configured user (e.g., “RedlineBot”). Parameters:
​
instruction
string
required
AI instruction describing what change to track
Returns: Promise<Result> Example: 
await ai.action.insertTrackedChange(
  'Rewrite the GDPR clause as bullet points'
);
Note: Tracked changes are also inserted as newly generated text, which can strip local formatting. Double-check for styling regressions after accepting or rejecting the change.

​
insertTrackedChanges

Inserts tracked changes for multiple matches. Parameters:
​
instruction
string
required
AI instruction describing what changes to track
Returns: Promise<Result>

​
insertComment

Inserts a comment annotating the first match. Parameters:
​
instruction
string
required
AI instruction describing what to comment on
Returns: Promise<Result>

​
insertComments

Inserts comments for every match. Parameters:
​
instruction
string
required
AI instruction describing what to comment on
Returns: Promise<Result>

​
literalInsertComment

Inserts a comment when you have exact find text and comment text. Prefer this over insertComments when the user provides explicit text to find and exact comment text to add. Automatically adds comments to all instances. Parameters:
​
findText
string
required
Exact text to find
​
commentText
string
required
Exact comment text to add
​
options
object
Optional search options
{
  caseSensitive?: boolean;      // Default: false
}
Returns: Promise<Result> Example: 
// Add comment to all instances
await ai.action.literalInsertComment('GDPR', 'Please review GDPR compliance');

// Case-sensitive search
await ai.action.literalInsertComment('CompanyA', 'Verify entity name', {
  caseSensitive: true
});

​
summarize

Returns AI-generated summary text in the suggestedText field. Streams results if the provider supports streaming. Parameters:
​
instruction
string
required
AI instruction describing what to summarize
Returns: Promise<Result> Example: 
const { results } = await ai.action.summarize('Summarize the introduction');
console.log(results[0]?.suggestedText);

​
insertContent

Inserts AI-generated content into the document at the current cursor position, or appends it to the end if no cursor location is set. Content streams directly into the editor as it arrives from the provider. Parameters:
​
instruction
string
required
AI instruction describing what content to insert
​
options
object
Optional insertion options
{
  position?: 'before' | 'after' | 'replace';  // Default: 'after'
}
Returns: Promise<Result> Example: 
// Insert after cursor
await ai.action.insertContent('Add a conclusion paragraph');

// Insert before cursor
await ai.action.insertContent('Add an introduction', { position: 'before' });

// Replace selection
await ai.action.insertContent('Rewrite this section', { position: 'replace' });

​
AI Planner

The AI Planner enables multi-step AI workflows where the AI can plan and execute a sequence of actions automatically.

​
planner

Access the planner instance via the planner property. The planner is lazily initialized on first access. Returns: AIPlanner Example: 
const ai = new AIActions(superdoc, { user, provider });

// Access the planner
const result = await ai.planner.execute('Review the document and add comments to all legal terms');

​
planner.execute

Executes a user instruction by having the AI plan and execute a sequence of actions. Parameters:
​
prompt
string
required
Natural language instruction describing the multi-step task to perform
​
options
CompletionOptions
Optional completion configuration for the planning phase
Returns: Promise<AIPlannerExecutionResult> Result structure: 
{
  success: boolean;
  executedTools: string[];        // Names of tools that were executed
  reasoning?: string;              // AI's reasoning for the plan
  response?: string;               // Final response from the AI
  plan?: AIPlan;                   // The execution plan that was created
  rawPlan?: string;                // Raw plan text from the AI
  error?: string;                  // Error message if execution failed
  warnings?: string[];             // Warnings encountered during execution
}
Example: 
const result = await ai.planner.execute('Fix all grammar issues and add comments to unclear sentences');

if (result.success) {
  console.log('Executed tools:', result.executedTools);
  console.log('AI reasoning:', result.reasoning);
  console.log('Final response:', result.response);
} else {
  console.error('Planner failed:', result.error);
  console.log('Warnings:', result.warnings);
}
Use cases:
  • Complex multi-step document reviews
  • Automated document improvement workflows
  • Batch operations across multiple document sections
  • Conditional workflows based on document content
The planner automatically selects and sequences the appropriate tools based on your instruction. You don’t need to specify which tools to use - the AI decides the best approach.

​
Types

​
Result

{
  success: boolean;
  results: FoundMatch[];
}
Standard result structure returned by all AI actions.

​
FoundMatch

{
  originalText?: string;
  suggestedText?: string;
  positions?: DocumentPosition[];
}
Represents a match found by AI operations, with optional original text, suggested replacement, and document positions.

​
DocumentPosition

{
  from: number;
  to: number;
}
Position range in the document (character offsets).

​
CompletionOptions

{
  temperature?: number;
  maxTokens?: number;
  stop?: string[];
  model?: string;
  signal?: AbortSignal;         // Cancel request
  metadata?: Record<string, unknown>;  // Custom metadata
  providerOptions?: Record<string, unknown>;  // Provider-specific options
  documentId?: string;          // Document tracking
}
Configuration options for getCompletion() calls.

​
StreamOptions

{
  temperature?: number;
  maxTokens?: number;
  stop?: string[];
  model?: string;
  signal?: AbortSignal;         // Cancel request
  metadata?: Record<string, unknown>;  // Custom metadata
  providerOptions?: Record<string, unknown>;  // Provider-specific options
  documentId?: string;          // Document tracking
  stream?: boolean;             // Force streaming on/off
}
Configuration options for streamCompletion() calls. Extends CompletionOptions with a stream flag.

​
Tool utilities

The package exports utilities for working with AI tools and the tool registry:

​
createToolRegistry

Creates a tool registry with built-in and custom tools. Used internally by the planner but can be used for custom implementations. Parameters:
​
actions
AIToolActions
required
AI actions service instance
​
customTools
AIToolDefinition[]
Optional array of custom tool definitions
Returns: Map<AIToolName, AIToolDefinition> Example: 
import { createToolRegistry, AIActionsService } from '@superdoc-dev/ai';

const service = new AIActionsService(provider, editor, getContext, false);
const registry = createToolRegistry(service, [
  {
    name: 'customTool',
    description: 'My custom tool',
    handler: async ({ instruction, context }) => {
      // Custom implementation
      return { success: true };
    },
  },
]);

​
getToolDescriptions

Gets formatted descriptions of all tools in a registry for use in system prompts. Parameters:
​
toolRegistry
Map<AIToolName, AIToolDefinition>
required
Tool registry map
Returns: string Example: 
import { getToolDescriptions } from '@superdoc-dev/ai';

const descriptions = getToolDescriptions(registry);
// Returns: "- findAll: Find all occurrences...\n- highlight: Highlight content..."

​
isValidTool

Type guard to validate if a value is a valid tool definition. Parameters:
​
tool
unknown
required
Value to validate
Returns: boolean Example: 
import { isValidTool } from '@superdoc-dev/ai';

if (isValidTool(myTool)) {
  // TypeScript knows myTool is AIToolDefinition
  console.log(myTool.name, myTool.description);
}

​
Advanced Exports

For advanced use cases, the package exports additional classes and utilities:
  • AIActionsService - Core service with direct access to action implementations
  • EditorAdapter - Editor interaction layer for custom integrations
  • createAIProvider(config) - Factory function for creating AI providers
  • Utilities: validateInput(), parseJSON(), removeMarkdownCodeBlocks(), generateId()