From 457f1eb4075a01f42fef8df4ccffa8d7a4b5e826 Mon Sep 17 00:00:00 2001
From: Marcel Klehr <mklehr@gmx.net>
Date: Thu, 15 Jun 2023 13:22:16 +0200
Subject: [PATCH] LLM OCP API: Rework to use Task objects

Signed-off-by: Marcel Klehr <mklehr@gmx.net>
(cherry picked from commit 01dd1a894dbf9eb6ed1fb013c4b5ee4816c32904)
---
 .../AbstractLanguageModelTask.php             | 72 +++++++++++++++++++
 .../Events/AbstractLanguageModelEvent.php     | 25 ++-----
 .../Events/PromptFailedEvent.php              | 24 -------
 .../Events/PromptSuccessfulEvent.php          | 23 ------
 .../Events/SummaryFailedEvent.php             | 24 -------
 .../Events/SummarySuccessfulEvent.php         | 23 ------
 .../LanguageModel/Events/TaskFailedEvent.php  | 23 ++++++
 .../Events/TaskSuccessfulEvent.php            | 23 ++++++
 lib/public/LanguageModel/FreePromptTask.php   | 25 +++++++
 .../LanguageModel/ILanguageModelManager.php   | 43 +++--------
 lib/public/LanguageModel/ISummaryProvider.php |  2 +-
 lib/public/LanguageModel/SummaryTask.php      | 28 ++++++++
 12 files changed, 185 insertions(+), 150 deletions(-)
 create mode 100644 lib/public/LanguageModel/AbstractLanguageModelTask.php
 delete mode 100644 lib/public/LanguageModel/Events/PromptFailedEvent.php
 delete mode 100644 lib/public/LanguageModel/Events/PromptSuccessfulEvent.php
 delete mode 100644 lib/public/LanguageModel/Events/SummaryFailedEvent.php
 delete mode 100644 lib/public/LanguageModel/Events/SummarySuccessfulEvent.php
 create mode 100644 lib/public/LanguageModel/Events/TaskFailedEvent.php
 create mode 100644 lib/public/LanguageModel/Events/TaskSuccessfulEvent.php
 create mode 100644 lib/public/LanguageModel/FreePromptTask.php
 create mode 100644 lib/public/LanguageModel/SummaryTask.php

diff --git a/lib/public/LanguageModel/AbstractLanguageModelTask.php b/lib/public/LanguageModel/AbstractLanguageModelTask.php
new file mode 100644
index 00000000000..50ae2095235
--- /dev/null
+++ b/lib/public/LanguageModel/AbstractLanguageModelTask.php
@@ -0,0 +1,72 @@
+<?php
+
+namespace OCP\LanguageModel;
+
+abstract class AbstractLanguageModelTask {
+
+	public const STATUS_UNKNOWN = 0;
+	public const STATUS_RUNNING = 1;
+	public const STATUS_SUCCESSFUL = 2;
+	public const STATUS_FAILED = 4;
+
+	protected ?int $id;
+	protected int $status = self::STATUS_UNKNOWN;
+
+	public function __construct(
+		protected string $input,
+		protected string $appId,
+		protected ?string $userId,
+	) {
+	}
+
+	abstract public function visitProvider(ILanguageModelProvider $provider): string;
+
+	/**
+	 * @return int
+	 */
+	public function getStatus(): int {
+		return $this->status;
+	}
+
+	/**
+	 * @param int $status
+	 */
+	public function setStatus(int $status): void {
+		$this->status = $status;
+	}
+
+	/**
+	 * @return int|null
+	 */
+	public function getId(): ?int {
+		return $this->id;
+	}
+
+	/**
+	 * @param int|null $id
+	 */
+	public function setId(?int $id): void {
+		$this->id = $id;
+	}
+
+	/**
+	 * @return string
+	 */
+	public function getInput(): string {
+		return $this->input;
+	}
+
+	/**
+	 * @return string
+	 */
+	public function getAppId(): string {
+		return $this->appId;
+	}
+
+	/**
+	 * @return string|null
+	 */
+	public function getUserId(): ?string {
+		return $this->userId;
+	}
+}
diff --git a/lib/public/LanguageModel/Events/AbstractLanguageModelEvent.php b/lib/public/LanguageModel/Events/AbstractLanguageModelEvent.php
index 593385b02f0..3d274330dc7 100644
--- a/lib/public/LanguageModel/Events/AbstractLanguageModelEvent.php
+++ b/lib/public/LanguageModel/Events/AbstractLanguageModelEvent.php
@@ -26,6 +26,7 @@ declare(strict_types=1);
 namespace OCP\LanguageModel\Events;
 
 use OCP\EventDispatcher\Event;
