IManager.php 4.8 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157
  1. <?php
  2. declare(strict_types=1);
  3. /**
  4. * SPDX-FileCopyrightText: 2023 Nextcloud GmbH and Nextcloud contributors
  5. * SPDX-License-Identifier: AGPL-3.0-or-later
  6. */
  7. namespace OCP\TaskProcessing;
  8. use OCP\Files\File;
  9. use OCP\Files\GenericFileException;
  10. use OCP\Files\NotPermittedException;
  11. use OCP\Lock\LockedException;
  12. use OCP\TaskProcessing\Exception\Exception;
  13. use OCP\TaskProcessing\Exception\NotFoundException;
  14. use OCP\TaskProcessing\Exception\PreConditionNotMetException;
  15. use OCP\TaskProcessing\Exception\UnauthorizedException;
  16. use OCP\TaskProcessing\Exception\ValidationException;
  17. /**
  18. * API surface for apps interacting with and making use of LanguageModel providers
  19. * without known which providers are installed
  20. * @since 30.0.0
  21. */
  22. interface IManager {
  23. /**
  24. * @since 30.0.0
  25. */
  26. public function hasProviders(): bool;
  27. /**
  28. * @return IProvider[]
  29. * @since 30.0.0
  30. */
  31. public function getProviders(): array;
  32. /**
  33. * @return array<string,array{name: string, description: string, inputShape: ShapeDescriptor[], optionalInputShape: ShapeDescriptor[], outputShape: ShapeDescriptor[], optionalOutputShape: ShapeDescriptor[]}>
  34. * @since 30.0.0
  35. */
  36. public function getAvailableTaskTypes(): array;
  37. /**
  38. * @param Task $task The task to run
  39. * @throws PreConditionNotMetException If no or not the requested provider was registered but this method was still called
  40. * @throws ValidationException the given task input didn't pass validation against the task type's input shape and/or the providers optional input shape specs
  41. * @throws Exception storing the task in the database failed
  42. * @throws UnauthorizedException the user scheduling the task does not have access to the files used in the input
  43. * @since 30.0.0
  44. */
  45. public function scheduleTask(Task $task): void;
  46. /**
  47. * Delete a task that has been scheduled before
  48. *
  49. * @param Task $task The task to delete
  50. * @throws Exception if deleting the task in the database failed
  51. * @since 30.0.0
  52. */
  53. public function deleteTask(Task $task): void;
  54. /**
  55. * @param int $id The id of the task
  56. * @return Task
  57. * @throws Exception If the query failed
  58. * @throws NotFoundException If the task could not be found
  59. * @since 30.0.0
  60. */
  61. public function getTask(int $id): Task;
  62. /**
  63. * @param int $id The id of the task
  64. * @throws Exception If the query failed
  65. * @throws NotFoundException If the task could not be found
  66. * @since 30.0.0
  67. */
  68. public function cancelTask(int $id): void;
  69. /**
  70. * @param int $id The id of the task
  71. * @param string|null $error
  72. * @param array|null $result
  73. * @throws Exception If the query failed
  74. * @throws NotFoundException If the task could not be found
  75. * @since 30.0.0
  76. */
  77. public function setTaskResult(int $id, ?string $error, ?array $result): void;
  78. /**
  79. * @param int $id
  80. * @param float $progress
  81. * @return bool `true` if the task should still be running; `false` if the task has been cancelled in the meantime
  82. * @throws ValidationException
  83. * @throws Exception
  84. * @throws NotFoundException
  85. * @since 30.0.0
  86. */
  87. public function setTaskProgress(int $id, float $progress): bool;
  88. /**
  89. * @param string|null $taskTypeId
  90. * @return Task
  91. * @throws Exception If the query failed
  92. * @throws NotFoundException If no task could not be found
  93. * @since 30.0.0
  94. */
  95. public function getNextScheduledTask(?string $taskTypeId = null): Task;
  96. /**
  97. * @param int $id The id of the task
  98. * @param string|null $userId The user id that scheduled the task
  99. * @return Task
  100. * @throws Exception If the query failed
  101. * @throws NotFoundException If the task could not be found
  102. * @since 30.0.0
  103. */
  104. public function getUserTask(int $id, ?string $userId): Task;
  105. /**
  106. * @param string|null $userId The user id that scheduled the task
  107. * @param string|null $taskTypeId The task type id to filter by
  108. * @param string|null $customId
  109. * @return list<Task>
  110. * @throws Exception If the query failed
  111. * @throws NotFoundException If the task could not be found
  112. * @since 30.0.0
  113. */
  114. public function getUserTasks(?string $userId, ?string $taskTypeId = null, ?string $customId = null): array;
  115. /**
  116. * @param string|null $userId
  117. * @param string $appId
  118. * @param string|null $customId
  119. * @return list<Task>
  120. * @throws Exception If the query failed
  121. * @throws \JsonException If parsing the task input and output failed
  122. * @since 30.0.0
  123. */
  124. public function getUserTasksByApp(?string $userId, string $appId, ?string $customId = null): array;
  125. /**
  126. * Prepare the task's input data, so it can be processed by the provider
  127. * ie. this replaces file ids with base64 data
  128. *
  129. * @param Task $task
  130. * @return array<array-key, list<numeric|string|File>|numeric|string|File>
  131. * @throws NotPermittedException
  132. * @throws GenericFileException
  133. * @throws LockedException
  134. * @throws ValidationException
  135. * @since 30.0.0
  136. */
  137. public function prepareInputData(Task $task): array;
  138. }