Merge pull request #41271 from nextcloud/enh/text-processing-iprovider2

enh(TextProcessing): Add two new provider interfaces

13 files changed, 329 insertions, 31 deletions

diff --git a/core/Controller/TextProcessingApiController.php b/core/Controller/TextProcessingApiController.php
index 8b5175f0e5c..a6b85fd46ae 100644
--- a/core/Controller/TextProcessingApiController.php
+++ b/core/Controller/TextProcessingApiController.php
@@ -35,8 +35,10 @@ use OCP\AppFramework\Http\Attribute\PublicPage;
 use OCP\AppFramework\Http\Attribute\UserRateLimit;
 use OCP\AppFramework\Http\DataResponse;
 use OCP\Common\Exception\NotFoundException;
+use OCP\DB\Exception;
 use OCP\IL10N;
 use OCP\IRequest;
+use OCP\TextProcessing\Exception\TaskFailureException;
 use OCP\TextProcessing\ITaskType;
 use OCP\TextProcessing\Task;
 use OCP\TextProcessing\IManager;
@@ -102,7 +104,7 @@ class TextProcessingApiController extends \OCP\AppFramework\OCSController {
 	 * @param string $appId ID of the app that will execute the task
 	 * @param string $identifier An arbitrary identifier for the task
 	 *
-	 * @return DataResponse<Http::STATUS_OK, array{task: CoreTextProcessingTask}, array{}>|DataResponse<Http::STATUS_BAD_REQUEST|Http::STATUS_PRECONDITION_FAILED, array{message: string}, array{}>
+	 * @return DataResponse<Http::STATUS_OK, array{task: CoreTextProcessingTask}, array{}>|DataResponse<Http::STATUS_INTERNAL_SERVER_ERROR|Http::STATUS_BAD_REQUEST|Http::STATUS_PRECONDITION_FAILED, array{message: string}, array{}>
 	 *
 	 * 200: Task scheduled successfully
 	 * 400: Scheduling task is not possible
@@ -118,7 +120,11 @@ class TextProcessingApiController extends \OCP\AppFramework\OCSController {
 			return new DataResponse(['message' => $this->l->t('Requested task type does not exist')], Http::STATUS_BAD_REQUEST);
 		}
 		try {
-			$this->textProcessingManager->scheduleTask($task);
+			try {
+				$this->textProcessingManager->runOrScheduleTask($task);
+			} catch(TaskFailureException) {
+				// noop, because the task object has the failure status set already, we just return the task json
+			}
 
 			$json = $task->jsonSerialize();
 
@@ -127,6 +133,8 @@ class TextProcessingApiController extends \OCP\AppFramework\OCSController {
 			]);
 		} catch (PreConditionNotMetException) {
 			return new DataResponse(['message' => $this->l->t('Necessary language model provider is not available')], Http::STATUS_PRECONDITION_FAILED);
+		} catch (Exception) {
+			return new DataResponse(['message' => 'Internal server error'], Http::STATUS_INTERNAL_SERVER_ERROR);
 		}
 	}
 