+use OCP\LanguageModel\AbstractLanguageModelTask;
 
 /**
  * @since 28.0.0
@@ -35,32 +36,16 @@ abstract class AbstractLanguageModelEvent extends Event {
 	 * @since 28.0.0
 	 */
 	public function __construct(
-		private int $requestId,
-		private ?string $userId,
-		private string $appId,
+		private AbstractLanguageModelTask $task
 	) {
 		parent::__construct();
 	}
 
 	/**
+	 * @return AbstractLanguageModelTask
 	 * @since 28.0.0
 	 */
-	public function getRequestId(): int {
-		return $this->requestId;
-	}
-
-
-	/**
-	 * @since 28.0.0
-	 */
-	public function getUserId(): ?string {
-		return $this->userId;
-	}
-
-	/**
-	 * @since 28.0.0
-	 */
-	public function getAppId(): string {
-		return $this->appId;
+	public function getTask(): AbstractLanguageModelTask {
+		return $this->task;
 	}
 }
diff --git a/lib/public/LanguageModel/Events/PromptFailedEvent.php b/lib/public/LanguageModel/Events/PromptFailedEvent.php
deleted file mode 100644
index 2ad8848d084..00000000000
--- a/lib/public/LanguageModel/Events/PromptFailedEvent.php
+++ /dev/null
@@ -1,24 +0,0 @@
-<?php
-
-namespace OCP\LanguageModel\Events;
-
-/**
- * @since 28.0.0
- */
-class PromptFailedEvent extends AbstractLanguageModelEvent {
-
-	public function __construct(int $requestId,
-								?string $userId,
-								string $appId,
-								private string $errorMessage) {
-		parent::__construct($requestId, $userId, $appId);
-	}
-
-	/**
-	 * @since 28.0.0
-	 * @return string
-	 */
-	public function getErrorMessage(): string {
-		return $this->errorMessage;
-	}
-}
diff --git a/lib/public/LanguageModel/Events/PromptSuccessfulEvent.php b/lib/public/LanguageModel/Events/PromptSuccessfulEvent.php
deleted file mode 100644
index f9e3a612318..00000000000
--- a/lib/public/LanguageModel/Events/PromptSuccessfulEvent.php
+++ /dev/null
@@ -1,23 +0,0 @@
-<?php
-
-namespace OCP\LanguageModel\Events;
-
-/**
- * @since 28.0.0
- */
-class PromptSuccessfulEvent extends AbstractLanguageModelEvent {
-
-	public function __construct(int $requestId,
-								?string $userId,
-								string $appId,
-								private string $output) {
-		parent::__construct($requestId, $userId, $appId);
-	}
-
-	/**
-	 * @return string
-	 */
-	public function getOutput(): string {
-		return $this->output;
-	}
-}
diff --git a/lib/public/LanguageModel/Events/SummaryFailedEvent.php b/lib/public/LanguageModel/Events/SummaryFailedEvent.php
deleted file mode 100644
index 49070656ec4..00000000000
--- a/lib/public/LanguageModel/Events/SummaryFailedEvent.php
+++ /dev/null
@@ -1,24 +0,0 @@
-<?php
-
-namespace OCP\LanguageModel\Events;
-
-/**
- * @since 28.0.0
- */
-class SummaryFailedEvent extends AbstractLanguageModelEvent {
-
-	public function __construct(int $requestId,
-								?string $userId,
-								string $appId,
-								private string $errorMessage) {
-		parent::__construct($requestId, $userId, $appId);
-	}
-
-	/**
-	 * @since 28.0.0
-	 * @return string
-	 */
-	public function getErrorMessage(): string {
-		return $this->errorMessage;
-	}
-}
diff --git a/lib/public/LanguageModel/Events/SummarySuccessfulEvent.php b/lib/public/LanguageModel/Events/SummarySuccessfulEvent.php
deleted file mode 100644
index 353394438f0..00000000000
--- a/lib/public/LanguageModel/Events/SummarySuccessfulEvent.php
+++ /dev/null
@@ -1,23 +0,0 @@
-<?php
-
-namespace OCP\LanguageModel\Events;
-
-/**
- * @since 28.0.0
- */
-class SummarySuccessfulEvent extends AbstractLanguageModelEvent {
-
-	public function __construct(int $requestId,
-								?string $userId,
-								string $appId,
-								private string $output) {
-		parent::__construct($requestId, $userId, $appId);
-	}
-
-	/**
-	 * @return string
-	 */
-	public function getOutput(): string {
-		return $this->output;
-	}
-}
diff --git a/lib/public/LanguageModel/Events/TaskFailedEvent.php b/lib/public/LanguageModel/Events/TaskFailedEvent.php
new file mode 100644
index 00000000000..2b0dea9153f
--- /dev/null
+++ b/lib/public/LanguageModel/Events/TaskFailedEvent.php
@@ -0,0 +1,23 @@
+<?php
+
+namespace OCP\LanguageModel\Events;
+
+use OCP\LanguageModel\AbstractLanguageModelTask;
+
+/**
+ * @since 28.0.0
+ */
+class TaskFailedEvent extends AbstractLanguageModelEvent {
+
+	public function __construct(AbstractLanguageModelTask $task,
+								private string $errorMessage) {
+		parent::__construct($task);
+	}
+
+	/**
+	 * @return string
+	 */
+	public function getErrorMessage(): string {
+		return $this->errorMessage;
+	}
+}
diff --git a/lib/public/LanguageModel/Events/TaskSuccessfulEvent.php b/lib/public/LanguageModel/Events/TaskSuccessfulEvent.php
new file mode 100644
index 00000000000..6cdb57143f9
--- /dev/null
+++ b/lib/public/LanguageModel/Events/TaskSuccessfulEvent.php
@@ -0,0 +1,23 @@
+<?php
+
+namespace OCP\LanguageModel\Events;
+
+use OCP\LanguageModel\AbstractLanguageModelTask;
+
+/**
+ * @since 28.0.0
+ */
+class TaskSuccessfulEvent extends AbstractLanguageModelEvent {
+
+	public function __construct(AbstractLanguageModelTask $task,
+								private string $output) {
+		parent::__construct($task);
+	}
+
+	/**
+	 * @return string
+	 */
+	public function getErrorMessage(): string {
+		return $this->output;
+	}
+}
diff --git a/lib/public/LanguageModel/FreePromptTask.php b/lib/public/LanguageModel/FreePromptTask.php
new file mode 100644
index 00000000000..ff7fa7fffed
--- /dev/null
+++ b/lib/public/LanguageModel/FreePromptTask.php
@@ -0,0 +1,25 @@
+<?php
+
+namespace OCP\LanguageModel;
+
+use RuntimeException;
+
+class FreePromptTask extends AbstractLanguageModelTask {
+
+	/**
+	 * @param ILanguageModelProvider $provider
+	 * @throws RuntimeException
+	 * @return string
+	 */
+	public function visitProvider(ILanguageModelProvider $provider): string {
+		$this->setStatus(self::STATUS_RUNNING);
+		try {
+			$output = $provider->prompt($this->getInput());
+		} catch (RuntimeException $e) {
+			$this->setStatus(self::STATUS_FAILED);
+			throw $e;
+		}
+		$this->setStatus(self::STATUS_SUCCESSFUL);
+		return $output;
+	}
+}
diff --git a/lib/public/LanguageModel/ILanguageModelManager.php b/lib/public/LanguageModel/ILanguageModelManager.php
index 68053099955..e0d33777052 100644
--- a/lib/public/LanguageModel/ILanguageModelManager.php
+++ b/lib/public/LanguageModel/ILanguageModelManager.php
@@ -27,6 +27,7 @@ declare(strict_types=1);
 namespace OCP\LanguageModel;
 
 use InvalidArgumentException;
