memory: add interfaces for Google AlloyDB and Cloud SQL (tmc#1205)

* memory: add interfaces for Google AlloyDB and Cloud SQL

Author: averikitsch

examples/google-alloydb-chat-message-history-example/README.md

@@ -0,0 +1,51 @@
+# Google AlloyDB Chat Message History Example
+
+This example demonstrates how to use [AlloyDB for Postgres](https://cloud.google.com/products/alloydb) as a backend for the ChatMessageHistory for LangChain in Go.
+
+## What This Example Does
+
+1. **Creates an AlloyDB Chat Message History:**
+    - Initializes the `alloydb.PostgresEngine` object to establish a connection to the AlloyDB database.
+    - Creates a new table to store the chat message history if it doesn't exist.
+    - Initializes an `alloydb.ChatMessageHistory` object, which provides methods to store, retrieve, and clear message contents with a specific session ID.
+
+2. **Add Single Messages:**
+    - Creates individual AI and Human messages and stores them in the chat message history.
+    - Prints the stored messages to the console.
+
+3. **Add Multiple Messages:**
+    - Creates multiple messages of different types (AI and Human) and stores them all at once in the chat message history.
+    - Prints the stored messages to the console.
+
+4. **Overwrite Messages:**
+    - Clears the existing messages and then stores a new set of messages.
+    - Prints the updated list of stored messages.
+
+5. **Clear All Messages:**
+    - Clears all messages stored for the current session.
+
+## How to Run the Example
+
+1. Set the following environment variables. Your AlloyDB values can be found in the [Google Cloud Console](https://console.cloud.google.com/alloydb/clusters):
+   ```
+   export PROJECT_ID=<your project Id>
+   export ALLOYDB_USERNAME=<your user>
+   export ALLOYDB_PASSWORD=<your password>
+   export ALLOYDB_REGION=<your region>
+   export ALLOYDB_CLUSTER=<your cluster>
+   export ALLOYDB_INSTANCE=<your instance>
+   export ALLOYDB_DATABASE=<your database>
+   export ALLOYDB_TABLE=<your tablename>
+   export ALLOYDB_SESSION_ID=<your sessionID>
+   ```
+
+2. Run the Go example:
+   ```
+   go run google_alloydb_chat_message_history_example.go
+   ```
+
+## Key Features
+- **AlloyDB Integration**: Connects to an AlloyDB instance for storing and managing chat messages.
+- **Message Storage**: Provides methods for storing chat messages with different operations like add, overwrite, and clear.
+- **Session-based Message Management**: Messages are stored and retrieved using a unique session ID, making it easy to manage separate chat sessions.
+- **Clear and Overwrite Capabilities**: Allows overwriting and clearing messages to maintain the chat history as needed.

examples/google-alloydb-chat-message-history-example/google_alloydb_chat_message_history_example.go

@@ -0,0 +1,152 @@
+package main
+
+import (
+	"context"
+	"fmt"
+	"log"
+	"os"
+
+	"github.com/tmc/langchaingo/llms"
+	"github.com/tmc/langchaingo/memory/alloydb"
+	"github.com/tmc/langchaingo/util/alloydbutil"
+)
+
+// getEnvVariables loads the necessary environment variables for the AlloyDB connection
+// and the chat message history creation.
+func getEnvVariables() (string, string, string, string, string, string, string, string, string) {
+	// Requires environment variable ALLOYDB_USERNAME to be set.
+	username := os.Getenv("ALLOYDB_USERNAME")
+	if username == "" {
+		log.Fatal("environment variable ALLOYDB_USERNAME is empty")
+	}
+	// Requires environment variable ALLOYDB_PASSWORD to be set.
+	password := os.Getenv("ALLOYDB_PASSWORD")
+	if password == "" {
+		log.Fatal("environment variable ALLOYDB_PASSWORD is empty")
+	}
+	// Requires environment variable ALLOYDB_DATABASE to be set.
+	database := os.Getenv("ALLOYDB_DATABASE")
+	if database == "" {
+		log.Fatal("environment variable ALLOYDB_DATABASE is empty")
+	}
+	// Requires environment variable PROJECT_ID to be set.
+	projectID := os.Getenv("PROJECT_ID")
+	if projectID == "" {
+		log.Fatal("environment variable PROJECT_ID is empty")
+	}
+	// Requires environment variable ALLOYDB_REGION to be set.
+	region := os.Getenv("ALLOYDB_REGION")
+	if region == "" {
+		log.Fatal("environment variable ALLOYDB_REGION is empty")
+	}
+	// Requires environment variable ALLOYDB_INSTANCE to be set.
+	instance := os.Getenv("ALLOYDB_INSTANCE")
+	if instance == "" {
+		log.Fatal("environment variable ALLOYDB_INSTANCE is empty")
+	}
+	// Requires environment variable ALLOYDB_CLUSTER to be set.
+	cluster := os.Getenv("ALLOYDB_CLUSTER")
+	if cluster == "" {
+		log.Fatal("environment variable ALLOYDB_CLUSTER is empty")
+	}
+	// Requires environment variable ALLOYDB_TABLE to be set.
+	tableName := os.Getenv("ALLOYDB_TABLE")
+	if tableName == "" {
+		log.Fatal("environment variable ALLOYDB_TABLE is empty")
+	}
+	// Requires environment variable ALLOYDB_SESSION_ID to be set.
+	sessionID := os.Getenv("ALLOYDB_SESSION_ID")
+	if sessionID == "" {
+		log.Fatal("environment variable ALLOYDB_SESSION_ID is empty")
+	}
+
+	return username, password, database, projectID, region, instance, cluster, tableName, sessionID
+}
+
+func printMessages(ctx context.Context, cmh alloydb.ChatMessageHistory) {
+	msgs, err := cmh.Messages(ctx)
+	if err != nil {
+		log.Fatal(err)
+	}
+	for _, msg := range msgs {
+		fmt.Println("Message:", msg)
+	}
+}
+
+func main() {
+	// Requires that the Environment variables to be set as indicated in the getEnvVariables function.
+	username, password, database, projectID, region, instance, cluster, tableName, sessionID := getEnvVariables()
+	ctx := context.Background()
+
+	pgEngine, err := alloydbutil.NewPostgresEngine(ctx,
+		alloydbutil.WithUser(username),
+		alloydbutil.WithPassword(password),
+		alloydbutil.WithDatabase(database),
+		alloydbutil.WithAlloyDBInstance(projectID, region, cluster, instance),
+	)
+	if err != nil {
+		log.Fatal(err)
+	}
+
+	// Creates a new table in the Postgres database, which will be used for storing Chat History.
+	err = pgEngine.InitChatHistoryTable(ctx, tableName)
+	if err != nil {
+		log.Fatal(err)
+	}
+
+	// Creates a new Chat Message History
+	cmh, err := alloydb.NewChatMessageHistory(ctx, pgEngine, tableName, sessionID)
+	if err != nil {
+		log.Fatal(err)
+	}
+
+	// Creates individual messages and adds them to the chat message history.
+	aiMessage := llms.AIChatMessage{Content: "test AI message"}
+	humanMessage := llms.HumanChatMessage{Content: "test HUMAN message"}
+	// Adds a user message to the chat message history.
+	err = cmh.AddUserMessage(ctx, aiMessage.GetContent())
+	if err != nil {
+		log.Fatal(err)
+	}
+	// Adds a user message to the chat message history.
+	err = cmh.AddUserMessage(ctx, humanMessage.GetContent())
+	if err != nil {
+		log.Fatal(err)
+	}
+
+	printMessages(ctx, cmh)
+
+	// Create multiple messages and store them in the chat message history at the same time.
+	multipleMessages := []llms.ChatMessage{
+		llms.AIChatMessage{Content: "first AI test message from AddMessages"},
+		llms.AIChatMessage{Content: "second AI test message from AddMessages"},
+		llms.HumanChatMessage{Content: "first HUMAN test message from AddMessages"},
+	}
+
+	// Adds multiple messages to the chat message history.
+	err = cmh.AddMessages(ctx, multipleMessages)
+	if err != nil {
+		log.Fatal(err)
+	}
+
+	printMessages(ctx, cmh)
+
+	// Create messages that will overwrite the existing ones
+	overWrittingMessages := []llms.ChatMessage{
+		llms.AIChatMessage{Content: "overwritten AI test message"},
+		llms.HumanChatMessage{Content: "overwritten HUMAN test message"},
+	}
+	// Overwrites the existing messages with new ones.
+	err = cmh.SetMessages(ctx, overWrittingMessages)
+	if err != nil {
+		log.Fatal(err)
+	}
+
+	printMessages(ctx, cmh)
+
+	// Clear all the messages from the current session.
+	err = cmh.Clear(ctx)
+	if err != nil {
+		log.Fatal(err)
+	}
+}

examples/google-cloudsql-chat-message-history-example/README.md

@@ -0,0 +1,50 @@
+# Google CloudSQL Chat Message History Example
+
+This example demonstrates how to use [CloudSQL for Postgres](https://cloud.google.com/sql) as a backend for the ChatMessageHistory for LangChain in Go.
+
+## What This Example Does
+
+1. **Creates a CloudSQL Chat Message History:**
+    - Initializes the `cloudsql.PostgresEngine` object to establish a connection to the CloudSQL database.
+    - Creates a new table to store the chat message history if it doesn't exist.
+    - Initializes a `cloudsql.ChatMessageHistory` object, which provides methods to store, retrieve, and clear message contents with a specific session ID.
+
+2. **Add Single Messages:**
+    - Creates individual AI and Human messages and stores them in the chat message history.
+    - Prints the stored messages to the console.
+
+3. **Add Multiple Messages:**
+    - Creates multiple messages of different types (AI and Human) and stores them all at once in the chat message history.
+    - Prints the stored messages to the console.
+
+4. **Overwrite Messages:**
+    - Clears the existing messages and then stores a new set of messages.
+    - Prints the updated list of stored messages.
+
+5. **Clear All Messages:**
+    - Clears all messages stored for the current session.
+
+## How to Run the Example
+
+1. Set the following environment variables. Your CloudSQL values can be found in the [Google Cloud Console](https://console.cloud.google.com/sql/instances):
+   ```
+   export PROJECT_ID=<your project Id>
+   export POSTGRES_USERNAME=<your user>
+   export POSTGRES_PASSWORD=<your password>
+   export POSTGRES_REGION=<your region>
+   export POSTGRES_INSTANCE=<your instance>
+   export POSTGRES_DATABASE=<your database>
+   export POSTGRES_TABLE=<your tablename>
+   export POSTGRES_SESSION_ID=<your sessionID>
+   ```
+
+2. Run the Go example:
+   ```
+   go run google_cloudsql_chat_message_history_example.go
+   ```
+
+## Key Features
+- **CloudSQL Integration**: Connects to a CloudSQL instance for storing and managing chat messages.
+- **Message Storage**: Provides methods for storing chat messages with different operations like add, overwrite, and clear.
+- **Session-based Message Management**: Messages are stored and retrieved using a unique session ID, making it easy to manage separate chat sessions.
+- **Clear and Overwrite Capabilities**: Allows overwriting and clearing messages to maintain the chat history as needed.