diff --git a/.github/workflows/docs-integration-tests.yml b/.github/workflows/docs-integration-tests.yml index bba8bdcdd..ad4457a20 100644 --- a/.github/workflows/docs-integration-tests.yml +++ b/.github/workflows/docs-integration-tests.yml @@ -1,15 +1,11 @@ name: Docs Integration Tests on: - pull_request: - types: - - opened - - reopened - branches: [ "main", "dev" ] - paths: - - "docs/**" + pull_request_review: + types: [submitted] jobs: test: + if: github.event.review.state == 'APPROVED' runs-on: ubuntu-latest strategy: fail-fast: false diff --git a/docs/examples/amazon-dynamodb-sessions.md b/docs/examples/amazon-dynamodb-sessions.md new file mode 100644 index 000000000..279cced2a --- /dev/null +++ b/docs/examples/amazon-dynamodb-sessions.md @@ -0,0 +1,92 @@ +Griptape provides [Conversation Memory](../griptape-framework/structures/conversation-memory.md) as a means of persisting conversation context across multiple Structure runs. +If you provide it with a suitable Driver, the memory of the previous conversation can be preserved between run of a Structure, giving it additional context for how to respond. +While we can use the [LocalConversationMemoryDriver](../griptape-framework/drivers/conversation-memory-drivers.md#localconversationmemorydriver) to store the conversation history in a local file, this may not be suitable for production use cases. + +In this example, we will show you how to use the [AmazonDynamoDbConversationMemoryDriver](../griptape-framework/drivers/conversation-memory-drivers.md#amazondynamodbconversationmemorydriver) to persist the memory in an [Amazon DynamoDB](https://aws.amazon.com/dynamodb/) table. Please refer to the [Amazon DynamoDB documentation](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/getting-started-step-1.html) for information on setting up DynamoDB. + +This code implements the idea of a generic "Session" that represents a Conversation Memory entry. For example, a "Session" could be used to represent an individual user's conversation, or a group conversation thread. + +```python +import sys +import os +import argparse + +import boto3 +from griptape.drivers import ( + AmazonDynamoDbConversationMemoryDriver, +) +from griptape.structures import Agent +from griptape.memory.structure import ConversationMemory + +if len(sys.argv) > 2: + input = sys.argv[1] + session_id = sys.argv[2] +else: + input = "Hello!" # Default input + session_id = "session-id-123" # Default session ID + +structure = Agent( + conversation_memory=ConversationMemory( + driver=AmazonDynamoDbConversationMemoryDriver( + session=boto3.Session( + aws_access_key_id=os.environ["AWS_ACCESS_KEY_ID"], + aws_secret_access_key=os.environ["AWS_SECRET_ACCESS_KEY"], + ), + table_name=os.environ["DYNAMODB_TABLE_NAME"], # The name of the DynamoDB table + partition_key="id", # The name of the partition key + partition_key_value=session_id, # The value of the partition key + value_attribute_key="value", # The key in the DynamoDB item that stores the memory value + ) + ) +) + +print(structure.run(input).output_task.output.value) +``` + +Conversation Memory for an individual user: + +```bash +python session.py "Hello my name is Collin." "user-id-123" +python session.py "What is my name?" "user-id-123" +``` + +``` +> Hello Collin! How can I assist you today? +> Your name is Collin. +``` + +```json +{ + "id": { + "S": "user-id-123" + }, + "value": { + "S": "{\"type\": \"ConversationMemory\", \"runs\": [{\"type\": \"Run\", \"id\": \"8c403fb92b134b14a0af8847e52e6212\", \"input\": \"Hello my name is Collin.\", \"output\": \"Hello Collin! How can I assist you today?\"}, {\"type\": \"Run\", \"id\": \"706d9fb072ca49e192bfed7fc1964925\", \"input\": \"What is my name?\", \"output\": \"Your name is Collin.\"}], \"max_runs\": null}" + } +} +``` + +Conversation Memory for a group of users: + +```bash +python session.py "Hello my name is Zach." "group-id-122" +python session.py "And I'm Matt" "group-id-123" +python session.py "And I'm Collin, who all is here?" "group-id-123" +``` + +``` +> Hello Zach! How can I assist you today? +> Hello Matt! Nice to meet you too. How can I help you today? +> Hello Collin! So far, we have Zach, Matt, and now you. How can I assist you all today? +``` + +```json +{ + "id": { + "S": "group-id-123" + }, + "value": { + "S": "{\"type\": \"ConversationMemory\", \"runs\": [{\"type\": \"Run\", \"id\": \"b612cdf5908845e392c026e1cf00460b\", \"input\": \"Hello my name is Zach.\", \"output\": \"Hello Zach! How can I assist you today?\"}, {\"type\": \"Run\", \"id\": \"4507988d82164cad8a288da8c984817c\", \"input\": \"And I'm Matt\", \"output\": \"Hello Matt! Nice to meet you too. How can I help you today?\"}, {\"type\": \"Run\", \"id\": \"65a70c22dae24655b312cf8eaa649bfd\", \"input\": \"And I'm Collin, who all is here?\", \"output\": \"Hello Collin! So far, we have Zach, Matt, and now you. How can I assist you all today?\"}], \"max_runs\": null}" + } +} +``` diff --git a/docs/griptape-framework/drivers/conversation-memory-drivers.md b/docs/griptape-framework/drivers/conversation-memory-drivers.md new file mode 100644 index 000000000..d429be527 --- /dev/null +++ b/docs/griptape-framework/drivers/conversation-memory-drivers.md @@ -0,0 +1,47 @@ +## Overview + +You can persist and load memory by using Conversation Memory Drivers. You can build drivers for your own data stores by extending [BaseConversationMemoryDriver](../../reference/griptape/drivers/memory/conversation/base_conversation_memory_driver.md). + +### LocalConversationMemoryDriver + +The [LocalConversationMemoryDriver](../../reference/griptape/drivers/memory/conversation/local_conversation_memory_driver.md) allows you to persist Conversation Memory in a local JSON file. + +```python +from griptape.structures import Agent +from griptape.drivers import LocalConversationMemoryDriver +from griptape.memory.structure import ConversationMemory + +local_driver = LocalConversationMemoryDriver(file_path="memory.json") +agent = Agent(conversation_memory=ConversationMemory(driver=local_driver)) + +agent.run("Surfing is my favorite sport.") +agent.run("What is my favorite sport?") +``` + +### AmazonDynamoDbConversationMemoryDriver + +!!! info + This driver requires the `drivers-memory-conversation-amazon-dynamodb` [extra](../index.md#extras). + +The [AmazonDynamoDbConversationMemoryDriver](../../reference/griptape/drivers/memory/conversation/amazon_dynamodb_conversation_memory_driver.md) allows you to persist Conversation Memory in [Amazon DynamoDb](https://aws.amazon.com/dynamodb/). + +```python +import os +import uuid +from griptape.drivers import AmazonDynamoDbConversationMemoryDriver +from griptape.memory.structure import ConversationMemory +from griptape.structures import Agent + +conversation_id = uuid.uuid4().hex +dynamodb_driver = AmazonDynamoDbConversationMemoryDriver( + table_name=os.environ["DYNAMODB_TABLE_NAME"], + partition_key="id", + value_attribute_key="memory", + partition_key_value=conversation_id, +) + +agent = Agent(conversation_memory=ConversationMemory(driver=dynamodb_driver)) + +agent.run("My name is Jeff.") +agent.run("What is my name?") +``` diff --git a/docs/griptape-framework/structures/conversation-memory.md b/docs/griptape-framework/structures/conversation-memory.md index 0fdcf1867..92fdf98c4 100644 --- a/docs/griptape-framework/structures/conversation-memory.md +++ b/docs/griptape-framework/structures/conversation-memory.md @@ -97,65 +97,3 @@ agent.run("Hello!") print(agent.conversation_memory.summary) ``` -## Conversation Memory Drivers - -You can persist and load memory by using Conversation Memory Drivers. You can build drivers for your own data stores by extending [BaseConversationMemoryDriver](../../reference/griptape/drivers/memory/conversation/base_conversation_memory_driver.md). - -```python -from griptape.drivers import LocalConversationMemoryDriver -from griptape.structures import Agent -from griptape.memory.structure import ConversationMemory - -memory_driver = LocalConversationMemoryDriver(file_path="memory.json") - -agent_1 = Agent(conversation_memory=ConversationMemory(driver=memory_driver)) -agent_1.run("Skateboarding is my favorite activity.") - -agent_2 = Agent(conversation_memory=memory_driver.load()) -agent_2.run("What is my favorite activity?") -``` - -### Local Conversation Memory Driver - -The [LocalConversationMemoryDriver](../../reference/griptape/drivers/memory/conversation/local_conversation_memory_driver.md) allows you to persist Conversation Memory in a local JSON file. - -```python -from griptape.structures import Agent -from griptape.drivers import LocalConversationMemoryDriver -from griptape.memory.structure import ConversationMemory - -local_driver = LocalConversationMemoryDriver(file_path="memory.json") -agent = Agent(conversation_memory=ConversationMemory(driver=local_driver)) - -agent.run("Surfing is my favorite sport.") -agent.run("What is my favorite sport?") -``` - -### Amazon DynamoDb Conversation Memory Driver - -!!! info - This driver requires the `drivers-memory-conversation-amazon-dynamodb` [extra](../index.md#extras). - -The [AmazonDynamoDbConversationMemoryDriver](../../reference/griptape/drivers/memory/conversation/amazon_dynamodb_conversation_memory_driver.md) allows you to persist Conversation Memory in [Amazon DynamoDb](https://aws.amazon.com/dynamodb/). - -```python -import os -import uuid -from griptape.drivers import AmazonDynamoDbConversationMemoryDriver -from griptape.memory.structure import ConversationMemory -from griptape.structures import Agent - -conversation_id = uuid.uuid4().hex -dynamodb_driver = AmazonDynamoDbConversationMemoryDriver( - table_name=os.environ["DYNAMODB_TABLE_NAME"], - partition_key="id", - value_attribute_key="memory", - partition_key_value=conversation_id, -) - -agent = Agent(conversation_memory=ConversationMemory(driver=dynamodb_driver)) - -agent.run("My name is Jeff.") -agent.run("What is my name?") -``` - diff --git a/mkdocs.yml b/mkdocs.yml index 0b9852e82..bb90117a3 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -102,6 +102,7 @@ nav: - SQL Drivers: "griptape-framework/drivers/sql-drivers.md" - Image Query Drivers: "griptape-framework/drivers/image-query-drivers.md" - Web Scraper Drivers: "griptape-framework/drivers/web-scraper-drivers.md" + - Conversation Memory Drivers: "griptape-framework/drivers/conversation-memory-drivers.md" - Data: - Overview: "griptape-framework/data/index.md" - Artifacts: "griptape-framework/data/artifacts.md" @@ -145,6 +146,7 @@ nav: - Talk to a Webpage: "examples/talk-to-a-webpage.md" - Talk to a PDF: "examples/talk-to-a-pdf.md" - Shared Memory Between Agents: "examples/multiple-agent-shared-memory.md" + - Chat Sessions with Amazon DynamoDB: "examples/amazon-dynamodb-sessions.md" - Data: - Load and Query Pinecone: "examples/load-and-query-pinecone.md" - Load and Query Marqo: "examples/load-query-and-chat-marqo.md"