couchbase: Add chat message history (langchain-ai#24356)

**Description:** : Add support for chat message history using Couchbase - [x] **Add tests and docs**: If you're adding a new integration, please include 1. a test for the integration, preferably unit tests that do not rely on network access, 2. an example notebook showing its use. It lives in `docs/docs/integrations` directory. - [x] **Lint and test**: Run `make format`, `make lint` and `make test` from the root of the package(s) you've modified. See contribution guidelines for more: https://python.langchain.com/docs/contributing/ --------- Co-authored-by: Nithish Raghunandanan <[email protected]>
hooman-bayer · Jul 17, 2024 · eb26b55 · eb26b55
1 parent 96bac8e
commit eb26b55
Show file tree

Hide file tree

Showing 8 changed files with 1,464 additions and 28 deletions.
diff --git a/docs/docs/integrations/memory/couchbase_chat_message_history.ipynb b/docs/docs/integrations/memory/couchbase_chat_message_history.ipynb
@@ -0,0 +1,325 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "id": "a283d2fd-e26e-4811-a486-d3cf0ecf6749",
+   "metadata": {},
+   "source": [
+    "# Couchbase\n",
+    "> Couchbase is an award-winning distributed NoSQL cloud database that delivers unmatched versatility, performance, scalability, and financial value for all of your cloud, mobile, AI, and edge computing applications. Couchbase embraces AI with coding assistance for developers and vector search for their applications.\n",
+    "\n",
+    "This notebook goes over how to use the `CouchbaseChatMessageHistory` class to store the chat message history in a Couchbase cluster\n"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "ff868a6c-3e17-4c3d-8d32-67b01f4d7bcc",
+   "metadata": {},
+   "source": [
+    "## Set Up Couchbase Cluster\n",
+    "To run this demo, you need a Couchbase Cluster. \n",
+    "\n",
+    "You can work with both [Couchbase Capella](https://www.couchbase.com/products/capella/) and your self-managed Couchbase Server."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "41fa85e7-6968-45e4-a445-de305d80f332",
+   "metadata": {},
+   "source": [
+    "## Install Dependencies\n",
+    "`CouchbaseChatMessageHistory` lives inside the `langchain-couchbase` package. "
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 1,
+   "id": "b744ca05-b8c6-458c-91df-f50ca2c20b3c",
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "Note: you may need to restart the kernel to use updated packages.\n"
+     ]
+    }
+   ],
+   "source": [
+    "%pip install --upgrade --quiet langchain-couchbase"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "41f29205-6452-493b-ba18-8a3b006bcca4",
+   "metadata": {},
+   "source": [
+    "## Create Couchbase Connection Object\n",
+    "We create a connection to the Couchbase cluster initially and then pass the cluster object to the Vector Store. \n",
+    "\n",
+    "Here, we are connecting using the username and password. You can also connect using any other supported way to your cluster. \n",
+    "\n",
+    "For more information on connecting to the Couchbase cluster, please check the [Python SDK documentation](https://docs.couchbase.com/python-sdk/current/hello-world/start-using-sdk.html#connect)."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 2,
+   "id": "f394908e-f5fe-408a-84d7-b97fdebcfa26",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "COUCHBASE_CONNECTION_STRING = (\n",
+    "    \"couchbase://localhost\"  # or \"couchbases://localhost\" if using TLS\n",
+    ")\n",
+    "DB_USERNAME = \"Administrator\"\n",
+    "DB_PASSWORD = \"Password\""
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 3,
+   "id": "ad4dce21-d80c-465a-b709-fd366ba5ce35",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from datetime import timedelta\n",
+    "\n",
+    "from couchbase.auth import PasswordAuthenticator\n",
+    "from couchbase.cluster import Cluster\n",
+    "from couchbase.options import ClusterOptions\n",
+    "\n",
+    "auth = PasswordAuthenticator(DB_USERNAME, DB_PASSWORD)\n",
+    "options = ClusterOptions(auth)\n",
+    "cluster = Cluster(COUCHBASE_CONNECTION_STRING, options)\n",
+    "\n",
+    "# Wait until the cluster is ready for use.\n",
+    "cluster.wait_until_ready(timedelta(seconds=5))"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "e3d0210c-e2e6-437a-86f3-7397a1899fef",
+   "metadata": {},
+   "source": [
+    "We will now set the bucket, scope, and collection names in the Couchbase cluster that we want to use for storing the message history.\n",
+    "\n",
+    "Note that the bucket, scope, and collection need to exist before using them to store the message history."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 4,
+   "id": "e8c7f846-a5c4-4465-a40e-4a9a23ac71bd",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "BUCKET_NAME = \"langchain-testing\"\n",
+    "SCOPE_NAME = \"_default\"\n",
+    "COLLECTION_NAME = \"conversational_cache\""
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "283959e1-6af7-4768-9211-5b0facc6ef65",
+   "metadata": {},
+   "source": [
+    "## Usage\n",
+    "In order to store the messages, you need the following:\n",
+    "- Couchbase Cluster object: Valid connection to the Couchbase cluster\n",
+    "- bucket_name: Bucket in cluster to store the chat message history\n",
+    "- scope_name: Scope in bucket to store the message history\n",
+    "- collection_name: Collection in scope to store the message history\n",
+    "- session_id: Unique identifier for the session\n",
+    "\n",
+    "Optionally you can configure the following:\n",
+    "- session_id_key: Field in the chat message documents to store the `session_id`\n",
+    "- message_key: Field in the chat message documents to store the message content\n",
+    "- create_index: Used to specify if the index needs to be created on the collection. By default, an index is created on the `message_key` and the `session_id_key` of the documents"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 5,
+   "id": "43c3b2d5-aae2-44a9-9e9f-f10adf054cfa",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from langchain_couchbase.chat_message_histories import CouchbaseChatMessageHistory\n",
+    "\n",
+    "message_history = CouchbaseChatMessageHistory(\n",
+    "    cluster=cluster,\n",
+    "    bucket_name=BUCKET_NAME,\n",
+    "    scope_name=SCOPE_NAME,\n",
+    "    collection_name=COLLECTION_NAME,\n",
+    "    session_id=\"test-session\",\n",
+    ")\n",
+    "\n",
+    "message_history.add_user_message(\"hi!\")\n",
+    "\n",
+    "message_history.add_ai_message(\"how are you doing?\")"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 6,
+   "id": "e7e348ef-79e9-481c-aeef-969ae03dea6a",
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "[HumanMessage(content='hi!'), AIMessage(content='how are you doing?')]"
+      ]
+     },
+     "execution_count": 6,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "message_history.messages"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "c8b942a7-93fa-4cd9-8414-d047135c2733",
+   "metadata": {},
+   "source": [
+    "## Chaining\n",
+    "The chat message history class can be used with [LCEL Runnables](https://python.langchain.com/v0.2/docs/how_to/message_history/)"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "8a9f0d91-d1d6-481d-8137-ea11229f485a",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import getpass\n",
+    "import os\n",
+    "\n",
+    "from langchain_core.prompts import ChatPromptTemplate, MessagesPlaceholder\n",
+    "from langchain_core.runnables.history import RunnableWithMessageHistory\n",
+    "from langchain_openai import ChatOpenAI\n",
+    "\n",
+    "os.environ[\"OPENAI_API_KEY\"] = getpass.getpass()"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 8,
+   "id": "946d45aa-5a61-49ae-816b-1c3949c56d9a",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "prompt = ChatPromptTemplate.from_messages(\n",
+    "    [\n",
+    "        (\"system\", \"You are a helpful assistant.\"),\n",
+    "        MessagesPlaceholder(variable_name=\"history\"),\n",
+    "        (\"human\", \"{question}\"),\n",
+    "    ]\n",
+    ")\n",
+    "\n",
+    "# Create the LCEL runnable\n",
+    "chain = prompt | ChatOpenAI()"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 9,
+   "id": "20dfd838-b549-42ed-b3ba-ac005f7e024c",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "chain_with_history = RunnableWithMessageHistory(\n",
+    "    chain,\n",
+    "    lambda session_id: CouchbaseChatMessageHistory(\n",
+    "        cluster=cluster,\n",
+    "        bucket_name=BUCKET_NAME,\n",
+    "        scope_name=SCOPE_NAME,\n",
+    "        collection_name=COLLECTION_NAME,\n",
+    "        session_id=session_id,\n",
+    "    ),\n",
+    "    input_messages_key=\"question\",\n",
+    "    history_messages_key=\"history\",\n",
+    ")"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 10,
+   "id": "17bd09f4-896d-433d-bb9a-369a06e7aa8a",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# This is where we configure the session id\n",
+    "config = {\"configurable\": {\"session_id\": \"testing\"}}"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 11,
+   "id": "4bda1096-2fc2-40d7-a046-0d5d8e3a8f75",
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "AIMessage(content='Hello Bob! How can I assist you today?', response_metadata={'token_usage': {'completion_tokens': 10, 'prompt_tokens': 22, 'total_tokens': 32}, 'model_name': 'gpt-3.5-turbo-0125', 'system_fingerprint': None, 'finish_reason': 'stop', 'logprobs': None}, id='run-a0f8a29e-ddf4-4e06-a1fe-cf8c325a2b72-0', usage_metadata={'input_tokens': 22, 'output_tokens': 10, 'total_tokens': 32})"
+      ]
+     },
+     "execution_count": 11,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "chain_with_history.invoke({\"question\": \"Hi! I'm bob\"}, config=config)"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 12,
+   "id": "1cfb31da-51bb-4c5f-909a-b7118b0ae08d",
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "AIMessage(content='Your name is Bob.', response_metadata={'token_usage': {'completion_tokens': 5, 'prompt_tokens': 43, 'total_tokens': 48}, 'model_name': 'gpt-3.5-turbo-0125', 'system_fingerprint': None, 'finish_reason': 'stop', 'logprobs': None}, id='run-f764a9eb-999e-4042-96b6-fe47b7ae4779-0', usage_metadata={'input_tokens': 43, 'output_tokens': 5, 'total_tokens': 48})"
+      ]
+     },
+     "execution_count": 12,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "chain_with_history.invoke({\"question\": \"Whats my name\"}, config=config)"
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "Python 3 (ipykernel)",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3",
+   "version": "3.10.13"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}
diff --git a/docs/docs/integrations/providers/couchbase.mdx b/docs/docs/integrations/providers/couchbase.mdx
@@ -89,3 +89,23 @@ set_llm_cache(
     )
 )
 ```
+
+## Chat Message History
+Use Couchbase as the storage for your chat messages.
+
+See a [usage example](/docs/integrations/memory/couchbase_chat_message_history).
+
+To use the chat message history in your applications:
+```python
+from langchain_couchbase.chat_message_histories import CouchbaseChatMessageHistory
+
+message_history = CouchbaseChatMessageHistory(
+    cluster=cluster,
+    bucket_name=BUCKET_NAME,
+    scope_name=SCOPE_NAME,
+    collection_name=COLLECTION_NAME,
+    session_id="test-session",
+)
+
+message_history.add_user_message("hi!")
+```
diff --git a/libs/partners/couchbase/langchain_couchbase/__init__.py b/libs/partners/couchbase/langchain_couchbase/__init__.py
@@ -1,7 +1,10 @@
+from langchain_couchbase.cache import CouchbaseCache, CouchbaseSemanticCache
+from langchain_couchbase.chat_message_histories import CouchbaseChatMessageHistory
 from langchain_couchbase.vectorstores import CouchbaseVectorStore
 
 __all__ = [
     "CouchbaseVectorStore",
     "CouchbaseCache",
     "CouchbaseSemanticCache",
+    "CouchbaseChatMessageHistory",
 ]