AI docs refinements

docs/ai/extvectorstore.rst

@@ -0,0 +1,80 @@
+.. _ref_extvectorstore_reference:
+
+=====================
+Vectorstore Extension
+=====================
+
+
+The ``vectorstore`` extension package provides simplified vectorstore workflows
+for |Gel|, built on top of the pgvector integration. It includes predefined
+vector dimensions and a base schema for vector storage records.
+
+
+Enabling the extension
+======================
+
+The extension package can be installed using the :gelcmd:`extension` CLI
+command:
+
+.. code-block:: bash
+
+    $ gel extension install vectorstore
+
+
+It can be enabled using the :ref:`extension <ref_datamodel_extensions>`
+mechanism:
+
+.. code-block:: sdl
+
+    using extension vectorstore;
+
+
+The Vectorstore extension is designed to be used in combination with the
+Vectostore Python binding or other integraions, rather than on its own.
+
+
+Types
+=====
+
+Vector Types
+------------
+
+The extension provides two pre-defined vector types with different dimensions:
+
+- ``ext::vectorstore::vector_1024``: 1024-dimensional vector
+- ``ext::vectorstore::vector_1536``: 1536-dimensional vector
+
+All vector types extend ``ext::pgvector::vector`` with their respective dimensions.
+
+
+Record Types
+------------
+
+.. eql:type:: ext::vectorstore::BaseRecord
+
+    Abstract type that defines the basic structure for vector storage records.
+
+    Properties:
+
+    * ``collection: str`` (required): Identifies the collection the record belongs to
+    * ``text: str``: Associated text content
+    * ``embedding: ext::pgvector::vector``: The vector embedding
+    * ``external_id: str``: External identifier with unique constraint
+    * ``metadata: json``: Additional metadata in JSON format
+
+
+.. eql:type:: ext::vectorstore::DefaultRecord
+
+    Extends :eql:type:`ext::vectorstore::BaseRecord` with specific
+    configurations.
+
+    Properties:
+
+    * Inherits all properties from :eql:type:`ext::vectorstore::BaseRecord`
+    * Specializes ``embedding`` to use ``vector_1536`` type
+    * Includes an HNSW cosine similarity index on the embedding with:
+
+      * ``m = 16``
+      * ``ef_construction = 128``
+
+

docs/ai/index.rst

@@ -12,6 +12,8 @@ Gel AI
     http
     python
     javascript
+    extvectorstore
+    vectorstore_python
 
 :edb-alt-title: Using Gel AI
 

docs/ai/javascript.rst

@@ -1,103 +1,65 @@
-.. _ref_ai_javascript:
+.. _ref_ai_javascript_reference:
 
 ==============
 JavaScript API
 ==============
 
-``@gel/ai`` offers a convenient wrapper around ``ext::ai``. Install it with
-npm or via your package manager of choice:
+``@gel/ai`` is a wrapper around the :ref:`AI extension
+<ref_ai_extai_reference>` in |Gel|.
 
 .. tabs::
 
     .. code-tab:: bash
+        :caption: npm
 
         $ npm install @gel/ai
 
     .. code-tab:: bash
+        :caption: yarn
 
         $ yarn add @gel/ai
 
     .. code-tab:: bash
+        :caption: pnpm
 
         $ pnpm add @gel/ai
 
     .. code-tab:: bash
+        :caption: bun
 
         $ bun add @gel/ai
 
 
-Usage
-=====
+Overview
+========
 
-Start by importing ``createClient`` from ``gel`` and ``createAI`` from
-``@gel/ai``:
+The AI package is built on top of the regular |Gel| client objects.
+
+**Example**:
 
 .. code-block:: typescript
 
     import { createClient } from "gel";
     import { createAI } from "@gel/ai";
 
-Create a |Gel| client. Create an instance of the AI client by passing in the
-Gel client and any options for the AI provider (like the text generation
-model):
-
-.. code-block:: typescript
 
     const client = createClient();
 
     const gpt4Ai = createAI(client, {
       model: "gpt-4-turbo-preview",
     });
 
-You may use any of the supported :ref:`text generation models
-<ref_ai_extai_reference_text_generation_models>`. Add your query as context:
-
-.. code-block:: typescript
-
     const astronomyAi = gpt4Ai.withContext({
       query: "Astronomy"
     });
 
-This "query" property doesn't have to be a proper query at all. It can be any
-expression that produces a set of objects, like ``Astronomy`` in the example
-above which will return all objects of that type. On the other hand, if you
-want to narrow the field more, you can give it a query like ``select Astronomy
-filter .topic = "Mars"``.
-
-The default text generation prompt will ask your selected provider to limit
-answer to information provided in the context and will pass the queried
-objects' AI index as context along with that prompt.
-
-Call your AI client's ``queryRag`` method, passing in a text query.
-
-.. code-block:: typescript
-
     console.log(
       await astronomyAi.queryRag("What color is the sky on Mars?")
     );
 
-You can chain additional calls of ``withContext`` or ``withConfig`` to create
-additional AI clients, identical except for the newly specified values.
-
-.. code-block:: typescript
-
-    const fastAstronomyAi = astronomyAi.withConfig({
-      model: "gpt-3.5-turbo",
-    });
-    console.log(
-      await fastAstronomyAi.queryRag("What color is the sky on Mars?")
-    );
-
-    const fastChemistryAi = fastAstronomyAi.withContext({
-      query: "Chemistry"
-    });
-    console.log(
-      await fastChemistryAi.queryRag("What is the atomic number of gold?")
-    );
 
-
-API Reference
-=============
+Factory functions
+=================
 
 .. js:function:: createAI( \
                    client: Client, \
@@ -120,14 +82,16 @@ API Reference
         interactions. The default is the built-in system prompt.
 
 
-GelAI
------
+Core classes
+============
+
+
+.. js:class:: GelAI
 
-Instances of ``GelAI`` offer methods for client configuration and utilizing
-RAG.
+    Instances of ``GelAI`` offer methods for client configuration and utilizing RAG.
 
-Public methods
-^^^^^^^^^^^^^^
+    :ivar client:
+        An instance of |Gel| client.
 
 .. js:method:: withConfig(options: Partial<AIOptions>): GelAI
 

docs/ai/python.rst

@@ -4,7 +4,8 @@
 Python API
 ==========
 
-The ``gel.ai`` package is an optional binding of the AI extension in |Gel|.
+The ``gel.ai`` package is an optional binding of the :ref:`AI extension
+<ref_ai_extai_reference>` in |Gel|.
 
 .. code-block:: bash