10 files changed, 502 insertions, 0 deletions
diff --git a/lib/public/TextToImage/Events/AbstractTextToImageEvent.php b/lib/public/TextToImage/Events/AbstractTextToImageEvent.php
new file mode 100644
index 00000000000..df850e1be33
--- /dev/null
+++ b/lib/public/TextToImage/Events/AbstractTextToImageEvent.php
@@ -0,0 +1,36 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * SPDX-FileCopyrightText: 2023 Nextcloud GmbH and Nextcloud contributors
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+namespace OCP\TextToImage\Events;
+
+use OCP\EventDispatcher\Event;
+use OCP\TextToImage\Task;
+
+/**
+ * @since 28.0.0
+ * @deprecated 30.0.0
+ */
+abstract class AbstractTextToImageEvent extends Event {
+	/**
+	 * @since 28.0.0
+	 */
+	public function __construct(
+		private Task $task,
+	) {
+		parent::__construct();
+	}
+
+	/**
+	 * @return Task
+	 * @since 28.0.0
+	 */
+	public function getTask(): Task {
+		return $this->task;
+	}
+}
diff --git a/lib/public/TextToImage/Events/TaskFailedEvent.php b/lib/public/TextToImage/Events/TaskFailedEvent.php
new file mode 100644
index 00000000000..8a1b8bbad61
--- /dev/null
+++ b/lib/public/TextToImage/Events/TaskFailedEvent.php
@@ -0,0 +1,38 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * SPDX-FileCopyrightText: 2023 Nextcloud GmbH and Nextcloud contributors
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+namespace OCP\TextToImage\Events;
+
+use OCP\TextToImage\Task;
+
+/**
+ * @since 28.0.0
+ * @deprecated 30.0.0
+ */
+class TaskFailedEvent extends AbstractTextToImageEvent {
+	/**
+	 * @param Task $task
+	 * @param string $errorMessage
+	 * @since 28.0.0
+	 */
+	public function __construct(
+		Task $task,
+		private string $errorMessage,
+	) {
+		parent::__construct($task);
+	}
+
+	/**
+	 * @return string
+	 * @since 28.0.0
+	 */
+	public function getErrorMessage(): string {
+		return $this->errorMessage;
+	}
+}
diff --git a/lib/public/TextToImage/Events/TaskSuccessfulEvent.php b/lib/public/TextToImage/Events/TaskSuccessfulEvent.php
new file mode 100644
index 00000000000..ae679437457
--- /dev/null
+++ b/lib/public/TextToImage/Events/TaskSuccessfulEvent.php
@@ -0,0 +1,17 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * SPDX-FileCopyrightText: 2023 Nextcloud GmbH and Nextcloud contributors
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+namespace OCP\TextToImage\Events;
+
+/**
+ * @since 28.0.0
+ * @deprecated 30.0.0
+ */
+class TaskSuccessfulEvent extends AbstractTextToImageEvent {
+}
diff --git a/lib/public/TextToImage/Exception/TaskFailureException.php b/lib/public/TextToImage/Exception/TaskFailureException.php
new file mode 100644
index 00000000000..89144c3033a
--- /dev/null
+++ b/lib/public/TextToImage/Exception/TaskFailureException.php
@@ -0,0 +1,15 @@
+<?php
+
+/**
+ * SPDX-FileCopyrightText: 2023 Nextcloud GmbH and Nextcloud contributors
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+namespace OCP\TextToImage\Exception;
+
+/**
+ * @since 28.0.0
+ * @deprecated 30.0.0
+ */
+class TaskFailureException extends TextToImageException {
+}
diff --git a/lib/public/TextToImage/Exception/TaskNotFoundException.php b/lib/public/TextToImage/Exception/TaskNotFoundException.php
new file mode 100644
index 00000000000..a488eceb7f4
--- /dev/null
+++ b/lib/public/TextToImage/Exception/TaskNotFoundException.php
@@ -0,0 +1,15 @@
+<?php
+
+/**
+ * SPDX-FileCopyrightText: 2023 Nextcloud GmbH and Nextcloud contributors
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+namespace OCP\TextToImage\Exception;
+
+/**
+ * @since 28.0.0
+ * @deprecated 30.0.0
+ */
+class TaskNotFoundException extends TextToImageException {
+}
diff --git a/lib/public/TextToImage/Exception/TextToImageException.php b/lib/public/TextToImage/Exception/TextToImageException.php
new file mode 100644
index 00000000000..d8672544072
--- /dev/null
+++ b/lib/public/TextToImage/Exception/TextToImageException.php
@@ -0,0 +1,15 @@
+<?php
+
+/**
+ * SPDX-FileCopyrightText: 2023 Nextcloud GmbH and Nextcloud contributors
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+namespace OCP\TextToImage\Exception;
+
+/**
+ * @since 28.0.0
+ * @deprecated 30.0.0
+ */
+class TextToImageException extends \Exception {
+}
diff --git a/lib/public/TextToImage/IManager.php b/lib/public/TextToImage/IManager.php
new file mode 100644
index 00000000000..df8adfc39f4
--- /dev/null
+++ b/lib/public/TextToImage/IManager.php
@@ -0,0 +1,101 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * SPDX-FileCopyrightText: 2023 Nextcloud GmbH and Nextcloud contributors
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+
+namespace OCP\TextToImage;
+
+use OCP\DB\Exception;
+use OCP\PreConditionNotMetException;
+use OCP\TextToImage\Exception\TaskFailureException;
+use OCP\TextToImage\Exception\TaskNotFoundException;
+use RuntimeException;
+
+/**
+ * API surface for apps interacting with and making use of TextToImage providers
+ * without knowing which providers are installed
+ * @since 28.0.0
+ * @deprecated 30.0.0
+ */
+interface IManager {
+	/**
+	 * @since 28.0.0
+	 */
+	public function hasProviders(): bool;
+
+	/**
+	 * @since 28.0.0
+	 * @return list<IProvider>
+	 */
+	public function getProviders(): 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 TaskFailureException If something else failed. When this is thrown task status was already set to failure.
+	 * @since 28.0.0
+	 */
+	public function runTask(Task $task): void;
+
+	/**
+	 * Will schedule a TextToImage process in the background. The result will become available
+	 * with the \OCP\TextToImage\TaskSuccessfulEvent
+	 * If inference fails a \OCP\TextToImage\Events\TaskFailedEvent will be dispatched instead
+	 *
+	 * @param Task $task The task to schedule
+	 * @throws PreConditionNotMetException If no provider was registered but this method was still called
+	 * @throws Exception If there was a problem inserting the task into the database
+	 * @since 28.0.0
+	 */
+	public function scheduleTask(Task $task) : void;
+
+	/**
+	 * @throws Exception if there was a problem inserting the task into the database
+	 * @throws PreConditionNotMetException if no provider is registered
+	 * @throws TaskFailureException If the task run failed
+	 * @since 28.0.0
+	 */
+	public function runOrScheduleTask(Task $task) : void;
+
+	/**
+	 * Delete a task that has been scheduled before
+	 *
+	 * @param Task $task The task to delete
+	 * @since 28.0.0
+	 */
+	public function deleteTask(Task $task): void;
+
+	/**
+	 * @param int $id The id of the task
+	 * @return Task
+	 * @throws RuntimeException If the query failed
+	 * @throws TaskNotFoundException If the task could not be found
+	 * @since 28.0.0
+	 */
+	public function getTask(int $id): Task;
+
+	/**
+	 * @param int $id The id of the task
+	 * @param string|null $userId The user id that scheduled the task
+	 * @return Task
+	 * @throws RuntimeException If the query failed
+	 * @throws TaskNotFoundException If the task could not be found
+	 * @since 28.0.0
+	 */
+	public function getUserTask(int $id, ?string $userId): Task;
+
+	/**
+	 * @param ?string $userId
+	 * @param string $appId
+	 * @param string|null $identifier
+	 * @return Task[]
+	 * @since 28.0.0
+	 * @throws RuntimeException If the query failed
+	 */
+	public function getUserTasksByApp(?string $userId, string $appId, ?string $identifier = null): array;
+}
diff --git a/lib/public/TextToImage/IProvider.php b/lib/public/TextToImage/IProvider.php
new file mode 100644
index 00000000000..4a278a0d706
--- /dev/null
+++ b/lib/public/TextToImage/IProvider.php
@@ -0,0 +1,49 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * SPDX-FileCopyrightText: 2023 Nextcloud GmbH and Nextcloud contributors
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+namespace OCP\TextToImage;
+
+use RuntimeException;
+
+/**
+ * This is the interface that is implemented by apps that
+ * implement a text to image provider
+ * @since 28.0.0
+ * @deprecated 30.0.0
+ */
+interface IProvider {
+	/**
+	 * An arbitrary unique text string identifying this provider
+	 * @since 28.0.0
+	 */
+	public function getId(): string;
+
+	/**
+	 * The localized name of this provider
+	 * @since 28.0.0
+	 */
+	public function getName(): string;
+
+	/**
+	 * Processes a text
+	 *
+	 * @param string $prompt The input text
+	 * @param resource[] $resources The file resources to write the images to
+	 * @return void
+	 * @since 28.0.0
+	 * @throws RuntimeException If the text could not be processed
+	 */
+	public function generate(string $prompt, array $resources): void;
+
+	/**
+	 * The expected runtime for one task with this provider in seconds
+	 * @since 28.0.0
+	 */
+	public function getExpectedRuntime(): int;
+}
diff --git a/lib/public/TextToImage/IProviderWithUserId.php b/lib/public/TextToImage/IProviderWithUserId.php
new file mode 100644
index 00000000000..a3eedbd9dc0
--- /dev/null
+++ b/lib/public/TextToImage/IProviderWithUserId.php
@@ -0,0 +1,19 @@
+<?php
+
+declare(strict_types=1);
+/**
+ * SPDX-FileCopyrightText: 2024 Nextcloud GmbH and Nextcloud contributors
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+namespace OCP\TextToImage;
+
+/**
+ * @since 29.0.0
+ * @deprecated 30.0.0
+ */
+interface IProviderWithUserId extends IProvider {
+	/**
+	 * @since 29.0.0
+	 */
+	public function setUserId(?string $userId): void;
+}
diff --git a/lib/public/TextToImage/Task.php b/lib/public/TextToImage/Task.php
new file mode 100644
index 00000000000..7b94de0fbb3
--- /dev/null
+++ b/lib/public/TextToImage/Task.php
@@ -0,0 +1,197 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * SPDX-FileCopyrightText: 2023 Nextcloud GmbH and Nextcloud contributors
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+namespace OCP\TextToImage;
+
+use DateTime;
+use OCP\Files\AppData\IAppDataFactory;
+use OCP\Files\NotFoundException;
+use OCP\Files\NotPermittedException;
+use OCP\IImage;
+use OCP\Image;
+
+/**
+ * This is a text to image task
+ *
+ * @since 28.0.0
+ * @deprecated 30.0.0
+ */
+final class Task implements \JsonSerializable {
+	protected ?int $id = null;
+
+	protected ?DateTime $completionExpectedAt = null;
+
+	/**
+	 * @since 28.0.0
+	 */
+	public const STATUS_FAILED = 4;
+	/**
+	 * @since 28.0.0
+	 */
+	public const STATUS_SUCCESSFUL = 3;
+	/**
+	 * @since 28.0.0
+	 */
+	public const STATUS_RUNNING = 2;
+	/**
+	 * @since 28.0.0
+	 */
+	public const STATUS_SCHEDULED = 1;
+	/**
+	 * @since 28.0.0
+	 */
+	public const STATUS_UNKNOWN = 0;
+
+	/**
+	 * @psalm-var self::STATUS_*
+	 */
+	protected int $status = self::STATUS_UNKNOWN;
+
+	/**
+	 * @param string $input
+	 * @param string $appId
+	 * @param int $numberOfImages
+	 * @param string|null $userId
+	 * @param null|string $identifier An arbitrary identifier for this task. max length: 255 chars
+	 * @since 28.0.0
+	 */
+	final public function __construct(
+		protected string $input,
+		protected string $appId,
+		protected int $numberOfImages,
+		protected ?string $userId,
+		protected ?string $identifier = '',
+	) {
+	}
+
+	/**
+	 * @return IImage[]|null
+	 * @since 28.0.0
+	 */
+	final public function getOutputImages(): ?array {
+		$appData = \OCP\Server::get(IAppDataFactory::class)->get('core');
+		try {
+			$folder = $appData->getFolder('text2image')->getFolder((string)$this->getId());
+			$images = [];
+			for ($i = 0; $i < $this->getNumberOfImages(); $i++) {
+				$image = new Image();
+				$image->loadFromFileHandle($folder->getFile((string)$i)->read());
+				$images[] = $image;
+			}
+			return $images;
+		} catch (NotFoundException|NotPermittedException) {
+			return null;
+		}
+	}
+
+	/**
+	 * @return int
+	 * @since 28.0.0
+	 */
+	final public function getNumberOfImages(): int {
+		return $this->numberOfImages;
+	}
+
+	/**
+	 * @psalm-return self::STATUS_*
+	 * @since 28.0.0
+	 */
+	final public function getStatus(): int {
+		return $this->status;
+	}
+
+	/**
+	 * @psalm-param self::STATUS_* $status
+	 * @since 28.0.0
+	 */
+	final public function setStatus(int $status): void {
+		$this->status = $status;
+	}
+
+	/**
+	 * @param ?DateTime $at
+	 * @since 28.0.0
+	 */
+	final public function setCompletionExpectedAt(?DateTime $at): void {
+		$this->completionExpectedAt = $at;
+	}
+
+	/**
+	 * @return ?DateTime
+	 * @since 28.0.0
+	 */
+	final public function getCompletionExpectedAt(): ?DateTime {
+		return $this->completionExpectedAt;
+	}
+
+	/**
+	 * @return int|null
+	 * @since 28.0.0
+	 */
+	final public function getId(): ?int {
+		return $this->id;
+	}
+
+	/**
+	 * @param int|null $id
+	 * @since 28.0.0
+	 */
+	final public function setId(?int $id): void {
+		$this->id = $id;
+	}
+
+	/**
+	 * @return string
+	 * @since 28.0.0
+	 */
+	final public function getInput(): string {
+		return $this->input;
+	}
+
+	/**
+	 * @return string
+	 * @since 28.0.0
+	 */
+	final public function getAppId(): string {
+		return $this->appId;
+	}
+
+	/**
+	 * @return null|string
+	 * @since 28.0.0
+	 */
+	final public function getIdentifier(): ?string {
+		return $this->identifier;
+	}
+
+	/**
+	 * @return string|null
+	 * @since 28.0.0
+	 */
+	final public function getUserId(): ?string {
+		return $this->userId;
+	}
+
+	/**
+	 * @psalm-return array{id: ?int, status: self::STATUS_*, userId: ?string, appId: string, input: string, identifier: ?string, numberOfImages: int, completionExpectedAt: ?int}
+	 * @since 28.0.0
+	 */
+	public function jsonSerialize(): array {
+		return [
+			'id' => $this->getId(),
+			'status' => $this->getStatus(),
+			'userId' => $this->getUserId(),
+			'appId' => $this->getAppId(),
+			'numberOfImages' => $this->getNumberOfImages(),
+			'input' => $this->getInput(),
+			'identifier' => $this->getIdentifier(),
+			'completionExpectedAt' => $this->getCompletionExpectedAt()->getTimestamp(),
+		];
+	}
+}