Merge branch 'master' into dependabot/pip/master/packaging-25.0

Signed-off-by: rakekniven <[email protected]>

Author: rakekniven

.github/workflows/openapi.yml

@@ -20,7 +20,7 @@ jobs:
           submodules: true
 
       - name: Set up php
-        uses: shivammathur/setup-php@cf4cade2721270509d5b1c766ab3549210a39a2a # v2
+        uses: shivammathur/setup-php@ccf2c627fe61b1b4d924adfcbd19d661a18133a0 # v2
         with:
           php-version: '8.1'
           # https://docs.nextcloud.com/server/stable/admin_manual/installation/source_installation.html#prerequisites-for-manual-installation

README.rst

@@ -143,6 +143,17 @@ Using venv
 5. Now you can use ``make ...`` to build all the stuff - for example ``make html`` to build the HTML flavor of all manuals
    The build assets will be put into the individual documentation subdirectories like ``developer_manual/_build/html/com``
 
+Building translated versions
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Only available in user_manual:
+
+1. Build the english version as described above before
+2. Create translation files: ``../build/change_file_extension.sh``
+3. Create German (``de``) version: ``make html-lang-de``
+4. Find the HTML files in ``_build/html/de/index.html``
+5. Before building another language you have to delete the complete ``_build`` directory
+
 Autobuilding
 ^^^^^^^^^^^^
 
@@ -157,6 +168,27 @@ When editing the documentation installing ``sphinx-autobuild`` though pip can be
 Building PDF
 ============
 
+Building inside docker
+^^^^^^^^^^^^^^^^^^^^^^
+
+1. Create a docker:: ``docker run --platform linux/amd64 --volume .:/docs --interactive --tty --name nextcloud-docs ghcr.io/nextcloud/continuous-integration-documentation:documentation-15 bash``
+2. Change into the documentation directory: ``cd /docs``
+3. Only once: Create a venv: ``python -m venv venv``
+4. Activate the environment: ``source venv/bin/activate``
+5. Install the dependencies ``pip install -r requirements.txt``
+6. Change into the documentation of choice (admin, developer, user): ``cd /docs/user_manual``
+7. To build the English version: ``make latexpdf``
+8. To build the translated version (only available in user_manual):
+   1. Create translation files: ``../build/change_file_extension.sh``
+   2. Create German (``de``) version: ``make latexpdf-lang-de``
+   3. Find the file in ``_build/latex/Nextcloud_User_Manual.pdf``
+   4. Before building another language you have to delete the complete ``_build`` directory
+
+Building locally
+^^^^^^^^^^^^^^^^
+
+.. note:: Because of the many dependencies LaTeX and the other tools bring in, it is not recommended to install the tools locally.
+
 1. Follow instructions for "Building HTML" above
 2. Install ``latexmk`` and ``texlive-latex-extra`` - https://pipenv.readthedocs.io/en/latest/
 3. Create a Python environment (typically inside this repository): ``pipenv --python 3.9``

admin_manual/_templates/versions.html

