--- title: "Getting started with AI Assistant and Nutrient Android SDK" canonical_url: "https://www.nutrient.io/sdk/ai-assistant/getting-started/android/" md_url: "https://www.nutrient.io/sdk/ai-assistant/getting-started/android.md" last_updated: "2026-05-30T02:20:01.489Z" description: "Integrate AI Assistant with Nutrient Android SDK for powerful document processing. Enable document querying, summarizing, and translation in your applications." --- # Getting started with AI Assistant and Nutrient Android SDK AI Assistant provides [Nutrient Android SDK](https://www.nutrient.io/guides/android.md) with AI functionality. Using intelligent document processing (IDP) technology, AI Assistant enables users to query, summarize, translate, and compare document text on the fly. **View example** Prefer to jump straight into code? View the example repo on GitHub. [Read more](https://github.com/PSPDFKit/ai-assistant-demo) To set up a fully functional AI system, you’ll need a Docker container service and a library working in unison: - [Nutrient Android SDK](https://www.nutrient.io/guides/android.md) — A document viewer for Android that also exposes a user interface (UI) for the AI features. - AI Assistant — A service to process the AI requests and process documents. ## Prerequisites AI Assistant is distributed as a Docker container. To run it on your computer, you need to install a Docker runtime distribution for your operating system. ### macOS Install and start Docker Desktop for Mac. Refer to the [Docker website](https://docs.docker.com/docker-for-mac/install/) for instructions. ### Windows Install and start Docker Desktop for Windows. Refer to the [Docker website](https://docs.docker.com/docker-for-windows/install/) for instructions. ### Linux Install and start Docker Engine. Refer to the [Docker website](https://docs.docker.com/engine/install/#server) for instructions on how to install it for your Linux distribution. \ \ After you install Docker, use [these instructions](https://docs.docker.com/compose/install/#install-compose-on-linux-systems) to install Docker Compose. ## Obtaining an OpenAI API key AI Assistant requires an API key from either of these LLM providers: - OpenAI - Azure OpenAI This example will use OpenAI, but if you want to use Azure OpenAI, refer to the [Azure OpenAI guide](https://www.nutrient.io/guides/ai-assistant/service-configuration/model-providers/azure-provider.md). If you don’t have an OpenAI key, create one by following the steps in the next section. Otherwise, skip to the [setting up AI Assistant](#setting-up-ai-assistant) section. ### Creating an OpenAI account To create an OpenAI account, [sign up](https://platform.openai.com/signup) to obtain an [API key](https://platform.openai.com/account/api-keys). > The OpenAI API has attained SOC 2 Type 2 compliance (see the [official announcement](https://trust.openai.com/?tcuUid=16a1f4e1-9120-45c1-96bd-5c1007f0f3d1)). Save your API key somewhere safe, as you’ll need it in the [setting up AI Assistant](#setting-up-ai-assistant) step. ## Setting up AI Assistant AI Assistant requires a PostgreSQL database with the [pgvector](https://github.com/pgvector/pgvector) extension to operate. Copy the code snippet below and save it anywhere on your computer in a file called `docker-compose.yml`. Replace the `` placeholder with your OpenAI API key: ```yaml version: "3.8" services: ai-assistant: image: pspdfkit/ai-assistant:nightly environment: OPENAI_API_KEY: PGUSER: db-user PGPASSWORD: password PGDATABASE: ai_assistant PGHOST: db PGPORT: 5432 API_AUTH_TOKEN: secret JWT_PUBLIC_KEY: | -----BEGIN PUBLIC KEY----- MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA2gzhmJ9TDanEzWdP1WG+ 0Ecwbe7f3bv6e5UUpvcT5q68IQJKP47AQdBAnSlFVi4X9SaurbWoXdS6jpmPpk24 QvitzLNFphHdwjFBelTAOa6taZrSusoFvrtK9x5xsW4zzt/bkpUraNx82Z8MwLwr t6HlY7dgO9+xBAabj4t1d2t+0HS8O/ed3CB6T2lj6S8AbLDSEFc9ScO6Uc1XJlSo rgyJJSPCpNhSq3AubEZ1wMS1iEtgAzTPRDsQv50qWIbn634HLWxTP/UH6YNJBwzt 3O6q29kTtjXlMGXCvin37PyX4Jy1IiPFwJm45aWJGKSfVGMDojTJbuUtM+8P9Rrn AwIDAQAB -----END PUBLIC KEY----- JWT_ALGORITHM: RS256 DASHBOARD_USERNAME: dashboard DASHBOARD_PASSWORD: secret SECRET_KEY_BASE: secret-key-base ports: - 4000:4000 depends_on: db: condition: service_healthy db: image: pgvector/pgvector:pg16 healthcheck: test: [ "CMD-SHELL", "pg_isready -U db-user -d ai_assistant" ] interval: 3s timeout: 3s retries: 10 environment: POSTGRES_USER: db-user POSTGRES_PASSWORD: password POSTGRES_DB: ai_assistant POSTGRES_INITDB_ARGS: --data-checksums PGDATA: /var/lib/postgresql/data/pgdata volumes: - pgdata:/var/lib/postgresql/data volumes: pgdata: ``` ## Starting AI Assistant Now, open a terminal emulator. ### macOS Use the terminal emulator integrated with your code editor or IDE. Alternatively, you can use `Terminal.app` or [iTerm2](https://iterm2.com/). ### Windows Use your code editor’s integrated terminal or [PowerShell](https://learn.microsoft.com/en-us/powershell/scripting/windows-powershell/starting-windows-powershell?view=powershell-7.5). ### Linux Use the terminal emulator integrated with your code editor or IDE, or one bundled with your desktop environment. Go to the directory where you saved the `docker-compose.yml` file: ```sh cd ``` Run the following: ```sh docker-compose up ``` This command might take a while to run, depending on your internet connection speed. Wait until you see the following message in the terminal: ``` ai_document_assistant | info: AI Assistant started ``` AI Assistant is now up and running! ## Setting up AI Assistant on Android To attach AI Assistant directly to a document, follow the steps below. 1. Add the following dependencies to your Gradle file, as AI Assistant depends on them: ```kotlin implementation("io.noties.markwon:core:4.6.2") implementation("io.noties.markwon:html:4.6.2") implementation("io.noties.markwon:linkify:4.6.2") implementation("io.noties.markwon:ext-tables:4.6.2") implementation("io.noties.markwon:ext-strikethrough:4.6.2") implementation("io.socket:socket.io-client:2.1.1") ``` 2. Create an instance of [AI Assistant](https://www.nutrient.io/api/android/nutrient/io.nutrient.domain.ai/-ai-assistant/index.html) using the [`createAiAssistant`](https://www.nutrient.io/api/android/nutrient/com.pspdfkit.ai/create-ai-assistant.html) method. This method requires: - `context` — The Android context - `documentsDescriptors` — List of document descriptors created from data providers (supports multiple documents) - `serverUrl` — The AI Assistant server URL - `sessionId` — A unique session identifier - `jwtToken` — A Lambda function that generates JSON Web Tokens (JWTs) with document IDs ```kotlin val assetFiles = listOf("document1.pdf", "document2.pdf", "document3.pdf") val documentDescriptors = assetFiles.map { DocumentDescriptor.fromDataProviders(listOf(AssetDataProvider(it)), listOf(), listOf()) } val assistant = createAiAssistant( context = this, documentsDescriptors = documentDescriptors, serverUrl = "your-server-url", sessionId = "your-session-id", jwtToken = { documentIds -> generateJwtToken( context = this, claims = mapOf( "document_ids" to documentIds, "session_ids" to listOf("your-session-id"), "request_limit" to mapOf( "requests" to 160, "time_period_s" to 600000 // 10 minutes ) ) ) } ) ``` > **Best practices:** > > - The `AiAssistant` instance should be treated as a singleton per document session. Create it once when opening a PDF and reuse it throughout that session rather than creating a new instance each time you open the AI Assistant dialog. This ensures optimal performance and maintains session continuity. - The JWT should be generated by your own server for security. For more details, refer to the guide on [generating a JWT](https://www.nutrient.io/guides/ai-assistant/viewer-integration/client-authentication/generate-a-jwt.md). 3. Implement the [`AiAssistantProvider`](https://www.nutrient.io/api/android/nutrient/io.nutrient.domain.ai/-ai-assistant-provider/index.html) interface in your Activity to provide the AI Assistant instance: ```kotlin class YourActivity : AppCompatActivity(), AiAssistantProvider { override fun getAiAssistant(): AiAssistant { return assistant } // Optional: Implement navigation callback for multi-document support. override fun navigateTo( documentRect: List, pageIndex: Int, documentIndex: Int ) { // Handle navigation to specific document, page, and highlight rectangles. // Example: Switch to the document at `documentIndex` and highlight the specified area. } } ``` 4. To display the AI Assistant icon in your toolbar, enable it with [`setAiAssistantEnabled`](https://www.nutrient.io/api/android/nutrient/com.pspdfkit.configuration.activity/-pdf-activity-configuration/-builder/set-ai-assistant-enabled.html) in [`PdfActivityConfiguration`](https://www.nutrient.io/api/android/nutrient/com.pspdfkit.configuration.activity/-pdf-activity-configuration/index.html). Now you can access AI Assistant in your Activity by clicking the AI Assistant icon in the Nutrient `MainToolbar`. ### Multi-document support AI Assistant supports analyzing multiple documents simultaneously. When you provide multiple `DocumentDescriptor` objects, users can ask questions that span across all documents, compare content between documents, and navigate between them. ### Document navigation When AI Assistant references content from specific documents, it can automatically navigate to the relevant location using the `navigateTo` callback in the `AiAssistantProvider` interface. This callback provides: - `documentRect` — List of rectangles to highlight on the page - `pageIndex` — The specific page number within the document - `documentIndex` — The index of the document in the list you provided This enables AI Assistant to guide users directly to relevant content across your document collection. ### Alternative AI Assistant display methods In addition to the built-in toolbar icon, you can show the AI Assistant dialog programmatically: ```kotlin import com.pspdfkit.ai.showAiAssistant // Show AI Assistant dialog. showAiAssistant(context) ``` > For interactive examples of AI Assistant with multiple documents, check out the [`AiAssistant` examples](https://github.com/PSPDFKit/pspdfkit-android-catalog/blob/master/app/src/main/java/com/pspdfkit/catalog/examples/kotlin/AiAssistantComposeExample.kt) in the Catalog app, including the ViewPager and Compose multi-document examples. ## Advanced usage For advanced control over AI Assistant, you can use the lower-level API methods. The `responseState` flow enables observing responses, and various methods allow fine-grained control over initialization and messaging. > **Note:** These low-level API methods are designed for scenarios where you need to customize access to AI Assistant. If you’re using the default AI Assistant icon in the toolbar, these methods are called automatically in the correct sequence internally, and you don’t need to invoke them manually. ### AI Assistant initialization The [`initialize`](https://www.nutrient.io/api/android/nutrient/io.nutrient.domain.ai/-ai-assistant/initialize.html) method provides a convenient way to set up AI Assistant: ```kotlin // Initialize with session history (default). aiAssistant.initialize(withSessionHistory = true) // Initialize without session history for faster startup. aiAssistant.initialize(withSessionHistory = false) ``` The `initialize` method automatically: - Checks if documents are already ingested - Ingests documents if necessary - Establishes a socket connection - Retrieves the session history (if enabled) ### Manual initialization steps For more granular control, you can perform initialization steps manually. 1. Check if documents are already ingested: ```kotlin val result = aiAssistant.checkIfDocumentIsAlreadyIngested(documentId, fileHash) ``` 2. Ingest documents: ```kotlin val ingestionResponse = aiAssistant.ingestDocument(dataProvider, jwtToken) ``` 3. Initialize socket connection: ```kotlin // Include session history in connection. aiAssistant.initializeSocketConnection(includeSessionHistory = true) // Connect without session history for faster startup. aiAssistant.initializeSocketConnection(includeSessionHistory = false) ``` 4. Retrieve session history separately: ```kotlin val history = aiAssistant.getSessionHistory() ``` ### Advanced messaging capabilities AI Assistant provides several methods for different types of interactions. **Standard messaging:** ```kotlin aiAssistant.emitMessage("Your query here") ``` **Context-specific messaging with selected text:** ```kotlin aiAssistant.emitContextSpecificMessage( message = "Explain this section", contextText = "Selected text from the document" ) ``` **Emit selected text for processing:** ```kotlin aiAssistant.emitSelectedText("Text selected by the user") ``` ### Observing responses After initialization, observe responses using the `responseState` flow and update your UI accordingly: ```kotlin val responseState: Flow = aiAssistant.responseState ``` ### Terminating AI Assistant To stop AI Assistant, call the `terminate` method: ```kotlin aiAssistant.terminate() ``` --- ## Related pages - [Getting started with AI Assistant](/sdk/ai-assistant/getting-started.md) - [Getting started with AI Assistant and Nutrient iOS SDK](/sdk/ai-assistant/getting-started/ios.md) - [Getting started with AI Assistant and Nutrient Web SDK + Document Engine](/sdk/ai-assistant/getting-started/document-engine.md) - [Getting started with AI Assistant and Nutrient Web SDK](/sdk/ai-assistant/getting-started/web.md)