@assistant-ui/local-pdf-adapter

Local PDF Attachment Adapter

A standalone PDF attachment adapter for @assistant-ui/react that provides native PDF text extraction support.

Features

• 📄 PDF Text Extraction: Extracts text content from PDF documents for LLM consumption
• 🌐 Cross-Platform: Works in both browser and Node.js environments
• ⚡ Performance Optimized: Configurable file size limits to prevent browser performance issues
• 🔒 Security Conscious: Support for self-hosted PDF.js worker scripts
• 🛡️ Error Handling: Comprehensive error handling for corrupted or invalid PDFs
• 📦 Standalone: Can be used as a separate package without modifying assistant-ui core

Installation

npm install local-pdf-adapter

Dependencies

This package requires:

• @assistant-ui/react (peer dependency)
• pdfjs-dist (for browser environments)

For Node.js environments, also install:

npm install pdf-parse

Usage

Basic Usage

import { LocalPDFAttachmentAdapter } from 'local-pdf-adapter';
import { CompositeAttachmentAdapter } from '@assistant-ui/react';

const pdfAdapter = new LocalPDFAttachmentAdapter();

// Use with CompositeAttachmentAdapter
const attachmentAdapter = new CompositeAttachmentAdapter([
  pdfAdapter,
  // Add other adapters as needed
]);

// Use in your runtime
const runtime = useLocalRuntime({
  attachmentAdapter,
});

Advanced Configuration

const pdfAdapter = new LocalPDFAttachmentAdapter({
  maxFileSize: 20 * 1024 * 1024, // 20MB limit
  workerSrc: '/pdf.worker.min.mjs', // Self-hosted worker
});

Configuration Options

LocalPDFAttachmentAdapterConfig

Option	Type	Default	Description
workerSrc	string	undefined	Custom URL for PDF.js worker script. If not provided, uses unpkg CDN
maxFileSize	number	10 * 1024 * 1024 (10MB)	Maximum file size in bytes

Security Considerations

Self-Hosting the PDF.js Worker

By default, the PDF.js worker is loaded from the unpkg CDN. For production applications, consider self-hosting:

• Download the worker from PDF.js releases
• Serve it from your domain (e.g., in your public directory)
• Configure the adapter:

const pdfAdapter = new LocalPDFAttachmentAdapter({
  workerSrc: '/pdf.worker.min.mjs'
});

Content Security Policy (CSP)

If using the default CDN, add it to your Content Security Policy:

script-src https://unpkg.com/pdfjs-dist@*

Environment Support

Browser Environment

• Uses pdfjs-dist for client-side PDF processing
• Supports all modern browsers
• Worker script handles heavy processing to avoid blocking UI

Node.js Environment

• Uses pdf-parse for server-side PDF processing
• Requires optional pdf-parse dependency
• Faster processing for server applications

Error Handling

The adapter handles various error scenarios:

• File size exceeded: Returns attachment with error status
• Corrupted PDFs: Returns error message in attachment content
• Network failures: Graceful fallback with error reporting
• Invalid format: Clear error messages for unsupported files

Example Implementation

import { 
  LocalRuntime, 
  CompositeAttachmentAdapter,
  useLocalRuntime 
} from '@assistant-ui/react';
import { LocalPDFAttachmentAdapter } from 'local-pdf-adapter';

function ChatComponent() {
  const attachmentAdapter = new CompositeAttachmentAdapter([
    new LocalPDFAttachmentAdapter({
      maxFileSize: 5 * 1024 * 1024, // 5MB limit
      workerSrc: '/assets/pdf.worker.min.mjs' // Self-hosted
    }),
    // Add other adapters for images, text, etc.
  ]);

  const runtime = useLocalRuntime({
    attachmentAdapter,
  });

  return (
    <ThreadContainer runtime={runtime}>
      <Viewport>
        <ThreadWelcome />
        <ThreadMessages />
        <ThreadComposer />
      </Viewport>
    </ThreadContainer>
  );
}

Development

# Install dependencies
npm install

# Run tests
npm test

# Build the package
npm run build

# Watch mode for development
npm run dev

License

MIT

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.