From 8762bc242b537cc39e36199d89a69f05891a1ac2 Mon Sep 17 00:00:00 2001
From: deepbuzin <contactbuzin@gmail.com>
Date: Thu, 20 Feb 2025 21:39:26 +0700
Subject: [PATCH] Restructure the JS reference

---
 docs/ai/index.rst                             |   2 +-
 ...avascript.rst => reference_javascript.rst} | 109 +++++++-----------
 docs/ai/reference_python.rst                  |   3 +-
 3 files changed, 45 insertions(+), 69 deletions(-)
 rename docs/ai/{javascript.rst => reference_javascript.rst} (71%)

diff --git a/docs/ai/index.rst b/docs/ai/index.rst
index d1b2af1fcbf..5426ef4609a 100644
--- a/docs/ai/index.rst
+++ b/docs/ai/index.rst
@@ -12,7 +12,7 @@ Gel AI
     reference_extai
     reference_http
     reference_python
-    javascript
+    reference_javascript
     guide_edgeql
     guide_python
     fastapi_gelai_searchbot
diff --git a/docs/ai/javascript.rst b/docs/ai/reference_javascript.rst
similarity index 71%
rename from docs/ai/javascript.rst
rename to docs/ai/reference_javascript.rst
index fc5e7f6305f..d1c9197a8f0 100644
--- a/docs/ai/javascript.rst
+++ b/docs/ai/reference_javascript.rst
@@ -1,38 +1,49 @@
-.. _ref_ai_javascript:
+.. _ref_ai_javascript_reference:
 
-==========
-JavaScript
-==========
+=================
+AI JavaScript API
+=================
 
-:edb-alt-title: Gel AI's JavaScript package
+:edb-alt-title: AI Extension 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|.
 
-.. code-block:: bash
+.. code-tabs::
 
-    $ npm install @gel/ai # or
-    $ yarn add @gel/ai # or
-    $ pnpm add @gel/ai # or
-    $ bun add @gel/ai
+    .. code-tab:: bash
+        :caption: npm
 
+        $ npm install @gel/ai
 
-Usage
-=====
+    .. code-tab:: bash
+        :caption: yarn
 
-Start by importing ``createClient`` from ``gel`` and ``createAI`` from
-``@gel/ai``:
+        $ yarn add @gel/ai
+
+    .. code-tab:: bash
+        :caption: pnpm
+
+        $ pnpm add @gel/ai
+
+    .. code-tab:: bash
+        :caption: bun
+
+        $ bun add @gel/ai
+
+
+Overview
+========
+
+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();
 
@@ -40,55 +51,17 @@ model):
       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, \
@@ -111,14 +84,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
 
diff --git a/docs/ai/reference_python.rst b/docs/ai/reference_python.rst
index fc0b1cecb87..28ee45f0e21 100644
--- a/docs/ai/reference_python.rst
+++ b/docs/ai/reference_python.rst
@@ -6,7 +6,8 @@ AI Python API
 
 :edb-alt-title: AI Extension 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