Document Rendering and Annotation¶

Note: For permission-related aspects of document rendering and annotations, see the Consolidated Permissioning Guide - comprehensive documentation covering permission flows, document-level access control, corpus-level permissions, and component integration patterns.

Overview¶

The DocumentKnowledgeBase component is responsible for rendering documents and enabling annotation functionality. It automatically selects the appropriate renderer based on the document's file type and provides a unified annotation experience across different document formats.

Renderer Selection¶

The component chooses between two renderers based on the document's fileType:

PDF Renderer¶

• File types: application/pdf
• Component: PDF (from components/annotator/renderers/pdf/PDF.tsx)
• When selected: When document.fileType === "application/pdf" and a PDF file URL is available

Text Renderer¶

• File types: application/txt, text/plain
• Component: TxtAnnotator (wrapped by TxtAnnotatorWrapper)
• When selected: When document.fileType === "application/txt" or "text/plain" and a text extract file is available

The selection logic can be found in DocumentKnowledgeBase.tsx around lines 1003-1064:

if (metadata.fileType === "application/pdf") {
  // Render PDF component
} else if (metadata.fileType === "application/txt" || metadata.fileType === "text/plain") {
  // Render TxtAnnotator component
} else {
  // Show unsupported file type message
}

How Annotation Works¶

PDF Annotation¶

1. Token-based System: PDFs use a PAWLS format that provides token-level information for each page
2. Page Structure: Each page is rendered as a canvas with an overlay for annotations
3. Selection: Users click and drag to select tokens on the page
4. Creation Flow:
5. User selects text by clicking and dragging
6. SelectionBoundary component detects the selection
7. Selection is converted to token indices
8. createAnnotationHandler is called with the annotation data
9. Annotation is sent to the backend via GraphQL mutation

Text Annotation¶

1. Character-based System: Text documents use character offsets (start/end indices) for annotations
2. Span-based Rendering: Text is broken into spans based on annotation boundaries
3. Selection: Users click and drag to select text
4. Creation Flow:
5. User selects text with mouse
6. handleMouseUp event captures the selection
7. Browser's Selection API provides the selected text and range
8. Global character offsets are calculated from the selection
9. getSpan creates a new ServerSpanAnnotation object
10. createAnnotation is called to persist the annotation

Key Differences¶

Annotation Data Structure¶

Both renderers create annotations that include: - Label information (type, color, text) - Position data (format depends on document type) - Permissions (can_update, can_remove, etc.) - Metadata (creator, created date, etc.)

The annotations are stored in the pdfAnnotationsAtom and synchronized with the backend through GraphQL mutations.

Smart Label Management¶

Overview¶

The Smart Label System provides an intelligent, streamlined approach to managing annotation labels directly from the document view. This eliminates the need to navigate away from your document to create labels or labelsets.

Key Features¶

1. Inline Label Creation: Create new labels without leaving the document
2. Automatic Labelset Management: System automatically creates labelsets when needed
3. Smart Search: Search existing labels with partial, case-insensitive matching
4. Type-Aware Labels: Automatically determines label type based on document format

How It Works¶

Label Selection and Creation Flow¶

1. Opening the Label Selector
2. Click the label selector button (tag icon) in the bottom-right corner

3. The selector expands to show available labels and a search field

4. Searching for Labels

5. Start typing in the search field
6. Results update in real-time with partial, case-insensitive matching

7. If no match is found, a "Create" option appears

8. Creating New Labels

9. When no labelset exists:
   • System prompts to create both labelset and label
   • Labelset is automatically named based on corpus title
   • Single operation creates all necessary components
10. When labelset exists:
    • Click "Create [label name]" from search results
    • Enter color and description (optional)
    • Label is immediately available for use

Smart Mutation System¶

The system uses a unified smartLabelSearchOrCreate GraphQL mutation that:

mutation SmartLabelSearchOrCreate(
  $corpusId: String!
  $searchTerm: String!
  $labelType: String!
  $createIfNotFound: Boolean
) {
  smartLabelSearchOrCreate(
    corpusId: $corpusId
    searchTerm: $searchTerm
    labelType: $labelType
    createIfNotFound: $createIfNotFound
  ) {
    labels { id, text, color }
    labelset { id, title }
    labelCreated
    labelsetCreated
  }
}

This single mutation handles: - Searching for existing labels - Creating new labels - Creating labelsets when needed - Updating corpus associations - All in a single atomic transaction

Context-Aware Guidance¶

When annotation conditions aren't met, the system provides helpful guidance:

Label Types by Document Format¶

The system automatically selects the appropriate label type:

• PDF Documents: Token labels (word/phrase level)
• Text Documents: Span labels (character range)
• Document Labels: Apply to entire document (available for all formats)

Common Features¶

Both renderers support: - Multiple annotation labels with different colors - Annotation selection and highlighting - Search result highlighting - Chat source highlighting - Hover effects showing annotation labels - Context menus for editing/deleting annotations - Smart label management system