Metadata-Version: 2.1
Name: odoo-addon-field_vector
Version: 19.0.1.0.0.3
Requires-Dist: numpy
Requires-Dist: odoo==19.0.*
Summary: New specialized field to store vector data
Home-page: https://github.com/OCA/server-tools
License: LGPL-3
Author: ACSONE SA/NV,Odoo Community Association (OCA)
Author-email: support@odoo-community.org
Classifier: Programming Language :: Python
Classifier: Framework :: Odoo
Classifier: Framework :: Odoo :: 19.0
Classifier: License :: OSI Approved :: GNU Lesser General Public License v3 (LGPLv3)
Description-Content-Type: text/x-rst

.. image:: https://odoo-community.org/readme-banner-image
   :target: https://odoo-community.org/get-involved?utm_source=readme
   :alt: Odoo Community Association

============
Field Vector
============

.. 
   !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
   !! This file is generated by oca-gen-addon-readme !!
   !! changes will be overwritten.                   !!
   !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
   !! source digest: sha256:bb378088b28008f1ae866656dec61feacb1935d4608e753c5a7b98507037e10c
   !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!

.. |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/license-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/19.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-19-0/server-tools-19-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=19.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.

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:%2019.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/19.0/field_vector>`_ project on GitHub.

You are welcome to contribute. To learn how please visit https://odoo-community.org/page/Contribute.
