Skip to content

Commit a586ddf

Browse files
skjnldsvskjnldsv
authored
Merge pull request #15055 from nextcloud/feature/developer-manual-assistant-integration
docs: add assistant integration developer documentation
2 parents e5e5ae0 + 210a3a2 commit a586ddf

4 files changed

Lines changed: 173 additions & 0 deletions

File tree

‎developer_manual/client_apis/OCS/index.rst‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,7 @@ The old documentation is still kept as it provides some additional documentation
1212

1313
ocs-openapi
1414
ocs-api-overview
15+
ocs-assistant-api
1516
ocs-share-api
1617
ocs-sharee-api
1718
ocs-status-api

‎developer_manual/client_apis/OCS/ocs-assistant-api.rst‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
.. _ocs-assistant-api:
2+
3+
=================
4+
Assistant OCS API
5+
=================
6+
7+
The assistant OCS API lets you schedule and manage AI tasks, retrieve task history, and query
8+
task results from any client or application.
9+
10+
The API is documented using OpenAPI. To browse the full specification:
11+
12+
1. Install the `OCS API viewer app <https://apps.nextcloud.com/apps/ocs_api_viewer>`_.
13+
2. Install the *assistant* app.
14+
3. Open the **OCS API viewer** from the app menu.
15+
4. Select **assistant** in the left sidebar.
16+
17+
.. note::
18+
The assistant API currently has separate endpoints for Text Processing, Speech to Text, and
19+
Image Generation. These will be unified in a future release, which may introduce breaking
20+
changes.
21+
22+
Related documentation
23+
---------------------
24+
25+
- Server-side integration: :doc:`../../digging_deeper/task_processing`
26+
- Frontend integration: :doc:`../../digging_deeper/assistant_integration`

‎developer_manual/digging_deeper/ai.rst‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,7 @@ AI & Machine Learning
77

88
context_chat
99
task_processing
10+
assistant_integration
1011
machinetranslation
1112
speech-to-text
1213
text_processing

‎developer_manual/digging_deeper/assistant_integration.rst‎

Lines changed: 145 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,145 @@
1+
.. _assistant-integration:
2+
3+
=========================
4+
Integrating the assistant
5+
=========================
6+
7+
This section covers integrating the Nextcloud assistant into the web frontend of other Nextcloud
8+
applications. For backend integration using the Task Processing OCP API, see
9+
:doc:`task_processing`. For the OCS API, see
10+
:doc:`../client_apis/OCS/ocs-assistant-api`.
11+
12+
Displaying a task result
13+
------------------------
14+
15+
There are two ways to display a task result using the assistant.
16+
17+
Open the assistant modal
18+
^^^^^^^^^^^^^^^^^^^^^^^^
19+
20+
If you have a task object retrieved from the
21+
``/ocs/v2.php/apps/assistant/api/v1/task/TASK_ID`` or
22+
``/ocs/v2.php/apps/assistant/api/v1/tasks`` OCS endpoint, pass it to the helper function
23+
``OCA.Assistant.openAssistantTask``. This opens the assistant modal with the task type, input,
24+
and output pre-loaded.
25+
26+
Browse the task result page
27+
^^^^^^^^^^^^^^^^^^^^^^^^^^^
28+
29+
A standalone page is available at ``/apps/assistant/task/view/TASK_ID``. It renders the same
30+
content as the assistant modal.
31+
32+
Running a task
33+
--------------
34+
35+
Use ``OCA.Assistant.openAssistantForm`` to open the assistant modal from your application. The
36+
function accepts a single configuration object with the following keys:
37+
38+
.. list-table:: ``openAssistantForm`` options
39+
:header-rows: 1
40+
:widths: 20 10 70
41+
42+
* - Key
43+
- Required
44+
- Description
45+
* - ``appId``
46+
- Yes
47+
- App ID of the calling application.
48+
* - ``customId``
49+
- No
50+
- Custom identifier for the task; useful when correlating the ``task finished`` backend
51+
event with the originating call. Defaults to ``''``.
52+
* - ``taskType``
53+
- No
54+
- Initially selected task type (e.g. ``core:text2text``, ``speech-to-text``,
55+
``OCP\TextToImage\Task``). Defaults to the last used task type.
56+
* - ``input``
57+
- No
58+
- Object containing initial input values, specific to each task type. Defaults to ``{}``.
59+
* - ``isInsideViewer``
60+
- No
61+
- Set to ``true`` if the function is called while the Viewer is open. Defaults to ``false``.
62+
* - ``closeOnResult``
63+
- No
64+
- If ``true``, the modal closes after a synchronous task completes and results are
65+
available. Defaults to ``false``.
66+
* - ``actionButtons``
67+
- No
68+
- List of extra buttons to show in the result form. Only used when ``closeOnResult`` is
69+
``false``. Defaults to an empty list.
70+
71+
The function returns a Promise that resolves when the modal is closed — either because a task
72+
was scheduled, or a synchronous task ran and produced results. The promise resolves with a task
73+
object:
74+
75+
.. code-block:: javascript
76+
77+
{
78+
appId: 'text',
79+
id: 310,
80+
customId: 'my custom identifier',
81+
input: { input: 'give me a short summary of a simple settings section about GitHub' },
82+
ocpTaskId: 152,
83+
output: { output: 'blabla' },
84+
status: 'STATUS_SUCCESSFUL',
85+
type: 'core:text2text',
86+
lastUpdated: 1711545305,
87+
scheduledAt: 1711545301,
88+
startedAt: 1711545302,
89+
endedAt: 1711545303,
90+
userId: 'janedoe',
91+
}
92+
93+
Possible ``status`` values are: ``STATUS_UNKNOWN`` (0), ``STATUS_SCHEDULED`` (1),
94+
``STATUS_RUNNING`` (2), ``STATUS_SUCCESSFUL`` (3), ``STATUS_FAILED`` (4).
95+
96+
Complete example:
97+
98+
.. code-block:: javascript
99+
100+
OCA.Assistant.openAssistantForm({
101+
appId: 'my_app_id',
102+
customId: 'my custom identifier',
103+
taskType: 'core:text2text',
104+
inputs: { input: 'count to 3' },
105+
actionButtons: [
106+
{
107+
label: 'Label 1',
108+
title: 'Title 1',
109+
variant: 'warning',
110+
iconSvg: cogSvg,
111+
onClick: (output) => { console.debug('first button clicked', output) },
112+
},
113+
{
114+
label: 'Label 2',
115+
title: 'Title 2',
116+
onClick: (output) => { console.debug('second button clicked', output) },
117+
},
118+
],
119+
}).then(task => {
120+
console.debug('assistant promise success', task)
121+
}).catch(error => {
122+
console.debug('assistant promise failure', error)
123+
})
124+
125+
Populating input from a file
126+
-----------------------------
127+
128+
You can pre-fill a task input field with the content of a file by passing a ``fileId`` or
129+
``filePath`` instead of a plain string value:
130+
131+
.. code-block:: javascript
132+
133+
OCA.Assistant.openAssistantForm({
134+
appId: 'my_app_id',
135+
customId: 'my custom identifier',
136+
taskType: 'core:text2text',
137+
inputs: { input: { fileId: 123 } },
138+
})
139+
140+
OCA.Assistant.openAssistantForm({
141+
appId: 'my_app_id',
142+
customId: 'my custom identifier',
143+
taskType: 'core:text2text',
144+
inputs: { input: { filePath: '/path/to/file.txt' } },
145+
})

0 commit comments

Comments
 (0)