IManager.php 4.1 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127
  1. <?php
  2. declare(strict_types=1);
  3. /**
  4. * @copyright Copyright (c) 2023 Marcel Klehr <mklehr@gmx.net>
  5. *
  6. * @author Marcel Klehr <mklehr@gmx.net>
  7. *
  8. * @license GNU AGPL version 3 or any later version
  9. *
  10. * This program is free software: you can redistribute it and/or modify
  11. * it under the terms of the GNU Affero General Public License as
  12. * published by the Free Software Foundation, either version 3 of the
  13. * License, or (at your option) any later version.
  14. *
  15. * This program is distributed in the hope that it will be useful,
  16. * but WITHOUT ANY WARRANTY; without even the implied warranty of
  17. * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
  18. * GNU Affero General Public License for more details.
  19. *
  20. * You should have received a copy of the GNU Affero General Public License
  21. * along with this program. If not, see <http://www.gnu.org/licenses/>.
  22. */
  23. namespace OCP\TextProcessing;
  24. use OCP\Common\Exception\NotFoundException;
  25. use OCP\DB\Exception;
  26. use OCP\PreConditionNotMetException;
  27. use OCP\TextProcessing\Exception\TaskFailureException;
  28. use RuntimeException;
  29. /**
  30. * API surface for apps interacting with and making use of LanguageModel providers
  31. * without known which providers are installed
  32. * @since 27.1.0
  33. */
  34. interface IManager {
  35. /**
  36. * @since 27.1.0
  37. */
  38. public function hasProviders(): bool;
  39. /**
  40. * @return IProvider[]
  41. * @since 27.1.0
  42. */
  43. public function getProviders(): array;
  44. /**
  45. * @return string[]
  46. * @since 27.1.0
  47. */
  48. public function getAvailableTaskTypes(): array;
  49. /**
  50. * @param Task $task The task to run
  51. * @throws PreConditionNotMetException If no or not the requested provider was registered but this method was still called
  52. * @throws TaskFailureException If running the task failed
  53. * @since 27.1.0
  54. */
  55. public function runTask(Task $task): string;
  56. /**
  57. * Will schedule an LLM inference process in the background. The result will become available
  58. * with the \OCP\LanguageModel\Events\TaskSuccessfulEvent
  59. * If inference fails a \OCP\LanguageModel\Events\TaskFailedEvent will be dispatched instead
  60. *
  61. * @param Task $task The task to schedule
  62. * @throws PreConditionNotMetException If no or not the requested provider was registered but this method was still called
  63. * @throws Exception storing the task in the database failed
  64. * @since 27.1.0
  65. */
  66. public function scheduleTask(Task $task) : void;
  67. /**
  68. * If the designated provider for the passed task provides an expected average runtime, we check if the runtime fits into the
  69. * 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)
  70. * execution is deferred to a background job
  71. *
  72. * @param Task $task The task to schedule
  73. * @returns bool A boolean indicating whether the task was run synchronously (`true`) or offloaded to a background job (`false`)
  74. * @throws PreConditionNotMetException If no or not the requested provider was registered but this method was still called
  75. * @throws TaskFailureException If running the task failed
  76. * @throws Exception storing the task in the database failed
  77. * @since 28.0.0
  78. */
  79. public function runOrScheduleTask(Task $task): bool;
  80. /**
  81. * Delete a task that has been scheduled before
  82. *
  83. * @param Task $task The task to delete
  84. * @since 27.1.0
  85. */
  86. public function deleteTask(Task $task): void;
  87. /**
  88. * @param int $id The id of the task
  89. * @return Task
  90. * @throws RuntimeException If the query failed
  91. * @throws NotFoundException If the task could not be found
  92. * @since 27.1.0
  93. */
  94. public function getTask(int $id): Task;
  95. /**
  96. * @param int $id The id of the task
  97. * @param string|null $userId The user id that scheduled the task
  98. * @return Task
  99. * @throws RuntimeException If the query failed
  100. * @throws NotFoundException If the task could not be found
  101. * @since 27.1.0
  102. */
  103. public function getUserTask(int $id, ?string $userId): Task;
  104. /**
  105. * @param string $userId
  106. * @param string $appId
  107. * @param string|null $identifier
  108. * @return array
  109. * @since 27.1.0
  110. */
  111. public function getUserTasksByApp(string $userId, string $appId, ?string $identifier = null): array;
  112. }