archive
/
nextcloud
mirror of https://github.com/nextcloud/server.git
1
0
Fork 0
Code Issues Releases Wiki Activity

core: Document text processing API

Browse Source 
Signed-off-by: jld3103 <jld3103yt@gmail.com>
pull/39634/head
jld3103 10 months ago committed by Julien Veyssier
parent 8c846ce103
commit dca22c1d2c
3 changed files with 519 additions and 0 deletions
Show Stats Download Patch File Download Diff File

23
core/Controller/TextProcessingApiController.php
Unescape Escape View File

@ -27,6 +27,7 @@ declare(strict_types=1);
namespace OC\Core\Controller;
use InvalidArgumentException;
use OCA\Core\ResponseDefinitions;
use OCP\AppFramework\Http;
use OCP\AppFramework\Http\DataResponse;
use OCP\Common\Exception\NotFoundException;
@ -41,6 +42,9 @@ use Psr\Container\ContainerInterface;
use Psr\Container\NotFoundExceptionInterface;
use Psr\Log\LoggerInterface;
/**
* @psalm-import-type CoreTextProcessingTask from ResponseDefinitions
*/
class TextProcessingApiController extends \OCP\AppFramework\OCSController {
public function __construct(
string $appName,
@ -58,10 +62,13 @@ class TextProcessingApiController extends \OCP\AppFramework\OCSController {
* This endpoint returns all available LanguageModel task types
*
* @PublicPage
*
* @return DataResponse<Http::STATUS_OK, array{types: array{id: string, name: string, description: string}[]}, array{}>
*/
public function taskTypes(): DataResponse {
$typeClasses = $this->languageModelManager->getAvailableTaskTypes();
$types = [];
/** @var string $typeClass */
foreach ($typeClasses as $typeClass) {
try {
/** @var ITaskType $object */
@ -88,6 +95,17 @@ class TextProcessingApiController extends \OCP\AppFramework\OCSController {
* @PublicPage
* @UserRateThrottle(limit=20, period=120)
* @AnonRateThrottle(limit=5, period=120)
*
* @param string $input Input text
* @param string $type Type of the task
* @param string $appId ID of the app that will execute the task
* @param string $identifier An arbitrary identifier for the task
*
* @return DataResponse<Http::STATUS_OK, array{task: CoreTextProcessingTask}, array{}>|DataResponse<Http::STATUS_BAD_REQUEST|Http::STATUS_PRECONDITION_FAILED, array{message: string}, array{}>
*
* 200: Task scheduled successfully
* 400: Scheduling task is not possible
* 412: Scheduling task is not possible
*/
public function schedule(string $input, string $type, string $appId, string $identifier = ''): DataResponse {
try {
@ -114,6 +132,11 @@ class TextProcessingApiController extends \OCP\AppFramework\OCSController {
*
* @PublicPage
* @param int $id The id of the task
*
* @return DataResponse<Http::STATUS_OK, array{task: CoreTextProcessingTask}, array{}>|DataResponse<Http::STATUS_NOT_FOUND|Http::STATUS_INTERNAL_SERVER_ERROR, array{message: string}, array{}>
*
* 200: Task returned
* 404: Task not found
*/
public function getTask(int $id): DataResponse {
try {

11
core/ResponseDefinitions.php
Unescape Escape View File

@ -126,6 +126,17 @@ namespace OCA\Core;
* subline: string,
* shareWithDisplayNameUnique: string,
* }
*
* @psalm-type CoreTextProcessingTask = array{
* id: ?int,
* type: string,
* status: 0|1|2|3|4,
* userId: ?string,
* appId: string,
* input: string,
* output: ?string,
* identifier: string,
* }
*/
class ResponseDefinitions {
}

485
core/openapi.json
Unescape Escape View File

@ -372,6 +372,70 @@
}
}
},
"TextProcessingTask": {
"type": "object",
"required": [
"id",
"type",
"status",
"userId",
"appId",
"input",
"output",
"identifier"
],
"properties": {
"id": {
"type": "integer",
"format": "int64",
"nullable": true
},
"type": {
"type": "string"
},
"status": {
"oneOf": [
{
"type": "integer",
"format": "int64"
},
{
"type": "integer",
"format": "int64"
},
{
"type": "integer",
"format": "int64"
},
{
"type": "integer",
"format": "int64"
},
{
"type": "integer",
"format": "int64"
}
]
},
"userId": {
"type": "string",
"nullable": true
},
"appId": {
"type": "string"
},
"input": {
"type": "string"
},
"output": {
"type": "string",
"nullable": true
},
"identifier": {
"type": "string"
}
}
},
"UnifiedSearchProvider": {
"type": "object",
"required": [
@ -4181,6 +4245,427 @@
}
}
},
"/ocs/v2.php/textprocessing/tasktypes": {
"get": {
"operationId": "text_processing_api-task-types",
"summary": "This endpoint returns all available LanguageModel task types",
"tags": [
"text_processing_api"
],
"security": [
{},
{
"bearer_auth": []
},
{
"basic_auth": []
}
],
"parameters": [
{
"name": "OCS-APIRequest",
"in": "header",
"required": true,
"schema": {
"type": "string",
"default": "true"
}
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"ocs"
],
"properties": {
"ocs": {
"type": "object",
"required": [
"meta",
"data"
],
"properties": {
"meta": {
"$ref": "#/components/schemas/OCSMeta"
},
"data": {
"type": "object",
"required": [
"types"
],
"properties": {
"types": {
"type": "object",
"required": [
"id",
"name",
"description"
],
"properties": {
"id": {
"type": "string"
},
"name": {
"type": "string"
},
"description": {
"type": "string"
}
}
}
}
}
}
}
}
}
}
}
}
}
}
},
"/ocs/v2.php/textprocessing/schedule": {
"post": {
"operationId": "text_processing_api-schedule",
"summary": "This endpoint allows scheduling a language model task",
"tags": [
"text_processing_api"
],
"security": [
{},
{
"bearer_auth": []
},
{
"basic_auth": []
}
],
"parameters": [
{
"name": "input",
"in": "query",
"description": "Input text",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "type",
"in": "query",
"description": "Type of the task",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "appId",
"in": "query",
"description": "ID of the app that will execute the task",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "identifier",
"in": "query",
"description": "An arbitrary identifier for the task",
"schema": {
"type": "string",
"default": ""
}
},
{
"name": "OCS-APIRequest",
"in": "header",
"required": true,
"schema": {
"type": "string",
"default": "true"
}
}
],
"responses": {
"200": {
"description": "Task scheduled successfully",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"ocs"
],
"properties": {
"ocs": {
"type": "object",
"required": [
"meta",
"data"
],
"properties": {
"meta": {
"$ref": "#/components/schemas/OCSMeta"
},
"data": {
"type": "object",
"required": [
"task"
],
"properties": {
"task": {
"$ref": "#/components/schemas/TextProcessingTask"
}
}
}
}
}
}
}
}
}
},
"400": {
"description": "Scheduling task is not possible",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"ocs"
],
"properties": {
"ocs": {
"type": "object",
"required": [
"meta",
"data"
],
"properties": {
"meta": {
"$ref": "#/components/schemas/OCSMeta"
},
"data": {
"type": "object",
"required": [
"message"
],
"properties": {
"message": {
"type": "string"
}
}
}
}
}
}
}
}
}
},
"412": {
"description": "Scheduling task is not possible",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"ocs"
],
"properties": {
"ocs": {
"type": "object",
"required": [
"meta",
"data"
],
"properties": {
"meta": {
"$ref": "#/components/schemas/OCSMeta"
},
"data": {
"type": "object",
"required": [
"message"
],
"properties": {
"message": {
"type": "string"
}
}
}
}
}
}
}
}
}
}
}
}
},
"/ocs/v2.php/textprocessing/task/{id}": {
"get": {
"operationId": "text_processing_api-get-task",
"summary": "This endpoint allows checking the status and results of a task. Tasks are removed 1 week after receiving their last update.",
"tags": [
"text_processing_api"
],
"security": [
{},
{
"bearer_auth": []
},
{
"basic_auth": []
}
],
"parameters": [
{
"name": "id",
"in": "path",
"description": "The id of the task",
"required": true,
"schema": {
"type": "integer",
"format": "int64"
}
},
{
"name": "OCS-APIRequest",
"in": "header",
"required": true,
"schema": {
"type": "string",
"default": "true"
}
}
],
"responses": {
"200": {
"description": "Task returned",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"ocs"
],
"properties": {
"ocs": {
"type": "object",
"required": [
"meta",
"data"
],
"properties": {
"meta": {
"$ref": "#/components/schemas/OCSMeta"
},
"data": {
"type": "object",
"required": [
"task"
],
"properties": {
"task": {
"$ref": "#/components/schemas/TextProcessingTask"
}
}
}
}
}
}
}
}
}
},
"404": {
"description": "Task not found",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"ocs"
],
"properties": {
"ocs": {
"type": "object",
"required": [
"meta",
"data"
],
"properties": {
"meta": {
"$ref": "#/components/schemas/OCSMeta"
},
"data": {
"type": "object",
"required": [
"message"
],
"properties": {
"message": {
"type": "string"
}
}
}
}
}
}
}
}
}
},
"500": {
"description": "",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"ocs"
],
"properties": {
"ocs": {
"type": "object",
"required": [
"meta",
"data"
],
"properties": {
"meta": {
"$ref": "#/components/schemas/OCSMeta"
},
"data": {
"type": "object",
"required": [
"message"
],
"properties": {
"message": {
"type": "string"
}
}
}
}
}
}
}
}
}
}
}
}
},
"/status.php": {
"get": {
"operationId": "get-status",

Write Preview
Loading…
Cancel
Save