diff --git a/core/Migrations/Version28000Date20231103104802.php b/core/Migrations/Version28000Date20231103104802.php
new file mode 100644
index 00000000000..aa54f1c5848
--- /dev/null
+++ b/core/Migrations/Version28000Date20231103104802.php
@@ -0,0 +1,61 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * @copyright Copyright (c) 2023 Marcel Klehr <mklehr@gmx.net>
+ *
+ * @author Marcel Klehr <mklehr@gmx.net>
+ *
+ * @license GNU AGPL version 3 or any later version
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as
+ * published by the Free Software Foundation, either version 3 of the
+ * License, or (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program. If not, see <http://www.gnu.org/licenses/>.
+ *
+ */
+
+namespace OC\Core\Migrations;
+
+use Closure;
+use OCP\DB\ISchemaWrapper;
+use OCP\DB\Types;
+use OCP\Migration\IOutput;
+use OCP\Migration\SimpleMigrationStep;
+
+/**
+ * Introduce completion_expected_at column in textprocessing_tasks table
+ */
+class Version28000Date20231103104802 extends SimpleMigrationStep {
+	/**
+	 * @param IOutput $output
+	 * @param Closure $schemaClosure The `\Closure` returns a `ISchemaWrapper`
+	 * @param array $options
+	 * @return null|ISchemaWrapper
+	 */
+	public function changeSchema(IOutput $output, Closure $schemaClosure, array $options): ?ISchemaWrapper {
+		/** @var ISchemaWrapper $schema */
+		$schema = $schemaClosure();
+		if ($schema->hasTable('textprocessing_tasks')) {
+			$table = $schema->getTable('textprocessing_tasks');
+
+			if (!$table->hasColumn('completion_expected_at')) {
+				$table->addColumn('completion_expected_at', Types::DATETIME, [
+					'notnull' => false,
+				]);
+				return $schema;
+			}
+		}
+
+		return null;
+	}
+}
diff --git a/core/ResponseDefinitions.php b/core/ResponseDefinitions.php
index 86eef1d2524..7d54cf66061 100644
--- a/core/ResponseDefinitions.php
+++ b/core/ResponseDefinitions.php
@@ -147,6 +147,7 @@ namespace OCA\Core;
  *     input: string,
  *     output: ?string,
  *     identifier: string,
+ *     completionExpectedAt: ?int
  * }
  *
  * @psalm-type CoreTextToImageTask = array{
diff --git a/core/openapi.json b/core/openapi.json
index a63d9380db7..b703cfff79f 100644
--- a/core/openapi.json
+++ b/core/openapi.json
@@ -416,7 +416,8 @@
                     "appId",
                     "input",
                     "output",
-                    "identifier"
+                    "identifier",
+                    "completionExpectedAt"
                 ],
                 "properties": {
                     "id": {
@@ -447,6 +448,11 @@
                     },
                     "identifier": {
                         "type": "string"
+                    },
+                    "completionExpectedAt": {
+                        "type": "integer",
+                        "format": "int64",
+                        "nullable": true
                     }
                 }
             },
@@ -4684,6 +4690,44 @@
                             }
                         }
                     },
