From fa66c85f87d4fe1840362c0b98de317ba5de4aa3 Mon Sep 17 00:00:00 2001 From: Edward Ly Date: Tue, 8 Jul 2025 14:43:43 -0700 Subject: [PATCH] feat(developer): add section documenting Context Chat OCP API Signed-off-by: Edward Ly --- .../digging_deeper/context_chat.rst | 135 ++++++++++++++++++ developer_manual/digging_deeper/index.rst | 1 + 2 files changed, 136 insertions(+) create mode 100644 developer_manual/digging_deeper/context_chat.rst diff --git a/developer_manual/digging_deeper/context_chat.rst b/developer_manual/digging_deeper/context_chat.rst new file mode 100644 index 000000000..242168f25 --- /dev/null +++ b/developer_manual/digging_deeper/context_chat.rst @@ -0,0 +1,135 @@ +.. _context_chat: + +============ +Context Chat +============ + +.. versionadded:: 32.0.0 + +Nextcloud offers a **Context Chat** API which allows apps to submit data +to the `Nextcloud Assistant Context Chat `_, +thereby enabling `Nextcloud Assistant `_ +to answer questions and provide insights based on the submitted data. + +Implementing a content provider for Context Chat +------------------------------------------------ + +The IContentProvider interface +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +A content provider for Context Chat needs to implement the ``\OCP\ContextChat\IContentProvider`` interface: + +.. code-block:: php + + /** + * This interface defines methods to implement a content provider + * @since 32.0.0 + */ + interface IContentProvider { + /** + * The ID of the provider + * + * @return string + * @since 32.0.0 + */ + public function getId(): string; + + /** + * The ID of the app making the provider available + * + * @return string + * @since 32.0.0 + */ + public function getAppId(): string; + + /** + * The absolute URL to the content item + * + * @param string $id + * @return string + * @since 32.0.0 + */ + public function getItemUrl(string $id): string; + + /** + * Starts the initial import of content items into context chat + * + * @return void + * @since 32.0.0 + */ + public function triggerInitialImport(): void; + } + +The ``triggerInitialImport`` method is called when Context Chat is first set up +and allows your app to import all existing content into Context Chat in one bulk. +Any other items that are created afterwards will need to be added on demand. + +Using the IContentManager service +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +To add content and register your provider implementation you will need to use the ``\OCP\ContextChat\IContentManager`` service. + +The ``IContentManager`` class has the following methods: + + * ``registerContentProvider(string $providerClass)`` + * ``submitContent(string $appId, array $items)``: Providers can use this to submit content for indexing in Context Chat. + * ``updateAccess(string $appId, string $providerId, string $itemId, string $op, array $userIds)``: Update the access rights for a content item. Use ``\OCP\ContextChat\Type\UpdateAccessOp`` constants for the ``$op`` value. + * ``updateAccessProvider(string $appId, string $providerId, string $op, array $userIds)``: Update the access rights for all content items from a provider. Use ``\OCP\ContextChat\Type\UpdateAccessOp`` constants for the ``$op`` value. + * ``updateAccessDeclarative(string $appId, string $providerId, string $itemId, array $userIds)``: Update the access rights for a content item. This method is declarative and will replace the current access rights with the provided ones. + * ``deleteProvider(string $appId, string $providerId)``: Remove all content items of a provider from the knowledge base of Context Chat. + * ``deleteContent(string $appId, string $providerId, array $itemIds)``: Remove specific content items from the knowledge base of Context Chat. + +Implementing the ContentProviderRegisterEvent event +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +To register your content provider, +your app needs to listen to the ``OCP\ContextChat\Events\ContentProviderRegisterEvent`` event +and call the ``registerContentProvider`` method in the event for every provider you want to register. + +Some partial implementations of ``Application.php`` and a ``ContentProvider`` for reference: + +.. code-block:: php + + use OCA\MyApp\ContextChat\ContentProvider; + use OCP\ContextChat\Events\ContentProviderRegisterEvent; + // ... + $context->registerEventListener(ContentProviderRegisterEvent::class, ContentProvider::class); + +.. code-block:: php + + class ContentProvider implements IContentProvider { + // ... + public function handle(Event $event): void { + if (!$event instanceof ContentProviderRegisterEvent) { + return; + } + $event->registerContentProvider('***appId***', '***providerId***', ContentProvider::class); + } + +Any interaction with the content manager using the ContentManager's methods +or listing the providers in the Assistant should automatically register the provider. + +You may call the ``registerContentProvider`` method explicitly +if you want to trigger an initial import of content items. + +Submitting ContentItem data +^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +To submit content, wrap it in an ``\OCP\ContextChat\ContentItem`` object: + +.. code-block:: php + + new ContentItem( + string $itemId, + string $providerId, + string $title, + string $content, + string $documentType, + \DateTime $lastModified, + array $users, + ) + +.. note:: + 1. Ensure that item IDs are unique across all users for a given provider. + 2. The app ID and provider ID both cannot contain double underscores, spaces, or colons. + 3. The ``documentType`` is a natural language term for your document type in English, e.g. ``E-Mail`` or ``Bookmark``. diff --git a/developer_manual/digging_deeper/index.rst b/developer_manual/digging_deeper/index.rst index 8e3bd8b47..b7a568ed4 100644 --- a/developer_manual/digging_deeper/index.rst +++ b/developer_manual/digging_deeper/index.rst @@ -8,6 +8,7 @@ Digging deeper api config/index classloader + context_chat continuous_integration dashboard deadlock