Release/v0.27.0

.coveragerc

@@ -1,28 +1,15 @@
 [run]
-data_file = coverage/.coverage
 branch = True
 
 [report]
-; Regexes for lines to exclude from consideration
 exclude_also =
-  ; Don't complain about missing debug-only code:
-  def __repr__
-  if self\.debug
-
-  ; Don't complain if tests don't hit defensive assertion code:
-  raise AssertionError
-  raise NotImplementedError
-
-  ; Don't complain if non-runnable code isn't run:
-  if 0:
-  if __name__ == .__main__.:
-  if TYPE_CHECKING:
-
-  ; Don't complain about abstract methods, they aren't run:
-  @(abc\.)?abstractmethod
-
-[html]
-directory = coverage/html
-
-[xml]
-output = coverage/coverage.xml
+    def __repr__
+    if self.debug:
+    if settings.DEBUG
+    raise AssertionError
+    raise NotImplementedError
+    if 0:
+    if __name__ == .__main__.:
+    if TYPE_CHECKING:
+    class .*\bProtocol\):
+    @(abc\.)?abstractmethod

.gitignore

@@ -16,7 +16,6 @@ __pycache__
 npm-debug.log
 **/.mypy_cache/**
 !yarn.lock
-coverage/
 cucumber-report.json
 **/.vscode-test/**
 **/.vscode test/**
@@ -57,3 +56,7 @@ dist/**
 # mkdocs build output
 site
 reference
+
+# coverage.py
+htmlcov/
+coverage.*

CHANGELOG.md

@@ -6,6 +6,77 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## Unreleased
 
+## [0.27.0] - 2024-06-19
+
+### Added
+- `BaseTask.add_child()` to add a child task to a parent task.
+- `BaseTask.add_children()` to add multiple child tasks to a parent task.
+- `BaseTask.add_parent()` to add a parent task to a child task.
+- `BaseTask.add_parents()` to add multiple parent tasks to a child task.
+- `Structure.resolve_relationships()` to resolve asymmetrically defined parent/child relationships. In other words, if a parent declares a child, but the child does not declare the parent, the parent will automatically be added as a parent of the child when running this method. The method is invoked automatically by `Structure.before_run()`.
+- `CohereEmbeddingDriver` for using Cohere's embeddings API.
+- `CohereStructureConfig` for providing Structures with quick Cohere configuration.
+- `AmazonSageMakerJumpstartPromptDriver.inference_component_name` for setting the `InferenceComponentName` parameter when invoking an endpoint.
+- `AmazonSageMakerJumpstartEmbeddingDriver.inference_component_name` for setting the `InferenceComponentName` parameter when invoking an endpoint.
+- `AmazonSageMakerJumpstartEmbeddingDriver.custom_attributes` for setting custom attributes when invoking an endpoint.
+- `ToolkitTask.response_stop_sequence` for overriding the default Chain of Thought stop sequence.
+- `griptape.utils.StructureVisualizer` for visualizing Workflow structures with Mermaid.js
+- `BaseTask.parents_outputs` to get the textual output of all parent tasks. 
+- `BaseTask.parents_output_text` to get a concatenated string of all parent tasks' outputs.
+- `parents_output_text` to Workflow context.
+- `OllamaPromptModelDriver` for using models with Ollama.
+- Parameter `output` on `Structure` as a convenience for `output_task.output`
+
+### Changed
+- **BREAKING**: `Workflow` no longer modifies task relationships when adding tasks via `tasks` init param, `add_tasks()` or `add_task()`. Previously, adding a task would automatically add the previously added task as its parent. Existing code that relies on this behavior will need to be updated to explicitly add parent/child relationships using the API offered by `BaseTask`.
+- **BREAKING**: Removed `AmazonBedrockPromptDriver.prompt_model_driver` as it is no longer needed with the `AmazonBedrockPromptDriver` Converse API implementation.
+- **BREAKING**: Removed `BedrockClaudePromptModelDriver`.
+- **BREAKING**: Removed `BedrockJurassicPromptModelDriver`.
+- **BREAKING**: Removed `BedrockLlamaPromptModelDriver`.
+- **BREAKING**: Removed `BedrockTitanPromptModelDriver`.
+- **BREAKING**: Removed `BedrockClaudeTokenizer`, use `SimpleTokenizer` instead.
+- **BREAKING**: Removed `BedrockJurassicTokenizer`, use `SimpleTokenizer` instead.
+- **BREAKING**: Removed `BedrockLlamaTokenizer`, use `SimpleTokenizer` instead.
+- **BREAKING**: Removed `BedrockTitanTokenizer`, use `SimpleTokenizer` instead.
+- **BREAKING**: Removed `OpenAiChatCompletionPromptDriver` as it uses the legacy [OpenAi Completions API](https://platform.openai.com/docs/api-reference/completions).
+- **BREAKING**: Removed `BasePromptDriver.count_tokens()`.
+- **BREAKING**: Removed `BasePromptDriver.max_output_tokens()`.
+- **BREAKING**: Moved/renamed `PromptStack.add_to_conversation_memory` to `BaseConversationMemory.add_to_prompt_stack`.
+- **BREAKING**: Moved `griptape.constants.RESPONSE_STOP_SEQUENCE` to `ToolkitTask`.
+- **BREAKING**: Renamed `AmazonSagemakerPromptDriver` to `AmazonSageMakerJumpstartPromptDriver`.
+- **BREAKING**: Removed `SagemakerFalconPromptModelDriver`, use `AmazonSageMakerJumpstartPromptDriver` instead.
+- **BREAKING**: Removed `SagemakerLlamaPromptModelDriver`, use `AmazonSageMakerJumpstartPromptDriver` instead.
+- **BREAKING**: Renamed `AmazonSagemakerEmbeddingDriver` to `AmazonSageMakerJumpstartEmbeddingDriver`.
+- **BREAKING**: Removed `SagemakerHuggingfaceEmbeddingModelDriver`, use `AmazonSageMakerJumpstartEmbeddingDriver` instead.
+- **BREAKING**: Removed `SagemakerTensorflowHubEmbeddingModelDriver`, use `AmazonSageMakerJumpstartEmbeddingDriver` instead.
+- **BREAKING**: `AmazonSageMakerJumpstartPromptDriver.model` parameter, which gets passed to `SageMakerRuntime.Client.invoke_endpoint` as `EndpointName`, is now renamed to `AmazonSageMakerPromptDriver.endpoint`.
+- **BREAKING**: Removed parameter `template_generator` on `PromptSummaryEngine` and added parameters `system_template_generator` and `user_template_generator`.
+- **BREAKING**: Removed template `engines/summary/prompt_summary.j2` and added templates `engines/summary/system.j2` and `engines/summary/user.j2`.
+- `ToolkitTask.RESPONSE_STOP_SEQUENCE` is now only added when using `ToolkitTask`.
+- Updated Prompt Drivers to use `BasePromptDriver.max_tokens` instead of using `BasePromptDriver.max_output_tokens()`.
+- Improved error message when `GriptapeCloudKnowledgeBaseClient` does not have a description set.
+- Updated `AmazonBedrockPromptDriver` to use [Converse API](https://docs.aws.amazon.com/bedrock/latest/userguide/conversation-inference.html).
+- `Structure.before_run()` now automatically resolves asymmetrically defined parent/child relationships using the new `Structure.resolve_relationships()`.
+- Updated `HuggingFaceHubPromptDriver` to use `transformers`'s `apply_chat_template`.
+- Updated `HuggingFacePipelinePromptDriver` to use chat features of `transformers.TextGenerationPipeline`.
+- Updated `CoherePromptDriver` to use Cohere's latest SDK.
+- Moved Task reset logic for all Structures to `Structure.before_run`.
+- Updated default prompt templates for `PromptSummaryEngine`.
+- Updated template `templates/tasks/tool_task/system.j2`.
+
+### Fixed
+- `Workflow.insert_task()` no longer inserts duplicate tasks when given multiple parent tasks.
+- Performance issue in `OpenAiChatPromptDriver` when extracting unused rate-limiting headers.
+- Streaming not working when using deprecated `Structure.stream` field.
+- Raw Tool output being lost when being executed by ActionsSubtask.
+- Re-order Workflow tasks on every task execution wave.
+- Web Loader to catch Exceptions and properly return an ErrorArtifact.
+- Conversation Memory entry only added if `output_task.output` is not `None` on all `Structures`
+- `TextArtifacts` contained in `ListArtifact` returned by `WebSearch.search` to properly formatted stringified JSON.
+- Structure run args not being set immediately.
+- Input and output logging in BaseAudioInputTasks and BaseAudioGenerationTasks
+- Validation of `max_tokens` < 0 on `BaseChunker`
+
 ## [0.26.0] - 2024-06-04
 
 ### Added
@@ -15,7 +86,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - `AudioTranscriptionTask` and `AudioTranscriptionClient` for transcribing audio content in Structures.
 - `OpenAiAudioTranscriptionDriver` for integration with OpenAI's speech-to-text models, including Whisper.
 - Parameter `env` to `BaseStructureRunDriver` to set environment variables for a Structure Run.
-- `PusherEventListenerDriver` to enable sending of framework events over a Pusher WebSocket. 
+- `PusherEventListenerDriver` to enable sending of framework events over a Pusher WebSocket.
 
 ### Changed
 - **BREAKING**: Removed `StructureConfig.global_drivers`. Pass Drivers directly to the Structure Config instead. 

Makefile

@@ -7,7 +7,7 @@ version: ## Bump version and push to release branch.
 
 .PHONY: publish
 publish: ## Push git tag and publish version to PyPI.
-	@git tag v$$(poetry version -s)
+	@git tag $$(poetry version -s)
 	@git push --tags
 	@poetry build
 	@poetry publish

docs/examples/amazon-dynamodb-sessions.md

@@ -1,8 +1,8 @@
 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.
+While we can use the [LocalConversationMemoryDriver](../griptape-framework/drivers/conversation-memory-drivers.md#local) to store the conversation history in a local file, in production use-cases we may want to store in a proper database.
 
-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. 
+In this example, we will show you how to use the [AmazonDynamoDbConversationMemoryDriver](../griptape-framework/drivers/conversation-memory-drivers.md#amazon-dynamodb) 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.
 

docs/examples/multi-agent-workflow.md

@@ -1,7 +1,7 @@
 In this example we implement a multi-agent Workflow. We have a single "Researcher" Agent that conducts research on a topic, and then fans out to multiple "Writer" Agents to write blog posts based on the research.
 
 By splitting up our workloads across multiple Structures, we can parallelize the work and leverage the strengths of each Agent. The Researcher can focus on gathering data and insights, while the Writers can focus on crafting engaging narratives.
-Additionally, this architecture opens us up to using services such as [Griptape Cloud](https://www.griptape.ai/cloud) to have each Agent run on a separate machine, allowing us to scale our Workflow as needed 🤯.
+Additionally, this architecture opens us up to using services such as [Griptape Cloud](https://www.griptape.ai/cloud) to have each Agent run completely independently, allowing us to scale our Workflow as needed 🤯. To try out how this would work, you can deploy this example as multiple structures from our [Sample Structures](https://github.com/griptape-ai/griptape-sample-structures/tree/main/griptape-multi-agent-workflows) repo.
 
 
 ```python
@@ -155,35 +155,33 @@ if __name__ == "__main__":
             ),
         ),
     )
-    end_task = team.add_task(
-        PromptTask(
-            'State "All Done!"',
-        )
-    )
-    team.insert_tasks(
-        research_task,
-        [
-            StructureRunTask(
-                (
-                    """Using insights provided, develop an engaging blog
+    writer_tasks = team.add_tasks(*[
+        StructureRunTask(
+            (
+                """Using insights provided, develop an engaging blog
                 post that highlights the most significant AI advancements.
                 Your post should be informative yet accessible, catering to a tech-savvy audience.
                 Make it sound cool, avoid complex words so it doesn't sound like AI.
 
                 Insights:
                 {{ parent_outputs["research"] }}""",
-                ),
-                driver=LocalStructureRunDriver(
-                    structure_factory_fn=lambda: build_writer(
-                        role=writer["role"],
-                        goal=writer["goal"],
-                        backstory=writer["backstory"],
-                    )
-                ),
-            )
-            for writer in WRITERS
-        ],
-        end_task,
+            ),
+            driver=LocalStructureRunDriver(
+                structure_factory_fn=lambda: build_writer(
+                    role=writer["role"],
+                    goal=writer["goal"],
+                    backstory=writer["backstory"],
+                )
+            ),
+            parent_ids=[research_task.id],
+        )
+        for writer in WRITERS
+    ])
+    end_task = team.add_task(
+        PromptTask(
+            'State "All Done!"',
+            parent_ids=[writer_task.id for writer_task in writer_tasks],
+        )
     )
 
     team.run()

docs/griptape-framework/data/artifacts.md

@@ -14,7 +14,7 @@ and access it with [embedding](../../reference/griptape/artifacts/text_artifact.
 ## CsvRowArtifact
 
 Used for passing structured row data around the framework. It inherits from [TextArtifact](../../reference/griptape/artifacts/text_artifact.md) and overrides the 
-[to_text()](../../reference/griptape/artifacts/text_artifact.md#griptape.artifacts.text_artifact.TextArtifact.to_text) method, which always returns a valid CSV row.
+[to_text()](../../reference/griptape/artifacts/csv_row_artifact.md#griptape.artifacts.csv_row_artifact.CsvRowArtifact.to_text) method, which always returns a valid CSV row.
 
 ## InfoArtifact
 
@@ -29,7 +29,7 @@ Used for passing errors back to the LLM without task memory storing them.
 Used for passing binary large objects (blobs) back to the LLM. 
 Treat it as a way to return unstructured data, such as images, videos, audio, and other files back from tools. 
 Each blob has a [name](../../reference/griptape/artifacts/base_artifact.md#griptape.artifacts.base_artifact.BaseArtifact.name) and 
-[dir](../../reference/griptape/artifacts/blob_artifact.md#griptape.artifacts.blob_artifact.BlobArtifact.dir) to uniquely identify stored objects.
+[dir](../../reference/griptape/artifacts/blob_artifact.md#griptape.artifacts.blob_artifact.BlobArtifact.dir_name) to uniquely identify stored objects.
 
 [TaskMemory](../../reference/griptape/memory/task/task_memory.md) automatically stores [BlobArtifact](../../reference/griptape/artifacts/blob_artifact.md)s returned by tool activities that can be reused by other tools.
 

docs/griptape-framework/data/loaders.md

@@ -4,7 +4,7 @@ Loaders are used to load textual data from different sources and chunk it into [
 Each loader can be used to load a single "document" with [load()](../../reference/griptape/loaders/base_loader.md#griptape.loaders.base_loader.BaseLoader.load) or
 multiple documents with [load_collection()](../../reference/griptape/loaders/base_loader.md#griptape.loaders.base_loader.BaseLoader.load_collection).
 
-## Pdf Loader
+## PDF
 
 !!! info
     This driver requires the `loaders-pdf` [extra](../index.md#extras).
@@ -33,7 +33,7 @@ with open("attention.pdf", "rb") as attention, open("CoT.pdf", "rb") as cot:
 PdfLoader().load_collection(list(load_files(["attention.pdf", "CoT.pdf"]).values()))
 ```
 
-## Sql Loader
+## SQL
 
 Can be used to load data from a SQL database into [CsvRowArtifact](../../reference/griptape/artifacts/csv_row_artifact.md)s:
 
@@ -54,7 +54,7 @@ SqlLoader(
 ).load_collection(["SELECT 'foo', 'bar';", "SELECT 'fizz', 'buzz';"])
 ```
 
-## Csv Loader
+## CSV
 
 Can be used to load CSV files into [CsvRowArtifact](../../reference/griptape/artifacts/csv_row_artifact.md)s:
 
@@ -76,7 +76,7 @@ CsvLoader().load_collection(list(load_files(["tests/resources/cities.csv", "test
 ```
 
 
-## DataFrame Loader
+## DataFrame
 
 !!! info
     This driver requires the `loaders-dataframe` [extra](../index.md#extras).
@@ -100,7 +100,7 @@ DataFrameLoader().load_collection(
 ```
 
 
-## Text Loader
+## Text
 
 Used to load arbitrary text and text files:
 
@@ -124,9 +124,9 @@ with open("example.txt", "r") as f:
     )
 ```
 
-You can set a custom [tokenizer](../../reference/griptape/loaders/text_loader.md#griptape.loaders.text_loader.TextLoader.tokenizer.md), [max_tokens](../../reference/griptape/loaders/text_loader.md#griptape.loaders.text_loader.TextLoader.max_tokens.md) parameter, and [chunker](../../reference/griptape/loaders/text_loader.md#griptape.loaders.text_loader.TextLoader.chunker.md).
+You can set a custom [tokenizer](../../reference/griptape/loaders/text_loader.md#griptape.loaders.text_loader.TextLoader.tokenizer), [max_tokens](../../reference/griptape/loaders/text_loader.md#griptape.loaders.text_loader.TextLoader.max_tokens) parameter, and [chunker](../../reference/griptape/loaders/text_loader.md#griptape.loaders.text_loader.TextLoader.chunker).
 
-## Web Loader
+## Web
 
 !!! info
     This driver requires the `loaders-web` [extra](../index.md#extras).
@@ -145,7 +145,7 @@ WebLoader().load_collection(
 )
 ```
 
-## Image Loader
+## Image
 
 !!! info
     This driver requires the `loaders-image` [extra](../index.md#extras).
@@ -183,7 +183,7 @@ ImageLoader().load_collection(list(load_files(["tests/resources/mountain.png", "
 ```
 
 
-## Email Loader
+## Email
 
 !!! info
     This driver requires the `loaders-email` [extra](../index.md#extras).
@@ -200,7 +200,7 @@ loader.load(EmailLoader.EmailQuery(label="INBOX"))
 loader.load_collection([EmailLoader.EmailQuery(label="INBOX"), EmailLoader.EmailQuery(label="SENT")])
 ```
 
-## Audio Loader 
+## Audio
 
 !!! info
     This driver requires the `loaders-audio` [extra](../index.md#extras).

docs/griptape-framework/drivers/conversation-memory-drivers.md

@@ -2,7 +2,7 @@
 
 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
+### Local
 
 The [LocalConversationMemoryDriver](../../reference/griptape/drivers/memory/conversation/local_conversation_memory_driver.md) allows you to persist Conversation Memory in a local JSON file.
 
@@ -18,7 +18,7 @@ agent.run("Surfing is my favorite sport.")
 agent.run("What is my favorite sport?")
 ```
 
-### AmazonDynamoDbConversationMemoryDriver
+### Amazon DynamoDb
 
 !!! info
     This driver requires the `drivers-memory-conversation-amazon-dynamodb` [extra](../index.md#extras).
@@ -47,7 +47,7 @@ agent.run("What is my name?")
 ```
 
 
-### Redis Conversation Memory Driver
+### Redis
 
 !!! info
     This driver requires the `drivers-memory-conversation-redis` [extra](../index.md#extras).