Revolutionizing Odoo Documentation with RAG & LLM: Introducing the Odoo Expert

Updates:

In the world of ERP software, documentation is both a necessity and a challenge. As a developer working at Odoo, I often found myself diving deep into documentation spread across multiple versions and pages. This experience led me to create Odoo Expert, a RAG-powered documentation assistant that transforms how users interact with Odoo's documentation.

The Problem: A Community Crying Out for Better Documentation

Anyone who has worked with software knows the struggle: you have a specific question, but finding the answer means navigating through hundreds or even thousands of documentation pages, version differences, and sometimes conflicting information. With Odoo's documentation spanning multiple versions (16.0, 17.0, and 18.0), this challenge becomes even more pronounced.

This isn't just a personal observation - it's a widely recognized challenge in the Odoo community. In a recent LinkedIn poll conducted by William McMahon (CEO at Gravitai), an overwhelming 80% of Odoo community members indicated that the documentation "Massively" needs improvement. Out of 316 votes, only 3% felt the current documentation was great, while 17% said it serves its purpose. These results strongly validate the need for better documentation tools and accessibility.

Traditional documentation search often falls short:

Keyword searches miss context and related concepts
Version-specific information is hard to filter
Users waste time jumping between pages
Complex questions require piecing together information from multiple sources

Enter Odoo Expert: How it Works and Solve the Problem

Rather than reinventing how documentation is written, we reimagined how it's accessed. Think of Odoo Expert as having a knowledgeable Odoo expert by your side, one who's read all the documentation and can instantly point you to exactly what you need. It combines the reliability of official documentation with the convenience of natural conversation.

The system leverages modern RAG technology with LLM to understand your questions in context, pulling relevant information from across all supported versions. No more manual cross-referencing or piecing together answers from multiple sources - just ask your question naturally, and get comprehensive, sourced answers.

        graph TD
        A[Odoo Documentation] -->|pull_rawdata.sh| B[Raw Data]
        B -->|process-raw| C[Markdown Files]
        C -->|process-docs| D[(Database with Embeddings)]
        D -->|serve --mode ui| E[Streamlit UI]
        D -->|serve --mode api| F[REST API]
        
        subgraph "Data Processing Pipeline"
            B
            C
            D
        end
        
        subgraph "Interface Layer"
            E
            F
        end
    
        style A fill:#f9f,stroke:#333,stroke-width:2px
        style D fill:#bbf,stroke:#333,stroke-width:2px
        style E fill:#bfb,stroke:#333,stroke-width:2px
        style F fill:#bfb,stroke:#333,stroke-width:2px

The Magic Behind the Scenes: A Journey of Challenges and Solutions

The path from concept to working system was far from straightforward. Let me share some of the major challenges we faced and how we overcame them.

Cracking the Documentation Processing Code

My first approach to handling Odoo's documentation was... interesting. I initially tried building the HTML from the Odoo documentation repo, and using crawl4ai to convert those HTMLs to Markdowns. It worked, but it was painfully slow - processing all three versions took around 4 hours. Not exactly ideal for regular updates!

The breakthrough came when we discovered we could use Pandoc to convert the RST source files directly to Markdown. This seemingly simple change yielded massive results - the same processing now takes just 5 minutes. That's a 50x improvement! This made the daily documentation updates actually feasible.

The Art of Smart Content Chunking

Content chunking proved to be another fascinating challenge. My first attempt used simple character counting to break down the content. Sounds reasonable, right? Well, it turned out to be a disaster for context preservation. Important relationships between different parts of the documentation were getting lost.

The solution came through LangChain's markdown splitter. By preserving the full header path of titles and using smart splitting algorithms, I maintained much more context. This wasn't just about keeping words together - it was about preserving the meaning and relationships within the documentation.

Wrestling with Vector Embeddings and Database Performance

Here's where things got really interesting. I initially used OpenAI's text-embedding-3-large model with its 3072-dimensional vectors. The data went into Supabase just fine, but trying to query it? Timeout city! The high dimensionality made indexing practically impossible, leading to severe performance issues.

After much experimentation, I switched to text-embedding-3-small, which only produce 1536 dimensions, less than 2000 dimensions limit. This wasn't just a compromise - it turned out to be crucial for enabling proper vector indexing in Supabase, dramatically improving query performance. Building and testing this vector store setup was a journey in itself, teaching me valuable lessons about the practical limits of vector databases.

Keeping Everything Current

One of the challenges with any documentation system is staying up to date. I've automated this process - every day, the system checks for updates in the Odoo documentation. When changes are detected, the file's MD5 hash will change, so it can automatically processes the new content and updates its knowledge base. This means you're always getting the most current information.

I also thought about using the git diff to show the difference, that might could be a future implementation.

Containerization and CI/CD

My containerization story is a classic example of "less is more." The first iteration had three separate containers, which seemed logical for separation of concerns. However, this approach bloated both the container size and operational complexity.