+                    "500": {
+                        "description": "",
+                        "content": {
+                            "application/json": {
+                                "schema": {
+                                    "type": "object",
+                                    "required": [
+                                        "ocs"
+                                    ],
+                                    "properties": {
+                                        "ocs": {
+                                            "type": "object",
+                                            "required": [
+                                                "meta",
+                                                "data"
+                                            ],
+                                            "properties": {
+                                                "meta": {
+                                                    "$ref": "#/components/schemas/OCSMeta"
+                                                },
+                                                "data": {
+                                                    "type": "object",
+                                                    "required": [
+                                                        "message"
+                                                    ],
+                                                    "properties": {
+                                                        "message": {
+                                                            "type": "string"
+                                                        }
+                                                    }
+                                                }
+                                            }
+                                        }
+                                    }
+                                }
+                            }
+                        }
+                    },
                     "400": {
                         "description": "Scheduling task is not possible",
                         "content": {
diff --git a/lib/composer/composer/autoload_classmap.php b/lib/composer/composer/autoload_classmap.php
index cb94551e35e..bb1dd4b5df0 100644
--- a/lib/composer/composer/autoload_classmap.php
+++ b/lib/composer/composer/autoload_classmap.php
@@ -682,10 +682,13 @@ return array(
     'OCP\\TextProcessing\\Events\\AbstractTextProcessingEvent' => $baseDir . '/lib/public/TextProcessing/Events/AbstractTextProcessingEvent.php',
     'OCP\\TextProcessing\\Events\\TaskFailedEvent' => $baseDir . '/lib/public/TextProcessing/Events/TaskFailedEvent.php',
     'OCP\\TextProcessing\\Events\\TaskSuccessfulEvent' => $baseDir . '/lib/public/TextProcessing/Events/TaskSuccessfulEvent.php',
+    'OCP\\TextProcessing\\Exception\\TaskFailureException' => $baseDir . '/lib/public/TextProcessing/Exception/TaskFailureException.php',
     'OCP\\TextProcessing\\FreePromptTaskType' => $baseDir . '/lib/public/TextProcessing/FreePromptTaskType.php',
     'OCP\\TextProcessing\\HeadlineTaskType' => $baseDir . '/lib/public/TextProcessing/HeadlineTaskType.php',
     'OCP\\TextProcessing\\IManager' => $baseDir . '/lib/public/TextProcessing/IManager.php',
     'OCP\\TextProcessing\\IProvider' => $baseDir . '/lib/public/TextProcessing/IProvider.php',
+    'OCP\\TextProcessing\\IProviderWithExpectedRuntime' => $baseDir . '/lib/public/TextProcessing/IProviderWithExpectedRuntime.php',
+    'OCP\\TextProcessing\\IProviderWithUserId' => $baseDir . '/lib/public/TextProcessing/IProviderWithUserId.php',
     'OCP\\TextProcessing\\ITaskType' => $baseDir . '/lib/public/TextProcessing/ITaskType.php',
     'OCP\\TextProcessing\\SummaryTaskType' => $baseDir . '/lib/public/TextProcessing/SummaryTaskType.php',
     'OCP\\TextProcessing\\Task' => $baseDir . '/lib/public/TextProcessing/Task.php',
@@ -1220,6 +1223,7 @@ return array(
     'OC\\Core\\Migrations\\Version28000Date20230803221055' => $baseDir . '/core/Migrations/Version28000Date20230803221055.php',
     'OC\\Core\\Migrations\\Version28000Date20230906104802' => $baseDir . '/core/Migrations/Version28000Date20230906104802.php',
     'OC\\Core\\Migrations\\Version28000Date20231004103301' => $baseDir . '/core/Migrations/Version28000Date20231004103301.php',
+    'OC\\Core\\Migrations\\Version28000Date20231103104802' => $baseDir . '/core/Migrations/Version28000Date20231103104802.php',
     'OC\\Core\\Notification\\CoreNotifier' => $baseDir . '/core/Notification/CoreNotifier.php',
     'OC\\Core\\Service\\LoginFlowV2Service' => $baseDir . '/core/Service/LoginFlowV2Service.php',
     'OC\\DB\\Adapter' => $baseDir . '/lib/private/DB/Adapter.php',
diff --git a/lib/composer/composer/autoload_static.php b/lib/composer/composer/autoload_static.php
index b19f568ac1f..9667aa68533 100644
--- a/lib/composer/composer/autoload_static.php
+++ b/lib/composer/composer/autoload_static.php
@@ -715,10 +715,13 @@ class ComposerStaticInit749170dad3f5e7f9ca158f5a9f04f6a2
         'OCP\\TextProcessing\\Events\\AbstractTextProcessingEvent' => __DIR__ . '/../../..' . '/lib/public/TextProcessing/Events/AbstractTextProcessingEvent.php',
         'OCP\\TextProcessing\\Events\\TaskFailedEvent' => __DIR__ . '/../../..' . '/lib/public/TextProcessing/Events/TaskFailedEvent.php',
         'OCP\\TextProcessing\\Events\\TaskSuccessfulEvent' => __DIR__ . '/../../..' . '/lib/public/TextProcessing/Events/TaskSuccessfulEvent.php',
+        'OCP\\TextProcessing\\Exception\\TaskFailureException' => __DIR__ . '/../../..' . '/lib/public/TextProcessing/Exception/TaskFailureException.php',
         'OCP\\TextProcessing\\FreePromptTaskType' => __DIR__ . '/../../..' . '/lib/public/TextProcessing/FreePromptTaskType.php',
         'OCP\\TextProcessing\\HeadlineTaskType' => __DIR__ . '/../../..' . '/lib/public/TextProcessing/HeadlineTaskType.php',
         'OCP\\TextProcessing\\IManager' => __DIR__ . '/../../..' . '/lib/public/TextProcessing/IManager.php',
         'OCP\\TextProcessing\\IProvider' => __DIR__ . '/../../..' . '/lib/public/TextProcessing/IProvider.php',
+        'OCP\\TextProcessing\\IProviderWithExpectedRuntime' => __DIR__ . '/../../..' . '/lib/public/TextProcessing/IProviderWithExpectedRuntime.php',
+        'OCP\\TextProcessing\\IProviderWithUserId' => __DIR__ . '/../../..' . '/lib/public/TextProcessing/IProviderWithUserId.php',
         'OCP\\TextProcessing\\ITaskType' => __DIR__ . '/../../..' . '/lib/public/TextProcessing/ITaskType.php',
         'OCP\\TextProcessing\\SummaryTaskType' => __DIR__ . '/../../..' . '/lib/public/TextProcessing/SummaryTaskType.php',
         'OCP\\TextProcessing\\Task' => __DIR__ . '/../../..' . '/lib/public/TextProcessing/Task.php',
@@ -1253,6 +1256,7 @@ class ComposerStaticInit749170dad3f5e7f9ca158f5a9f04f6a2
         'OC\\Core\\Migrations\\Version28000Date20230803221055' => __DIR__ . '/../../..' . '/core/Migrations/Version28000Date20230803221055.php',
         'OC\\Core\\Migrations\\Version28000Date20230906104802' => __DIR__ . '/../../..' . '/core/Migrations/Version28000Date20230906104802.php',
         'OC\\Core\\Migrations\\Version28000Date20231004103301' => __DIR__ . '/../../..' . '/core/Migrations/Version28000Date20231004103301.php',
+        'OC\\Core\\Migrations\\Version28000Date20231103104802' => __DIR__ . '/../../..' . '/core/Migrations/Version28000Date20231103104802.php',
         'OC\\Core\\Notification\\CoreNotifier' => __DIR__ . '/../../..' . '/core/Notification/CoreNotifier.php',
         'OC\\Core\\Service\\LoginFlowV2Service' => __DIR__ . '/../../..' . '/core/Service/LoginFlowV2Service.php',
         'OC\\DB\\Adapter' => __DIR__ . '/../../..' . '/lib/private/DB/Adapter.php',
diff --git a/lib/private/TextProcessing/Db/Task.php b/lib/private/TextProcessing/Db/Task.php
index 9c6f16d11ae..5f362d429f3 100644
--- a/lib/private/TextProcessing/Db/Task.php
+++ b/lib/private/TextProcessing/Db/Task.php
@@ -45,6 +45,8 @@ use OCP\TextProcessing\Task as OCPTask;
  * @method string getAppId()
  * @method setIdentifier(string $identifier)
  * @method string getIdentifier()
+ * @method setCompletionExpectedAt(null|\DateTime $completionExpectedAt)
+ * @method null|\DateTime getCompletionExpectedAt()
  */
 class Task extends Entity {
 	protected $lastUpdated;
@@ -55,16 +57,17 @@ class Task extends Entity {
 	protected $userId;
 	protected $appId;
 	protected $identifier;
+	protected $completionExpectedAt;
 
 	/**
 	 * @var string[]
 	 */
-	public static array $columns = ['id', 'last_updated', 'type', 'input', 'output', 'status', 'user_id', 'app_id', 'identifier'];
+	public static array $columns = ['id', 'last_updated', 'type', 'input', 'output', 'status', 'user_id', 'app_id', 'identifier', 'completion_expected_at'];
 
 	/**
 	 * @var string[]
 	 */
-	public static array $fields = ['id', 'lastUpdated', 'type', 'input', 'output', 'status', 'userId', 'appId', 'identifier'];
+	public static array $fields = ['id', 'lastUpdated', 'type', 'input', 'output', 'status', 'userId', 'appId', 'identifier', 'completionExpectedAt'];
 
 
 	public function __construct() {
@@ -78,6 +81,7 @@ class Task extends Entity {
 		$this->addType('userId', 'string');
 		$this->addType('appId', 'string');
 		$this->addType('identifier', 'string');
+		$this->addType('completionExpectedAt', 'datetime');
 	}
 
 	public function toRow(): array {
@@ -98,6 +102,7 @@ class Task extends Entity {
 			'userId' => $task->getUserId(),
 			'appId' => $task->getAppId(),
 			'identifier' => $task->getIdentifier(),
+			'completionExpectedAt' => $task->getCompletionExpectedAt(),
 		]);
 		return $task;
 	}
@@ -107,6 +112,7 @@ class Task extends Entity {
 		$task->setId($this->getId());
 		$task->setStatus($this->getStatus());
 		$task->setOutput($this->getOutput());
+		$task->setCompletionExpectedAt($this->getCompletionExpectedAt());
 		return $task;
 	}
 }
diff --git a/lib/private/TextProcessing/Manager.php b/lib/private/TextProcessing/Manager.php
index b9cb06c298e..c98ff893143 100644
--- a/lib/private/TextProcessing/Manager.php
+++ b/lib/private/TextProcessing/Manager.php
@@ -28,6 +28,8 @@ namespace OC\TextProcessing;
 use OC\AppFramework\Bootstrap\Coordinator;
 use OC\TextProcessing\Db\Task as DbTask;
 use OCP\IConfig;
+use OCP\TextProcessing\Exception\TaskFailureException;
+use OCP\TextProcessing\IProviderWithExpectedRuntime;
 use OCP\TextProcessing\Task;
 use OCP\TextProcessing\Task as OCPTask;
 use OC\TextProcessing\Db\TaskMapper;
@@ -114,26 +116,16 @@ class Manager implements IManager {
 		if (!$this->canHandleTask($task)) {
 			throw new PreConditionNotMetException('No text processing provider is installed that can handle this task');
 		}
-		$providers = $this->getProviders();
-		$json = $this->config->getAppValue('core', 'ai.textprocessing_provider_preferences', '');
-		if ($json !== '') {
-			$preferences = json_decode($json, true);
-			if (isset($preferences[$task->getType()])) {
-				// If a preference for this task type is set, move the preferred provider to the start
-				$provider = current(array_filter($providers, fn ($provider) => $provider::class === $preferences[$task->getType()]));
-				if ($provider !== false) {
-					$providers = array_filter($providers, fn ($p) => $p !== $provider);
-					array_unshift($providers, $provider);
-				}
-			}
-		}
+		$providers = $this->getPreferredProviders($task);
 
 		foreach ($providers as $provider) {
-			if (!$task->canUseProvider($provider)) {
-				continue;
-			}
 			try {
 				$task->setStatus(OCPTask::STATUS_RUNNING);
+				if ($provider instanceof IProviderWithExpectedRuntime) {
+					$completionExpectedAt = new \DateTime('now');
+					$completionExpectedAt->add(new \DateInterval('PT'.$provider->getExpectedRuntime().'S'));
+					$task->setCompletionExpectedAt($completionExpectedAt);
+				}
 				if ($task->getId() === null) {
 					$taskEntity = $this->taskMapper->insert(DbTask::fromPublicTask($task));
 					$task->setId($taskEntity->getId());
@@ -145,31 +137,37 @@ class Manager implements IManager {
 				$task->setStatus(OCPTask::STATUS_SUCCESSFUL);
 				$this->taskMapper->update(DbTask::fromPublicTask($task));
 				return $output;
-			} catch (\RuntimeException $e) {
-				$this->logger->info('LanguageModel call using provider ' . $provider->getName() . ' failed', ['exception' => $e]);
-				$task->setStatus(OCPTask::STATUS_FAILED);
-				$this->taskMapper->update(DbTask::fromPublicTask($task));
-				throw $e;
 			} catch (\Throwable $e) {
 				$this->logger->info('LanguageModel call using provider ' . $provider->getName() . ' failed', ['exception' => $e]);
 				$task->setStatus(OCPTask::STATUS_FAILED);
 				$this->taskMapper->update(DbTask::fromPublicTask($task));
-				throw new RuntimeException('LanguageModel call using provider ' . $provider->getName() . ' failed: ' . $e->getMessage(), 0, $e);
+				throw new TaskFailureException('LanguageModel call using provider ' . $provider->getName() . ' failed: ' . $e->getMessage(), 0, $e);
 			}
 		}
 
-		throw new RuntimeException('Could not run task');
+		$task->setStatus(OCPTask::STATUS_FAILED);
+		$this->taskMapper->update(DbTask::fromPublicTask($task));
+		throw new TaskFailureException('Could not run task');
 	}
 
 	/**
 	 * @inheritDoc
-	 * @throws Exception
 	 */
 	public function scheduleTask(OCPTask $task): void {
 		if (!$this->canHandleTask($task)) {
 			throw new PreConditionNotMetException('No LanguageModel provider is installed that can handle this task');
 		}
 		$task->setStatus(OCPTask::STATUS_SCHEDULED);
+		$providers = $this->getPreferredProviders($task);
+		if (count($providers) === 0) {
+			throw new PreConditionNotMetException('No LanguageModel provider is installed that can handle this task');
+		}
+		[$provider,] = $providers;
+		if ($provider instanceof IProviderWithExpectedRuntime) {
+			$completionExpectedAt = new \DateTime('now');
+			$completionExpectedAt->add(new \DateInterval('PT'.$provider->getExpectedRuntime().'S'));
+			$task->setCompletionExpectedAt($completionExpectedAt);
+		}
 		$taskEntity = DbTask::fromPublicTask($task);
 		$this->taskMapper->insert($taskEntity);
 		$task->setId($taskEntity->getId());
@@ -181,6 +179,25 @@ class Manager implements IManager {
 	/**
 	 * @inheritDoc
 	 */
+	public function runOrScheduleTask(OCPTask $task): bool {
+		if (!$this->canHandleTask($task)) {
+			throw new PreConditionNotMetException('No LanguageModel provider is installed that can handle this task');
+		}
+		[$provider,] = $this->getPreferredProviders($task);
+		$maxExecutionTime = (int) ini_get('max_execution_time');
+		// Offload the task to a background job if the expected runtime of the likely provider is longer than 80% of our max execution time
+		// or if the provider doesn't provide a getExpectedRuntime() method
+		if (!$provider instanceof IProviderWithExpectedRuntime || $provider->getExpectedRuntime() > $maxExecutionTime * 0.8) {
+			$this->scheduleTask($task);
+			return false;
+		}
+		$this->runTask($task);
+		return true;
+	}
+
+	/**
+	 * @inheritDoc
+	 */
 	public function deleteTask(Task $task): void {
 		$taskEntity = DbTask::fromPublicTask($task);
 		$this->taskMapper->delete($taskEntity);
@@ -253,4 +270,26 @@ class Manager implements IManager {
 			throw new RuntimeException('Failure while trying to find tasks by appId and identifier: ' . $e->getMessage(), 0, $e);
 		}
 	}
+
+	/**
+	 * @param OCPTask $task
+	 * @return IProvider[]
+	 */
+	public function getPreferredProviders(OCPTask $task): array {
+		$providers = $this->getProviders();
+		$json = $this->config->getAppValue('core', 'ai.textprocessing_provider_preferences', '');
+		if ($json !== '') {
+			$preferences = json_decode($json, true);
+			if (isset($preferences[$task->getType()])) {
+				// If a preference for this task type is set, move the preferred provider to the start
+				$provider = current(array_values(array_filter($providers, fn ($provider) => $provider::class === $preferences[$task->getType()])));
+				if ($provider !== false) {
+					$providers = array_filter($providers, fn ($p) => $p !== $provider);
+					array_unshift($providers, $provider);
+				}
+			}
+		}
+		$providers = array_values(array_filter($providers, fn (IProvider $provider) => $task->canUseProvider($provider)));
+		return $providers;
+	}
 }
diff --git a/lib/public/TextProcessing/Exception/TaskFailureException.php b/lib/public/TextProcessing/Exception/TaskFailureException.php
new file mode 100644
index 00000000000..300864711e7
--- /dev/null
+++ b/lib/public/TextProcessing/Exception/TaskFailureException.php
@@ -0,0 +1,10 @@
+<?php
+
+namespace OCP\TextProcessing\Exception;
+
+/**
+ * Exception thrown when a task failed
+ * @since 28.0.0
+ */
+class TaskFailureException extends \RuntimeException {
+}
diff --git a/lib/public/TextProcessing/IManager.php b/lib/public/TextProcessing/IManager.php
index dec0baba4bb..ff1222b094d 100644
--- a/lib/public/TextProcessing/IManager.php
+++ b/lib/public/TextProcessing/IManager.php
@@ -27,7 +27,9 @@ declare(strict_types=1);
 namespace OCP\TextProcessing;
 
 use OCP\Common\Exception\NotFoundException;
+use OCP\DB\Exception;
 use OCP\PreConditionNotMetException;
+use OCP\TextProcessing\Exception\TaskFailureException;
 use RuntimeException;
 
 /**
@@ -56,7 +58,7 @@ interface IManager {
 	/**
 	 * @param Task $task The task to run
 	 * @throws PreConditionNotMetException If no or not the requested provider was registered but this method was still called
-	 * @throws RuntimeException If something else failed
+	 * @throws TaskFailureException If running the task failed
 	 * @since 27.1.0
 	 */
 	public function runTask(Task $task): string;
@@ -68,11 +70,26 @@ interface IManager {
 	 *
 	 * @param Task $task The task to schedule
 	 * @throws PreConditionNotMetException If no or not the requested provider was registered but this method was still called
+	 * @throws Exception storing the task in the database failed
 	 * @since 27.1.0
 	 */
 	public function scheduleTask(Task $task) : void;
 
 	/**
+	 * If the designated provider for the passed task provides an expected average runtime, we check if the runtime fits into the
+	 * max execution time of this php process and run it synchronously if it does, if it doesn't fit (or the provider doesn't provide that information)
+	 * execution is deferred to a background job
+	 *
+	 * @param Task $task The task to schedule
+	 * @returns bool A boolean indicating whether the task was run synchronously (`true`) or offloaded to a background job (`false`)
+	 * @throws PreConditionNotMetException If no or not the requested provider was registered but this method was still called
+	 * @throws TaskFailureException If running the task failed
+	 * @throws Exception storing the task in the database failed
+	 * @since 28.0.0
+	 */
+	public function runOrScheduleTask(Task $task): bool;
+
+	/**
 	 * Delete a task that has been scheduled before
 	 *
 	 * @param Task $task The task to delete
diff --git a/lib/public/TextProcessing/IProviderWithExpectedRuntime.php b/lib/public/TextProcessing/IProviderWithExpectedRuntime.php
new file mode 100644
index 00000000000..17767fc02d4
--- /dev/null
+++ b/lib/public/TextProcessing/IProviderWithExpectedRuntime.php
@@ -0,0 +1,41 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * @copyright Copyright (c) 2023 Marcel Klehr <mklehr@gmx.net>
+ *
+ * @author Marcel Klehr <mklehr@gmx.net>
+ *
+ * @license GNU AGPL version 3 or any later version
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as
+ * published by the Free Software Foundation, either version 3 of the
+ * License, or (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program. If not, see <http://www.gnu.org/licenses/>.
+ */
+
+
+namespace OCP\TextProcessing;
+
+/**
+ * This interface  allows the system to learn the provider's expected runtime
+ * @since 28.0.0
+ * @template T of ITaskType
+ * @template-extends IProvider<T>
+ */
+interface IProviderWithExpectedRuntime extends IProvider {
+	/**
+	 * @return int The expected average runtime of a task in seconds
+	 * @since 28.0.0
+	 */
+	public function getExpectedRuntime(): int;
+}
diff --git a/lib/public/TextProcessing/IProviderWithUserId.php b/lib/public/TextProcessing/IProviderWithUserId.php
new file mode 100644
index 00000000000..0a01a4c56c4
--- /dev/null
+++ b/lib/public/TextProcessing/IProviderWithUserId.php
@@ -0,0 +1,41 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * @copyright Copyright (c) 2023 Marcel Klehr <mklehr@gmx.net>
+ *
+ * @author Marcel Klehr <mklehr@gmx.net>
+ *
+ * @license GNU AGPL version 3 or any later version
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as
+ * published by the Free Software Foundation, either version 3 of the
+ * License, or (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program. If not, see <http://www.gnu.org/licenses/>.
+ */
+
+
+namespace OCP\TextProcessing;
+
+/**
+ * This interface allows providers to access the user that initiated the task being run.
+ * @since 28.0.0
+ * @template T of ITaskType
+ * @template-extends IProvider<T>
+ */
+interface IProviderWithUserId extends IProvider {
+	/**
+	 * @param ?string $userId the current user's id
+	 * @since 28.0.0
+	 */
+	public function setUserId(?string $userId): void;
+}
diff --git a/lib/public/TextProcessing/Task.php b/lib/public/TextProcessing/Task.php
index 446e414cb04..25b7132ee31 100644
--- a/lib/public/TextProcessing/Task.php
+++ b/lib/public/TextProcessing/Task.php
@@ -35,6 +35,7 @@ namespace OCP\TextProcessing;
 final class Task implements \JsonSerializable {
 	protected ?int $id = null;
 	protected ?string $output = null;
+	private ?\DateTime $completionExpectedAt = null;
 
 	/**
 	 * @since 27.1.0
@@ -98,6 +99,9 @@ final class Task implements \JsonSerializable {
 	 */
 	public function visitProvider(IProvider $provider): string {
 		if ($this->canUseProvider($provider)) {
+			if ($provider instanceof IProviderWithUserId) {
+				$provider->setUserId($this->getUserId());
+			}
 			return $provider->process($this->getInput());
 		} else {
 			throw new \RuntimeException('Task of type ' . $this->getType() . ' cannot visit provider with task type ' . $provider->getTaskType());
@@ -203,7 +207,7 @@ final class Task implements \JsonSerializable {
 	}
 
 	/**
-	 * @psalm-return array{id: ?int, type: S, status: 0|1|2|3|4, userId: ?string, appId: string, input: string, output: ?string, identifier: string}
+	 * @psalm-return array{id: ?int, type: S, status: 0|1|2|3|4, userId: ?string, appId: string, input: string, output: ?string, identifier: string, completionExpectedAt: ?int}
 	 * @since 27.1.0
 	 */
 	public function jsonSerialize(): array {
@@ -216,6 +220,24 @@ final class Task implements \JsonSerializable {
 			'input' => $this->getInput(),
 			'output' => $this->getOutput(),
 			'identifier' => $this->getIdentifier(),
+			'completionExpectedAt' => $this->getCompletionExpectedAt()?->getTimestamp(),
 		];
 	}
+
+	/**
+	 * @param null|\DateTime $completionExpectedAt
+	 * @return void
+	 * @since 28.0.0
+	 */
+	final public function setCompletionExpectedAt(?\DateTime $completionExpectedAt): void {
+		$this->completionExpectedAt = $completionExpectedAt;
+	}
+
+	/**
+	 * @return \DateTime|null
+	 * @since 28.0.0
+	 */
+	final public function getCompletionExpectedAt(): ?\DateTime {
+		return $this->completionExpectedAt;
+	}
 }