Merge pull request #15113 from nextcloud/enh/noid/taskprocessing-provider-options

docs(dev): Document recent changes in the TaskProcessing API

Author: julien-nc

developer_manual/digging_deeper/task_processing.rst

@@ -347,7 +347,7 @@ A **Task processing provider** will usually be a class that implements the inter
     use OCP\TaskProcessing\SummaryTaskType;
     use OCP\IL10N;
 
-    class Provider implements ISynchrounousProvider {
+    class Provider implements ISynchronousProvider {
 
         public function __construct(
             private IL10N $l,
@@ -417,6 +417,43 @@ Important to note here is that ``Image``, ``Audio``, ``Video`` and ``File`` slot
 
 This class would typically be saved into a file in ``lib/TaskProcessing`` of your app but you are free to put it elsewhere as long as it's loadable by Nextcloud's :ref:`dependency injection container<dependency-injection>`.
 
+Implementing an advanced TaskProcessing provider
+------------------------------------------------
+
+The ``\OCP\TaskProcessing\ISynchronousOptionsAwareProvider`` interface is available if you want your provider
+to support watermarking or streaming. If your provider implements ``\OCP\TaskProcessing\ISynchronousOptionsAwareProvider``,
+the process method should be adjusted:
+
+.. code-block:: php
+
+    public function process(
+        ?string $userId, array $input, callable $reportProgress,
+        SynchronousProviderOptions $options = new SynchronousProviderOptions(),
+    ): array {
+        $includeWatermark = $options->getIncludeWatermark();
+        $preferStreaming = $options->getPreferStreaming();
+        $reportOutput = $options->getReportIntermediateOutput();
+
+        $textOutput = '1';
+        if ($preferStreaming) {
+            $reportOutput(['output' => $textOutput]);
+        }
+        foreach (range(2, 100) as $i) {
+            $textOutput .= ' and ' . $i;
+            $reportProgress($i / 100);
+            if ($preferStreaming) {
+                $reportOutput(['output' => $textOutput]);
+            }
+        }
+
+        if ($includeWatermark) {
+            $textOutput .= "\n" . 'This was generated using artificial intelligence.';
+        }
+
+        return ['output' => $textOutput];
+    }
+
+
 Providing additional inputs and outputs
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 

developer_manual/release_notes/new.rst

@@ -34,3 +34,19 @@ but they might be required to have a fully working instance later on.
 Expensive repair steps are only executed when explicitly requested by the administrator.
 
 See :ref:`migration-repair-steps` for details.
+
+Added APIs
+^^^^^^^^^^
+
+- There is a new TaskProcessing provider interface: ``\OCP\TaskProcessing\ISynchronousOptionsAwareProvider``. It takes a ``\OCP\TaskProcessing\SynchronousProviderOptions`` option object that contains includeWatermarks, preferStreaming and the callback to report intermediate output.
+
+Changed APIs
+^^^^^^^^^^^^
+
+- The ``\OCP\TaskProcessing\Task`` class now has ``getPreferStreaming`` and ``setPreferStreaming`` methods for indicating whether the provider should report the output progressively if it supports it.
+- The TaskProcessing OCS API now also accepts the ``preferStreaming`` flag when scheduling tasks.
+
+Deprecated APIs
+^^^^^^^^^^^^^^^
+
+- ``\OCP\TaskProcessing\ISynchronousWatermarkingProvider`` is now deprecated. ``\OCP\TaskProcessing\ISynchronousOptionsAwareProvider`` should now be used instead.