community: Deprecate Amazon Neptune resources in langchain-community (#29191)

Related: https://github.com/langchain-ai/langchain-aws/pull/322

The legacy `NeptuneOpenCypherQAChain` and `NeptuneSparqlQAChain` classes
are being replaced by the new LCEL format chains
`create_neptune_opencypher_qa_chain` and
`create_neptune_sparql_qa_chain`, respectively, in the `langchain_aws`
package.

This PR adds deprecation warnings to all Neptune classes and functions
that have been migrated to `langchain_aws`. All relevant documentation
has also been updated to replace `langchain_community` usage with the
new `langchain_aws` implementations.

---------

Co-authored-by: Chester Curme <chester.curme@gmail.com>

docs/docs/integrations/graphs/amazon_neptune_open_cypher.ipynb

@@ -15,13 +15,14 @@
     ">[openCypher](https://opencypher.org/) is an open-source implementation of Cypher.# Neptune Open Cypher QA Chain\n",
     "This QA chain queries Amazon Neptune using openCypher and returns human readable response\n",
     "\n",
-    "LangChain supports both [Neptune Database](https://docs.aws.amazon.com/neptune/latest/userguide/intro.html) and [Neptune Analytics](https://docs.aws.amazon.com/neptune-analytics/latest/userguide/what-is-neptune-analytics.html) with `NeptuneOpenCypherQAChain` \n",
+    "LangChain supports both [Neptune Database](https://docs.aws.amazon.com/neptune/latest/userguide/intro.html) and [Neptune Analytics](https://docs.aws.amazon.com/neptune-analytics/latest/userguide/what-is-neptune-analytics.html) with `create_neptune_opencypher_qa_chain`.\n",
-    "\n",
     "\n",
     "Neptune Database is a serverless graph database designed for optimal scalability and availability. It provides a solution for graph database workloads that need to scale to 100,000 queries per second, Multi-AZ high availability, and multi-Region deployments. You can use Neptune Database for social networking, fraud alerting, and Customer 360 applications.\n",
     "\n",
     "Neptune Analytics is an analytics database engine that can quickly analyze large amounts of graph data in memory to get insights and find trends. Neptune Analytics is a solution for quickly analyzing existing graph databases or graph datasets stored in a data lake. It uses popular graph analytic algorithms and low-latency analytic queries.\n",
     "\n",
+    "\n",
+    "\n",
     "## Using Neptune Database"
    ]
   },
@@ -31,7 +32,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "from langchain_community.graphs import NeptuneGraph\n",
+    "from langchain_aws.graphs import NeptuneGraph\n",
     "\n",
     "host = \"<neptune-host>\"\n",
     "port = 8182\n",
@@ -53,7 +54,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "from langchain_community.graphs import NeptuneAnalyticsGraph\n",
+    "from langchain_aws.graphs import NeptuneAnalyticsGraph\n",
     "\n",
     "graph = NeptuneAnalyticsGraph(graph_identifier=\"<neptune-analytics-graph-id>\")"
    ]
@@ -62,36 +63,35 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "## Using NeptuneOpenCypherQAChain\n",
+    "## Using the Neptune openCypher QA Chain\n",
     "\n",
