# ShinrAI for Nextcloud Create protected PDF and text copies from Files, and protect selected Assistant tasks before they reach the configured model. The connector is free software under AGPL-3.0-or-later; ShinrAI service requests use your account allowance. [Deutsch](README.de.md). ## Install Tested with Nextcloud **33.0.8** and **34.0.3**, Assistant **3.5.0**, and OpenAI and LocalAI integration **4.5.2**. This preview supports Nextcloud 33 and 34. Marketplace approval is not required for direct installation and is not claimed. 1. Sign in to ShinrAI and create or choose an existing API key. Keep it private. 2. Extract `shinrai-nextcloud-0.1.1.tar.gz` into Nextcloud's `custom_apps` directory. It contains a single `shinrai` directory. Give the web-server account ownership, then run `php occ app:enable shinrai` as that account. For the official container, use `docker exec -u www-data php occ app:enable shinrai` after copying the extracted directory into `/var/www/html/custom_apps/`. 3. Open **Administration settings → Additional settings → ShinrAI**. Enter your ShinrAI service URL and API key, save, then select **Test connection and protection**. The sample name and email should be replaced. 4. Set Nextcloud's background jobs to **Cron**, and keep its normal cron runner active. Document conversion runs in the ShinrAI service; no OCR installation is needed inside Nextcloud. 5. In **Files**, open the action menu of a TXT, PDF or DOCX file you own and choose **Create protected copies**. The ShinrAI page shows progress. When complete, open the protected PDF or text beside the original. Original files stay unchanged. Only administrators can configure service credentials or providers. The saved key is encrypted with Nextcloud's server secret, and is never returned by the settings endpoint. Back up that secret with the Nextcloud database and data directory. The app suppresses exception argument capture so HTTP traces do not retain provider authorization headers. ## Assistant Install the tested Assistant and OpenAI/LocalAI apps. Configure the model URL, model and **administrator** credentials in the existing model integration. In ShinrAI settings, explicitly select its original provider for **Generate text**, **Summarize** and/or **Chat**. Saving makes ShinrAI the required provider for those task types. Personal model credentials are not used; the task remains owned by its Nextcloud user, and no user ID is sent as model metadata. - **Retain pseudonyms** keeps recognized replacements in replies. - **Restore recognized values** restores exact recognized replacements locally after inference. Mappings live only for that invocation and are never passed to the model. The three supported task IDs are `core:text2text`, `core:text2text:summary` and `core:text2text:chat`. Chat history supports structured human/user and assistant text messages. Tool calls, multimodal messages, memories, context agents and other task types are outside this connector. Unselected types are not protected; disable unwanted providers/task types in Nextcloud's AI settings. The separate **Chat with AI** experience can use other task types, so selecting a provider for **Chat** does not promise coverage of that whole experience. For a document, choose **Summarize protected text** on its completed operation. The app sends the protected text through the selected summary provider and opens the finished result in Assistant. Document originals and their restoration mappings are not used for this handoff. ## Coverage and recovery - Supports TXT, digital/scanned PDF and DOCX, including supported English/German text in embedded images. Outputs are extracted text and flattened PDF, not editable Word files. Limits are 10 MB input, 100 pages, 125,000 extracted characters, 40 MB output and five minutes processing. Unsupported or incomplete documents fail without exporting partial protection. - Copies have generic `protected-.pdf/.txt` names. The app checks original ownership, access, file version and permissions again before saving. Choose a file you own in a writable folder. Files received through someone else's share are rejected. Existing source sharing links are not copied to new files; folder permissions apply to the new copies. - This covers chosen exports and selected task providers. Nextcloud still stores the original files and user-entered text. Other apps, external search/indexing, external storage, direct model routes and previous uploads are outside this integration. - Recent operation records are encrypted and expire after 24 hours. Saved copies remain in Files until their owner deletes them. Service inputs are transient; service results expire after 24 hours and the app requests deletion after saving copies. - A failed connection or exhausted/expired key stops the operation. Fix the settings, then choose **Retry operation**. Retrying the same operation reuses its service job and paid result. Do not create a fresh operation just to retry. After a restart, a processing operation older than six minutes can be retried. If the source changed, start a new operation for that version. If progress stays queued, check Nextcloud's cron runner. If protection fails, use the connection test, check the account allowance and supported format, and verify that the owner still has access. If the Files action is absent, confirm the app is enabled on a supported version and reload Files. Customer installations should use HTTPS for Nextcloud and ShinrAI; the LAN lab explicitly permits its local HTTP service. ## Build and validation `npm ci` followed by `python3 build.py` validates PHP/XML, builds the Files action against pinned `@nextcloud/files` 4.0.0, and writes the direct-install archive under `dist/`. The archive includes its app source and license. `php tests/provider.php` checks structured history, restoration, cancellation and rejection before inference. The lab scripts exercise actual application installations, documents, owner isolation and real-model tasks; they do not imply marketplace approval. References: [Nextcloud task processing](https://docs.nextcloud.com/server/stable/developer_manual/digging_deeper/task_processing.html), [Assistant integration](https://github.com/nextcloud/assistant/blob/v3.5.0/docs/developer/web-integration.md). ## Validated example The [screenshots](screenshots/) show the actual installed test application with synthetic data. Replacement values vary between runs. The download includes shared example documents and an executable connection test in `../fixtures/`.