MitDesk docs
Using MitDesk

Knowledge and sources

5 min read Odoo 20.0

Knowledge lets an agent answer from your own documents and records, not only from general knowledge. An administrator sets it up under Configuration ▸ Engine ▸ Knowledge.

Who this is for: administrators who set up knowledge sources, and users who ask about them.

You need: Edition: Pro and above (minddesk_pro). See Editions. The search tools need a licence that includes Pro.

Behind the scenes, MitDesk cuts each source into small passages and stores them in an index. This is often called RAG (retrieval-augmented generation): the agent first finds the best passages, then answers with them.

The Knowledge sources list with kind, index result and chunk count

What a source can be

A knowledge source form with Sync Now and Re-index

  • An Odoo model, for example contacts or tickets. You can limit it to some record ids. Empty means the whole model. Each model can be a source once.
  • A document, uploaded here. It belongs to the company you uploaded it in.
  • A web page, a public HTTPS address. MitDesk reads the page once and stores the text with the address and the time. The button Read the page again reads it again.

Write a short note on each source about why it is part of the knowledge. You can also add sources from the chat: open the agent settings and click Add sources. You can upload a file, add a link, add business data, or add from Documents or Knowledge.

Which files can be read

MitDesk checks an upload before it stores it. If it cannot read the type, you get a message.

  • Always: plain text, Markdown, CSV, HTML, XML, JSON and email files.
  • PDF: when pdfplumber or docling is installed on the server.
  • Excel (.xlsx): when openpyxl is installed.
  • Word and PowerPoint: when markitdown and the converter for that format are installed.
  • RTF and OpenDocument: when markitdown is installed.

Images, audio and video cannot be indexed as knowledge.

Indexing

Indexing runs on a schedule, in small batches, with Odoo's normal access checks. If the licence or access rights do not allow a model, MitDesk skips it and shows Not permitted.

Each source shows how the last pass ended:

Result Meaning
Not indexed yet Nothing was indexed so far.
Indexed All went well.
Indexed with skipped records Some records were skipped.
Not permitted The licence or access rights do not allow it.
Failed An error happened. The message says why.

Sync Now runs one indexing pass at once. It adds new things and updates changed ones. The schedule does this too, so the button only saves you waiting. Re-index deletes the chunks of this source and builds them again. Use it after you change the embedding model, or when the source changed in a way a sync cannot see.

Next to the sources, Settings has a block for knowledge:

  • Search company knowledge turns search on or off. It is on until you turn it off.
  • Ground answers automatically searches the knowledge for every question. It is off by default.
  • Where to look limits the search to some models.
  • How close a passage must be is a score from 0 to 1 (default 0.35). How well the words must match cannot be negative (default 0.10). Raise them if answers cite loosely related text. Lower them if a question finds nothing.
  • Never index these fields lists fields to skip, one per line. A bare name matches on every model, model.field names one, and * at the end matches a prefix. The default list has keys, tokens, passwords, private keys, bank accounts, IBANs, VAT numbers and all fields that start with amount_. The record id can never be blocked, because it is the citation key.

How a search works

A search from the chat runs as the account of that chat. The search code refuses to run as the superuser. A search started by a schedule or an automation as OdooBot runs as the administrator account.

  1. MitDesk removes chat words from your question, such as "please find…". Business terms and ids stay.
  2. It collects keyword matches and meaning matches, and joins them. If the embedding service is down, it uses keywords only.
  3. Every result is checked. The record must still exist, you must be allowed to read it, and the indexed fields must be readable. Anything else is dropped.

Step 3 is the security check. An agent that is limited to some models, or a pinned record, only narrows the search. It never gives more access. Uploaded documents stay searchable even when the search is narrowed to a model.

So two people can ask the same question and correctly get different answers.

What you get back

Each result is a citation with the record, a passage, the score, the search tier and a place: a page number, a section or a paragraph. For indexed files there is a link that opens the file. You see the citations in the chat.

An answer that cites its sources

Automatic grounding and "answer only from sources"

When Ground answers automatically is on, MitDesk finds passages before the first model call. It marks them as untrusted business data, not as instructions. It tells the model to base facts on them and to name the source, or to say when they do not answer the question. If the search fails, the chat goes on without them.

On an agent, open the Sources tab and turn on Answer only with RAG sources. If no passage reaches the score limit, the agent gives a no-source answer instead of guessing.

If it does not work

If Settings shows "Requires MitDesk Pro (not installed)", see Troubleshooting.