Table of contents

Cozy AI chat doctypes

Cozy can store and manipulate the data of a chat with an AI, distributed across several doctypes.

Cf the stack documentation for AI.

io.cozy.ai.chat.conversations

The io.cozy.ai.chat.conversations doctype is used to keep history of chat conversations with an assistant (AI).

A system message is not written by the clients: it is added by the stack when the conversation is created with an assistant that has a prompt, see io.cozy.ai.chat.assistants. Clients should not render it as a regular conversation turn.

Example

{
  "_id": "e21dce8058b9013d800a18c04daba326",
  "_rev": "1-23456",
  "cozyMetadata": {
    "createdAt": "2024-09-24T13:24:07.576Z",
    "createdOn": "http://cozy.localhost:8080/",
    "doctypeVersion": "1",
    "metadataVersion": 1,
    "updatedAt": "2024-09-24T13:24:07.576Z"
  },
  "messages": [
    {
      "id": "eb17c3205bf1013ddea018c04daba326",
      "role": "user",
      "content": "Why the sky is blue?",
      "createdAt": "2024-09-24T13:24:07.576Z"
    },
    {
      "id": "0192756f2428758abe0aec7ecefc0c60",
      "content": "The sky appears blue because of a phenomenon called Rayleigh scattering.",
      "createdAt": "2024-09-24T13:24:08.987Z",
      "role": "assistant",
      "sources": [
        {
          "sourceType": "document",
          "doctype": "io.cozy.files",
          "id": "3fa17b7c5d1e013e9c2a18c04daba326",
          "filename": "why-is-the-sky-blue.pdf",
          "page": 2,
          "fileUrl": "http://cozy.localhost:8080/files/3fa17b7c5d1e013e9c2a18c04daba326",
          "chunkUrl": "http://cozy.localhost:8080/files/3fa17b7c5d1e013e9c2a18c04daba326#page=2"
        },
        {
          "sourceType": "document",
          "doctype": "com.linagora.email",
          "id": "d90a1f4e2b73013e9c2a18c04daba327",
          "email.subject": "Physics newsletter",
          "email.preview": "This month, we look at why the sky is blue…",
          "datetime": "2024-09-20T08:12:00.000Z"
        },
        {
          "sourceType": "web",
          "doctype": "io.cozy.urls",
          "url": "https://en.wikipedia.org/wiki/Rayleigh_scattering",
          "title": "Rayleigh scattering",
          "snippet": "Rayleigh scattering is the scattering of light by particles much smaller than the wavelength."
        }
      ]
    }
  ],
  "relationships": {
    "assistant": {
      "data": {
        "_id": "e21dce8058b9013d800a18c04daba326",
        "_type": "io.cozy.ai.chat.assistants"
      }
    }
  }
}

io.cozy.ai.chat.events

This doctype is not persisted, it is only used on the realtime websockets to allow the application to display the tokens of the response step by step.

io.cozy.ai.chat.assistants

The io.cozy.ai.chat.assistants doctype is used to keep configuration of an assistant (AI).

LLM provider

The relationships.provider.data object identifies the LLM account (an io.cozy.accounts document) used by the assistant. Note that the assistant document itself does not carry the model, the base URL, nor the API key: they all live on that account.

When providerId is empty or equal to "openrag", the stack’s default RAG configuration is used. For any other value, the stack reads the linked account and forwards:

If the account cannot be read, or if none of those three fields is set, the default configuration is used.

Assistant prompt and conversations

When a conversation is created via the cozy-stack POST /ai/chat/conversations/:id route with an assistantID, if the assistant has a non-empty prompt, a role: "system" message carrying that prompt is prepended to the conversation’s messages (before the user’s own message), and consumed as-is by OpenRAG’s chat completion format. It is persisted in the io.cozy.ai.chat.conversations document, and clients should not render system messages as regular conversation turns. The prompt is only injected at creation time: editing an assistant’s prompt does not update the conversations already created with it.

If a conversation references an assistant that no longer exists, the stack answers with an error rather than falling back to unscoped retrieval, which would silently widen a folder-scoped conversation to the whole instance.

Example

{
  "_id": "e21dce8058b9013d800a18c04daba326",
  "_rev": "1-23456",
  "cozyMetadata": {
    "createdAt": "2024-09-24T13:24:07.576Z",
    "createdOn": "http://cozy.localhost:8080/",
    "doctypeVersion": "1",
    "metadataVersion": 1,
    "updatedAt": "2024-09-24T13:24:07.576Z"
  },
  "name": "My assistant",
  "prompt": "This is my assistant",
  "icon": "[encoded base64 string of the content of the icon or svg binary]",
  "knowledgeBase": [
    {
      "doctype": "io.cozy.files",
      "dirId": "b21dce8058b9013d800a18c04daba333"
    }
  ],
  "relationships": {
    "provider": {
      "data": {
        "_type": "io.cozy.accounts",
        "_id": "e21dce8058b9013d800a18c04daba322",
        "metadata": {
          "providerId": "openrag"
        }
      }
    }
  }
}

io.cozy.ai.chat.rag

The io.cozy.ai.chat.rag doctype is used to keep the RAG indexation status of a document. Its identifier is the identifier of the document it describes. Only files are indexed for now, and the relationship always points to an io.cozy.files document.

A status is only replaced by one about a revision that is not older than the recorded docRev, so a callback that comes in late cannot bring an outdated status back. The status document is deleted along with the document it describes.

Example

{
  "_id": "e21dce8058b9013d800a18c04daba326",
  "_rev": "1-23456",
  "indexed": true,
  "status": "success",
  "docRev": "3-6a1b0b8a51a4e0e0a3b7f0f1d2c3b4a5",
  "lastSuccessDate": "2026-08-28T13:24:07.576Z",
  "relationships": {
    "doc": {
      "data": {
        "_id": "e21dce8058b9013d800a18c04daba326",
        "_type": "io.cozy.files"
      }
    }
  }
}