+use OCP\LanguageModel\Events\AbstractLanguageModelEvent;
 use OCP\PreConditionNotMetException;
 use RuntimeException;
 
@@ -37,53 +38,25 @@ interface ILanguageModelManager {
 	public function hasProviders(): bool;
 
 	/**
+	 * @return string[]
 	 * @since 28.0.0
 	 */
-	public function hasSummaryProviders(): bool;
+	public function getAvailableTasks(): array;
 
 	/**
-	 * @param string $prompt The prompt to call the Language model with
-	 * @returns string The output
-	 * @throws PreConditionNotMetException If no provider was registered but this method was still called
+	 * @throws PreConditionNotMetException If no or not the requested provider was registered but this method was still called
 	 * @throws InvalidArgumentException If the file could not be found or is not of a supported type
 	 * @throws RuntimeException If the transcription failed for other reasons
 	 * @since 28.0.0
 	 */
-	public function prompt(string $prompt): string;
+	public function runTask(AbstractLanguageModelTask $task): AbstractLanguageModelEvent;
 
 	/**
 	 * Will schedule an LLM inference process in the background. The result will become available
-	 * with the \OCP\LanguageModel\Events\PromptFinishedEvent
+	 * with the \OCP\LanguageModel\Events\TaskFinishedEvent
 	 *
-	 * @param string $prompt The prompt to call the Language model with
-	 * @param ?string $userId The user that triggered this request (only for convenience, will be available on the TranscriptEvents)
-	 * @param string $appId The app that triggered this request (only for convenience, will be available on the TranscriptEvents)
-	 * @returns int The id of the prompt request
-	 * @throws PreConditionNotMetException If no provider was registered but this method was still called
+	 * @throws PreConditionNotMetException If no or not the requested provider was registered but this method was still called
 	 * @since 28.0.0
 	 */
-	public function schedulePrompt(string $prompt, ?string $userId, string $appId): int;
-
-	/**
-	 * Will schedule an LLM inference process in the background. The result will become available
-	 * with the \OCP\LanguageModel\Events\PromptFinishedEvent
-	 *
-	 * @param string $text The text to summarize
-	 * @param ?string $userId The user that triggered this request (only for convenience, will be available on the TranscriptEvents)
-	 * @param string $appId The app that triggered this request (only for convenience, will be available on the TranscriptEvents)
-	 * @returns int The id of the prompt request
-	 * @throws PreConditionNotMetException If no summary provider was registered but this method was still called
-	 * @since 28.0.0
-	 */
-	public function scheduleSummary(string $text, ?string $userId, string $appId): int;
-
-	/**
-	 * @param string $text The text to summarize
-	 * @returns string The output
-	 * @throws PreConditionNotMetException If no summary provider was registered but this method was still called
-	 * @throws InvalidArgumentException If the file could not be found or is not of a supported type
-	 * @throws RuntimeException If the transcription failed for other reasons
-	 * @since 28.0.0
-	 */
-	public function summarize(string $text): string;
+	public function scheduleTask(AbstractLanguageModelTask $task) : void;
 }
