{"id":26500102,"url":"https://github.com/mfydev/odoo-expert","last_synced_at":"2025-07-19T00:37:35.099Z","repository":{"id":273549568,"uuid":"917789372","full_name":"MFYDev/odoo-expert","owner":"MFYDev","description":"RAG-powered documentation assistant that converts, processes, and provides semantic search capabilities for Odoo's technical documentation. Supports multiple Odoo versions with an interactive chat interface powered by LLM models.","archived":false,"fork":false,"pushed_at":"2025-02-22T06:08:00.000Z","size":311,"stargazers_count":77,"open_issues_count":1,"forks_count":21,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-07-11T18:48:42.015Z","etag":null,"topics":["chatbot","documentation","embeddings","openai","rag","retrieval-augmented-generation"],"latest_commit_sha":null,"homepage":"https://fanyangmeng.blog/introducing-odoo-expert/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/MFYDev.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":"mfydev","patreon":null,"open_collective":null,"ko_fi":"fanyangmeng","tidelift":null,"community_bridge":null,"liberapay":null,"issuehunt":null,"lfx_crowdfunding":null,"polar":null,"buy_me_a_coffee":null,"thanks_dev":null,"custom":null}},"created_at":"2025-01-16T16:44:41.000Z","updated_at":"2025-07-09T14:33:49.000Z","dependencies_parsed_at":"2025-06-06T14:31:21.644Z","dependency_job_id":null,"html_url":"https://github.com/MFYDev/odoo-expert","commit_stats":null,"previous_names":["mfydev/odoo-expert"],"tags_count":13,"template":false,"template_full_name":null,"purl":"pkg:github/MFYDev/odoo-expert","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MFYDev%2Fodoo-expert","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MFYDev%2Fodoo-expert/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MFYDev%2Fodoo-expert/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MFYDev%2Fodoo-expert/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/MFYDev","download_url":"https://codeload.github.com/MFYDev/odoo-expert/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MFYDev%2Fodoo-expert/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":264987765,"owners_count":23693884,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["chatbot","documentation","embeddings","openai","rag","retrieval-augmented-generation"],"created_at":"2025-03-20T15:28:44.522Z","updated_at":"2025-07-19T00:37:35.074Z","avatar_url":"https://github.com/MFYDev.png","language":"Python","funding_links":["https://github.com/sponsors/mfydev","https://ko-fi.com/fanyangmeng"],"categories":[],"sub_categories":[],"readme":"# Odoo Expert\nRAG-Powered Odoo Documentation Assistant\n\nIntro, Updates \u0026 Demo Video: https://fanyangmeng.blog/introducing-odoo-expert/\n\nBrowser extension now available for Chrome and Edge!\n\nCheck it out: https://microsoftedge.microsoft.com/addons/detail/odoo-expert/mnmapgdlgncmdiofbdacjilfcafgapci\n\n\u003e ⚠️ PLEASE NOTE:\n\u003e This project is not sponsored or endrosed by Odoo S.A. or Odoo Inc. yet. I am developing this project as a personal project with the intention of helping the Odoo community on my own.\n\nA comprehensive documentation processing and chat system that converts Odoo's documentation to a searchable knowledge base with an AI-powered chat interface. This tool supports multiple Odoo versions (16.0, 17.0, 18.0) and provides semantic search capabilities powered by OpenAI embeddings.\n\n## Initial Intention Behind This Project\n\nThe project was conceived with the vision of enhancing the Odoo documentation experience. The goal was to create a system similar to Perplexity or Google, where users could receive AI-powered answers directly within the documentation website, complete with proper source links. This eliminates the need for users to manually navigate through complex documentation structures.\n\n## How it works?\n\n```mermaid\ngraph TD\n    A[Odoo Documentation] --\u003e|pull_rawdata.sh| B[Raw Data]\n    B --\u003e|process-raw| C[Markdown Files]\n    C --\u003e|process-docs| D[(Database with Embeddings)]\n    D --\u003e|serve --mode ui| E[Streamlit UI]\n    D --\u003e|serve --mode api| F[REST API]\n    \n    subgraph \"Data Processing Pipeline\"\n        B\n        C\n        D\n    end\n    \n    subgraph \"Interface Layer\"\n        E\n        F\n    end\n\n    style A fill:#f9f,stroke:#333,stroke-width:2px\n    style D fill:#bbf,stroke:#333,stroke-width:2px\n    style E fill:#bfb,stroke:#333,stroke-width:2px\n    style F fill:#bfb,stroke:#333,stroke-width:2px\n```\n\nThe system operates through a pipeline of data processing and serving steps:\n\n1. **Documentation Pulling**: Fetches raw documentation from Odoo's repositories\n2. **Format Conversion**: Converts RST files to Markdown for better AI processing\n3. **Embedding Generation**: Processes Markdown files and stores them with embeddings\n4. **Interface Layer**: Provides both UI and API access to the processed knowledge base\n\n## Features\n\n### Core Functionality\n\n- Documentation Processing: Automated conversion of RST to Markdown with smart preprocessing\n- Semantic Search: Real-time semantic search across documentation versions\n- AI-Powered Chat: Context-aware responses with source citations\n- Multi-Version Support: Comprehensive support for Odoo versions 16.0, 17.0, and 18.0\n- Always updated: Efficiently detect and process documentation updates.\n\n### Interface Options\n\n- Web UI: Streamlit-based interface for interactive querying\n- REST API: Authenticated endpoints for programmatic access\n- CLI: Command-line interface for document processing and chat\n\n## Prerequisites\n\n- Docker and Docker Compose\n- PostgreSQL with pgvector extension\n- OpenAI API access\n- Git\n\nif you want to do source install, you need to install the following dependencies:\n\n- Python 3.10+\n- Pandoc\n- PostgreSQL with pgvector extension\n\n## Installation \u0026 Usage\n\nAssuming the table name is `odoo_docs`. If you have a different table name, please update the table name in the following SQL commands.\n\n### Docker Compose Install\n\n1. Download the [docker-compose.yml](./docker-compose.yml) file to your local machine.\n2. Set up environment variables in the `.env` file by using the `.env.example` file as a template.\n   ```bash\n    OPENAI_API_KEY=your_openai_api_key\n    OPENAI_API_BASE=https://api.openai.com/v1\n    POSTGRES_USER=odoo_expert\n    POSTGRES_PASSWORD=your_secure_password\n    POSTGRES_DB=odoo_expert_db\n    POSTGRES_HOST=db\n    POSTGRES_PORT=5432\n    LLM_MODEL=gpt-4o\n    BEARER_TOKEN=comma_separated_bearer_tokens\n    CORS_ORIGINS=http://localhost:3000,http://localhost:8501,https://www.odoo.com\n    ODOO_VERSIONS=16.0,17.0,18.0\n    SYSTEM_PROMPT=same as .env.example\n    # Data Directories\n    RAW_DATA_DIR=raw_data\n    MARKDOWN_DATA_DIR=markdown\n   ```\n3. Run the following command:\n    ```bash\n    docker-compose up -d\n    ```\n4. Pull the raw data and write to your PostgreSQL's table:\n    ```bash\n    # Pull documentation (uses ODOO_VERSIONS from .env)\n    docker compose run --rm odoo-expert ./pull_rawdata.sh\n\n    # Convert RST to Markdown\n    docker compose run --rm odoo-expert python main.py process-raw\n\n    # Process documents\n    docker compose run --rm odoo-expert python main.py process-docs\n    ```\n5. Access the UI at port 8501 and the API at port 8000\n6. Docker compose will automatically pull the latest changes and update the system once a day, or you can manually update by running the following command:\n    ```bash\n    docker compose run --rm odoo-expert python main.py check-updates\n    ```\n\n### Source Install\n\n1. Install PostgreSQL and pgvector:\n    ```bash\n    # For Debian/Ubuntu\n    sudo apt-get install postgresql postgresql-contrib\n    \n    # Install pgvector extension\n    git clone https://github.com/pgvector/pgvector.git\n    cd pgvector\n    make\n    make install\n    ```\n\n2. Create database and enable extension:\n    ```sql\n    CREATE DATABASE odoo_expert;\n    \\c odoo_expert\n    CREATE EXTENSION vector;\n    ```\n\n3. Set up the database schema by running the SQL commands in `src/sqls/init.sql`.\n\n4. Create a `.env` file from the template and configure your environment variables:\n    ```bash\n    cp .env.example .env\n    # Edit .env with your settings including ODOO_VERSIONS and SYSTEM_PROMPT\n    ```\n\n5. Pull Odoo documentation:\n    ```bash\n    chmod +x pull_rawdata.sh\n    ./pull_rawdata.sh  # Will use ODOO_VERSIONS from .env\n    ```\n\n6. Convert RST to Markdown:\n    ```bash\n    python main.py process-raw\n    ```\n\n7. Process and embed documents:\n    ```bash\n    python main.py process-docs\n    ```\n\n8. Launch the chat interface:\n    ```bash\n    python main.py serve --mode ui\n    ```\n\n9. Launch the API:\n    ```bash\n    python main.py serve --mode api\n    ```\n\n10. Access the UI at port 8501 and the API at port 8000\n\n11. To sync with the latest changes in the Odoo documentation, run:\n    ```bash\n    python main.py check-updates\n    ```\n\n## API Endpoints\n\nThe project provides a REST API for programmatic access to the documentation assistant.\n\n### Authentication\n\nAll API endpoints require Bearer token authentication. Add your API token in the Authorization header:\n```bash\nAuthorization: Bearer your-api-token\n```\n\n### Endpoints\n\nPOST `/api/chat`\nQuery the documentation and get AI-powered responses.\n\nRequest body:\n```json\n{\n    \"query\": \"string\",        // The question about Odoo\n    \"version\": integer,       // Odoo version (160, 170, or 180)\n    \"conversation_history\": [ // Optional\n        {\n            \"user\": \"string\",\n            \"assistant\": \"string\"\n        }\n    ]\n}\n```\n\nResponse:\n```json\n{\n    \"answer\": \"string\",       // AI-generated response\n    \"sources\": [              // Reference documents used\n        {\n            \"url\": \"string\",\n            \"title\": \"string\"\n        }\n    ]\n}\n```\n\nExample:\n```bash\ncurl -X POST \"http://localhost:8000/api/chat\" \\\n-H \"Authorization: Bearer your-api-token\" \\\n-H \"Content-Type: application/json\" \\\n-d '{\n    \"query\": \"How do I install Odoo?\",\n    \"version\": 180,\n    \"conversation_history\": []\n}'\n```\n\nPOST `/api/stream`\nQuery the documentation and get AI-powered responses in streaming format.\n\nRequest body:\n```json\n{\n    \"query\": \"string\",        // The question about Odoo\n    \"version\": integer,       // Odoo version (160, 170, or 180)\n    \"conversation_history\": [ // Optional\n        {\n            \"user\": \"string\",\n            \"assistant\": \"string\"\n        }\n    ]\n}\n```\n\nResponse:\nStream of text chunks (text/event-stream content type)\n\nExample:\n```bash\ncurl -X POST \"http://localhost:8000/api/stream\" \\\n-H \"Authorization: Bearer your-api-token\" \\\n-H \"Content-Type: application/json\" \\\n-d '{\n    \"query\": \"How do I install Odoo?\",\n    \"version\": 180,\n    \"conversation_history\": []\n}'\n```\n\n## Browser Extension Setup\n\nThe project includes a browser extension that enhances the Odoo documentation search experience with AI-powered responses. To set up the extension:\n\n1. Open Chrome/Edge and navigate to the extensions page:\n   - Chrome: `chrome://extensions/`\n   - Edge: `edge://extensions/`\n\n2. Enable \"Developer mode\" in the top right corner\n\n3. Click \"Load unpacked\" and select the `browser-ext` folder from this project\n\n4. The Odoo Expert extension icon should appear in your browser toolbar\n\n5. Make sure your local API server is running (port 8000)\n\nThe extension will now enhance the search experience on Odoo documentation pages by providing AI-powered responses alongside the traditional search results.\n\n## Future Roadmap\n\nPlease see [GitHub Issues](https://github.com/MFYDev/odoo-expert/issues) for the future roadmap.\n\n\n## Support\nIf you encounter any issues or have questions, please:\n\n- Check the known issues\n- Create a new issue in the GitHub repository\n- Provide detailed information about your environment and the problem\n\n\u003e ⚠️ **Please do not directly email me for support, as I will not respond to it at all, let's keep the discussion in the GitHub issues for clarity and transparency.**\n\n## Contributing\nContributions are welcome! Please feel free to submit a Pull Request.\n\nThanks for the following contributors during the development of this project:\n\n- [Viet Din (Desdaemon)](https://github.com/Desdaemon): Giving me important suggestions on how to improve the performance.\n\n## License\n\nThis project is licensed under [Apache License 2.0](./LICENSE): No warranty is provided. You can use this project for any purpose, but you must include the original copyright and license.\n\nExtra license [CC-BY-SA 4.0](./LICENSE-DOCS) to align with the original Odoo/Documentation license.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmfydev%2Fodoo-expert","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmfydev%2Fodoo-expert","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmfydev%2Fodoo-expert/lists"}