@@ -2,15 +2,22 @@
 {# Add rst-badge after rst-versions for small badge style. #}
   <div class="rst-versions" data-toggle="rst-versions" role="note" aria-label="versions">
     <span class="rst-current-version" data-toggle="rst-current-version">
-      <span class="fa fa-book"> Read the Docs</span>
-      v: {{ current_version }}
+      ☁️ {{ current_version }}
       <span class="fa fa-caret-down"></span>
     </span>
     <div class="rst-other-versions">
       <dl>
-        <dt>{{ _('Versions') }}</dt>
-        {% for slug, url in versions %}
-          <dd><a href="{{ url }}">{{ slug }}</a></dd>
+        <dt>☁️ {{ _('Versions') }}</dt>
+        {% for slug, url in versions|reverse %}
+        <dd style="width: 32%">
+          <a href="{{ url }}"
+             {% if current_version == slug %}
+             style="color: var(--dark-link-color);"
+             {% endif %}
+          >
+            {{ slug }}
+          </a>
+        </dd>
         {% endfor %}
       </dl>
     </div>

admin_manual/ai/app_assistant.rst

@@ -74,11 +74,8 @@ These apps currently implement the following Assistant Tasks:
 * *Summarize* (Tested with OpenAI GPT-3.5 and Llama 3.1 8B)
 * *Generate headline* (Tested with OpenAI GPT-3.5 and Llama 3.1 8B)
 * *Extract topics* (Tested with OpenAI GPT-3.5 and Llama 3.1 8B)
-
-Additionally, *integration_openai* also implements the following Assistant Tasks:
-
-* *Context write* (Tested with OpenAI GPT-3.5)
-* *Reformulate text* (Tested with OpenAI GPT-3.5)
+* *Context write* (Tested with OpenAI GPT-3.5 and Llama 3.1 8B)
+* *Reformulate text* (Tested with OpenAI GPT-3.5 and Llama 3.1 8B)
 
 These tasks may work with other models, but we can give no guarantees.
 
@@ -98,7 +95,7 @@ In order to make use of our special Context Chat feature, offering in-context in
 
 * :ref:`context_chat + context_chat_backend<ai-app-context_chat>` -  (Customer support available upon request)
 
-You will also need a text processing provider as specified above (ie. llm2 or integration_openai).
+You will also need a text processing provider as specified above (ie. llm2, integration_openai or integration_watsonx).
 
 Context Agent
 ~~~~~~~~~~~~~
@@ -117,6 +114,7 @@ Text-To-Speech
 In order to make use of Text-To-Speech, you will need an app that provides a Text-To-Speech backend:
 
 * *integration_openai* - Integrates with the OpenAI API to provide AI functionality from OpenAI servers  (Customer support available upon request; see :ref:`AI as a Service<ai-ai_as_a_service>`)
+* *text2speech_kokoro* - Runs a local model
 
 Configuration
 -------------

admin_manual/ai/app_context_agent.rst

@@ -7,21 +7,30 @@ App: Context Agent (context_agent)
 The *context_agent* app is the app that provides AI agent functionality in Nextcloud and acts as a backend for the :ref:`Nextcloud Assistant app<ai-app-assistant>`. Nextcloud can provide customer support upon request, please talk to your account manager for the possibilities.
 
 When the Context Agent app is installed the AI Chat in Nextcloud Assistant will be able to interact with your Nextcloud apps via virtual integrations that are called "tools". They allow the Assistant to perform actions in your Nextcloud upon sending instructions in a chat message.
+Tool groups are only available if their requirements are met. They can be en- and disabled in the AI admin settings.
 
 Currently implemented tools:
 
 * List the user's calendars
 
   * Example prompt: *"List my calendars"*
 
-* List the user's talk conversations
+* List the user's talk conversations (requires `Talk <https://apps.nextcloud.com/apps/spreed>`_)
 
   * Example prompt: *"List my talk conversations"*
 
-* List messages in a talk conversation
+* List messages in a talk conversation (requires `Talk <https://apps.nextcloud.com/apps/spreed>`_)
 
   * Example prompt: *"List the latest messages in my conversation with Andrew"*
 
+* Send a message to a talk conversation (requires `Talk <https://apps.nextcloud.com/apps/spreed>`_)
+
+  * Example prompt: *"Can you send a joke to Andrew in talk?"*
+
+* Create a public talk conversation (requires `Talk <https://apps.nextcloud.com/apps/spreed>`_)
+
+  * Example prompt: *"Can you create a new public talk conversation titled 'Press conference'?"*
+
 * Find a person in the user's contacts
 
   * Example prompt: *"What is Andrew's Email address?"*
@@ -30,31 +39,49 @@ Currently implemented tools:
 
   * Example prompt: *"Where do I live?"*
 
-* Ask a question to context chat
+* Ask a question to context chat (requires :ref:`Context Chat<ai-app-context_chat>`)
 
   * Example prompt: *"What is the company's sick leave process?"*
 
+* Transcribe a media file (requires Transcribe audio task type enabled)
+
+  * Example prompt: *"Can you transcribe the following file? https://mycloud.com/f/9825679"* (Can be selected via smart picker.)
+
+* Generate documents (requires `Nextcloud Office <https://apps.nextcloud.com/apps/richdocuments>`_)
+
+  * Example prompt: *"Can you generate me a slide deck for my presentation about cats?"*
+  * Example prompt: *"Can you generate me a spreadsheet with some plausible numbers for countries and their population count?"*
+  * Example prompt: *"Can you generate me a pdf with an outline about what to see in Berlin?"*
+
+* Generate images (requires Image generation task type enabled)
+
+  * Example prompt: *"Can you generate me an image of a cartoon drawing of a roman soldier typing something on a laptop?"*
+
 * Get coordinates for an Address from Open Street Maps Nomatim
 
-  * Example prompt: *"List my calendars"*
+  * Example prompt: *"What are the coordinates for Berlin, Germany?"*
+
+* Get the URL for a map of a location using Open Street Maps
+
+  * Example prompt: *"Can you show me a map of New York, please"*
 
 * Get the current weather at a location
 
   * Example prompt: *"How is the weather in Berlin?"*
 
 * Schedule an event in the user's calendar
 
-  * Example prompt: *"Make schedule an event with Andrew tomorrow at noon."*
+  * Example prompt: *"Schedule an event with Andrew tomorrow at noon."*
 
-* Send a message to a talk conversation
+* Find free times in users' calendar
 
-  * Example prompt: *"Can you send a joke to Andrew in talk?"*
+  * Example prompt: *"Find a free 1-hour slot for a meeting with me and Marco next week."*
 
-* Create a deck card
+* Create a deck card (requires `Deck <https://apps.nextcloud.com/apps/deck>`_)
 
   * Example prompt: *"Create a deck card for 'Buy Groceries' in my Personal board."*
 
-* Access information in deck boards
+* Access information in deck boards (requires `Deck <https://apps.nextcloud.com/apps/deck>`_)
 
   * Example prompt: *"Which deck cards are currently in the To do list in my Personal board?"*
 
@@ -66,10 +93,41 @@ Currently implemented tools:
 
   * Example prompt: *"Show me the youtube video of the Nextcloud hub 10 launch."*
 
-* Send an email via Nextcloud Mail
+* Search Duckduckgo
+
+  * Example prompt: *"Show me search results for quick pasta recipes, please."*
+
+* Send an email via Nextcloud Mail (requires `Mail <https://apps.nextcloud.com/apps/mail>`_)
+
+  * Example prompt: *"Send a test email from my [email protected] account to [email protected]"*
+
+* Get contents of a file
+
+  * Example prompt: *"Can you summarize the following file in my documents? Design/Planning.md"*
+
+* Generate a public share link for a file
+
+  * Example prompt: *"Can create a share link for the following file in my documents? Design/Planning.md"*
+
+* Get the folder tree of the user's files
+
+  * Example prompt: *"Can you show me the folder tree of my files?"*
+
+* Determine public transport routes (requires a `HERE <https://www.here.com/>`_ API key configured in the admin settings)
+
+  * Example prompt: *"How can I get from Würzburg Hauptbahnhof to Berlin Hauptbahnhof?"*
+
+* List all projects in OpenProject (requires the `OpenProject integration <https://apps.nextcloud.com/apps/integration_openproject>`_)
+
+  * Example prompt: *"List all my projects in OpenProject, please"*
+
+* List all available assignees of a project in OpenProject (requires the `OpenProject integration <https://apps.nextcloud.com/apps/integration_openproject>`_)
+
+  * Example prompt: *"List all available assignees for the 'Product launch' project in OpenProject"*
+
+* Create a new work package in a given project in OpenProject (requires the `OpenProject integration <https://apps.nextcloud.com/apps/integration_openproject>`_)
+  * Example prompt: *"Create a work package called 'Publish release video' in the 'Product launch' project in OpenProject"*
 
-  * Example prompt *"Send a test email from [email protected] to [email protected] from my account with id 12"*
-  * (The account ID will soon be irrelevant)
 
 These tools can also be combined by the agent to fulfil tasks like the following:
 
@@ -85,6 +143,21 @@ These tools can also be combined by the agent to fulfil tasks like the following
 
   * Uses contacts to look up Andrew's email and then sends an email
 
+Custom Tools using MCP
+-----------------------
+
+Model Context Protocol (MCP) is a protocol that enables Large Language Models (LLMs) to interact with external data sources and tools.
+The Context Agent app allows administrators to extend its capabilities by adding custom services via MCP. This can be configured in the admin settings under "MCP Config," where you can provide a JSON configuration in the following format:
+
+.. code-block:: json
+
+  {
+    "service-name": {
+      "url": "https://service-url.com/endpoint",
+      "transport": "streamable_http"
+    }
+  }
+
 Requirements
 ------------
 
@@ -118,6 +191,13 @@ Other models that may give good results are:
 
 See :ref:`llm2 documentation <ai-app-llm2>` on how to configure alternate models.
 
+Using Nextcloud MCP Server
+--------------------------
+
+Context Agent exposes an MCP server that can be used by other large language models or applications to access the tools provided by Context Agent.
+The server will be available at `https://your-nextcloud-domain.com/index.php/apps/app_api/proxy/context_agent/mcp/`, and
+it requires authentication via an app password passed in the `Authorization` header. Ex: `Authorization: Bearer <app-password>`.
+
 Scaling
 -------
 
@@ -139,4 +219,8 @@ Known Limitations
 -----------------
 * Make sure to test the language model you are using in concert with this app for whether they meet the use-case's quality requirements
 * Most models have difficulties with languages other than English. Some sometimes answer in another language than used by the user. 
-* Customer support is available upon request, however we can't solve false or problematic output, most performance issues, or other problems caused by the underlying model. Support is thus limited only to bugs directly caused by the implementation of the app (connectors, API, front-end, AppAPI)
+* Customer support is available upon request, however we can't solve false or problematic output, most performance issues, or other problems caused by the underlying model. 
+  Support is thus limited only to bugs directly caused by the implementation of the app (connectors, API, front-end, AppAPI). We still try to optimize this as far as possible, so if you encounter any false or problematic output, you can report it `in a dedicated Github issue <https://github.com/nextcloud/context_agent/issues/51>`_ to help us improve this app. 
+* When multiple MCP services are configured that have tools with the same name undefined behavior will occur.
+* Only remote MCP services are supported (streamable_http transport).
+* MCP services that require different access tokens for each user are not currently supported.