AI Documents #

AI Documents analyzes documents with an AI service that you choose. The app assigns a category, writes a summary, and detects deadlines, risks, and details such as people, companies, amounts, or IBANs. In the Files app, it adds an assistant for questions about your own documents and an analysis per file. Only accounts that can read the original file see a result.

Requirements #

On Debian and Ubuntu:

sudo apt install poppler-utils
# only for local text recognition
sudo apt install ocrmypdf tesseract-ocr tesseract-ocr-deu tesseract-ocr-eng

The app analyzes PDF, DOCX, XLSX, PPTX, ODT, ODS, ODP, TXT, HTML, CSV, XML, EML, PNG, JPEG, and TIFF.

Installation #

The app starts working right away. During the installation it queues up to 500 existing files, and from the next cron run on it also analyzes new uploads. Until you have set up the AI connection, the documents go to the prefilled addresses from 1. Connect AI. Turn the analysis off before the installation and turn it back on after the setup:

# 1. Turn the analysis off for now. You can set this value before the installation.
sudo -u www-data php8.4 occ config:app:set ai_documents ai_enabled --value false

# 2. Install the app from the Marketplace and enable it
sudo -u www-data php8.4 occ market:install ai_documents

Step 2 also works in the Market in the web interface; step 1 needs the command line. Then set up the AI connection (next section). Finally, select Enable AI Documents under "2. Analyze documents" and click Save settings.

Setup #

The settings are under Settings → Admin → Additional in the AI Documents section. At the top, three labels show the status: Plugin active or Plugin off, Auto analysis or Manual only, AI Assist or Chat off. Four steps follow.

Save settings in step "2. Analyze documents" saves the fields of all steps. It skips empty fields, so the old value stays in place. Stored keys are shown masked only. If you leave a key field empty, the stored key remains in use. To remove a stored value, use the command line; the default then applies again:

sudo -u www-data php8.4 occ config:app:delete ai_documents brave_api_key

1. Connect AI #

1. Enter the address and key for each block. All three address fields take the base address of the service, for example https://api.openai.com/v1 or, for Ollama, http://ollama.example.com:11434/v1. The app adds /chat/completions or /embeddings itself. A full address with that ending works as well.
2. Load models fetches the list from the service. Select a model.
3. Check the connection with Test Text AI, Test Vision OCR, and Test Embeddings.
4. Save settings.

The address and model fields are prefilled when you install the app. Enter the values of your own service in all three blocks, even if you use the same service for everything. If you leave a prefilled address in place, the app uses it. The Vision API Key field is empty by default. If it stays empty, the app sends the key of the text AI to the Vision API URL.

2. Analyze documents #

Under Advanced settings:

With Backfill user, Backfill path, Backfill limit, Force re-analysis, OCR candidates only, and Start backfill now, you queue files once, the same way as with occ ai-documents:backfill.

More switches in this area control search and the assistant. All of them are on by default:

With Model routing policy (Balanced, Lowest cost, Fastest, Highest quality) and the fields Fast model, Balanced model, Quality model, and Economy model, you spread tasks across different models. Empty fields mean the model of the text AI.

Three values exist only on the command line:

sudo -u www-data php8.4 occ config:app:set ai_documents web_search_enabled --value 0
sudo -u www-data php8.4 occ config:app:set ai_documents scope_folders --value "Contracts,Invoices"

After switching to Qdrant or OpenSearch, the new index only contains files that are analyzed afterwards. occ ai-documents:backfill --force adds the existing files, split with --user or --path if there are many. This costs tokens again.

3. Results and health #

This step shows the progress of the queue and the areas Recently processed, Statistics, and Recent errors.

4. Index quality and evaluation #

At the top you see the index coverage: how many documents are fully analyzed, outdated, or failed. In the Evaluation catalog you add test cases, each with Test name, Question, Expected file IDs, Expected answer terms, and Forbidden answer terms. Run all enabled tests measures whether the search finds the expected files. The hallucination rate is a fixed check based on forbidden terms and invalid citations, not a review of the content.

Background jobs #

If system cron runs every 15 minutes as usual, the app also analyzes only every 15 minutes. To shorten the wait, run cron.php every 5 minutes from the crontab of www-data:

*/5 * * * * /usr/bin/php8.4 -f /var/www/owncloud.online/cron.php

Command line #

# queue existing files, by default at most 500 per call
sudo -u www-data php8.4 occ ai-documents:backfill

# only one account and one folder, more files per call
sudo -u www-data php8.4 occ ai-documents:backfill --user alice --path /Invoices --limit 2000

# analyze files again that were already analyzed (costs tokens again)
sudo -u www-data php8.4 occ ai-documents:backfill --force

# only PDF files and images for text recognition
sudo -u www-data php8.4 occ ai-documents:backfill --ocr

# token usage of the instance, also for a period or as JSON
sudo -u www-data php8.4 occ ai-documents:token-usage
sudo -u www-data php8.4 occ ai-documents:token-usage --from 2026-10-01 --to 2026-10-31 --json

ai-documents:backfill only queues files; the analysis happens in the next cron run. One call queues at most 10,000 files. ai-documents:token-usage lists requests and tokens by service, task, and model.

Usage #

The assistant has the tabs Chat, Tasks, Versions, Briefing, and Intelligence. In the chat you choose the context: All readable files, Current folder, or Selected files. Answers name their sources. Open at page and Open file jump to the passage.

• AI summary finishes large files in the background: more than 20 MB, more than about 36,000 characters of text, or more than 5 scanned pages. The view updates itself.
• Analyze again requires write permission on the file.
• Tasks lists detected deadlines, tasks, and risks. The app does not carry out any of them. Done and Dismiss apply to your own account only.
• When the assistant suggests a change, such as a share, a move, or a rename, it only runs after Yes, execute. You can undo shares, moves, and renames in the Action history under Intelligence with Rollback. Files the assistant deletes go to Deleted files if the files_trashbin app is enabled.
• The assistant acts with the permissions of the logged-in account. For administrators, this includes creating accounts and groups and installing or disabling apps from the Market, each after confirmation.

Limits and notes #

Data flow #

web_search_enabled set to 0 turns off the last three rows.

Other limits #

• The app cannot be limited to groups. occ app:enable ai_documents --groups … stops with "ai_documents can't be enabled for groups." Use scope_folders to limit the analysis to certain folders.
• Vision OCR reads every page as an image. PDF OCR pages set to 0 and a backfill over all existing files create many requests. occ ai-documents:token-usage shows the usage. LLM requests/min and Embedding requests/min slow down the analysis; the daily quotas only apply to the assistant.
• The app cannot read password-protected PDF and office files.
• The results come from an AI model and can be wrong. Check important details in the source.
• When a file is deleted, the app only marks its analysis as deleted. Summary, entities, and text sections stay in the oc_ai_doc_* tables, also after an account is deleted. Keep this in mind for data deletion requirements.
• The app stores conversations per account until the account deletes them.
• occ app:disable ai_documents disables the app. Settings and tables are kept.
• With the MCP Connector, MCP clients query the documents through the ai_ask tool.

Troubleshooting #

The app writes its messages to the server log under ai_documents.