The aha moment came when I discovered I could use Supervisor to manage multiple processes in a single container. This consolidation significantly reduced the container and image size while simplifying our deployment pipeline. It also made my GitHub Actions CI/CD setup much more streamlined. The whole docker image building time now is just around 1 minute.

All these challenges and solutions came together to create a system that could efficiently process, index, and serve Odoo's documentation in a way that makes technical information instantly accessible through natural language queries.

Getting Started: Simpler Than You'd Think

Setting up Odoo Expert is straightforward. If you choose the docker compose deployment, all you need the the docker-compose.yml file and the .env.example file.

First, download the docker-compose.yml file to your local machine.
Create your environment configuration by copying the example cp .env.example .env . Then configure these essential variables in your .env
Launch the Docker container by running docker-compose up -d
Set up the database structure using Supabase's SQL editor:

Execute the table creation script from src/sqls/create_table_schema.sql
Execute the search function script from src/sqls/search_odoo_docs.sql

Initialize your documentation data:

# Pull documentation
docker compose run --rm odoo-expert ./pull_rawdata.sh

# Convert RST to Markdown
docker compose run --rm odoo-expert python main.py process-raw --raw-dir ./raw_data --output-dir ./markdown

# Process documents
docker compose run --rm odoo-expert python main.py process-docs ./markdown

Create the necessary database indexes in Supabase's SQL editor

SET maintenance_work_mem = '128MB';
CREATE INDEX idx_odoo_docs_version ON odoo_docs (version);

CREATE INDEX idx_odoo_docs_embedding ON odoo_docs
USING ivfflat (embedding vector_cosine_ops)
WITH (lists = 328);

Access your installation:

Web UI: http://localhost:8501
API: http://localhost:8000

The system will automatically update its documentation daily. If you need to manually trigger an update, you can run:

docker compose run --rm odoo-expert python main.py check-updates

For more information, you can follow the steps on Github Repo's README.

Beyond Just Documentation

While I built Odoo Expert specifically for Odoo documentation, its architecture opens up possibilities for handling any kind of technical documentation. Think about using it for:

Your company's internal knowledge base, where it could answer questions about company-specific implementations and customizations.
Technical documentation portals, making complex information more accessible to users of all skill levels.
Educational content, helping students navigate through course materials more effectively.

What's Next

I’m currently working at Odoo, and my CEO, Fabien, recently reached out to me regarding the internal team’s already exploring the integration of RAG (Retrieval-Augmented Generation) and AI into Odoo in the future.

I am trying to reach out to the Belgian office, to ask about the possibility if I can contribute anything to it, but honestly, I am not holding any hope. The company is pretty conservative when things are related to R&D, so I might not have chance to officially work on it and contribute to Odoo, sigh.

Talking about feedbacks, over the past few days, the feedback from colleagues and others who have seen the demo video and used it has been overwhelmingly positive, with 90% of responses being supportive.

When I started this project last week, I hadn't anticipated receiving such positive feedback on LinkedIn. My idea was actually quite simple - I encountered a problem and wanted to help others who might be facing the same challenge. As a Chinese, I always remember an old saying: 'Don't neglect to do a good deed, however small it may be.' I've never believed that we should give up on making changes just because they seem insignificant. I've always held firm to the belief that whether a change serves the masses or just a small group of people, any contribution that makes our daily lives better is worthwhile. So, even if my work is seen as naive, I believe that as long as it can help people, the effort is worth it, I want to make some difference.

My primary goal is to integrate AI capabilities, such as advanced search functionalities akin to Google or Perplexity, into the Odoo documentation website. This would greatly enhance the user experience by making information retrieval more intuitive and efficient. However, I don’t plan to stop there. There are several future enhancements I envision:

Streaming API Chat Responses: To make conversations feel more natural and dynamic.
Enhanced API Capabilities: To provide broader integration options for developers.
Improved Semantic Search: To continuously refine the accuracy and relevance of responses.
Odoo Open-Sourced Code Integration: This is a long-term vision I’ve been considering, though it would require at least 100x more effort and time compared to the documentation integration.

I’m excited about the potential of these ideas and am committed to pushing forward, despite the challenges.

Join Me in Improving the Project

The overwhelming response to the poll above shows I am not alone in wanting better documentation tools. Odoo Expert is my contribution to solving this challenge, and I invite you to be part of it.

Whether you're interested in using the tool, contributing to its development, or adapting it for your own documentation needs, I'd love to have you involved.

The project is open source under the Apache License 2.0, with an additional CC-BY-SA 4.0 license for documentation content. This ensures it remains open and accessible to everyone who might benefit from it.

Visit my GitHub repository to get started, and join me in making technical documentation work better for everyone. After all, shouldn't finding answers in documentation be as easy as asking a knowledgeable colleague?