diff options
author | Marcel Klehr <mklehr@gmx.net> | 2023-07-14 15:59:50 +0200 |
---|---|---|
committer | Marcel Klehr <mklehr@gmx.net> | 2023-08-09 10:05:05 +0200 |
commit | cf2c42ae36a3c7280887bd3f15329739f9a6d221 (patch) | |
tree | 3e682483cc8177afd7b9e682fcaa103791f78d2a /lib/public/TextProcessing | |
parent | 696a45ddf1d460de7ffa6f252912375efd7e190e (diff) | |
download | nextcloud-server-cf2c42ae36a3c7280887bd3f15329739f9a6d221.tar.gz nextcloud-server-cf2c42ae36a3c7280887bd3f15329739f9a6d221.zip |
Massive refactoring: Turn LanguageModel OCP API into TextProcessing API
Signed-off-by: Marcel Klehr <mklehr@gmx.net>
(cherry picked from commit ffe27ce14ca74b509c8721c9fba7c759498fa471)
Diffstat (limited to 'lib/public/TextProcessing')
-rw-r--r-- | lib/public/TextProcessing/Events/AbstractTextProcessingEvent.php | 52 | ||||
-rw-r--r-- | lib/public/TextProcessing/Events/TaskFailedEvent.php | 30 | ||||
-rw-r--r-- | lib/public/TextProcessing/Events/TaskSuccessfulEvent.php | 18 | ||||
-rw-r--r-- | lib/public/TextProcessing/FreePromptTaskType.php | 60 | ||||
-rw-r--r-- | lib/public/TextProcessing/HeadlineTaskType.php | 60 | ||||
-rw-r--r-- | lib/public/TextProcessing/IManager.php | 77 | ||||
-rw-r--r-- | lib/public/TextProcessing/IProvider.php | 61 | ||||
-rw-r--r-- | lib/public/TextProcessing/ITaskType.php | 49 | ||||
-rw-r--r-- | lib/public/TextProcessing/SummaryTaskType.php | 60 | ||||
-rw-r--r-- | lib/public/TextProcessing/Task.php | 235 | ||||
-rw-r--r-- | lib/public/TextProcessing/TopicsTaskType.php | 60 |
11 files changed, 762 insertions, 0 deletions
diff --git a/lib/public/TextProcessing/Events/AbstractTextProcessingEvent.php b/lib/public/TextProcessing/Events/AbstractTextProcessingEvent.php new file mode 100644 index 00000000000..10c592fe031 --- /dev/null +++ b/lib/public/TextProcessing/Events/AbstractTextProcessingEvent.php @@ -0,0 +1,52 @@ +<?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\Events; + +use OCP\EventDispatcher\Event; +use OCP\TextProcessing\ILanguageModelTask; +use OCP\TextProcessing\Task; + +/** + * @since 27.1.0 + */ +abstract class AbstractTextProcessingEvent extends Event { + /** + * @since 27.1.0 + */ + public function __construct( + private Task $task + ) { + parent::__construct(); + } + + /** + * @return Task + * @since 27.1.0 + */ + public function getTask(): Task { + return $this->task; + } +} diff --git a/lib/public/TextProcessing/Events/TaskFailedEvent.php b/lib/public/TextProcessing/Events/TaskFailedEvent.php new file mode 100644 index 00000000000..f9765e362dc --- /dev/null +++ b/lib/public/TextProcessing/Events/TaskFailedEvent.php @@ -0,0 +1,30 @@ +<?php + +namespace OCP\TextProcessing\Events; + +use OCP\TextProcessing\Task; + +/** + * @since 27.1.0 + */ +class TaskFailedEvent extends AbstractTextProcessingEvent { + /** + * @param Task $task + * @param string $errorMessage + * @since 27.1.0 + */ + public function __construct( + Task $task, + private string $errorMessage, + ) { + parent::__construct($task); + } + + /** + * @return string + * @since 27.1.0 + */ + public function getErrorMessage(): string { + return $this->errorMessage; + } +} diff --git a/lib/public/TextProcessing/Events/TaskSuccessfulEvent.php b/lib/public/TextProcessing/Events/TaskSuccessfulEvent.php new file mode 100644 index 00000000000..73fbbb87f45 --- /dev/null +++ b/lib/public/TextProcessing/Events/TaskSuccessfulEvent.php @@ -0,0 +1,18 @@ +<?php + +namespace OCP\TextProcessing\Events; + +use OCP\TextProcessing\Task; + +/** + * @since 27.1.0 + */ +class TaskSuccessfulEvent extends AbstractTextProcessingEvent { + /** + * @param Task $task + * @since 27.1.0 + */ + public function __construct(Task $task) { + parent::__construct($task); + } +} diff --git a/lib/public/TextProcessing/FreePromptTaskType.php b/lib/public/TextProcessing/FreePromptTaskType.php new file mode 100644 index 00000000000..aa1d6842b54 --- /dev/null +++ b/lib/public/TextProcessing/FreePromptTaskType.php @@ -0,0 +1,60 @@ +<?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; + +use OCP\IL10N; + +/** + * This is the text processing task type for free prompting + * @since 27.1.0 + */ +class FreePromptTaskType implements ITaskType { + /** + * Constructor for FreePromptTaskType + * + * @param IL10N $l + * @since 27.1.0 + */ + public function __construct( + private IL10N $l, + ) { + } + + + /** + * @inheritDoc + */ + public function getName(): string { + return $this->l->t('Free prompt'); + } + + /** + * @inheritDoc + */ + public function getDescription(): string { + return $this->l->t('Runs an arbitrary prompt through the built-in language model.'); + } +} diff --git a/lib/public/TextProcessing/HeadlineTaskType.php b/lib/public/TextProcessing/HeadlineTaskType.php new file mode 100644 index 00000000000..4ced298fd4d --- /dev/null +++ b/lib/public/TextProcessing/HeadlineTaskType.php @@ -0,0 +1,60 @@ +<?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; + +use OCP\IL10N; + +/** + * This is the text processing task type for creating headline + * @since 27.1.0 + */ +class HeadlineTaskType implements ITaskType { + /** + * Constructor for HeadlineTaskType + * + * @param IL10N $l + * @since 27.1.0 + */ + public function __construct( + private IL10N $l, + ) { + } + + + /** + * @inheritDoc + */ + public function getName(): string { + return $this->l->t('Generate headline'); + } + + /** + * @inheritDoc + */ + public function getDescription(): string { + return $this->l->t('Generates a possible headline for a text'); + } +} diff --git a/lib/public/TextProcessing/IManager.php b/lib/public/TextProcessing/IManager.php new file mode 100644 index 00000000000..90e25894d4f --- /dev/null +++ b/lib/public/TextProcessing/IManager.php @@ -0,0 +1,77 @@ +<?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; + +use OCP\Common\Exception\NotFoundException; +use OCP\PreConditionNotMetException; +use RuntimeException; + +/** + * API surface for apps interacting with and making use of LanguageModel providers + * without known which providers are installed + * @since 27.1.0 + */ +interface IManager { + /** + * @since 27.1.0 + */ + public function hasProviders(): bool; + + /** + * @return class-string<ITaskType>[] + * @since 27.1.0 + */ + public function getAvailableTaskTypes(): array; + + /** + * @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 + * @since 27.1.0 + */ + public function runTask(Task $task): string; + + /** + * Will schedule an LLM inference process in the background. The result will become available + * with the \OCP\LanguageModel\Events\TaskSuccessfulEvent + * If inference fails a \OCP\LanguageModel\Events\TaskFailedEvent will be dispatched instead + * + * @param Task $task The task to schedule + * @throws PreConditionNotMetException If no or not the requested provider was registered but this method was still called + * @since 27.1.0 + */ + public function scheduleTask(Task $task) : void; + + /** + * @param int $id The id of the task + * @return Task + * @throws RuntimeException If the query failed + * @throws NotFoundException If the task could not be found + * @since 27.1.0 + */ + public function getTask(int $id): Task; +} diff --git a/lib/public/TextProcessing/IProvider.php b/lib/public/TextProcessing/IProvider.php new file mode 100644 index 00000000000..3eb83aef8c3 --- /dev/null +++ b/lib/public/TextProcessing/IProvider.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 OCP\TextProcessing; + +use RuntimeException; + +/** + * This is the interface that is implemented by apps that + * implement a text processing provider + * @template T of ITaskType + * @since 27.1.0 + */ +interface IProvider { + /** + * The localized name of this provider + * @since 27.1.0 + */ + public function getName(): string; + + /** + * Processes a text + * + * @param string $prompt The input text + * @return string the output text + * @since 27.1.0 + * @throws RuntimeException If the text could not be processed + */ + public function process(string $prompt): string; + + /** + * Returns the task type class string of the task type, that this + * provider handles + * + * @return class-string<T> + */ + public function getTaskType(): string; +} diff --git a/lib/public/TextProcessing/ITaskType.php b/lib/public/TextProcessing/ITaskType.php new file mode 100644 index 00000000000..d08da3f7ac7 --- /dev/null +++ b/lib/public/TextProcessing/ITaskType.php @@ -0,0 +1,49 @@ +<?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 is a task type interface that is implemented by text processing + * task types + * @since 27.1.0 + */ +interface ITaskType { + /** + * Returns the localized name of this task type + * + * @since 27.1.0 + * @return string + */ + public function getName(): string; + + /** + * Returns the localized description of this task type + * + * @since 27.1.0 + * @return string + */ + public function getDescription(): string; +} diff --git a/lib/public/TextProcessing/SummaryTaskType.php b/lib/public/TextProcessing/SummaryTaskType.php new file mode 100644 index 00000000000..7db695c18f7 --- /dev/null +++ b/lib/public/TextProcessing/SummaryTaskType.php @@ -0,0 +1,60 @@ +<?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; + +use OCP\IL10N; + +/** + * This is the text processing task type for summaries + * @since 27.1.0 + */ +class SummaryTaskType implements ITaskType { + /** + * Constructor for SummaryTaskType + * + * @param IL10N $l + * @since 27.1.0 + */ + public function __construct( + private IL10N $l, + ) { + } + + + /** + * @inheritDoc + */ + public function getName(): string { + return $this->l->t('Summarize'); + } + + /** + * @inheritDoc + */ + public function getDescription(): string { + return $this->l->t('Summarizes text by reducing its length without losing key information.'); + } +} diff --git a/lib/public/TextProcessing/Task.php b/lib/public/TextProcessing/Task.php new file mode 100644 index 00000000000..59cd38b720c --- /dev/null +++ b/lib/public/TextProcessing/Task.php @@ -0,0 +1,235 @@ +<?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 is a text processing task + * @since 27.1.0 + * @template T of ITaskType + */ +final class Task implements \JsonSerializable { + protected ?int $id = null; + protected ?string $output = null; + + /** + * @since 27.1.0 + */ + public const TYPES = [ + FreePromptTaskType::class, + SummaryTaskType::class, + HeadlineTaskType::class, + TopicsTaskType::class, + ]; + + /** + * @since 27.1.0 + */ + public const STATUS_FAILED = 4; + /** + * @since 27.1.0 + */ + public const STATUS_SUCCESSFUL = 3; + /** + * @since 27.1.0 + */ + public const STATUS_RUNNING = 2; + /** + * @since 27.1.0 + */ + public const STATUS_SCHEDULED = 1; + /** + * @since 27.1.0 + */ + public const STATUS_UNKNOWN = 0; + + /** + * @psalm-var self::STATUS_* + */ + protected int $status = self::STATUS_UNKNOWN; + + /** + * @param class-string<T> $type + * @param string $input + * @param string $appId + * @param string|null $userId + * @param string $identifier An arbitrary identifier for this task. max length: 255 chars + * @since 27.1.0 + */ + final public function __construct( + protected string $type, + protected string $input, + protected string $appId, + protected ?string $userId, + protected string $identifier = '', + ) { + } + + /** + * @psalm-param IProvider<T> $provider + * @param IProvider $provider + * @return string + * @since 27.1.0 + */ + public function visitProvider(IProvider $provider): string { + if ($this->canUseProvider($provider)) { + return $provider->process($this->getInput()); + } else { + throw new \RuntimeException('Task of type ' . $this->getType() . ' cannot visit provider with task type ' . $provider->getTaskType()); + } + } + + /** + * @psalm-param IProvider<T> $provider + * @param IProvider $provider + * @return bool + * @since 27.1.0 + */ + public function canUseProvider(IProvider $provider): bool { + return $provider->getTaskType() === $this->getType(); + } + + /** + * @return class-string<T> + * @since 27.1.0 + */ + final public function getType(): string { + return $this->type; + } + + /** + * @return string|null + * @since 27.1.0 + */ + final public function getOutput(): ?string { + return $this->output; + } + + /** + * @param string|null $output + * @since 27.1.0 + */ + final public function setOutput(?string $output): void { + $this->output = $output; + } + + /** + * @psalm-return self::STATUS_* + * @since 27.1.0 + */ + final public function getStatus(): int { + return $this->status; + } + + /** + * @psalm-param self::STATUS_* $status + * @since 27.1.0 + */ + final public function setStatus(int $status): void { + $this->status = $status; + } + + /** + * @return int|null + * @since 27.1.0 + */ + final public function getId(): ?int { + return $this->id; + } + + /** + * @param int|null $id + * @since 27.1.0 + */ + final public function setId(?int $id): void { + $this->id = $id; + } + + /** + * @return string + * @since 27.1.0 + */ + final public function getInput(): string { + return $this->input; + } + + /** + * @return string + * @since 27.1.0 + */ + final public function getAppId(): string { + return $this->appId; + } + + /** + * @return string + * @since 27.1.0 + */ + final public function getIdentifier(): string { + return $this->identifier; + } + + /** + * @return string|null + * @since 27.1.0 + */ + final public function getUserId(): ?string { + return $this->userId; + } + + /** + * @return array{id: ?string, type: class-string<T>, status: int, userId: ?string, appId: string, input: string, output: ?string, identifier: string} + * @since 27.1.0 + */ + public function jsonSerialize(): array { + return [ + 'id' => $this->getId(), + 'type' => $this->getType(), + 'status' => $this->getStatus(), + 'userId' => $this->getUserId(), + 'appId' => $this->getAppId(), + 'input' => $this->getInput(), + 'output' => $this->getOutput(), + 'identifier' => $this->getIdentifier(), + ]; + } + + /** + * @param string $type + * @param string $input + * @param string|null $userId + * @param string $appId + * @param string $identifier + * @return Task + * @throws \InvalidArgumentException + * @since 27.1.0 + */ + final public static function factory(string $type, string $input, ?string $userId, string $appId, string $identifier = ''): Task { + if (!in_array($type, self::TYPES)) { + throw new \InvalidArgumentException('Unknown task type'); + } + return new Task($type, $input, $appId, $userId, $identifier); + } +} diff --git a/lib/public/TextProcessing/TopicsTaskType.php b/lib/public/TextProcessing/TopicsTaskType.php new file mode 100644 index 00000000000..8b41b3ee61a --- /dev/null +++ b/lib/public/TextProcessing/TopicsTaskType.php @@ -0,0 +1,60 @@ +<?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; + +use OCP\IL10N; + +/** + * This is the text processing task type for topics extraction + * @since 27.1.0 + */ +class TopicsTaskType implements ITaskType { + /** + * Constructor for TopicsTaskType + * + * @param IL10N $l + * @since 27.1.0 + */ + public function __construct( + private IL10N $l, + ) { + } + + + /** + * @inheritDoc + */ + public function getName(): string { + return $this->l->t('Extract topics'); + } + + /** + * @inheritDoc + */ + public function getDescription(): string { + return $this->l->t('Extracts topics from a text and outputs them separated by commas.'); + } +} |