-    "This QA chain queries Neptune graph database using openCypher and returns human readable response."
+    "This QA chain queries the Neptune graph database using openCypher and returns a human-readable response."
    ]
   },
   {
    "cell_type": "code",
    "execution_count": null,
    "metadata": {},
-   "outputs": [
+   "outputs": [],
-    {
-     "data": {
-      "text/plain": [
-       "'The Austin airport has 98 outgoing routes.'"
-      ]
-     },
-     "execution_count": 3,
-     "metadata": {},
-     "output_type": "execute_result"
-    }
-   ],
    "source": [
-    "from langchain.chains import NeptuneOpenCypherQAChain\n",
+    "from langchain_aws import ChatBedrockConverse\n",
-    "from langchain_openai import ChatOpenAI\n",
+    "from langchain_aws.chains import create_neptune_opencypher_qa_chain\n",
     "\n",
-    "llm = ChatOpenAI(temperature=0, model=\"gpt-4\")\n",
+    "MODEL_ID = \"anthropic.claude-3-5-sonnet-20241022-v2:0\"\n",
+    "llm = ChatBedrockConverse(\n",
+    "    model=MODEL_ID,\n",
+    "    temperature=0,\n",
+    ")\n",
     "\n",
-    "chain = NeptuneOpenCypherQAChain.from_llm(llm=llm, graph=graph)\n",
+    "chain = create_neptune_opencypher_qa_chain(\n",
+    "    llm=llm,\n",
+    "    graph=graph,\n",
+    ")\n",
     "\n",
-    "chain.invoke(\"how many outgoing routes does the Austin airport have?\")"
+    "result = chain.invoke(\n",
+    "    {\"query\": \"How many outgoing routes does the Austin airport have?\"}\n",
+    ")\n",
+    "print(result[\"result\"].content)"
    ]
   }
  ],

docs/docs/integrations/graphs/amazon_neptune_sparql.ipynb

@@ -15,7 +15,7 @@
     "\n",
     "\n",
     "This example uses a `NeptuneRdfGraph` class that connects with the Neptune database and loads its schema. \n",
-    "The `NeptuneSparqlQAChain` is used to connect the graph and LLM to ask natural language questions.\n",
+    "The `create_neptune_sparql_qa_chain` is used to connect the graph and LLM to ask natural language questions.\n",
     "\n",
     "This notebook demonstrates an example using organizational data.\n",
     "\n",
@@ -60,6 +60,11 @@
     "STAGE_BUCKET = \"<bucket-name>\""
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": ""
+  },
   {
    "cell_type": "code",
    "execution_count": null,
@@ -118,7 +123,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "!pip install --upgrade --quiet langchain langchain-community langchain-aws"
+    "!pip install --upgrade --quiet langchain-aws"
    ]
   },
   {
@@ -238,48 +243,37 @@
     "\"\"\""
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": "### Create the Neptune Database RDF Graph"
+  },
   {
    "cell_type": "code",
    "execution_count": null,
    "metadata": {},
    "outputs": [],
    "source": [
-    "import boto3\n",
+    "from langchain_aws.graphs import NeptuneRdfGraph\n",
-    "from langchain_aws import ChatBedrock\n",
-    "from langchain_community.chains.graph_qa.neptune_sparql import NeptuneSparqlQAChain\n",
-    "from langchain_community.graphs import NeptuneRdfGraph\n",
     "\n",
     "host = \"<your host>\"\n",
     "port = 8182  # change if different\n",
     "region = \"us-east-1\"  # change if different\n",
     "graph = NeptuneRdfGraph(host=host, port=port, use_iam_auth=True, region_name=region)\n",
     "\n",
-    "# Optionally change the schema\n",
+    "# Optionally, change the schema\n",
     "# elems = graph.get_schema_elements\n",
     "# change elems ...\n",
-    "# graph.load_schema(elems)\n",
+    "# graph.load_schema(elems)"
-    "\n",
-    "MODEL_ID = \"anthropic.claude-v2\"\n",
-    "bedrock_client = boto3.client(\"bedrock-runtime\")\n",
-    "llm = ChatBedrock(model_id=MODEL_ID, client=bedrock_client)\n",
-    "\n",
-    "chain = NeptuneSparqlQAChain.from_llm(\n",
-    "    llm=llm,\n",
-    "    graph=graph,\n",
-    "    examples=EXAMPLES,\n",
-    "    verbose=True,\n",
-    "    top_K=10,\n",
-    "    return_intermediate_steps=True,\n",
-    "    return_direct=False,\n",
-    ")"
    ]
   },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "## Ask questions\n",
