[18.0][MIG] field_vector: Migration to 18.0

field_vector/README.rst

@@ -0,0 +1,258 @@
+============
+Field Vector
+============
+
+.. 
+   !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+   !! This file is generated by oca-gen-addon-readme !!
+   !! changes will be overwritten.                   !!
+   !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+   !! source digest: sha256:9545962191ec37e88fe11fd9d6e8c01b540134dad5a6482b6a0c19110c7fd3f4
+   !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+
+.. |badge1| image:: https://img.shields.io/badge/maturity-Beta-yellow.png
+    :target: https://odoo-community.org/page/development-status
+    :alt: Beta
+.. |badge2| image:: https://img.shields.io/badge/licence-LGPL--3-blue.png
+    :target: http://www.gnu.org/licenses/lgpl-3.0-standalone.html
+    :alt: License: LGPL-3
+.. |badge3| image:: https://img.shields.io/badge/github-OCA%2Fserver--tools-lightgray.png?logo=github
+    :target: https://github.com/OCA/server-tools/tree/18.0/field_vector
+    :alt: OCA/server-tools
+.. |badge4| image:: https://img.shields.io/badge/weblate-Translate%20me-F47D42.png
+    :target: https://translation.odoo-community.org/projects/server-tools-18-0/server-tools-18-0-field_vector
+    :alt: Translate me on Weblate
+.. |badge5| image:: https://img.shields.io/badge/runboat-Try%20me-875A7B.png
+    :target: https://runboat.odoo-community.org/builds?repo=OCA/server-tools&target_branch=18.0
+    :alt: Try me on Runboat
+
+|badge1| |badge2| |badge3| |badge4| |badge5|
+
+This addon provides a new field type called "Vector" that allows you to
+store and manage vector into your Odoo database.
+
+**Table of contents**
+
+.. contents::
+   :local:
+
+Use Cases / Context
+===================
+
+The advent of large language models (LLMs) has highlighted the
+importance of vector representation as a powerful representation of data
+to easily determine the similarity between different pieces of
+information. Vector representation is a way of encoding information in a
+numerical format that captures the semantic meaning of the data. This
+allows for efficient similarity comparisons.
+
+Installation
+============
+
+To install this module, you need to ensure that the
+`pgvector <https://github.com/pgvector/pgvector>`__ extension is
+installed and available in your PostgreSQL instance.
+
+Configuration
+=============
+
+[ This file is not always required; it should explain **how to configure
+the module before using it**; it is aimed at users with administration
+privileges.
+
+Please be detailed on the path to configuration (eg: do you need to
+activate developer mode?), describe step by step configurations and the
+use of screenshots is strongly recommended.]
+
+To configure this module, you need to:
+
+- Go to *App* > Menu > Menu item
+- Activate boolean… > save
+- …
+
+Usage
+=====
+
+   | **⚠️ Warning**
+   | This addon is **not compatible** with the Python ``pgvector``
+     library. Please ensure that you do not use this library alongside
+     the addon to avoid potential issues. This is mainly due to the fact
+     that numpy arrays can't be stored into the odoo cache since they
+     are not comparable with the default '==' or '!=' operators.
+
+The module is a technical module providing a new field type called
+"Vector". It's intended to be used by developers who want to store and
+manage vector data in their Odoo database when they develop their own
+modules.
+
+Field declaration
+-----------------
+
+To declare a field of type vector, you can use the following syntax:
+
+.. code:: python
+
+
+   from odoo.addons.field_vector.fields import Vector
+
+
+   class YourModel(models.Model):
+       _name = 'your.model'
+
+       vector_field = Vector(dimensions=3)
+
+The ``dimensions`` parameter is required and specifies the number of
+dimensions of the vector. The field will be stored as a ``vector`` type
+in PostgreSQL, which is a native type for storing vectors.
+
+By default the field is declared as no ``prefetch=False`` and with
+``autopad=True``. You can override these parameters by passing them as
+arguments to the field:
+
+.. code:: python
+
+   from odoo.addons.field_vector.fields import Vector
+   class YourModel(models.Model):
+       _name = 'your.model'
+
+       vector_field = Vector(dimensions=3, prefetch=True, autopad=False)
+
+The ``prefetch`` parameter allows you to enable or disable prefetching
+of the field when loading records. If set to ``True``, the field will be
+prefetched when loading records, which can improve performance when
+accessing the field frequently. If set to ``False``, the field will not
+be prefetched, which can save memory and improve performance when
+accessing the field infrequently (which would be the common case).
+
+The ``autopad`` parameter allows you to enable or disable automatic
+padding of the vector when storing it in the database. If set to
+``True``, the vector will be automatically padded with zeros to match
+the specified dimensions. If set to ``False``, the vector will not be
+padded but if the vector is shorter than the specified dimensions an
+error will be raised.
+
+Field usage
+-----------
+
+The vector field can be used like any other field in Odoo. When
+accessing the field, it will always return an
+``odoo.addons.field_vector.fields.VectorValue`` object, which is a
+wrapper around value stored into the database. This object provides a
+convenient way to get the value of the vector as a numpy array.
+
+.. code:: python
+
+   import numpy as np
+   from odoo.addons.field_vector.fields import  VectorValue
+
+   record = self.env['your.model'].create({
+       'vector_field': [1.0, 2.0, 3.0]
+   })
+
+   assert isinstance(record.vector_field, VectorValue)
+   assert isinstance(record.vector_field.value, np.ndarray)
+
+When setting the field, you can pass a list of values or a numpy array
+or a ``VectorValue`` object or a list/tuple of values. The field will
+automatically convert the value to a VectorValue and store it in the
+database into the vector format.
+
+.. code:: python
+
+
+   record.vector_field = [1.0, 2.0, 3.0]
+   assert isinstance(record.vector_field, VectorValue)
+
+   record.vector_field = np.array([1.0, 2.0, 3.0])
+   assert isinstance(record.vector_field, VectorValue)
+
+   record.vector_field = VectorValue([1.0, 2.0, 3.0])
+   assert isinstance(record.vector_field, VectorValue)
+
+Plain SQL queries
+-----------------
+
+When reading the field in plain SQL queries, the field will be returned
+as a ``VectorValue`` object. You can use the ``value`` property to get
+the value of the vector as a numpy array.
+
+.. code:: python
+
+
+   env.cr.execute('SELECT vector_field FROM your_model WHERE id = 1')
+   record = env.cr.fetchone()
+   vector_value = record[0]
+   assert isinstance(vector_value, VectorValue)
+
+When writing the field in plain SQL queries, you can pass a numpy array
+or a list of values or a VectorValue object as the value of the field
+(in this specific case tuples are not supported).
+
+.. code:: python
+
+
+   env.cr.execute('UPDATE your_model SET vector_field = %s WHERE id = 1', (np.array([1.0, 2.0, 3.0]),))
+   env.cr.execute('UPDATE your_model SET vector_field = %s WHERE id = 1', ([1.0, 2.0, 3.0],))
+   env.cr.execute('UPDATE your_model SET vector_field = %s WHERE id = 1', (VectorValue([1.0, 2.0, 3.0]),))
+
+Known issues / Roadmap
+======================
+
+- allows the use of specific operators into domain filters to search for
+  similar vectors.
+- dedicated widget to display the vector in a more user-friendly way.
+
+Bug Tracker
+===========
+
+Bugs are tracked on `GitHub Issues <https://github.com/OCA/server-tools/issues>`_.
+In case of trouble, please check there if your issue has already been reported.
+If you spotted it first, help us to smash it by providing a detailed and welcomed
+`feedback <https://github.com/OCA/server-tools/issues/new?body=module:%20field_vector%0Aversion:%2018.0%0A%0A**Steps%20to%20reproduce**%0A-%20...%0A%0A**Current%20behavior**%0A%0A**Expected%20behavior**>`_.
+
+Do not contact contributors directly about support or help with technical issues.
+
+Credits
+=======
+
+Authors
+-------
+
+* ACSONE SA/NV
+
+Contributors
+------------
+
+- Laurent Mignon laurent.mignon@acsone.eu (https://www.acsone.eu)
+
+Other credits
+-------------
+
+The development of this module has been financially supported by:
+
+- `Alcyon Belux <https://www.alcyonbelux.be/>`__
+
+Maintainers
+-----------
+
+This module is maintained by the OCA.
+
+.. image:: https://odoo-community.org/logo.png
+   :alt: Odoo Community Association
+   :target: https://odoo-community.org
+
+OCA, or the Odoo Community Association, is a nonprofit organization whose
+mission is to support the collaborative development of Odoo features and
+promote its widespread use.
+
+.. |maintainer-lmignon| image:: https://github.com/lmignon.png?size=40px
+    :target: https://github.com/lmignon
+    :alt: lmignon
+
+Current `maintainer <https://odoo-community.org/page/maintainer-role>`__:
+
+|maintainer-lmignon| 
+
+This module is part of the `OCA/server-tools <https://github.com/OCA/server-tools/tree/18.0/field_vector>`_ project on GitHub.
+
+You are welcome to contribute. To learn how please visit https://odoo-community.org/page/Contribute.

field_vector/__init__.py

@@ -0,0 +1,2 @@
+from . import models
+from .hooks import pre_init_hook

field_vector/__manifest__.py

@@ -0,0 +1,18 @@
+# Copyright 2025 ACSONE SA/NV
+# License LGPL-3.0 or later (https://www.gnu.org/licenses/lgpl).
+
+{
+    "name": "Field Vector",
+    "summary": """New specialized field to store vector data""",
+    "version": "18.0.1.0.0",
+    "license": "LGPL-3",
+    "author": "ACSONE SA/NV,Odoo Community Association (OCA)",
+    "website": "https://github.com/OCA/server-tools",
+    "depends": ["base"],
+    "maintainers": ["lmignon"],
+    "installable": True,
+    "pre_init_hook": "pre_init_hook",
+    "external_dependencies": {
+        "python": ["numpy"],
+    },
+}