Using metadata

With metadata, you can safely inform any tool about a session or a user. Passing metadata to Toolhouse is useful when you use tools who need to work with scoped information about a user, such as memory tools.

Some tools can require metadata; when that happens, you must set metadata in your code. If your code does not send required metadata, you'll receive an error when trying to get your tools or execute a tool call.

At present, Toolhouse only supports one type of metadata called id. You can use it to set a unique identifier for a user.

Toolhouse does not send metadata to the LLM.

Setting metadata

To set metadata, use the set_metadata method.

from toolhouse import Toolhouse

th = Toolhouse()
th.set_metadata('id', 'alice')

Metadata are only sent to functions that require them. In other words, Toolhouse will not send metadata if the LLM calls a tool that does not require them, even if you set them.

Metadata scoping

Toolhouse automatically scopes any metadata you pass to your app. In other words, suppose you have a user whose ID is alice. If you have two Toolhouse instances (for example production and development), production alice will be treated as a separate user than development alice.

While metadata is scoped at the instance level, all tools in that instance will share the same metadata. Effectively, this means each tool will rely on the same metadata you pass, meaning that you cannot override metadata on a per-tool basis.

Hashed users

Hashing is a one-way process that converts input data into a fixed-size string of characters. It's deterministic, meaning the same input always produces the same output, but it's computationally infeasible to reverse.

Toolhouse automatically protects your data and the data of your users by hashing the value you pass in the id metadata. This means you can safely pass any user ID you normally use, and Toolhouse will convert it into its hashed representation.

Hashing your username avoids tools (including tools from Toolhouse) to see your actual user IDs, while still working with a deterministic representation of the value you pass. For example, if you pass a user value of [e-mail], Toolhouse will automatically it into something like 5e884898da28047151d0e56f8dc6292773603d0d6aabbdd62a11ef721d1542d8. Due to the one-way nature of hashing, it is infeasible to convert this long string into its input user ID.

This makes it safe to pass your unique IDs as user metadata, because tools will not be able to decode them. Toolhouse will not pass your cleartext user ID to any tools, including first-party tools built by Toolhouse.