+    "## Using the Neptune SPARQL QA Chain\n",
-    "Depends on the data we ingested above"
+    "\n",
+    "This QA chain queries the Neptune graph database using SPARQL and returns a human-readable response."
    ]
   },
   {
@@ -288,7 +282,31 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "chain.invoke(\"\"\"How many organizations are in the graph\"\"\")"
+    "from langchain_aws import ChatBedrockConverse\n",
+    "from langchain_aws.chains import create_neptune_sparql_qa_chain\n",
+    "\n",
+    "MODEL_ID = \"anthropic.claude-3-5-sonnet-20241022-v2:0\"\n",
+    "llm = ChatBedrockConverse(\n",
+    "    model_id=MODEL_ID,\n",
+    "    temperature=0,\n",
+    ")\n",
+    "\n",
+    "chain = create_neptune_sparql_qa_chain(\n",
+    "    llm=llm,\n",
+    "    graph=graph,\n",
+    "    examples=EXAMPLES,\n",
+    ")\n",
+    "\n",
+    "result = chain.invoke({\"query\": \"How many organizations are in the graph?\"})\n",
+    "print(result[\"result\"].content)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Extra questions\n",
+    "Here are a few more prompts to try on the graph data that was ingested.\n"
    ]
   },
   {
@@ -297,7 +315,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "chain.invoke(\"\"\"Are there any mergers or acquisitions\"\"\")"
+    "chain.invoke({\"query\": \"Are there any mergers or acquisitions?\"})"
    ]
   },
   {
@@ -306,7 +324,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "chain.invoke(\"\"\"Find organizations\"\"\")"
+    "chain.invoke({\"query\": \"Find organizations.\"})"
    ]
   },
   {
@@ -315,7 +333,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "chain.invoke(\"\"\"Find sites of MegaSystems or MegaFinancial\"\"\")"
+    "chain.invoke({\"query\": \"Find sites of MegaSystems or MegaFinancial.\"})"
    ]
   },
   {
@@ -324,7 +342,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "chain.invoke(\"\"\"Find a member who is manager of one or more members.\"\"\")"
+    "chain.invoke({\"query\": \"Find a member who is a manager of one or more members.\"})"
    ]
   },
   {
@@ -333,7 +351,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "chain.invoke(\"\"\"Find five members and who their manager is.\"\"\")"
+    "chain.invoke({\"query\": \"Find five members and their managers.\"})"
    ]
   },
   {
@@ -343,7 +361,9 @@
    "outputs": [],
    "source": [
     "chain.invoke(\n",
-    "    \"\"\"Find org units or suborganizations of The Mega Group. What are the sites of those units?\"\"\"\n",
+    "    {\n",
+    "        \"query\": \"Find org units or suborganizations of The Mega Group. What are the sites of those units?\"\n",
+    "    }\n",
     ")"
    ]
   }

docs/docs/integrations/providers/aws.mdx

@@ -310,14 +310,25 @@ from langchain_community.chat_message_histories import DynamoDBChatMessageHistor
 
 ## Graphs
 
