-
Notifications
You must be signed in to change notification settings - Fork 2.3k
feat: Add docs for \OCP\TaskProcessing #11794
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Merged
Merged
Changes from all commits
Commits
Show all changes
2 commits
Select commit
Hold shift + click to select a range
File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
256 changes: 256 additions & 0 deletions
256
developer_manual/client_apis/OCS/ocs-taskprocessing-api.rst
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,256 @@ | ||
| .. _ocs-taskprocessing-api: | ||
|
|
||
| ====================== | ||
| OCS TaskProcessing API | ||
| ====================== | ||
|
|
||
| .. versionadded:: 30.0.0 | ||
|
|
||
| The OCS Text processing API allows you to run text processing tasks, like prompting large language models implemented by apps using :ref:`the backend Text Processing API<text_processing>`. | ||
|
|
||
| The base URL for all calls to this API is: ``<nextcloud_base_url>/ocs/v2.php/taskprocessing/`` | ||
|
|
||
| All calls to OCS endpoints require the ``OCS-APIRequest`` header to be set to ``true``. | ||
|
|
||
|
|
||
| Get available task types | ||
| ------------------------ | ||
|
|
||
| .. versionadded:: 30.0.0 | ||
|
|
||
| * Method: ``GET`` | ||
| * Endpoint: ``/tasktypes`` | ||
| * Response: | ||
| - Status code: | ||
| + ``200 OK`` | ||
| - Data: | ||
|
|
||
| +----------------------+--------+---------------------------------------------------------------------------------------------------------------+ | ||
| | field | type | Description | | ||
| +----------------------+--------+---------------------------------------------------------------------------------------------------------------+ | ||
| |``types`` | array | A map of supported task types. The keys are the task type IDs See below for the values. | | ||
| +----------------------+--------+---------------------------------------------------------------------------------------------------------------+ | ||
|
|
||
| Task type fields: | ||
|
|
||
| +-----------------------+--------+---------------------------------------------------------------------------------------------------------------+ | ||
| | field | type | Description | | ||
| +-----------------------+--------+---------------------------------------------------------------------------------------------------------------+ | ||
| |``name`` | string | The name of the task type in the user's language | | ||
| +-----------------------+--------+---------------------------------------------------------------------------------------------------------------+ | ||
| |``description`` | string | A description of the task type in the user's language | | ||
| +-----------------------+--------+---------------------------------------------------------------------------------------------------------------+ | ||
| |``inputShape`` | array | The input shape of this task type | | ||
| +-----------------------+--------+---------------------------------------------------------------------------------------------------------------+ | ||
| |``outputShape`` | array | The output shape of this task type | | ||
| +-----------------------+--------+---------------------------------------------------------------------------------------------------------------+ | ||
|
|
||
| Input and output shape fields are maps from slot key to slot metadata: | ||
|
|
||
| +----------------------+--------+---------------------------------------------------------------------------------------------------------------+ | ||
| | field | type | Description | | ||
| +----------------------+--------+---------------------------------------------------------------------------------------------------------------+ | ||
| |``name`` | string | The name of the I/O slot | | ||
| +----------------------+--------+---------------------------------------------------------------------------------------------------------------+ | ||
| |``description`` | string | A description of the I/O slot | | ||
| +----------------------+--------+---------------------------------------------------------------------------------------------------------------+ | ||
| |``type`` | int | The I/O slot type (See backend API for the available types) | | ||
| +----------------------+--------+---------------------------------------------------------------------------------------------------------------+ | ||
| |``mandatory`` | bool | Whether this slot is mandatory or not | | ||
| +----------------------+--------+---------------------------------------------------------------------------------------------------------------+ | ||
|
|
||
| Schedule a task | ||
| --------------- | ||
|
|
||
| .. versionadded:: 30.0.0 | ||
|
|
||
| .. note:: The endpoint is rate limited as it can be quite resource intensive. Users can make 20 requests in 2 minutes, guests only 5 | ||
|
|
||
| * Method: ``POST`` | ||
| * Endpoint: ``/schedule`` | ||
| * Data: | ||
|
|
||
| +-----------------+-------------+--------------------------------------------------------------------------------+ | ||
| | field | type | Description | | ||
| +-----------------+-------------+--------------------------------------------------------------------------------+ | ||
| |``input`` | array | The input text for the task | | ||
| +-----------------+-------------+--------------------------------------------------------------------------------+ | ||
| |``type`` | string | Id of this task's type. | | ||
| +-----------------+-------------+--------------------------------------------------------------------------------+ | ||
| |``appId`` | string | The id of the requesting app | | ||
| +-----------------+-------------+--------------------------------------------------------------------------------+ | ||
| |``customId`` | string | An custom app-defined identifier for the task (optional) | | ||
| +-----------------+-------------+--------------------------------------------------------------------------------+ | ||
|
|
||
| * Response: | ||
| - Status code: | ||
| + ``200 OK`` | ||
| + ``400 Bad Request`` - When the task type is invalid | ||
| + ``412 Precondition Failed`` - When the task type is not available currently | ||
| + ``401 Unauthenticated`` - When the input references a file that the user doesn't have access to | ||
| + ``429 Too Many Requests`` - When the rate limiting was exceeded | ||
|
|
||
| - Data: | ||
| + ``input`` - Only provided in case of ``200 OK``, the task input, array | ||
| + ``type`` - Only provided in case of ``200 OK``, the task type, string | ||
| + ``id`` - Only provided in case of ``200 OK``, the assigned task id, int | ||
| + ``status`` - Only provided in case of ``200 OK``, the current task status, int, see backend API | ||
| + ``userId`` - Only provided in case of ``200 OK``, the originating userId of the task, string | ||
| + ``appId`` - Only provided in case of ``200 OK``, the originating appId of the task, string | ||
| + ``customId`` - Only provided in case of ``200 OK``, the custom id of the task, string | ||
| + ``output`` - Only provided in case of ``200 OK``, null | ||
| + ``message`` - Only provided when not ``200 OK``, an error message in the user's language, ready to be displayed | ||
|
|
||
| Fetch a task by ID | ||
| ------------------ | ||
|
|
||
| .. versionadded:: 30.0.0 | ||
|
|
||
| .. note:: The endpoint is rate limited as it can be quite resource intensive. Users can make 20 requests in 2 minutes, guests only 5 | ||
|
|
||
| * Method: ``POST`` | ||
| * Endpoint: ``/task/{id}`` | ||
|
|
||
| * Response: | ||
| - Status code: | ||
| + ``200 OK`` | ||
| + ``404 Not Found`` - When the task could not be found | ||
|
|
||
| - Data: | ||
| + ``input`` - Only provided in case of ``200 OK``, the task input, array | ||
| + ``type`` - Only provided in case of ``200 OK``, the task type, string | ||
| + ``id`` - Only provided in case of ``200 OK``, the assigned task id, int | ||
| + ``status`` - Only provided in case of ``200 OK``, the current task status, int, see backend API | ||
| + ``userId`` - Only provided in case of ``200 OK``, the originating userId of the task, string | ||
| + ``appId`` - Only provided in case of ``200 OK``, the originating appId of the task, string | ||
| + ``customId`` - Only provided in case of ``200 OK``, the custom id of the task, string | ||
| + ``output`` - Only provided in case of ``200 OK``, the output from the model, array or null | ||
| + ``message`` - Only provided when not ``200 OK``, an error message in the user's language, ready to be displayed | ||
|
|
||
|
|
||
| Cancel a task | ||
| ------------- | ||
|
|
||
| .. versionadded:: 30.0.0 | ||
|
|
||
| * Method: ``POST`` | ||
| * Endpoint: ``/task/{id}/cancel`` | ||
|
|
||
| * Response: | ||
| - Status code: | ||
| + ``200 OK`` | ||
| + ``404 Not Found`` - When the task could not be found | ||
|
|
||
| - Data: | ||
| - Data: | ||
| + ``input`` - Only provided in case of ``200 OK``, the task input, array | ||
| + ``type`` - Only provided in case of ``200 OK``, the task type, string | ||
| + ``id`` - Only provided in case of ``200 OK``, the assigned task id, int | ||
| + ``status`` - Only provided in case of ``200 OK``, the current task status, int, see backend API | ||
| + ``userId`` - Only provided in case of ``200 OK``, the originating userId of the task, string | ||
| + ``appId`` - Only provided in case of ``200 OK``, the originating appId of the task, string | ||
| + ``customId`` - Only provided in case of ``200 OK``, the custom id of the task, string | ||
| + ``output`` - Only provided in case of ``200 OK``, the output from the model, array or null | ||
| + ``message`` - Only provided when not ``200 OK``, an error message in the user's language, ready to be displayed | ||
|
|
||
|
|
||
| Delete a task | ||
| ------------- | ||
|
|
||
| .. versionadded:: 30.0.0 | ||
|
|
||
| * Method: ``DELETE`` | ||
| * Endpoint: ``/task/{id}`` | ||
|
|
||
| * Response: | ||
| - Status code: | ||
| + ``200 OK`` | ||
| + ``404 Not Found`` - When the task could not be found | ||
|
|
||
| - Data: | ||
| + ``message`` - Only provided when not ``200 OK``, an error message in the user's language, ready to be displayed | ||
|
|
||
|
|
||
| Get task file contents | ||
| ---------------------- | ||
|
|
||
| .. versionadded:: 30.0.0 | ||
|
|
||
| * Method: ``GET`` | ||
| * Endpoint: ``/task/{id}/file/{fileId}`` | ||
|
|
||
| * Response: | ||
| - Status code: | ||
| + ``200 OK`` | ||
| + ``404 Not Found`` - When the task could not be found | ||
|
|
||
| - Data: | ||
| + If ``200 OK`` this endpoint returns the raw data of the file | ||
| + ``message`` - Only provided when not ``200 OK``, an error message in the user's language, ready to be displayed | ||
|
|
||
| Set task progress | ||
| ----------------- | ||
|
|
||
| .. versionadded:: 30.0.0 | ||
|
|
||
| * Method: ``GET`` | ||
| * Endpoint: ``/task/{id}/progress`` | ||
| * Data: | ||
|
|
||
| +-----------------+-------------+--------------------------------------------------------------------------------+ | ||
| | field | type | Description | | ||
| +-----------------+-------------+--------------------------------------------------------------------------------+ | ||
| |``progress`` | float | A number between 0-1 indicating the task progress | | ||
| +-----------------+-------------+--------------------------------------------------------------------------------+ | ||
|
|
||
|
|
||
| * Response: | ||
| - Status code: | ||
| + ``200 OK`` | ||
| + ``404 Not Found`` - When the task could not be found | ||
|
|
||
| - Data: | ||
| - Data: | ||
| + ``input`` - Only provided in case of ``200 OK``, the task input, array | ||
| + ``type`` - Only provided in case of ``200 OK``, the task type, string | ||
| + ``id`` - Only provided in case of ``200 OK``, the assigned task id, int | ||
| + ``status`` - Only provided in case of ``200 OK``, the current task status, int, see backend API | ||
| + ``userId`` - Only provided in case of ``200 OK``, the originating userId of the task, string | ||
| + ``appId`` - Only provided in case of ``200 OK``, the originating appId of the task, string | ||
| + ``customId`` - Only provided in case of ``200 OK``, the custom id of the task, string | ||
| + ``output`` - Only provided in case of ``200 OK``, the output from the model, array or null | ||
| + ``message`` - Only provided when not ``200 OK``, an error message in the user's language, ready to be displayed | ||
|
|
||
| Set task result | ||
| --------------- | ||
|
|
||
| .. versionadded:: 30.0.0 | ||
|
|
||
| * Method: ``POST`` | ||
| * Endpoint: ``/task/{id}/result`` | ||
| * Data: | ||
|
|
||
| +-----------------+-------------+--------------------------------------------------------------------------------+ | ||
| | field | type | Description | | ||
| +-----------------+-------------+--------------------------------------------------------------------------------+ | ||
| |``output`` | array | The task output if the task was successful (optional) | | ||
| +-----------------+-------------+--------------------------------------------------------------------------------+ | ||
| |``errorMessage`` | string | The error message if the task failed (optional) | | ||
| +-----------------+-------------+--------------------------------------------------------------------------------+ | ||
|
|
||
| * Response: | ||
| - Status code: | ||
| + ``200 OK`` | ||
| + ``404 Not Found`` - When the task could not be found | ||
|
|
||
| - Data: | ||
| - Data: | ||
| + ``input`` - Only provided in case of ``200 OK``, the task input, array | ||
| + ``type`` - Only provided in case of ``200 OK``, the task type, string | ||
| + ``id`` - Only provided in case of ``200 OK``, the assigned task id, int | ||
| + ``status`` - Only provided in case of ``200 OK``, the current task status, int, see backend API | ||
| + ``userId`` - Only provided in case of ``200 OK``, the originating userId of the task, string | ||
| + ``appId`` - Only provided in case of ``200 OK``, the originating appId of the task, string | ||
| + ``customId`` - Only provided in case of ``200 OK``, the custom id of the task, string | ||
| + ``output`` - Only provided in case of ``200 OK``, the output from the model, array or null | ||
| + ``message`` - Only provided when not ``200 OK``, an error message in the user's language, ready to be displayed | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Can it be:
without multiple "Only provided in case of
200 OK" belowThere was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
there's a single entry for when it's not 200 OK, I copied this pattern from other OCS docs so 🤷