Documentation updates (neo4j#70)

* 0.2.1 documentation update

* Docstring updates

Author: willtai

README.md

@@ -22,50 +22,6 @@ pip install neo4j-genai
 
 ## Examples
 
-While the library has more retrievers than shown here, the following examples should be able to get you started.
-
-### Performing a similarity search
-
-Assumption: Neo4j running with populated vector index in place.
-
-In the following example, we use a simple vector search as retriever,
-that will perform a similarity search over the `index-name` vector index
-in Neo4j.
-
-```python
-from neo4j import GraphDatabase
-from neo4j_genai.retrievers import VectorRetriever
-from neo4j_genai.llm import OpenAILLM
-from neo4j_genai.generation import GraphRAG
-from neo4j_genai.embeddings.openai import OpenAIEmbeddings
-
-URI = "neo4j://localhost:7687"
-AUTH = ("neo4j", "password")
-
-INDEX_NAME = "index-name"
-
-# Connect to Neo4j database
-driver = GraphDatabase.driver(URI, auth=AUTH)
-
-# Create Embedder object
-embedder = OpenAIEmbeddings(model="text-embedding-3-large")
-
-# Initialize the retriever
-retriever = VectorRetriever(driver, INDEX_NAME, embedder)
-
-# Initialize the LLM
-# Note: the OPENAI_API_KEY must be in the env vars
-llm = OpenAILLM(model_name="gpt-4o", model_params={"temperature": 0})
-
-# Initialize the RAG pipeline
-rag = GraphRAG(retriever=retriever, llm=llm)
-
-# Query the graph
-query_text = "How do I do similarity search in Neo4j?"
-response = rag.search(query_text=query_text, retriever_config={"top_k": 5})
-print(response.answer)
-```
-
 ### Creating a vector index
 
 When creating a vector index, make sure you match the number of dimensions in the index with the number of dimensions the embeddings have.
@@ -79,7 +35,7 @@ from neo4j_genai.indexes import create_vector_index
 URI = "neo4j://localhost:7687"
 AUTH = ("neo4j", "password")
 
-INDEX_NAME = "chunk-index"
+INDEX_NAME = "vector-index-name"
 
 # Connect to Neo4j database
 driver = GraphDatabase.driver(URI, auth=AUTH)
@@ -98,8 +54,8 @@ create_vector_index(
 
 ### Populating the Neo4j Vector Index
 
-This library does not write to the database, that is up to you.
-See below for how to write using Cypher via the Neo4j driver.
+This library does not provide functionality to write data to the database.
+See below for how to do this using [the Neo4j Python driver](https://github.com/neo4j/neo4j-python-driver).
 
 Assumption: Neo4j running with a defined vector index
 
@@ -115,19 +71,65 @@ driver = GraphDatabase.driver(URI, auth=AUTH)
 
 # Upsert the vector
 vector = [random() for _ in range(DIMENSION)]
-insert_query = (
-    "MERGE (n:Document {id: $id})"
-    "WITH n "
-    "CALL db.create.setNodeVectorProperty(n, 'vectorProperty', $vector)"
-    "RETURN n"
-)
+insert_query = """
+    MERGE (n:Document {id: $id})
+    WITH n
+    CALL db.create.setNodeVectorProperty(n, 'vectorProperty', $vector)
+    RETURN n
+"""
 parameters = {
     "id": 0,
     "vector": vector,
 }
 driver.execute_query(insert_query, parameters)
 ```
 
+### Performing a similarity search
+
+Assumption: Neo4j running with populated vector index in place.
+
+Limitation: The query over the vector index is an _approximate_ nearest neighbor search and may not give exact results. [See this reference for more details](https://neo4j.com/docs/cypher-manual/current/indexes/semantic-indexes/vector-indexes/#_limitiations_and_known_issues).
+
+While the library has more retrievers than shown here, the following examples should be able to get you started.
+
+In the following example, we use a simple vector search as retriever,
+that will perform a similarity search over the `index-name` vector index
+in Neo4j.
+
+```python
+from neo4j import GraphDatabase
+from neo4j_genai.retrievers import VectorRetriever
+from neo4j_genai.llm import OpenAILLM
+from neo4j_genai.generation import GraphRAG
+from neo4j_genai.embeddings.openai import OpenAIEmbeddings
+
+URI = "neo4j://localhost:7687"
+AUTH = ("neo4j", "password")
+
+INDEX_NAME = "vector-index-name"
+
+# Connect to Neo4j database
+driver = GraphDatabase.driver(URI, auth=AUTH)
+
+# Create Embedder object
+embedder = OpenAIEmbeddings(model="text-embedding-3-large")
+
+# Initialize the retriever
+retriever = VectorRetriever(driver, INDEX_NAME, embedder)
+
+# Initialize the LLM
+# Note: An OPENAI_API_KEY environment variable is required here
+llm = OpenAILLM(model_name="gpt-4o", model_params={"temperature": 0})
+
+# Initialize the RAG pipeline
+rag = GraphRAG(retriever=retriever, llm=llm)
+
+# Query the graph
+query_text = "How do I do similarity search in Neo4j?"
+response = rag.search(query_text=query_text, retriever_config={"top_k": 5})
+print(response.answer)
+```
+
 # Development
 
 ## Install dependencies

docs/source/api.rst

@@ -3,6 +3,8 @@
 API Documentation
 #################
 
+.. _retrievers-section:
+
 **********
 Retrievers
 **********
@@ -63,6 +65,21 @@ PineconeNeo4jRetriever
     :members: search
 
 
+********************
+Database Interaction
+********************
+
+.. _create-vector-index:
+
+.. autofunction:: neo4j_genai.indexes.create_vector_index
+
+.. autofunction:: neo4j_genai.indexes.create_fulltext_index
+
+.. autofunction:: neo4j_genai.indexes.drop_index_if_exists
+
+.. autofunction:: neo4j_genai.indexes.upsert_vector
+
+
 ******
 Errors
 ******

docs/source/index.rst

@@ -54,46 +54,14 @@ To install the latest stable version, use:
 Examples
 ********
 
-While the library has more retrievers than shown here, the following examples should be able to get you started.
-
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-Performing a similarity search
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-.. code:: python
-
-    from neo4j import GraphDatabase
-    from neo4j_genai.retrievers import VectorRetriever
-    from langchain_openai import OpenAIEmbeddings
-
-    URI = "neo4j://localhost:7687"
-    AUTH = ("neo4j", "password")
-
-    INDEX_NAME = "embedding-name"
-
-    # Connect to Neo4j database
-    driver = GraphDatabase.driver(URI, auth=AUTH)
-
-    # Create Embedder object
-    embedder = OpenAIEmbeddings(model="text-embedding-3-large")
-
-    # Initialize the retriever
-    retriever = VectorRetriever(driver, INDEX_NAME, embedder)
-
-    # Run the similarity search
-    query_text = "How do I do similarity search in Neo4j?"
-    response = retriever.search(query_text=query_text, top_k=5)
-
-.. note::
-
-    Assumption: Neo4j running with populated vector index in place.
-
 ~~~~~~~~~~~~~~~~~~~~~~~
 Creating a vector index
 ~~~~~~~~~~~~~~~~~~~~~~~
 
 When creating a vector index, make sure you match the number of dimensions in the index with the number of dimensions the embeddings have.
 
+See :ref:`the API documentation<create-vector-index>` for more details.
+
 .. code:: python
 
     from neo4j import GraphDatabase
@@ -102,7 +70,7 @@ When creating a vector index, make sure you match the number of dimensions in th
     URI = "neo4j://localhost:7687"
     AUTH = ("neo4j", "password")
 
-    INDEX_NAME = "chunk-index"
+    INDEX_NAME = "vector-index-name"
 
     # Connect to Neo4j database
     driver = GraphDatabase.driver(URI, auth=AUTH)
@@ -119,14 +87,15 @@ When creating a vector index, make sure you match the number of dimensions in th
 
 .. note::
 
-    Assumption: Neo4j running
+    Assumed Neo4j is running
 
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 Populating the Neo4j Vector Index
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-This library does not write to the database, that is up to you.
-See below for how to write using Cypher via the Neo4j driver.
+This library does not provide functionality to write data to the database.
+See below for writing data using `the Neo4j Python driver <https://github.com/neo4j/neo4j-python-driver>`_.
+
 
 .. code:: python
 
@@ -141,12 +110,12 @@ See below for how to write using Cypher via the Neo4j driver.
 
     # Upsert the vector
     vector = [random() for _ in range(DIMENSION)]
-    insert_query = (
-        "MERGE (n:Document {id: $id})"
-        "WITH n "
-        "CALL db.create.setNodeVectorProperty(n, 'vectorProperty', $vector)"
-        "RETURN n"
-    )
+    insert_query = """
+        MERGE (n:Document {id: $id})
+        WITH n
+        CALL db.create.setNodeVectorProperty(n, 'vectorProperty', $vector)
+        RETURN n
+    """
     parameters = {
         "id": 0,
         "vector": vector,
@@ -156,7 +125,49 @@ See below for how to write using Cypher via the Neo4j driver.
 
 .. note::
 
-    Assumption: Neo4j running with a defined vector index
+    Assumed Neo4j is running with a defined vector index
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Performing a similarity search
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+While the library has more retrievers than shown here, the following examples should be able to get you started.
+
+.. code:: python
+
+    from neo4j import GraphDatabase
+    from neo4j_genai.retrievers import VectorRetriever
+    from langchain_openai import OpenAIEmbeddings
+
+    URI = "neo4j://localhost:7687"
+    AUTH = ("neo4j", "password")
+
+    INDEX_NAME = "vector-index-name"
+
+    # Connect to Neo4j database
+    driver = GraphDatabase.driver(URI, auth=AUTH)
+
+    # Create Embedder object
+    # Note: An OPENAI_API_KEY environment variable is required here
+    embedder = OpenAIEmbeddings(model="text-embedding-3-large")
+
+    # Initialize the retriever
+    retriever = VectorRetriever(driver, INDEX_NAME, embedder)
+
+    # Run the similarity search
+    query_text = "How do I do similarity search in Neo4j?"
+    response = retriever.search(query_text=query_text, top_k=5)
+
+.. note::
+
+    Assumed Neo4j is running with populated vector index in place.
+
+***********
+Limitations
+***********
+
+The query over the vector index is an *approximate* nearest neighbor search and may not give exact results. `See this reference for more details <https://neo4j.com/docs/cypher-manual/current/indexes/semantic-indexes/vector-indexes/#_limitiations_and_known_issues>`_.
+
 
 Development
 ===========

docs/source/rag.rst

@@ -11,6 +11,8 @@ source information from external data stores to augment generated responses.
 
 This package enables Python developers to perform RAG using Neo4j.
 
+For more information about different retrieval strategies, see `the API documentation <api.html#retrievers-section>`_.
+
 
 ************************************
 Overview
@@ -27,7 +29,7 @@ Overview
     URI = "neo4j://localhost:7687"
     AUTH = ("neo4j", "password")
 
-    INDEX_NAME = "index-name"
+    INDEX_NAME = "vector-index-name"
 
     # Connect to Neo4j database
     driver = GraphDatabase.driver(URI, auth=AUTH)