+### Amazon Neptune
+
+>[Amazon Neptune](https://aws.amazon.com/neptune/)
+> is a high-performance graph analytics and serverless database for superior scalability and availability.
+
+For the Cypher and SPARQL integrations below, we need to install the `langchain-aws` library.
+
+```bash
+pip install langchain-aws
+```
+
 ### Amazon Neptune with Cypher
 
 See a [usage example](/docs/integrations/graphs/amazon_neptune_open_cypher).
 
 ```python
-from langchain_community.graphs import NeptuneGraph
+from langchain_aws.graphs import NeptuneGraph
-from langchain_community.graphs import NeptuneAnalyticsGraph
+from langchain_aws.graphs import NeptuneAnalyticsGraph
-from langchain_community.chains.graph_qa.neptune_cypher import NeptuneOpenCypherQAChain
+from langchain_aws.chains import create_neptune_opencypher_qa_chain
 ```
 
 ### Amazon Neptune with SPARQL
@@ -325,8 +336,8 @@ from langchain_community.chains.graph_qa.neptune_cypher import NeptuneOpenCypher
 See a [usage example](/docs/integrations/graphs/amazon_neptune_sparql).
 
 ```python
-from langchain_community.graphs import NeptuneRdfGraph
+from langchain_aws.graphs import NeptuneRdfGraph
-from langchain_community.chains.graph_qa.neptune_sparql import NeptuneSparqlQAChain
+from langchain_aws.chains import create_neptune_sparql_qa_chain
 ```
 
 

libs/community/langchain_community/chains/graph_qa/neptune_cypher.py

@@ -6,6 +6,7 @@ from typing import Any, Dict, List, Optional
 from langchain.chains.base import Chain
 from langchain.chains.llm import LLMChain
 from langchain.chains.prompt_selector import ConditionalPromptSelector
+from langchain_core._api.deprecation import deprecated
 from langchain_core.callbacks import CallbackManagerForChainRun
 from langchain_core.language_models import BaseLanguageModel
 from langchain_core.prompts.base import BasePromptTemplate
@@ -82,6 +83,11 @@ PROMPT_SELECTOR = ConditionalPromptSelector(
 )
 
 
+@deprecated(
+    since="0.3.15",
+    removal="1.0",
+    alternative_import="langchain_aws.create_neptune_opencypher_qa_chain",
+)
 class NeptuneOpenCypherQAChain(Chain):
     """Chain for question-answering against a Neptune graph
     by generating openCypher statements.

libs/community/langchain_community/chains/graph_qa/neptune_sparql.py

@@ -8,6 +8,7 @@ from typing import Any, Dict, List, Optional
 
 from langchain.chains.base import Chain
 from langchain.chains.llm import LLMChain
+from langchain_core._api.deprecation import deprecated
 from langchain_core.callbacks.manager import CallbackManagerForChainRun
 from langchain_core.language_models import BaseLanguageModel
 from langchain_core.prompts.base import BasePromptTemplate
@@ -75,6 +76,11 @@ def extract_sparql(query: str) -> str:
     return query
 
 
+@deprecated(
+    since="0.3.15",
+    removal="1.0",
+    alternative_import="langchain_aws.create_neptune_sparql_qa_chain",
+)
 class NeptuneSparqlQAChain(Chain):
     """Chain for question-answering against a Neptune graph
     by generating SPARQL statements.

libs/community/langchain_community/graphs/neptune_graph.py

@@ -2,6 +2,8 @@ import json
 from abc import ABC, abstractmethod
 from typing import Any, Dict, List, Optional, Tuple, Union
 
+from langchain_core._api.deprecation import deprecated
+
 
 class NeptuneQueryException(Exception):
     """Exception for the Neptune queries."""
@@ -139,6 +141,11 @@ class BaseNeptuneGraph(ABC):
         """
 
 
+@deprecated(
+    since="0.3.15",
+    removal="1.0",
+    alternative_import="langchain_aws.NeptuneAnalyticsGraph",
+)
 class NeptuneAnalyticsGraph(BaseNeptuneGraph):
     """Neptune Analytics wrapper for graph operations.
 
@@ -269,6 +276,11 @@ class NeptuneAnalyticsGraph(BaseNeptuneGraph):
             return summary
 
 
+@deprecated(
+    since="0.3.15",
+    removal="1.0",
+    alternative_import="langchain_aws.NeptuneGraph",
+)
 class NeptuneGraph(BaseNeptuneGraph):
     """Neptune wrapper for graph operations.
 

libs/community/langchain_community/graphs/neptune_rdf_graph.py

@@ -3,6 +3,7 @@ from types import SimpleNamespace
 from typing import Any, Dict, Optional, Sequence
 
 import requests
+from langchain_core._api.deprecation import deprecated
 
 # Query to find OWL datatype properties
 DTPROP_QUERY = """
@@ -28,6 +29,11 @@ ELEM_TYPES = {
 }
 
 
+@deprecated(
+    since="0.3.15",
+    removal="1.0",
+    alternative_import="langchain_aws.NeptuneRdfGraph",
+)
 class NeptuneRdfGraph:
     """Neptune wrapper for RDF graph operations.