AI features

Right-side AI panel with Document Summary, Explain Selection, Explain Page, Intelligent Document Extraction (IDE), and Intelligent Document Parsing (IDP). Provider abstraction supports Anthropic, Google Gemini, any OpenAI-compatible endpoint (OpenRouter-style gateways, Ollama, vLLM, LM Studio, …), and on-prem MCP gateways via createMcpProvider.

Enable

import type { AIConfig } from '@trupdf/viewer';
 
const aiConfig: AIConfig = {
  provider: 'anthropic',
  model: 'claude-sonnet-4-6', // optional; each provider has a default
  // Recommended: route calls through your own server so the API key
  // never reaches the browser.
  proxyUrl: '/api/ai-proxy',
};
 
<DocViewer source="…" licenseManager={license} aiConfig={aiConfig} />;

To supply an apiKey directly from browser code (no proxyUrl) you must also set optInDirectBrowserAccess: true — without it the provider constructor throws, preventing accidental key exposure in network traffic and DevTools.

Providers

Provider	`provider` value	Default model	Notes
Anthropic	`'anthropic'`	`claude-sonnet-4-6`	Pay-per-token API
Google Gemini	`'gemini'`	`gemini-2.5-flash`	Free-tier default; override via `model`
OpenAI-compatible endpoint	`'openai-compatible'`	`gpt-4o-mini`	Requires `baseUrl`; works with OpenRouter-style gateways, Azure, Ollama, vLLM, LM Studio

Pick one — the AI engine binds a single provider per session.

For on-prem MCP gateways, createMcpProvider builds a preconfigured provider (the wire format is the OpenAI-compatible one):

import { createMcpProvider } from '@trupdf/viewer';
 
const provider = createMcpProvider({
  baseUrl: 'https://mcp.acme.internal',
  model: 'acme-llm-1',
  apiKey: bearerToken, // omit for mTLS / header-based auth
  headers: { 'X-Tenant': 'acme' }, // optional routing headers
  supportsVision: false, // text-only gateways
});

Features in the panel

Document Summary

Walks the text layer (or OCR'd page images in secure mode), chunks by section, and returns a structured summary with citation chips that deep-link to the source rect.

Explain Selection

User selects text → "Explain". The panel streams a plain-language explanation (or Simplify / Translate / Rephrase); citations link back to the selected range. Disabled in secure mode — there is no selectable text.

Explain Page

The same four actions — Explain, Simplify, Translate, Rephrase — applied to the whole current page when nothing is selected. Pages with a usable text layer go through a text-only call; image-only / scanned pages are handled by sending the rendered page image to a vision-capable model. Either way the result streams into the panel and carries a whole-page citation chip. Page text is wrapped in delimiter tags so content embedded in the PDF can't inject instructions. Disabled in secure mode.

Intelligent Document Extraction (IDE)

Schema-first extraction: define fields as a FieldSchema, run from the IDE tab of the AI panel, get typed results with confidence + source rects. Built-in Invoice / Receipt / Contract / Resume templates ship out of the box; add your own via aiConfig.fieldTemplates (set includeBuiltInTemplates: false to hide the defaults).

import type { FieldSchema } from '@trupdf/viewer';
 
const schema: FieldSchema = {
  id: 'invoice-v1',
  name: 'Invoice',
  fields: [
    { id: 'invoiceNumber', label: 'Invoice number', type: 'string' },
    { id: 'total', label: 'Grand total', type: 'money' },
    { id: 'dueDate', label: 'Due date', type: 'date' },
  ],
};

Field types: string, number, date, money, phone, email, address. Every extracted field returns its value, a confidence score, and citations.

Intelligent Document Parsing (IDP)

Layout-aware reading order, table extraction, image classification. AIEngine.parseDocument() returns a ParsedDocument block tree plus per-region citation rects; export emitters toJsonString and toPlainText produce downloadable JSON or plain text.

Streaming

Every chat / explain call streams tokens through the panel. Cards update incrementally; users can abort with the close button.

Citations

Every result carries citations: Citation[] — each one is a { page, rect } pair the viewer can highlight and scroll to.

Caching

Page-image and extracted-text caches sit in IndexedDB keyed by SHA- 256 of the page bytes. Set disableCache: true in aiConfig to disable for sensitive workflows.

Secure mode

In secureMode: true:

Explain Selection and Explain Page auto-disable (typed SECURE_MODE_DISABLED error; the panel shows a banner).
Document Summary falls back to the in-browser OCR extraction route instead of the text layer.
IDE and IDP continue to work — they operate on page images and OCR, not the text layer.

Audit & PII chokepoint

Every AI request flows through a single chokepoint before it leaves the browser. Register onPromptCheck in aiConfig to inspect, rewrite (e.g. scrub emails, SSNs, phone numbers), or reject any prompt; the decision and reason land in the audit log. Wire an AuditLogger into the engine to receive ai.query, ai.response, ai.cache_hit, ai.error, ai.extraction.completed, and ai.parsing.completed events on the same timeline as redaction and signature events.

License gating

AIEngine calls gate.require('ai') in its constructor; the AI panel hides itself when the feature isn't bound.