Work with multiple documents in AI Assistant

This guide shows how to use AI Assistant with multiple documents, enabling users to ask questions and get insights across their entire document collection using AIAssistantViewController.

When working with multiple documents, AI Assistant enables users to:

• Ask questions that span across multiple documents in your app
• Get contextual answers that reference specific content from any document
• Navigate seamlessly between documents based on links

Working with multiple documents is particularly powerful for apps that handle document workflows, research materials, or any scenario where users require the content of multiple related documents simultaneously.

Before starting, ensure you have a working setup running AI Assistant for your project.

Creating the configuration

To support multiple documents, create an AIAssistantConfiguration that includes all document IDs in its JSON Web Token (JWT). This token authorizes the session and tells the AI Assistant server which documents are available for the session. You can read more about JWTs and supported claims in the generate a JWT guide.

func createAIAssistantConfiguration(for documents: [Document]) -> AIAssistantConfiguration {
    let sessionID = "multi-document-ios-session"

    let claims: [String: Any] = [
        "document_ids": documents.compactMap { $0.documentId?.hexadecimalEncodedString() },
        "session_ids": [sessionID]
    ]

    // In production, generate a JWT server-side for security.
    let jwt = generateJWT(claims: claims)

    // Use the server URL where your AI Assistant is hosted.
    let serverURL = URL(string: "http://localhost:4000")!

    return AIAssistantConfiguration(serverURL: serverURL, jwt: jwt, sessionID: sessionID)
}

Presenting the UI

Create an AIAssistantSession with the document collection you want to make available to AI Assistant and your configuration, and use it to create AIAssistantViewController and present the view controller:

func setupAIAssistant(with documents: [Document]) -> AIAssistantViewController {
    let configuration = createAIAssistantConfiguration(for: documents)

    let session = AIAssistantSession(documents: documents, configuration: configuration)
    let aiAssistantViewController = AIAssistantViewController(session: session)

    aiAssistantViewController.delegate = self
    return aiAssistantViewController
}

AIAssistantViewController handles setting up the connection to AI Assistant and shows the chat interface to start interacting with the documents once it’s ready.

Handling document navigation

Implement AIAssistantViewControllerDelegate to handle navigation when AI Assistant directs users to specific content. This delegate method is called whenever AI Assistant wants to show the user relevant information in a particular document:

func aiAssistantViewController(_ aiAssistantViewController: AIAssistantViewController, navigateTo document: Document, pageIndex: PageIndex, rects: [CGRect]) {
    // Switch to the correct document in your interface.
    switchToDocument(document)

    // Navigate to the specific page and highlight relevant areas.
    navigateToPage(pageIndex, highlightingRects: rects)
}

The rects parameter contains the specific areas on the page that AI Assistant wants to highlight in PDF coordinate space.

If you’re using PDFViewController to display documents, you can use the setPageIndexWithHighlights(_:_:) API to navigate to the page and highlight the relevant areas:

func navigateToPage(_ pageIndex: PageIndex, rects: [CGRect]) {
    // Navigate to and highlight the specific locations.
    pdfController.setPageIndexWithHighlights(pageIndex, rects)
}

Integration patterns

For projects using PDFTabbedViewController, integrate AI Assistant to work seamlessly with your existing document tabs. You can make the relevant document tab automatically visible when navigating to content from separate documents:

func aiAssistantViewController(_ aiAssistantViewController: AIAssistantViewController, navigateTo document: Document, pageIndex: PageIndex, rects: [CGRect]) {
    // Switch to the document tab.
    tabbedViewController.setVisibleDocument(document, scrollToPosition: true, animated: true)

    // Navigate to and highlight the specific locations.
    if let pdfController = tabbedViewController.pdfController {
        pdfController.setPageIndexWithHighlights(pageIndex, highlights: rects)
    }
}

Managing document changes

When your document collection changes, you need to recreate the AIAssistantViewController with an updated JWT that reflects the new document set. This ensures AI Assistant has access to the correct documents:

func addDocument(_ document: Document) {
    // Remove existing AI Assistant.
    aiAssistantViewController?.removeFromParent()
    aiAssistantViewController = nil

    // Recreate with updated document list.
    let aiAssistantViewController = setupAIAssistant(with: documents)
}

Example integrations

Take a look at MultiDocumentAIAssistantExample(opens in a new tab) in our Catalog project for an example of how you can use multiple documents with AI Assistant.