diff --git a/lib/public/LanguageModel/ISummaryProvider.php b/lib/public/LanguageModel/ISummaryProvider.php
index 125ef313f80..fa4bf873e8f 100644
--- a/lib/public/LanguageModel/ISummaryProvider.php
+++ b/lib/public/LanguageModel/ISummaryProvider.php
@@ -31,7 +31,7 @@ use RuntimeException;
 /**
  * @since 28.0.0
  */
-interface ISummaryProvider {
+interface ISummaryProvider extends ILanguageModelProvider {
 
 	/**
 	 * @param string $text The text to summarize
diff --git a/lib/public/LanguageModel/SummaryTask.php b/lib/public/LanguageModel/SummaryTask.php
new file mode 100644
index 00000000000..0037beb4593
--- /dev/null
+++ b/lib/public/LanguageModel/SummaryTask.php
@@ -0,0 +1,28 @@
+<?php
+
+namespace OCP\LanguageModel;
+
+use RuntimeException;
+
+class SummaryTask extends AbstractLanguageModelTask {
+
+	/**
+	 * @param ILanguageModelProvider&ISummaryProvider $provider
+	 * @throws RuntimeException
+	 * @return string
+	 */
+	public function visitProvider(ILanguageModelProvider $provider): string {
+		if (!$provider instanceof ISummaryProvider) {
+			throw new \RuntimeException('SummaryTask#visitProvider expects ISummaryProvider');
+		}
+		$this->setStatus(self::STATUS_RUNNING);
+		try {
+			$output = $provider->summarize($this->getInput());
+		} catch (RuntimeException $e) {
+			$this->setStatus(self::STATUS_FAILED);
+			throw $e;
+		}
+		$this->setStatus(self::STATUS_SUCCESSFUL);
+		return $output;
+	}
+}
-- 
2.39.5